Cardsmobile Place Info API

API синхронизации списка адресов

Общие сведения

Руководство предназначено для компаний-партнеров ООО «Бесконтакт», выпускающих карты лояльности своих клиентов в мобильном приложении «Кошелёк».

Интерфейс Cardsmobile Place Info API предназначен для передачи и обновления информации о точках обслуживания (магазинах, ресторанах), принимающих карты лояльности, выпущенные в Кошельке.

Подключение к API

Провайдером API выступает хост Cardsmobile. Партнеру передаются следующие параметры для подключения к API:

Параметры

Описание

host:port

Адрес и порт хоста Cardsmobile, предоставляющего API.

login:password

Имя пользователя и пароль для авторизации API-запросов.

offerId

Идентификатор партнерской программы лояльности в системе Cardsmobile; обязателен для указания в заголовках запросов к API.

Авторизация запросов

Взаимодействие осуществляется по протоколу HTTPS. Для авторизации запросов необходимо использовать HTTP Basic Authentication (RFC 7617). Данные для авторизации запросов передаются в заголовке "Authorization".

Требования к кодировкам

Как в запросах, так и в ответах используется кодировка UTF-8.

Коды ответов

В случае успешного выполнения запроса со стороны хоста Cardsmobile будет возвращен тип данных, описанный в документации запроса, и HTTP-код 200.

В случае ошибки обработки бизнес-сценария запроса будет возвращен HTTP-код 422 и строковое сообщение с описанием причины ошибки на русском языке в кодировке UTF-8.

Cardsmobile Place Info API

Синхронизация списка точек обслуживания представляет собой асинхронный процесс, выполняемый в рамках сессии:

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

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

/places/sync
Хост партнера отправляет хосту Cardsmobile полный список точек обслуживания. Список содержит информацию о каждой точке обслуживания (название, адрес, время работы, контактные и другие данные). Хост Cardsmobile принимает список в обработку и возвращает партнеру ID сессии синхронизации.
Request
Response
Headers
offerId
required
string
Идентификатор программы лояльности партнера в системе Cardsmobile
Body Parameters
places
required
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
Запрос статуса обработки списка

/places/sync/{sessionId}
Используя идентификатор sessionId, хост партнера периодически опрашивает хост Cardsmobile о текущем статусе обработки списка точек обслуживания. Статус "FINISHED" означает завершение сессии.
Request
Response
Path Parameters
sessionId
required
string
Идентификатор сессии синхронизации точек обслуживания
Headers
offerId
required
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 — в этом случае партнер должен считать, что данные точки не были добавлены/обновлены, и должен прислать корректные данные при очередной синхронизации.