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

Выпуск и обслуживание карт лояльности
Документация перемещена
Информация на этой странице не обновляется и может быть устаревшей. 
Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:
​https://developers.koshelek.app​
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" : "[email protected]",
   "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" : "[email protected]",
   "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" : "[email protected]",
   "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.В полях, перечисленных ниже, должно содержаться строковое представление числа (допускаются как целые числа, так и числа с дробной частью):
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
Запрос истории покупок по номеру карты за указанный период
Пример запроса:
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"
        }
    }
]
Поле	Тип	Обазятельное	Описание
`paramName`	String	Да	Имя параметра
`values`	Object[]	Да	Значения параметра. Массив объектов вида `{` `"name": String,` `"value": String` `}`
Тег HTML	Формат текста
`b`, `strong`	Полужирный
`i`, `em,` `cite`, `dfn`	Курсивный
`u`	Подчеркнутый
`sub`	Нижний индекс
`sup`	Верхний индекс
`big`	Увеличенный размер
`small`	Уменьшенный размер
`tt`	Моноширинный
`h1`, ..., `h6`	Заголовок уровня 1 — 6
`img`	Изображение
`font`	Параметры шрифта (семейство, размер, цвет)
`blockquote`	Блок цитирования
`a`	Ссылка
`div`, `p`	Параграф
`br`	Разрыв (перевод) строки
Cardsmobile Loyalty Online API - Previous
Обзор сценариев карты лояльности
Next - Cardsmobile Loyalty Online API
Дополнительные запросы API
Last modified 24d ago