Links
Comment on page

Основные запросы API

Выпуск и обслуживание карт лояльности
Документация перемещена
Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:
get
https://<base-URL>
/v1/card
Поиск карты лояльности по данным профиля пользователя

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

GET /v1/card?msisdn=79216668899&[email protected]&birthDate=1990-01-01
Правила обработки запроса
  • Параметры поиска комбинируются по условию логического оператора ИЛИ.
  • Неизвестные партнеру условия поиска должны игнорироваться.
  • Если условиям поиска соответствует несколько различных карт лояльности, разрешение конфликта происходит на стороне партнера. Допускается вернуть ошибку; в этом случае пользователю будет рекомендовано обратиться в службу поддержки партнера.
  • Если переданным условиям поиска соответствует заблокированная карта и при наличии заблокированной карты партнер запрещает выпуск карты (новой или с номером, указанным пользователем), то в ответ на этот запрос необходимо вместо данных заблокированной карты возвращать ошибку 422: Unprocessable Entity.
put
https://<base-URL>
/v1/card/{cardNumber}/communication
Обновление разрешенных пользователем каналов коммуникации

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

PUT /v1/card/2337658900/communication
{
"allow": [ // разрешенные каналы связи
"sms",
"email"
],
"deny": [ // запрещенные каналы связи
"call"
]
}
post
https://<base-URL>
/v1/card/{cardNumber}
Обновление персональных данных пользователя

Передача дополнительных параметров

Дополнительные параметры запроса передаются в виде массива JSON-объектов AdditionalParameter. Этот объект имеет следующие поля:
Поле
Тип
Обазятельное
Описание
paramName
String
Да
Имя параметра
values
Object[]
Да
Значения параметра. Массив объектов вида
{ "name": String, "value": String }

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

POST /v1/card/2337658900
{
"phone" : "71111111111",
"email" : "user@domain",
"surname": "Иванов",
"firstname": "Иван",
"sex": "м",
"birthDate": "1990-01-01"
}
Этот запрос следует ожидать:
  • В ходе сценария выпуска карты — если номер карты был найден в базе данных партнера (см. Поиск карты лояльности по данным профиля пользователя).
  • После выпуска карты — при обновлении пользователем данных своего профиля в Кошельке (в запросе будут переданы только измененные персональные данные).
Если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных, они будут переданы в массиве объектов additionalParameters (по одному объекту на каждый параметр). Перечень и формат представления таких параметров предварительно согласуется с Cardsmobile.
post
https://<base-URL>
/v1/card/provided/{cardNumber}
Выпуск карты с номером, указанным пользователем

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

POST /v1/card/provided/2337658900
{
"phone" : "71111111111",
"email" : "user@domain",
"surname": "Иванов",
"firstname": "Иван",
"sex": "м",
"birthDate": "1990-01-01"
}
  • Номер карты, использующийся в запросе, сообщается пользователем приложения и никак не проверяется на стороне Cardsmobile. Если такой карты не существует в системе партнера, либо если она не анонимна (т.е. привязана к другому пользователю), или заблокирована, то возвращается ошибка.
  • Если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных, они будут переданы в массиве объектов additionalParameters (по одному объекту на каждый параметр). Перечень и формат представления таких параметров предварительно согласуется с Cardsmobile.
get
https://<base-URL>
/v1/card/anonymous
Резервирование новой анонимной карты

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

GET /v1/card/anonymous
Правило обработки запроса
Реализация системы со стороны партнера должна гарантировать, что выданный номер карты будет зарезервирован (недоступен для повторного использования) в течение часа.
post
https://<base-URL>
/v1/card/anonymous/{cardNumber}
Выпуск карты по номеру ранее зарезервированной анонимной карты

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

POST /v1/card/anonymous/2337658900
{
"phone" : "71111111111",
"email" : "user@domain",
"surname": "Иванов",
"firstname": "Иван",
"sex": "м",
"birthDate": "1990-01-01"
}
Если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных, они будут переданы в массиве объектов additionalParameters (по одному объекту на каждый параметр). Перечень и формат представления таких параметров предварительно согласуется с Cardsmobile.
Правило обработки запроса
Информация о балансе карты должна быть доступна сразу же после ее привязки.
get
https://<base-URL>
/v1/card/{cardNumber}
Запрос информации о карте лояльности по ее номеру

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

