Перейти к содержанию

Loyalty Online API v1.2.0

API для выпуска и обслуживания карт лояльности в Кошельке.


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

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

Loyalty Online API реализует базовый набор пользовательских сценариев жизненного цикла карты лояльности в Кошельке.

Изменения: Loyalty API v1.1.0 → v1.2.0

  • Добавлен метод POST /v1/card/anonymous для выпуска карты лояльности без предварительного резервирования номера карты.

Демонстрационная зона API

Демо-зона для тестирования сценариев Loyalty Online API расположена по адресу:

https://cmapi-selftest.cardsmobile.ru/

Реализация API-сервиса на стороне партнёра

Веб-сервис, реализующий Loyalty Online API, развёртывается на узле партнёра и интегрируется с его информационной системой в соответствии с документацией Koshelek Developers. Для обмена сообщениями используется стандартная модель RESTful, данные передаются в формате JSON по протоколу HTTPS:

Loyalty Online API ru

Поскольку веб-сервис, реализующий API, разворачивается на узле партнёра, необходимо предоставить Кошельку следующие данные для интеграции:

Параметр Описание
host:port URL узла партнёра, предоставляющего API.
login:password Имя пользователя и пароль для авторизации API-запросов со стороны Кошелька.

Авторизация

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

Кодировки

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

Структура сообщений

1. Заголовки

Ответ со стороны партнёра должен содержать заголовок:

HTTP
Content-Type: application/json; charset=utf-8;

2. Тело ответа

Тело ответа со стороны партнёра должно соответствовать требованию к ответу, указанному в документации к запросу.

Коды HTTP

Коды HTTP-ответов со стороны партнёра:

Код Назначение
200 Возвращается в случае успешного выполнения запроса API.
422 Возвращается в случае любой ошибки выполнения запроса.

Ошибки

В случае ошибки обработки запроса необходимо вернуть JSON-объект, содержащий код ошибки и строковое сообщение с техническим описанием причины ошибки на русском языке.

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

HTTP
HTTP/1.1 422 Unprocessable Entity
<заголовки>

{
    "code": "123",
    "description": "Недоступен сервер баз данных"
}

Обратите внимание:

API предполагает, что все «элементарные» поля объектов JSON, возвращаемых в ответах, имеют строковый тип (string), даже если они содержат значения других типов (числовой, логический и т.п.).

См. пример возврата числового кода ошибки выше.