Russian
Основные запросы API
Выпуск и обслуживание карт лояльности
get
https://<base-URL>
/v1/card
Поиск карты лояльности по данным профиля пользователя

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

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

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

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

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

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

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

1
POST /v1/card/2337658900
Copied!
1
{
2
"phone" : "71111111111",
3
"email" : "[email protected]",
4
"surname": "Иванов",
5
"firstname": "Иван",
6
"sex": "м",
7
"birthDate": "1990-01-01"
8
}
Copied!
Этот запрос следует ожидать:
  • В ходе сценария выпуска карты — если номер карты был найден в базе данных партнера (см. Поиск карты лояльности по данным профиля пользователя). Если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных, они будут переданы в массиве объектов additionalParameters (по одному объекту на каждый параметр). Перечень и формат представления таких параметров предварительно согласуется с Cardsmobile.
  • После выпуска карты — при обновлении пользователем данных своего профиля в «Кошельке» (в запросе будут переданы только измененные персональные данные).
post
https://<base-URL>
/v1/card/provided/{cardNumber}
Выпуск карты с номером, указанным пользователем

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

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

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

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

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

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

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

1
GET /v1/card/2337658900
Copied!

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

1
{
2
"card": {
3
"cardNumber": "65046476",
4
"cardState": "active",
5
"barcode": {
6
"barcodeNumber": "0000660277088",
7
"barcodeType": "EAN_13"
8
},
9
"status": {
10
"discountPercent": "10",
11
"cardType": "default",
12
"totalPurchaseAmount": "200",
13
"statusConfirmAmount": "0"
14
},
15
"nextStatus": {
16
"discountPercent": "20",
17
"cardType": "next_status",
18
"totalPurchaseAmount": "2000"
19
},
20
"bonus": {
21
"total": "0",
22
"available": "0",
23
"bonuses": [
24
{
25
"description": "Бонус № 1",
26
"amount": "100",
27
"validUntil": "2018-12-01"
28
},
29
{
30
"description": "Бонус № 2",
31
"amount": "10",
32
"validUntil": "2018-12-12"
33
},
34
{
35
"description": "Бонус № 3",
36
"amount": "1",
37
"validUntil": "2018-10-29"
38
}
39
]
40
}
41
}
42
}
Copied!
Обратите внимание:
  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
Запрос истории покупок по номеру карты за указанный период

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

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

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

1
GET /v1/card/2337658900/specials
Copied!

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

  • 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
Разрыв (перевод) строки

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

1
[
2
{
3
"id": "1",
4
"startDate": "2019-09-09",
5
"endDate": "2019-09-15",
6
"name": "SALE до -50%",
7
"description": "Скидка предоставляется по промокоду «SALE50».<br>Акция действует при покупке товара в магазине c 09 до 15 сентября.",
8
"barcodeNumber": "123456789",
9
"barcodeType": "EAN_13",
10
"assets": {
11
"imageUrl": "https://partnerresource/image1.jpg",
12
"imageLargeUrl": "https://partnerresource/image2.jpg"
13
}
14
},
15
{
16
"id": "2",
17
"startDate": "2019-09-09",
18
"endDate": "2019-09-15",
19
"name": "SALE до -70%",
20
"description": "Скидка предоставляется по промокоду «SALE70».<br>Акция действует при покупке товара в магазине c 09 до 15 сентября.",
21
"barcodeNumber": "987654321",
22
"barcodeType": "EAN_13",
23
"assets": {
24
"imageUrl": "https://partnerresource/image1.jpg",
25
"imageLargeUrl": "https://partnerresource/image2.jpg"
26
}
27
}
28
]
Copied!
Запрос списка специальных акций поддерживает только версия приложения «Кошелёк», предназначенная для устройств, работающих на платформе iOS.
Last modified 18d ago