Основные запросы 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.В полях, перечисленных ниже, должно содержаться строковое представление числа (допускаются как целые числа, так и с числа дробной частью):
discountPercent, totalPurchaseAmount, statusConfirmAmount (объект status);
discountPercent, totalPurchaseAmount (объект nextStatus);
total, available, bonuses[].amount (объект bonus).
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.