Main API Requests

Loyalty cards issuance and maintenance

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/

Search a Loyalty Card on User's Profile Data

GET https://<base-URL>/v1/card

A Koshelek app user and a customer's loyalty card are corresponding as "one-to-one" and are presented as a single entity.

If the partner's loyalty program allows one customer to own several loyalty cards (active or not), the partner should define logic of selection of loyalty cards accessible for the user to issue in the Koshelek app.

Query Parameters

Name	Type	Description
msisdn	string	Mobile phone number without the + prefix. Not more than 15 digits; starts at country code (1-3 digits)
email	string	User's email address
birthDate	string	User's date of birth (YYYY-MM-DD format)

200: OK The request is processed. The response body contains information on a loyalty card that meets search conditions. The response body is empty, if such loyalty card is not found:

A. Card found:

{
   "card": { // user's loyalty card
      "cardNumber": "", // card number in partner's CRM
      "cardState" : "", // status of the card ("active" / "inactive")
      "barcode": { // barcode of the card
         "barcodeNumber": "", // barcode number
         "barcodeType": ""    // barcode type ("EAN_8" / "EAN_13" / "CODE_128" / "UPC_A" / "QR_CODE")
    }
  }
}

B. Card not found:

422: Unprocessable Entity An error occurred. The response body contains information on the error (code and description):

{
  "code": "123",
  "description": "DBMS server is not available"
}

Example of the request:

GET /v1/card?msisdn=79216668899&email=[e-mail]&birthDate=1990-01-01

Request processing rules

• Search parameters are combined by Boolean OR operator.

• Search parameters unknown to the partner must be ignored.

• If search parameters return several loyalty cards, the conflict must be resolved on partner's side. It is possible to return an error; in this case the Koshelek app will recommend that a user contact partner's customer service.

• If search parameters return blocked loyalty card and the partner forbids issuing a card (new one or with user-specified number) under this condition, the response must be error 422: Unprocessable Entity instead of the blocked card data.

Update List of Communication Channels Allowed by the User

PUT https://<base-URL>/v1/card/{cardNumber}/communication

The request is transmitted during issuance of a loyalty card (the user selects allowed communication ways on the Koshelek app screen). Possible values (call, email, sms, etc.) are transmitted in an array field.

Path Parameters

Name	Type	Description
cardNumber*	string	Loyalty card number

Request Body

Name	Type	Description
allow*	array	Allowed communication channels
deny*	array	Denied communication channels

200: OK The request is processed. The response body is empty:

422: Unprocessable Entity An error occurred. The response body contains information on the error (code and description):

{
  "code": "123",
  "description": "DBMS server is not available"
}

Example of the request:

PUT /v1/card/2337658900/communication

{
   "allow": [ // allowed channels
      "sms",
      "email"
   ],
   "deny": [ // denied channels
      "call"
   ]
}

Update Customer Personal Data

POST https://<base-URL>/v1/card/{cardNumber}

Transfer the changed personal data of a user owning the loyalty card to the partner. Usually, when a card is issued in the Koshelek app, the following field values are transmitted: phone, email, surname, firstname, sex, birthDate.

Path Parameters

Name	Type	Description
cardNumber*	string	Loyalty card number

Request Body

Name	Type	Description
phone	string	Mobile phone number without the + prefix
email	string	Email address
surname	string	Surname
firstname	string	Name
sex	string	Sex ("m" or "f")
birthDate	string	Date of birth (YYYY-MM-DD format is used)
patronymic	string	Patronymic
locality	string	Name of location (city) at the time of issuing the card
countryCode	string	ISO code of the country at the time of issuing the card (ISO 3166-1 alpha-2)
additionalParameters	array	Array of additional parameters used for the card issuing (each parameter as a JSON object AdditionalParameter)

200: OK The request is processed. The response body is empty:

422: Unprocessable Entity An error occurred. The response body contains information on the error (code and description):

{
  "code": "123",
  "description": "DBMS server is not available"
}

Transferring additional parameters

Additional parameters, if available, are transmitted as an array of JSON objects AdditionalParameter. The object consists of the following fields:

Field	Type	Mandatory	Description
paramName	String	Yes	Parameter name
values	Object[]	Yes	Parameter values. Array of objects as follows: { "name": String, "value": String }

Example of the request:

POST /v1/card/2337658900