GET /v1/card/2337658900

Пример ответа с информацией о найденной карте лояльности:

{
"card": {
"cardNumber": "65046476",
"cardState": "active",
"barcode": {
"barcodeNumber": "0000660277088",
"barcodeType": "EAN_13"
},
"status": {
"discountPercent": "10",
"cardType": "default",
"totalPurchaseAmount": "200",
"statusConfirmAmount": "0"
},
"nextStatus": {
"discountPercent": "20",
"cardType": "next_status",
"totalPurchaseAmount": "2000"
},
"bonus": {
"total": "0",
"available": "0",
"bonuses": [
{
"description": "Бонус № 1",
"amount": "100",
"validUntil": "2018-12-01"
},
{
"description": "Бонус № 2",
"amount": "10",
"validUntil": "2018-12-12"
},
{
"description": "Бонус № 3",
"amount": "1",
"validUntil": "2018-10-29"
}
]
}
}
}
Обратите внимание:
  1. 1.
    В полях, перечисленных ниже, должно содержаться строковое представление числа (допускаются как целые числа, так и числа с дробной частью):
    • discountPercent, totalPurchaseAmount, statusConfirmAmount (объект status);
    • discountPercent, totalPurchaseAmount (объект nextStatus);
    • total, available, bonuses[].amount (объект bonus).
  2. 2.
    Поле bonuses[].validUntil (объект bonus) должно содержать дату в формате YYYY-MM-DD.
get
https://<base-URL>
/v1/card/{cardNumber}/purchases
Запрос истории покупок по номеру карты за указанный период

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

GET /v1/card/2337658900/purchases?startDate=2019-01-01
Обратите внимание:
  • В полях ответа amount, quantity и bonuses должно содержаться строковое представление числа (допускаются как целые числа, так и с числа дробной частью).
  • Поля ответа date, item, amount и quantity — обязательные (не допускается пустых значений).
  • Поля ответа location и bonuses могут содержать пустые значения (в частности, если они не предусмотрены программой лояльности).
get
https://<base-URL>
/v1/card/{cardNumber}/specials
Запрос специальных акций по номеру карты

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

GET /v1/card/2337658900/specials

Требования к ответу о найденной специальной акции:

  • startDate, endDate — на стороне сервера Cardsmobile ожидается, что даты начала и окончания акции будут сформированы партнером, исходя из региона присутствия клиента на момент выпуска карты (передается в поле locality — см. сценарии выпуска), и соответствующего часового пояса.
  • description — в подробном описании акции допускается использование набора тегов HTML-разметки для форматирования описания:
Тег HTML
Формат текста
b, strong
Полужирный
i, em, cite, dfn
Курсивный
u
Подчеркнутый
sub
Нижний индекс
sup
Верхний индекс
big
Увеличенный размер
small
Уменьшенный размер
tt
Моноширинный
h1, ..., h6
Заголовок уровня 1 — 6
img
Изображение
font
Параметры шрифта (семейство, размер, цвет)
blockquote
Блок цитирования
a
Ссылка
div, p
Параграф
br
Разрыв (перевод) строки

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

[
{
"id": "1",
"startDate": "2019-09-09",
"endDate": "2019-09-15",
"name": "SALE до -50%",
"description": "Скидка предоставляется по промокоду «SALE50».<br>Акция действует при покупке товара в магазине c 09 до 15 сентября.",
"barcodeNumber": "123456789",
"barcodeType": "EAN_13",
"assets": {
"imageUrl": "https://partnerresource/image1.jpg",
"imageLargeUrl": "https://partnerresource/image2.jpg"
}
},
{
"id": "2",
"startDate": "2019-09-09",
"endDate": "2019-09-15",
"name": "SALE до -70%",
"description": "Скидка предоставляется по промокоду «SALE70».<br>Акция действует при покупке товара в магазине c 09 до 15 сентября.",
"barcodeNumber": "987654321",
"barcodeType": "EAN_13",
"assets": {
"imageUrl": "https://partnerresource/image1.jpg",
"imageLargeUrl": "https://partnerresource/image2.jpg"
}
}
]