Основные запросы 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!