API Requests

For service point list synchronization

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/

Send List of Service Points

POST https://<base-URL>/places/sync

Partner's host prepares and sends a full list of service points to the Cardsmobile host. The list contains information on each service point (name or title, address, working hours, contact data, etc.). The Cardsmobile host receives the list for processing and returns an ID of the synchronization session.

Headers

Name	Type	Description
offerId*	string	ID of a loyalty program in the Cardsmobile platform

Request Body

Name	Type	Description
places*	array	Service point list

200: OK The request is processed. The response contains an ID of the synchronization session that has begun:

{
  "sessionId": "string"
}

422: Unprocessable Entity An error occurred. Response body contains an error message

Structure of the request body:

{
  "places": [ // service point list
    {
      "itemId": "string", // partner's ID of the service point
      "placeInfo": { // service point info
         "name": "string",    // name or title
         "address": "string", // address
         "phones": [          // phone list
           {
             "type": "string",
             "number": "string"
           }
         ],
         "schedule": "string", // operation schedule
         "metroStations": [    // nearest metro station
           "string"
         ],
         "type": "string",     // service point type
         "geoPoint": {         // geo coordinates
            "lat": 0,  // latitude
            "lng": 0   // longitude
         }
      }
    }
  ]
}

• Theaddressfield is mandatory.

• Where applicable, text data must be transferred in Russian using the UTF-8 encoding.

Response Parameters

If the Cardsmobile host returns an ID of the synchronization session (thesessionId field), it means that processing of the transferred list has begun.

Get Status of List Processing

GET https://<base-URL>/places/sync/{sessionId}

Partner's host uses the sessionId value to address the Cardsmobile host periodically in order to determine the current processing status of the sent service point list. If the FINISHED status is received, the synchronization session is completed.

Path Parameters

Name	Type	Description
sessionId*	string	ID of the synchronization session

Headers

Name	Type	Description
offerId*	string	ID of a loyalty program in the Cardsmobile platform

200: OK The request is processed. Response body contains the current status of the list processing:

{
  "sessionId": "string", // ID of the synchronization session
  "status": "FINISHED",  // current session status: "PROCESSING" or "FINISHED"
  "errors": [ // when processing is finished, the array contains unprocessed service points
    {
      "place": {
        "itemId": "string",
        "placeInfo": {
          "name": "string",
          "address": "string",
          "phones": [
            {
              "type": "string",
              "number": "string"
            }
          ],
          "schedule": "string",
          "metroStations": [
            "string"
          ],
          "type": "string",
          "geoPoint": {
            "lat": 0,
            "lng": 0
          }
        }
      },
      "description": "string" // error description
    }
  ]
}

422: Unprocessable Entity An error occurred. Response body contains an error message

How often to check the processing status?

The FINISHED status means that the processing is finished. In average, list processing takes about a minute. In general, the processing time depends on the size of the list and the number of changes made.

On unprocessed list items:

In the final response ("status": "FINISHED"), all the detected processing errors, if any, will be transmitted in the errors array. Data on the service point containing errors is rejected by the Cardsmobile host. In this case, the partner must consider that these points were not added (updated), and must send correct data during the next synchronization.