Запросы API

Для синхронизации списка точек обслуживания

Документация перемещена

Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:

https://developers.koshelek.app

Cинхронизация списка точек обслуживания

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

Узел партнера отправляет узлу Cardsmobile полный список точек обслуживания. Список содержит информацию о каждой точке обслуживания (название, адрес, время работы, контактные и другие данные). Узел Cardsmobile принимает список в обработку и возвращает партнеру ID сессии синхронизации.

Headers

Name	Type	Description
offerId*	string	Идентификатор программы лояльности партнера в системе Cardsmobile

Request Body

Name	Type	Description
places*	array	Список точек обслуживания

200: OK Запрос обработан. В ответе узел Cardsmobile вернет идентификатор сессии синхронизации:

{
  "sessionId": "string"
}

422: Unprocessable Entity Ошибка обработки запроса. Ответ содержит сообщение об ошибке

Структура тела запроса:

{
  "places": [ // список точек обслуживания
    {
      "itemId": "string", // идентификатор точки обслуживания в информационной системе партнера
      "placeInfo": { // информация о точке обслуживания
         "name": "string", // название точки обслуживания
         "address": "string", // адрес точки обслуживания
         "phones": [ // телефон(ы) точки обслуживания
           {
             "type": "string",
             "number": "string"
           }
         ],
         "schedule": "string", // режим работы
         "metroStations": [ // ближайшие станции метро
           "string"
         ],
         "type": "string", // тип точки обслуживания
         "geoPoint": { // координаты точки обслуживания
            "lat": 0, // географическая широта
            "lng": 0 // географическая долгота
         }
      }
    }
  ]
}

• Поле address является обязательным.

• Где применимо, текстовые данные должны передаваться на русском языке в кодировке UTF-8.

Параметры ответа

Узел Cardsmobile в ответе вернет партнеру идентификатор сессии синхронизации sessionId — это означает, что обработка переданного партнером списка началась.

Запрос статуса обработки списка

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

Используя идентификатор sessionId, узел партнера периодически опрашивает узел Cardsmobile о текущем статусе обработки списка точек обслуживания. Статус «FINISHED» означает завершение сессии.

Path Parameters

Name	Type	Description
sessionId*	string	Идентификатор сессии синхронизации точек обслуживания

Headers

Name	Type	Description
offerId*	string	Идентификатор программы лояльности партнера в системе Cardsmobile

200: OK Запрос обработан. В ответе узел Cardsmobile вернет текущий статус обработки списка:

{
  "sessionId": "string", // идентификатор сессии синхронизации
  "status": "FINISHED", // статус обработки: "PROCESSING" или "FINISHED"
  "errors": [ // по окончании обработки, здесь будут перечислены позиции, содержащие ошибки
    {
      "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" // описание ошибки
    }
  ]
}

422: Unprocessable Entity Ошибка обработки запроса. Ответ содержит сообщение об ошибке

С какой периодичностью проверять статус обработки?

Окончанию обработки соответствует статус FINISHED. В среднем обработка списка занимает около минуты. Общая длительность обработки зависит от объема списка и количества изменений.

О позициях, содержащих ошибки:

В финальном ответе ("status": "FINISHED") все обнаруженные ошибки обработки в случае их наличия будут переданы в массиве errors. Данные о точке обслуживания, содержащие ошибки, отбраковываются сервисом Cardsmobile — в этом случае партнер должен считать, что данные точки не были добавлены/обновлены, и должен прислать корректные данные при очередной синхронизации.