{
   "phone" : "71111111111",
   "email" : "user@domain",
   "surname": "Johnson",
   "firstname": "John",
   "sex": "m",
   "birthDate": "1990-01-01"
}

This request should be expected:

• During the card issuing scenario, if the card number was found in partner's database (see Search a loyalty card on user's profile data).

• After the card issuing, when user updates their personal data in the Koshelek app profile (in this case the request contains changed data only).

If card issuance requires any additional parameters beside personal data, these additional data is sent in the additionalParameters array of objects (one object per one additional parameter). List and format of such parameters are pre-agreed with Cardsmobile.

Issue a Card with the User-Specified Number

POST https://<base-URL>/v1/card/provided/{cardNumber}

To issue a card, user's personal data is transmitted to the partner. Usually the following field values are transmitted: phone, email, surname, firstname, sex, birthDate.

Path Parameters

Name	Type	Description
cardNumber*	string	User-specified card number

Request Body

Name	Type	Description
phone	string	Mobile phone number without the + prefix
email	string	Email address
surname	string	Surname
firstname	string	Name
sex	string	Sex ("m" or "f")
birthDate	string	Date of birth (YYYY-MM-DD format is used)
patronymic	string	Patronymic
locality	string	Name of location (city) at the time of issuing the card
countryCode	string	ISO code of the country at the time of issuing the card (ISO 3166-1 alpha-2)
additionalParameters	array	Array of additional parameters used for the card issuing (each parameter as a JSON object AdditionalParameter)

200: OK The request is processed. The response body is empty:

422: Unprocessable Entity An error occurred. The response body contains information on the error (code and description):

{
  "code": "123",
  "description": "DBMS server is not available"
}

Example of the request:

POST /v1/card/provided/2337658900

{
   "phone" : "71111111111",
   "email" : "user@domain",
   "surname": "Johnson",
   "firstname": "John",
   "sex": "m",
   "birthDate": "1990-01-01"
}

• The card number is used in the request as it is specified by the user, without any validation on the Cardsmobile side. It is expected that if such card does not exist in the system or it is non-anonymous (i.e. related to another user) or blocked, an error is returned.

• If card issuance requires any additional parameters beside personal data, this additional data is sent in the additionalParameters array of objects (one object for one additional parameter). List and format of such parameters are pre-agreed with Cardsmobile.

Reserve New Anonymous Card

GET https://<base-URL>/v1/card/anonymous

Requesting a partner to reserve a new loyalty card that is not associated with any customer of the loyalty program. The reservation starts in case if the loyalty card with user's personal data was not found (i.e. the user is not a customer of the loyalty program). After this request, partner's side should wait the request for issuing a loyalty card with the reserved number of an anonymous card (below).

200: OK The request is processed. The response body contains the reserved card number:

2337658900

422: Unprocessable Entity An error occurred. The response body contains information on the error (code and description):

{
  "code": "123",
  "description": "DBMS server is not available"
}

Example of the request:

GET /v1/card/anonymous

Request processing rule

Implementation on partner's side must guarantee that the returned card number will stay reserved (not available for re-usage) at least for one hour.

Issue a Card by Pre-Reserved Number of Anonymous Card

POST https://<base-URL>/v1/card/anonymous/{cardNumber}

This requests contains the pre-reserved number of an anonymous card received in answer to the request above. To issue a card, user's personal data is transmitted to the partner. Usually the following field values are transmitted: phone, email, surname, firstname, sex, birthDate.

Path Parameters

Name	Type	Description
cardNumber*	string	Reserved number of anonymous card

Request Body

Name	Type	Description
phone	string	Mobile phone number without the + prefix
email	string	Email address
surname	string	Surname
firstname	string	Name
sex	string	Sex ("m" or "f")
birthDate	string	Date of birth (YYYY-MM-DD format is used)
patronymic	string	Patronymic
locality	string	Name of location (city) at the time of issuing the card
countryCode	string	ISO code of the country at the time of issuing the card (ISO 3166-1 alpha-2)
additionalParameters	array	Array of additional parameters used for the card issuing (each parameter as a JSON object AdditionalParameter)

200: OK The request is processed. The response body is empty:

422: Unprocessable Entity A error occurred. The response body contains information on the error (code and description):

{
  "code": "123",
  "description": "DBMS server is not available"
}

Example of the request:

POST /v1/card/anonymous/2337658900

