Основные запросы API
Выпуск и обслуживание карт лояльности
Документация перемещена
Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:
Поиск карты лояльности по данным профиля пользователя
GET
https://<base-URL>/v1/card
Пользователь приложения «Кошелёк» и карта лояльности клиента соотносятся как «один-к-одному» и представляют собой единую сущность.
Если программа лояльности партнера допускает наличие нескольких карт лояльности (активных или нет) у одного пользователя, то логика выбора карт, доступных пользователю для выпуска в Кошельке, реализуется на стороне партнера.
Query Parameters
Name | Type | Description |
---|---|---|
msisdn | string | Номер телефона пользователя без префикса |
string | Адрес электронной почты пользователя | |
birthDate | string | Дата рождения пользователя в формате YYYY-MM-DD |
Пример запроса:
Правила обработки запроса
Параметры поиска комбинируются по условию логического оператора ИЛИ.
Неизвестные партнеру условия поиска должны игнорироваться.
Если условиям поиска соответствует несколько различных карт лояльности, разрешение конфликта происходит на стороне партнера. Допускается вернуть ошибку; в этом случае пользователю будет рекомендовано обратиться в службу поддержки партнера.
Если переданным условиям поиска соответствует заблокированная карта и при наличии заблокированной карты партнер запрещает выпуск карты (новой или с номером, указанным пользователем), то в ответ на этот запрос необходимо вместо данных заблокированной карты возвращать ошибку
422: Unprocessable Entity
.
Обновление разрешенных пользователем каналов коммуникации
PUT
https://<base-URL>/v1/card/{cardNumber}/communication
Запрос передается при выпуске карты (пользователь выбирает способы коммуникации на экране Кошелька). Возможные значения (call, email, sms) передаются внутри массива.
Path Parameters
Name | Type | Description |
---|---|---|
cardNumber* | string | Номер карты лояльности |
Request Body
Name | Type | Description |
---|---|---|
allow* | array | Разрешенные каналы коммуникации |
deny* | array | Запрет на коммуникацию с использованием указанных каналов связи (отписка пользователя) |
Пример запроса:
Обновление персональных данных пользователя
POST
https://<base-URL>/v1/card/{cardNumber}
Передача партнеру изменений персональных данных пользователя, владеющего картой лояльности. Как правило, при выпуске карты в теле сообщения всегда передаются значения полей: phone
, email
, surname
, firstname
, sex
, birthDate
.
Path Parameters
Name | Type | Description |
---|---|---|
cardNumber* | string | Номер карты лояльности |
Request Body
Name | Type | Description |
---|---|---|
phone | string | Номер телефона без префикса |
string | Адрес электронной почты | |
surname | string | Фамилия |
firstname | string | Имя |
sex | string | Пол («м» или «ж») |
birthDate | string | Дата рождения в формате YYYY-MM-DD |
patronymic | string | Отчество |
locality | string | Название населенного пункта пребывания на момент выпуска карты |
countryCode | string | ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2) |
additionalParameters | array | Массив JSON-объектов AdditionalParameter с дополнительными параметрами, требуемыми для выпуска карты |
Передача дополнительных параметров
Дополнительные параметры запроса передаются в виде массива JSON-объектов AdditionalParameter. Этот объект имеет следующие поля:
Поле | Тип | Обазятельное | Описание |
---|---|---|---|
| String | Да | Имя параметра |
| Object[] | Да | Значения параметра. Массив объектов вида
|
Пример запроса:
Этот запрос следует ожидать:
В ходе сценария выпуска карты — если номер карты был найден в базе данных партнера (см. Поиск карты лояльности по данным профиля пользователя).
После выпуска карты — при обновлении пользователем данных своего профиля в Кошельке (в запросе будут переданы только измененные персональные данные).
Если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных, они будут переданы в массиве объектов additionalParameters
(по одному объекту на каждый параметр). Перечень и формат представления таких параметров предварительно согласуется с Cardsmobile.
Выпуск карты с номером, указанным пользователем
POST
https://<base-URL>/v1/card/provided/{cardNumber}
Для выпуска происходит передача партнеру персональных данных пользователя. Как правило, в теле сообщения всегда передаются значения следующих полей: phone
, email
, surname
, firstname
, sex
, birthDate
.
Path Parameters
Name | Type | Description |
---|---|---|
cardNumber* | string | Номер карты, указанный пользователем |
Request Body
Name | Type | Description |
---|---|---|
phone | string | Номер телефона без префикса |
string | Адрес электронной почты | |
surname | string | Фамилия |
firstname | string | Имя |
sex | string | Пол («м» или «ж») |
birthDate | string | Дата рождения в формате YYYY-MM-DD |
patronymic | string | Отчество |
locality | string | Название населенного пункта пребывания на момент выпуска карты |
countryCode | string | ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2) |
additionalParameters | array | Массив JSON-объектов AdditionalParameter с дополнительными параметрами, требуемыми для выпуска карты |
Пример запроса:
Номер карты, использующийся в запросе, сообщается пользователем приложения и никак не проверяется на стороне Cardsmobile. Если такой карты не существует в системе партнера, либо если она не анонимна (т.е. привязана к другому пользователю), или заблокирована, то возвращается ошибка.
Если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных, они будут переданы в массиве объектов
additionalParameters
(по одному объекту на каждый параметр). Перечень и формат представления таких параметров предварительно согласуется с Cardsmobile.
Резервирование новой анонимной карты
GET
https://<base-URL>/v1/card/anonymous
Запрос у партнера номера новой карты лояльности, не привязанной ни к одному клиенту программы лояльности.
Резервирование происходит в случае, если поиск карты по данным профиля пользователя не принес результатов (пользователь не является клиентом программы лояльности). Вслед за этим запросом стоит ожидать запрос на выпуск по номеру ранее зарезервированной анонимной карты (ниже).
Пример запроса:
Правило обработки запроса
Реализация системы со стороны партнера должна гарантировать, что выданный номер карты будет зарезервирован (недоступен для повторного использования) в течение часа.
Выпуск карты по номеру ранее зарезервированной анонимной карты
POST
https://<base-URL>/v1/card/anonymous/{cardNumber}
В этот запрос передается номер анонимной карты, предварительно полученный запросом резервирования новой анонимной карты. Для выпуска происходит передача партнеру персональных данных пользователя. Как правило, в теле сообщения всегда передаются значения следующих полей: phone
, email
, surname
, firstname
, sex
, birthDate
.
Path Parameters
Name | Type | Description |
---|---|---|
cardNumber* | string | Зарезервированный номер анонимной карты |
Request Body
Name | Type | Description |
---|---|---|
phone | string | Номер телефона без префикса |
string | Адрес электронной почты | |
surname | string | Фамилия |
firstname | string | Имя |
sex | string | Пол («м» или «ж») |
birthDate | string | Дата рождения в формате YYYY-MM-DD |
patronymic | string | Отчество |
locality | string | Название населенного пункта пребывания на момент выпуска карты |
countryCode | string | ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2) |
additionalParameters | array | Массив JSON-объектов AdditionalParameter с дополнительными параметрами, требуемыми для выпуска карты |
Пример запроса:
Если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных, они будут переданы в массиве объектов additionalParameters
(по одному объекту на каждый параметр). Перечень и формат представления таких параметров предварительно согласуется с Cardsmobile.
Правило обработки запроса
Информация о балансе карты должна быть доступна сразу же после ее привязки.
Запрос информации о карте лояльности по ее номеру
GET
https://<base-URL>/v1/card/{cardNumber}
Вызывается для запроса состояния и баланса карты по ее номеру. Информация по карте запрашивается в момент выпуска карты по номеру, а также для запроса баланса. Полученные в ответе метода параметры передаются на экран баланса карты пользователя в Кошельке.
Path Parameters
Name | Type | Description |
---|---|---|
cardNumber* | string | Номер карты лояльности |
Пример запроса:
Пример ответа с информацией о найденной карте лояльности:
Обратите внимание:
В полях, перечисленных ниже, должно содержаться строковое представление числа (допускаются как целые числа, так и числа с дробной частью):
discountPercent
,totalPurchaseAmount
,statusConfirmAmount
(объект status);discountPercent
,totalPurchaseAmount
(объект nextStatus);total
,available
,bonuses[].amount
(объект bonus).
Поле
bonuses[].validUntil
(объект bonus) должно содержать дату в формате YYYY-MM-DD.
Запрос истории покупок по номеру карты за указанный период
GET
https://<base-URL>/v1/card/{cardNumber}/purchases
В запросе передаются даты начала и окончания периода, полученные от Кошелька.
Path Parameters
Name | Type | Description |
---|---|---|
cardNumber* | string | Номер карты лояльности |
startDate* | string | Начало периода: YYYY-MM-DD |
endDate | string | Окончание периода: YYYY-MM-DD. Может отсутствовать (в таком случае равно текущей дате) |
Пример запроса:
Обратите внимание:
В полях ответа
amount
,quantity
иbonuses
должно содержаться строковое представление числа (допускаются как целые числа, так и с числа дробной частью).Поля ответа
date
,item
,amount
иquantity
— обязательные (не допускается пустых значений).Поля ответа
location
иbonuses
могут содержать пустые значения (в частности, если они не предусмотрены программой лояльности).
Запрос специальных акций по номеру карты
GET
https://<base-URL>/v1/card/{cardNumber}/specials
Вызывается при переходе пользователя на экран выпущенной карты. Позволяет приложению «Кошелёк» получить и отобразить для пользователя на экране перечень специальных акций, доступных ему как владельцу карты лояльности.
Path Parameters
Name | Type | Description |
---|---|---|
cardNumber* | string | Номер карты лояльности |
Пример запроса:
Требования к ответу о найденной специальной акции:
startDate
,endDate
— на стороне сервера Cardsmobile ожидается, что даты начала и окончания акции будут сформированы партнером, исходя из региона присутствия клиента на момент выпуска карты (передается в полеlocality
— см. сценарии выпуска), и соответствующего часового пояса.description
— в подробном описании акции допускается использование набора тегов HTML-разметки для форматирования описания:
Тег HTML | Формат текста |
---|---|
| Полужирный |
| Курсивный |
| Подчеркнутый |
| Нижний индекс |
| Верхний индекс |
| Увеличенный размер |
| Уменьшенный размер |
| Моноширинный |
| Заголовок уровня 1 — 6 |
| Изображение |
| Параметры шрифта (семейство, размер, цвет) |
| Блок цитирования |
| Ссылка |
| Параграф |
| Разрыв (перевод) строки |
Пример ответа с информацией о специальных акциях:
Last updated