API Requests

Documentation has moved

The information on this page is no longer updated and may be obsolete. The most current Koshelek documentation is now available at the new address:

https://developers.koshelek.app/en/

Get promos

GET https://api.cardsmobile.ru/promo/v1/all

This endpoint allows a partner to obtain a list of partner's created promos.

Request Body

Name	Type	Description
limit	number	Number of list items to be returned. Max. value: 100. Default value: 15.
offset	number	List offset (number of dismissed items). Default value: 0.
activeOnly	boolean	true — get only active promos. false — get all promos, including ended or planned. Processed by default as false.

200: OK The request is processed. The response body contains a list of partner's promos:

HTTP: 200

{
  "metadata": {
    "limit": 15,
    "offset": 0,
    "totalCount": 2,
    "activeOnly": false
  },
  "items": [
    {
      "promoId": 1010,
      "name": "Total SALE!",
      "startDate": "2020-09-01T00:00:00+03",
      "endDate": "2020-09-10T00:00:00+03",
      "status": "active"
    },
    {
      "promoId": 977,
      "name": "Meet this week's featured positions!",
      "startDate": "2020-08-20T15:00:00+03",
      "endDate": "2020-08-27T21:00:00+03",
      "status": "completed"
    }
  ]
}

400: Bad Request Invalid request format. The response body contains the error description:

HTTP: 400

{
  "code": "REQUEST_PARAMS_ERROR",
  "details": "Invalid request parameters format"
}

​Response parameters:

Parameter	Type	Mandatory	Description
metadata	Object	Yes	Metadata object containing constraints specified in the request, as well as the total count of promos.
metadata.limit	Number	Yes	Number of items on the list.
metadata.offset	Number	Yes	List offset (number of dismissed items).
metadata.totalCount	Number	Yes	Total number of items.
metadata.activeOnly	Boolean	Yes	true — the list contains only active promos. false — the list contains all promos.
items	Array	Yes	Array of Item objects that contain promo details. Refer to API Objects for Item object description.

Get promo details by ID

GET https://api.cardsmobile.ru/promo/v1/details?promoId

This endpoint allows a partner to obtain complete details for a specified promo.

Query Parameters

Name	Type	Description
promoId*	number	Promo unique ID reference assigned by the Cardsmobile host upon promo creation.

200: OK The request is processed. The response body contains complete details for the requested promo:

HTTP: 200

{
  "promoId": 1010,
  "name": "Shop the BLACK WAY!",
  "startDate": "2020-09-01T00:00:00+03",
  "endDate": "2020-09-10T00:00:00+03",
  "status": "active",
  "images": {
    "imageWide": "https://promo.partner.com/wide.jpg",
    "imageSquare": "https://promo.partner.com/square.jpg"
  },
  "description": "<p>Black Friday is here to smash the prices!</p>\n<p>Get a good discount and shop the black way!</p>\n<p><a href=\"https://www.partner.com/promo/black-friday/?utm_source=crm&utm_medium=wallet&utm_content=promo&utm_campaign=261119_bf_wallet_w48\">See details</a></p>",
  "discount": "10",
  "source": "api"
}

400: Bad Request Invalid request format. The response body contains the error description:

HTTP: 400

{
  "code": "NO_EXPECTED_PARAMETERS",
  "details": "No expected parameters in the request"
}

HTTP: 400

{
  "code": "DATABASE_CONNECTION_ERROR",
  "details": "Error connecting to database"
}

422: Unprocessable Entity A business logic error. The response body contains the error description:

HTTP: 422

{
  "code": "PROMOID_NOT_FOUND",
  "details": "promoId not found"
}

Note that the request body is empty.

Response parameters:

Field	Type	Mandatory	Description
promoId	Number	Yes	Unique promo reference ID.
name	String	Yes	Promo title.
startDate	String	Yes	Promo start date in format: YYYY-MM-DDTHH:MM:SS+00
endDate	String	No	Promo end date in format: YYYY-MM-DDTHH:MM:SS+00 null: indefinite promo (for source = rmc).
status	String	Yes	Current promo state, based on promo start and end dates. Available promo states: active — the promo is ongoing; completed — the promo has ended; planned — the promo is scheduled, yet not started.
images	Object	Yes	Container for promo banners to display on the card presentation screen in the Koshelek app.
images.imageWide	String	Yes	URL to the promo large-sized banner (1080×420 pixels).
images.imageSquare		Yes	URL to the promo small-sized banner (600×600 pixels).
description	String	Yes	Promo description in HTML for displaying in the Koshelek app catalog.
discount	Number	Yes	Discount value for the promo to be displayed as a tag over promo banner. 0 — no discount.
source	String	Yes	Promo data download source: api — the download source is the Promo API. rmc — the download source is partner's Koshelek for Business account page.