{
   "phone" : "71111111111",
   "email" : "user@domain",
   "surname": "Johnson",
   "firstname": "John",
   "sex": "m",
   "birthDate": "1990-01-01"
}

If card issuance requires any additional parameters beside personal data, this additional data is sent in the additionalParameters array of objects (one object for one additional parameter). List and format of such parameters are previously agreed with Cardsmobile.

Request processing rule

Information on the card balance must be available right after the card is assigned to a user.

Get Loyalty Card Information by Number

GET https://<base-URL>/v1/card/{cardNumber}

The request is used to get information on balance and status of the card by its number. The information is requested when issuing the card as well as when requesting its balance. Returned data are transmitted to a balance screen of the user's card in the Koshelek app.

Path Parameters

Name	Type	Description
cardNumber*	string	Loyalty card number

200: OK The request is processed. The response body contains full information on the current status of the loyalty card (fields that are not used in the partner's loyalty program must also be presented with empty values):

{
   "card": {   // customer's loyalty card
      "cardNumber": "",  // card number
      "cardState" : "",  // status of the card ("active" / "inactive")
      "barcode": {   // barcode of the card
         "barcodeNumber": "", // barcode number
         "barcodeType": ""    // barcode type ("EAN_8" / "EAN_13" / "CODE_128" / "UPC_A" / "QR_CODE")
      },
      "status": {    // current level of the card
         "discountPercent": "",     // discount percent (number)
         "cardType": "",            // card level name (golden, silver, etc.)
         "totalPurchaseAmount": "", // total purchase amount for the card (number)
         "statusConfirmAmount": ""  // how the purchase amount should be reached to confirm the current level (number)
      },
      "nextStatus": {  // next level of the card
         "discountPercent": "",    // discount percent (number)
         "cardType": "",           // card level name
         "totalPurchaseAmount": "" // how the purchase amount should be reached to get the level (number)
      },
      "bonus": {       // bonuses on the card
         "total": "",     // total of bonuses (number)
         "available": "", // accessible bonuses (number)
         "bonuses": [     // bonuses description
           {
             "description": "", // bonus description
             "amount": "",      // bonus amount (number)
             "validUntil": ""   // bonus validity date
           }
         ]
      }  
   }
}

422: Unprocessable Entity An error occurred. The response body contains information on the error (code and description):

{
  "code": "123",
  "description": "DBMS server is not available"
}

Example of the request:

GET /v1/card/2337658900

Example of a response containing data on an existing loyalty card:

{
   "card": {
      "cardNumber": "65046476",
      "cardState": "active",
      "barcode": {
         "barcodeNumber": "0000660277088",
         "barcodeType": "EAN_13"
      },
      "status": {
         "discountPercent": "10",
         "cardType": "default",
         "totalPurchaseAmount": "200",
         "statusConfirmAmount": "0"
      },
      "nextStatus": {
         "discountPercent": "20",
         "cardType": "next_status",
         "totalPurchaseAmount": "2000"
      },
      "bonus": {
         "total": "0",
         "available": "0",
         "bonuses": [
           {
             "description": "Bonus #1",
             "amount": "100",
             "validUntil": "2019-12-01"
           },
           {
             "description": "Bonus #2",
             "amount": "10",
             "validUntil": "2019-12-12"
           },
           {
             "description": "Bonus #3",
             "amount": "1",
             "validUntil": "2019-10-29"
           }
         ]
      }
   }
}

Please note:

1. The fields listed below should contain a string presentation of numbers (both integers and numbers with a fractional part are allowed):

   • discountPercent, totalPurchaseAmount, statusConfirmAmount (status object);

   • discountPercent, totalPurchaseAmount (nextStatus object);

   • total, available, bonuses[].amount (bonus object).

2. Thebonuses[].validUntil field (bonus object) should contain a date in the format YYYY-MM-DD.

Request Purchase History by Card Number for Specified Period

GET https://<base-URL>/v1/card/{cardNumber}/purchases

The request contains the start and end dates of the period are received from the Koshelek app.

Path Parameters

Name	Type	Description
cardNumber*	string	Loyalty card number
startDate*	string	Beginning of the period, YYYY-MM-DD
endDate	string	End of the period, YYYY-MM-DD. Can be absent, in this case end of period equals the current date

200: OK The request is processed. The response body contains information on purchases for the specified period, or an empty array, if there are no purchases for the period:

A. List of purchases for the period:

[
   {
      "date": "",     // purchase date YYYY-MM-DD
      "item": "",     // product name
      "amount": "",   // product price in kopeks (signed number; negative is purchase refund)
      "quantity": "", // product items count (number)
      "location": "", // purchase location
      "bonuses": ""   // added ('+') and subtracted ('-') bonuses (numbers)
   }
]

B. There is no purchases:

[]

422: Unprocessable Entity An error occurred. The response body contains information on the error (code and description):

{
  "code": "123",
  "description": "DBMS server is not available"
}

Example of the request:

GET /v1/card/2337658900/purchases?startDate=2019-01-01

Please note:

• The response fields amount, quantity and bonuses should contain a string representation of the number (both integers and the fractional part are allowed).

• The response fields date, item, amount and quantity are mandatory (empty values are not allowed).

• The response fields location and bonuses can contain empty values (for example, if they are not supported by the loyalty program).

Request Special Promotional Offers by Card Number

GET https://<base-URL>/v1/card/{cardNumber}/specials

The request is called when a user activates the screen of the issued loyalty card. The request allows the Koshelek app to receive and display a list of special promotional offers of the loyalty program operator that are available for the loyalty card owners.

Path Parameters

Name	Type	Description
cardNumber*	string	Loyalty card number

200: OK The request is processed. The response body contains information on all offers (promotional actions) available for the specified card as an array. If there no offers (promotional actions) for the card, an empty array is returned:

A. List of offers for the card:

[
    {  // information on offer
        "id": "",            // offer ID
        "name": "",          // offer title (not great than 40 characters recommended)
        "startDate": "",     // offer start date ("YYYY-MM-DD")
        "endDate": "",       // offer end date ("YYYY-MM-DD")
        "description": "",   // offer description (not great than 500 characters recommended, HTML tags allowed)
        "barcodeNumber": "", // barcode number
        "barcodeType": "",   // barcode type ("EAN_8" / "EAN_13" / "CODE_128" / "UPC_A" / "QR_CODE")
        "assets": {  // presentation of the offer
           "imageUrl": "",     // image (direct link to 600x600px image. Mandatory)
           "imageLargeUrl": "" // additional image (banner). Direct link to 1080х420px image. Optional
        }
    }
    // similar objects {...} in the array for the other offers (comma-separated)
]

B. There are no offers:

[]

422: Unprocessable Entity An error occurred. The response body contains information on the error (code and description):

{
  "code": "123",
  "description": "DBMS server is not available"
}

Example of the request:

GET /v1/card/2337658900/specials

Response requirements:

• startDate, endDate fields: on the Cardsmobile server side, it is expected that the start and end dates of the promotion will be formed by the partner depending on the region where the client is present at the time of the card issuance (transmitted in the locality field — see the issuance scenarios) and using the corresponding time zone.

• description field: detailed description of the offer can contain subset of HTML tags to format and markup the description:

HTML tag	Text formatting
b, strong	Bold
i, em, cite, dfn	Italic
u	Underline
sub	Subscript
sup	Superscript
big	Big size
small	Small size
tt	Monospace
h1, ..., h6	Heading of level 1 — 6
img	Image
font	Font settings (family, size, color)
blockquote	Quote block
a	Link
div, p	Paragraph
br	Line break

Example of a response containing data on special promotional offers:

[
    {
        "id": "1",
        "startDate": "2019-09-09",
        "endDate": "2019-09-15",
        "name": "SALE 50%",
        "description": "The discount is provided by the promotional code 'SALE50'. <br>Promotion is valid for the purchase of goods in the store from 09 to 15 September.",
        "barcodeNumber": "123456789",
        "barcodeType": "EAN_13",
        "assets": {
           "imageUrl": "https://partnerresource/image1.jpg",
           "imageLargeUrl": "https://partnerresource/image2.jpg"
        }
    },
    {
        "id": "2",
        "startDate": "2019-09-09",
        "endDate": "2019-09-15",
        "name": "SALE 70%",
        "description": "The discount is provided by the promotional code 'SALE70'. <br>Promotion is valid for the purchase of goods in the store from 09 to 15 September.",
        "barcodeNumber": "987654321",
        "barcodeType": "EAN_13",
        "assets": {
           "imageUrl": "https://partnerresource/image1.jpg",
           "imageLargeUrl": "https://partnerresource/image2.jpg"
        }
    }
 ]