Cardsmobile Place Info API
Руководство предназначено для компаний-партнеров ООО «Бесконтакт», выпускающих карты лояльности своих клиентов в мобильном приложении «Кошелёк».
Интерфейс Cardsmobile Place Info 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.
Синхронизация списка точек обслуживания представляет собой асинхронный процесс, выполняемый в рамках сессии:
postCинхронизация списка точек обслуживания
{"sessionId": "string"}
Структура тела запроса:
{"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Запрос статуса обработки списка
sessionId, хост партнера периодически опрашивает хост Cardsmobile о текущем статусе обработки списка точек обслуживания. Статус "FINISHED" означает завершение сессии.{"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" // описание ошибки}]}
С какой периодичностью проверять статус обработки?
Окончанию обработки соответствует статус "FINISHED". В среднем, обработка списка занимает около минуты. В целом, длительность обработки зависит от объема списка и количества изменений.
О позициях, содержащих ошибки:
В финальном ответе ("status": "FINISHED") все обнаруженные ошибки обработки, в случае их наличия, будут переданы в массиве "errors". Данные о точке обслуживания, содержащие ошибки, отбраковываются сервисом Cardsmobile — в этом случае партнер должен считать, что данные точки не были добавлены/обновлены, и должен прислать корректные данные при очередной синхронизации.