Cardsmobile Check-In API

API гео-регистрации мобильных карт лояльности

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

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

Сервис Cardsmobile Check-In реализует сценарий гео-регистрации (check-in) мобильной карты лояльности клиента при ее предъявлении в точке обслуживания торгово-сервисной сети партнера.

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

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

Параметры

Описание

host:port

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

login:password

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

offerId

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

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

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

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

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

Коды ответов API

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

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

Cardsmobile Check-In API

На диаграмме продемонстрирован сценарий жизненного цикла чек-ина посетителя в точке обслуживания (ресторане, магазине) партнера, с использованием Cardsmobile Check-In API.

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

get
Запрос списка активных чек-инов

/partner/api/place/{placeId}/checkins
Хост партнера запрашивает у Cardsmobile список чек-инов, активных в данный момент, и возвращает актуальный список на экран кассового ПО.
Request
Response
Path Parameters
placeId
required
string
Идентификатор точки обслуживания, для которой выполняется запрос
Headers
offerId
required
string
Идентификатор программы лояльности партнера в системе CardsMobile
200: OK
Ответ содержит массив текущих активных чек-инов и соответствующих им карт лояльности:
[
{"secretCode": "5533", "checkinNumber": 1024, "cardNumber": "000000111001"},
{"secretCode": "8387", "checkinNumber": 1025, "cardNumber": "000000111002"},
{"secretCode": "0022", "checkinNumber": 1026, "cardNumber": "000000111003"}
]
422: Unprocessable Entity

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

Параметр

Тип

Значение

secretCode

string

Секретный код чек-ина (4 цифры)

checkinNumber

string

Идентификатор чек-ина

cardNumber

string

Номер карты лояльности в информационной системе партнера

post
Регистрация использованного чек-ина

/partner/api/checkin/register
Запрос на погашение активного чек-ина.
Request
Response
Headers
offerId
required
string
Идентификатор программы лояльности партнера в системе Cardsmobile
Body Parameters
checkinNumber
required
string
Идентификатор чек-ина
200: OK
В случае успеха хост Cardsmobile вернет HTTP-код 200 с пустым телом ответа:
422: Unprocessable Entity

При добавлении к заказу карты лояльности, прошедшей чек-ин, кассовое ПО партнера должно инициировать деактивацию чек-ина; запрос на деактивацию должен быть передан на хост Cardsmobile.

Пример тела запроса:

{"checkinNumber": 1025}

После деактивации чек-ин будет отсутствовать в списке, получаемом в ответ на Запрос списка активных чек-инов. Чтобы совершить очередную покупку (заказ) с картой лояльности, пользователю потребуется выполнить новый чек-ин.