Перейти к содержанию

Promo API v1.0.0

Promos for the Koshelek App users.

General information

The manual is intended for partner companies of Bescontact LLC that provide loyalty cards issuance in the Koshelek app using the Koshelek platform.

Promo API provides a partner with an interface for creating, distributing and updating nationwide promos for customers.

Interaction model

The API uses the RESTful model, all the data are transferred as JSON objects.

Partner and Koshelek interaction model

Connecting to API

Promo API is provided by the Koshelek host. The following request parameters are provided for a partner in order to get access:

Parameter Description
host:port Address and port of the Koshelek host providing the API.
login:password Username and password for API requests authorization.


The HTTPS protocol is used. HTTP Basic Authentication (RFC 7617) mechanism should be used for API requests authorization. Credentials for authorization are transferred in the Authorization HTTP header.


Both API requests and responses should use the UTF-8 encoding.

Message structure and format

1. Headers

All API requests expect the following in the request header:

Content-Type: application/json; charset=utf-8;

2. Image formats

Allowed format for images involved in API exchange: PNG or JPG. For image resolution requirements, refer to API requests documentation.

HTTP codes

If the request is successfully processed, the Koshelek host returns an HTTP response containing the status code 200, and the body with a payload described in the request documentation.

HTTP code Description
200 OK API request is successfully processed.

If an error occurred during the request processing, the host returns an HTTP response containing one of the status codes from the table below, and the error description as a JSON object in the body (the UTF-8 encoding is used):

HTTP Code Description
400 Bad Request Invalid request format/structure.
401 Unauthorized Request authorization error.
403 Forbidden Request authentication error (lack of rights to perform the request).
422 Unprocessable Entity Business scenario processing error.
500 Internal Server Error Problems on Koshelek server.

For any of the 4XX error codes described above, the response body contains a JSON object with fields code and details:

    "code": "string",
    "details": "string"
Parameter Description
code Error code. Does not match HTTP status code. Human readable message in UPPER_SNAKE_CASE.
details Error description in English. Not intended for display in UI.