Create new promo

POST https://api.cardsmobile.ru/promo/v1/create

This endpoint allows a partner to create a new promo.

Request Body

Name	Type	Description
name*	string	Promo title (max 255 characters).
startDate*	string	Promo start date in format: YYYY-MM-DDTHH:MM:SS+00.
endDate	string	Promo end date in format: YYYY-MM-DDTHH:MM:SS+00. For open-ended promos, omit this parameter or pass null in value.
images*	object	Container for promo banners to be displayed on the card presentation screen in the Koshelek app.
images.imageWide*	string	URL (max 1024 characters) to the promo large-sized banner (1080×420 pixels).
images.imageSquare*	string	URL (max 1024 characters) to the promo small-sized banner (600×600 pixels).
description*	string	Promo description (max 10 000 characters) in HTML for display in the Koshelek app catalog. Supported HTML tags: <a> <b> <br> <i> <ol>, <li> <ul>, <li> <p> <s> <u>
discount	number	Discount value for the promo: integer number from 1 to 100, displayed in the Koshelek app UI as a tag over promo banner. If there is no discount, you may omit this field or pass 0.

200: OK The request is processed. The response body contains the identifier and current status of the newly created promo:

HTTP: 200

{
  "promoId": 1020,
  "status": "planned"
}

400: Bad Request Invalid request format. The response body contains the error description:

HTTP: 400

{
  "code": "JSON_VALIDATION_ERROR",
  "details": "Invalid JSON request format"
}

HTTP: 400

{
  "code": "IMAGE_VALIDATION_ERROR",
  "details": "Image validation error"
}

HTTP: 400

{
  "code": "DATA_VALIDATION_ERROR",
  "details": "Data validation error"
}

Response parameters:

Field	Type	Mandatory	Description
promoId	Number	Yes	Unique promo reference ID.
status	String	Yes	Current promo state, based on promo start and end dates. Available promo states: active — the promo is ongoing; completed — the promo has ended; planned — the promo is scheduled, yet not started.

Update existing promo

POST https://api.cardsmobile.ru/promo/v1/update

This endpoint allows the partner to update existing promo metadata.

Request Body

Name	Type	Description
promoId*	string	Unique promo reference ID assigned by Cardsmobile host upon promo creation (cannot be modified).
name*	string	Promo title (max 255 characters).
startDate*	string	Promo start date in format: YYYY-MM-DDTHH:MM:SS+00.
endDate	string	Promo end date in format: YYYY-MM-DDTHH:MM:SS+00. For open end promos, omit this parameter or pass null in value.
images*	object	Container for promo banners to be displayed on the card presentation screen in the Koshelek app.
images.ImageWide*	string	URL (max 1024 characters) to the promo large-sized banner (1080×420 pixels).
images.imageSquare*	string	URL (max 1024 characters) to the promo small-sized banner (600×600 pixels).
description*	string	Promo description (max 10 000 characters) in HTML for display in the Koshelek app catalog. Supported HTML tags: <a> <b> <br> <i> <ol>, <li> <ul>, <li> <p> <s> <u>
discount	number	Discount value for the promo: integer number from 1 to 100, displayed in the Koshelek app UI as a tag over promo banner. If there is no discount, you may omit this field or pass 0.

200: OK The request is processed. The response body contains the identifier and current status of the updated promo:

HTTP: 200

{
  "promoId": 1020,
  "status": "planned"
}

400: Bad Request Invalid request format. The response body contains the error description:

HTTP: 400

{
  "code": "JSON_VALIDATION_ERROR",
  "details": "Invalid JSON request format"
}

HTTP: 400

{
  "code": "IMAGE_VALIDATION_ERROR",
  "details": "Image validation error"
}

HTTP: 400

{
  "code": "DATA_VALIDATION_ERROR",
  "details": "Data validation error"
}

422: Unprocessable Entity A business logic error. The response body contains the error description:

HTTP: 422

{
  "code": "PROMOID_NOT_FOUND",
  "details": "promoId not found"
}

​Response parameters:

Field	Type	Mandatory	Description
promoId	Number	Yes	Unique promo reference ID.
status	String	Yes	Current promo state, based on promo start and end dates. Available promo states: active — the promo is ongoing; completed — the promo has ended; planned — the promo is scheduled, yet not started.