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

Выпуск и обслуживание карт лояльности
get
Поиск карты лояльности по данным профиля пользователя
https://<base-URL>/v1/card
Пользователь приложения «Кошелёк» и карта лояльности клиента соотносятся как «один-к-одному» и представляют собой единую сущность. 

Если программа лояльности партнера допускает у пользователя наличие нескольких карт лояльности (активных или нет), то логика выбора карты, которая будет доступна пользователю для выпуска в «Кошельке», реализуется на стороне партнера.
Request
Response
Request
Query Parameters
msisdn
optional
string
Номер телефона пользователя без ведущего "+". До 15-ти символов, начиная с 1-3х-значного кода страны
email
optional
string
Адрес электронной почты пользователя
birthDate
optional
string
Дата рождения пользователя в формате YYYY-MM-DD
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа содержит информацию о карте лояльности, удовлетворяющей условиям поиска, либо пустое, если такой карты не найдено:
А. Карта найдена:
Б. Карта не найдена:
А. Карта найдена:
{
   "card": { // карта лояльности пользователя
      "cardNumber": "", // номер карты в информационной системе партнера
      "cardState" : "", // состояние карты ("active" / "inactive")
      "barcode": { // штрихкод карты
         "barcodeNumber": "", // номер штрихкода
         "barcodeType": ""    // тип штрихкода ("EAN_8" / "EAN_13" / "CODE_128" / "UPC_A" / "QR_CODE")
    }
  }
}
Б. Карта не найдена:
​
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
  "code": "123",
  "description": "Недоступен сервер баз данных"
}
Пример запроса:
GET /v1/card?msisdn=79216668899&email=sample@domain.com&birthDate=1990-01-01
Правила обработки запроса:
Параметры поиска комбинируются по условию логического ИЛИ.
Если переданным условиям поиска соответствует несколько различных карт лояльности, разрешение конфликта происходит на стороне партнера. Допускается вернуть ошибку; в этом случае пользователю будет рекомендовано обратиться в службу поддержки партнера.
Неизвестные партнеру условия поиска должны игнорироваться.
put
Обновление разрешенных пользователем каналов коммуникации
https://<base-URL>/v1/card/{cardNumber}/communication
Запрос передается при выпуске карты (пользователь выбирает способы коммуникации на экране «Кошелька»). Возможные значения (call, email, sms) передаются внутри массива.
Request
Response
Request
Path Parameters
cardNumber
required
string
Номер карты лояльности
Body Parameters
allow
required
array
Разрешенные каналы коммуникации
deny
required
array
Запрет на коммуникацию с использованием указанных каналов связи (отписка пользователя)
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
​
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
  "code": "123",
  "description": "Недоступен сервер баз данных"
}
Пример запроса:
PUT /v1/card/2337658900/communication
{
   "allow": [ // разрешенные каналы связи
      "sms",
      "email"
   ],
   "deny": [ // запрещенные каналы связи
      "call"
   ]
}
post
Обновление персональных данных пользователя
https://<base-URL>/v1/card/{cardNumber}
Передача партнеру изменений персональных данных пользователя, владеющего картой лояльности партнера. Как правило, при выпуске карты в теле сообщения всегда передаются значения полей: phone, email, surname, firstname, sex, birthDate.
Request
Response
Request
Path Parameters
cardNumber
required
string
Номер карты лояльности
Body Parameters
phone
optional
string
Номер телефона без ведущего +
email
optional
string
Адрес электронной почты
surname
optional
string
Фамилия
firstname
optional
string
Имя
sex
optional
string
Пол ("м" или "ж")
birthDate
optional
string
Дата рождения в формате YYYY-DD-MM
patronymic
optional
string
Отчество
locality
optional
string
Название населенного пункта пребывания на момент выпуска карты
countryCode
optional
string
ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2)
additionalParameters
optional
array
Массив JSON-объектов AdditionalParameter с дополнительными параметрами, требуемыми для выпуска карты
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
​
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
  "code": "123",
  "description": "Недоступен сервер баз данных"
}
Передача дополнительных параметров
Дополнительные параметры запроса передаются в виде массива 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}
Для выпуска происходит передача партнеру персональных данных пользователя. Как правило, в теле сообщения всегда передаются значения следующих полей: phone, email, surname, firstname, sex, birthDate.
Request
Response
Request
Path Parameters
cardNumber
required
string
Номер карты, указанный пользователем
Body Parameters
phone
optional
string
Номер телефона без ведущего +
email
optional
string
Адрес электронной почты
surname
optional
string
Фамилия
firstname
optional
string
Имя
sex
optional
string
Пол ("м" или "ж")
birthDate
optional
string
Дата рождения в формате YYYY-MM-DD
patronymic
optional
string
Отчество
locality
optional
string
Название населенного пункта пребывания на момент выпуска карты
countryCode
optional
string
ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2)
additionalParameters
optional
array
Массив JSON-объектов AdditionalParameter с дополнительными параметрами, требуемыми для выпуска карты
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
​
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
  "code": "123",
  "description": "Недоступен сервер баз данных"
}
Пример запроса:
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
Запрос у партнера номера новой карты лояльности, не привязанной ни к какому клиенту программы лояльности.

Резервирование происходит в случае, если поиск карты по данным профиля пользователя не принес результатов (пользователь не является клиентом программы лояльности). Вслед за этим запросом стоит ожидать запрос на выпуск по номеру ранее зарезервированной анонимной карты.
Request
Response
Request
​
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — номер зарезервированной карты:
2337658900
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
  "code": "123",
  "description": "Недоступен сервер баз данных"
}
Пример запроса:
GET /v1/card/anonymous
Правила обработки запроса:
Реализация системы со стороны партнера должна гарантировать, что выданный номер карты будет оставаться зарезервированным (недоступным для повторного использования) в течение часа.
post
Выпуск карты по номеру ранее зарезервированной анонимной карты
https://<base-URL>/v1/card/anonymous/{cardNumber}
В этот запрос передается номер анонимной карты, предварительно полученный запросом резервирования новой анонимной карты. Для выпуска происходит передача партнеру персональных данных пользователя. Как правило, в теле сообщения всегда передаются значения следующих полей: phone, email, surname, firstname, sex, birthDate.
Request
Response
Request
Path Parameters
cardNumber
required
string
Зарезервированный номер анонимной карты
Body Parameters
phone
optional
string
Номер телефона без ведущего +
email
optional
string
Адрес электронной почты
surname
optional
string
Фамилия
firstname
optional
string
Имя
sex
optional
string
Пол ("м" или "ж")
birthDate
optional
string
Дата рождения в формате YYYY-MM-DD
patronymic
optional
string
Отчество
locality
optional
string
Название населенного пункта пребывания на момент выпуска карты
countryCode
optional
string
ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2)
additionalParameters
optional
array
Массив JSON-объектов AdditionalParameter с дополнительными параметрами, требуемыми для выпуска карты
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
​
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
  "code": "123",
  "description": "Недоступен сервер баз данных"
}
Пример запроса:
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}
Вызывается для запроса состояния и баланса карты по ее номеру. Информация по карте запрашивается в момент выпуска карты по номеру, а также для запроса баланса. Полученные в ответе метода параметры передаются на экран баланса карты пользователя в «Кошельке».
Request
Response
Request
Path Parameters
cardNumber
required
string
Номер карты лояльности
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа содержит информацию о полном текущем состоянии карты лояльности со всеми значениями (поля, не предусмотренные программой лояльности партнера, должны содержать пустое значение):
{
   "card": {   // карта лояльности пользователя
      "cardNumber": "",  // номер карты
      "cardState" : "",  // состояние карты ("active" / "inactive")
      "barcode": {   // штрихкод карты
         "barcodeNumber": "", // номер штрихкода
         "barcodeType": ""    // тип штрихкода ("EAN_8" / "EAN_13" / "CODE_128" / "UPC_A" / "QR_CODE")
      },
      "status": {    // текущий статус карты
         "discountPercent": "",     // процент скидки
         "cardType": "",            // статус карты (золотая, серебряная и т.д.)
         "totalPurchaseAmount": "", // общая сумма покупок по карте (число)
         "statusConfirmAmount": ""  // оставшаяся сумма покупок по карте до подтверждения текущего статуса (число)
      },
      "nextStatus": {  // следующий статус карты
         "discountPercent": "",    // процент скидки (число)
         "cardType": "",           // статус карты (золотая, серебряная и т.д.)
         "totalPurchaseAmount": "" // оставшаяся сумма покупок по карте до получения следующего статуса (число)
      },
      "bonus": {       // количество бонусов на карте
         "total": "",     // общее кол-во бонусов (число)
         "available": "", // доступное кол-во бонусов (число)
         "bonuses": [     // описание бонусов
           {
             "description": "", // название бонуса
             "amount": "",      // кол-во бонусов (число)
             "validUntil": ""   // дата, до которой бонусы действительны
           }
         ]
      }  
   }
}
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
   "code": "123",
   "description": "Недоступен сервер баз данных"
}
Пример запроса:
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"
           }
         ]
      }
   }
}
Обратите внимание:
В полях, перечисленных ниже, должно содержаться строковое представление числа (допускаются как целые числа, так и с числа дробной частью):
discountPercent, totalPurchaseAmount, statusConfirmAmount (объект status);
discountPercent, totalPurchaseAmount (объект nextStatus);
total, available, bonuses[].amount (объект bonus).
get
Запрос истории покупок по номеру карты за указанный период
https://<base-URL>/v1/card/{cardNumber}/purchases
В запросе передаются даты начала и окончания периода, полученные от «Кошелька».
Request
Response
Request
Path Parameters
cardNumber
required
string
Номер карты лояльности
startDate
required
string
Начало периода: YYYY-DD-MM
endDate
optional
string
Окончание периода: YYYY-DD-MM. Может отсутствовать (в таком случае равно текущей дате)
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа содержит информацию о покупках за указанный период, или пустой массив, если покупок не зарегистрировано: 
А. Список покупок за указанный период:
Б. Нет покупок в указанном периоде:
А. Список покупок за указанный период:
[
   {
      "date": "",     // дата операции YYYY-MM-DD
      "item": "",     // наименование товара
      "amount": "",   // стоимость товара в копейках (Число. Со знаком "-" - возврат покупки)
      "quantity": "", // кол-во единиц товара (число)
      "location": "", // место проведения операции
      "bonuses": ""   // начисленные "+" и списанные "-" бонусы за покупку (числа)
   }
]
Б. Нет покупок в указанном периоде:
[]
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
   "code": "123",
   "description": "Недоступен сервер баз данных"
}
Пример запроса:
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
Вызывается при переходе пользователя на экран выпущенной карты. Позволяет приложению «Кошелёк» получить и отобразить для пользователя на экране перечень специальных акций, доступных ему как владельцу карты лояльности.
Request
Response
Request
Path Parameters
cardNumber
required
string
Номер карты лояльности
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа содержит информацию обо всех доступных для указанной карты специальных акций (в виде массива объектов). Если специальных акций для указанной акции не имеется, возвращается пустой массив:
А. Список специальных акций для карты:
Б. Специальных акций нет:
А. Список специальных акций для карты:
[
    {  // информация об акции
        "id": "",            // идентификатор акции
        "name": "",          // название персональной акции - рекомендуемая длина до 40 символов. Название может быть длиннее, но тогда на некоторых экранах будет обрезаться многоточием
        "startDate": "",     // дата начала действия - "ГГГГ-ММ-ДД"
        "endDate": "",       // дата окончания действия - "ГГГГ-ММ-ДД"
        "description": "",   // описание персональной акции (рекомендуемая длина до 500 символов, разрешены теги HTML)
        "barcodeNumber": "", // номер штрихкода
        "barcodeType": "",   // тип штрихкода ("EAN_8" / "EAN_13" / "CODE_128" / "UPC_A" / "QR_CODE")
        "assets": {  // внешнее оформление акции
           "imageUrl": "",     // графическое изображение – прямая ссылка на ресурс с изображением формата 600x600px. Обязательно
           "imageLargeUrl": "" // дополнительное графическое изображение (формат баннера) – прямая ссылка на ресурс с изображением формата 1080х420px. Не обязательно
        }
    }
    // аналогичные объекты {...} в массиве для остальных акций (через запятую)
]
Б. Специальных акций нет:
[]
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
   "code": "123",
   "description": "Недоступен сервер баз данных"
}
Пример запроса:
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"
        }
    }
]
Cardsmobile Loyalty Online API - Previous
Обзор сценариев карты лояльности
Next - Cardsmobile Loyalty Online API
Дополнительные запросы API
Last updated 4 days ago
Тег HTML	Формат текста
`b`, `strong`	Полужирный
`i`, `em,` `cite`, `dfn`	Курсивный
`u`	Подчеркнутый
`sub`	Нижний индекс
`sup`	Верхний индекс
`big`	Увеличенный размер
`small`	Уменьшенный размер
`tt`	Моноширинный
`h1`, ..., `h6`	Заголовок уровня 1 — 6
`img`	Изображение
`font`	Параметры шрифта (семейство, размер, цвет)
`blockquote`	Блок цитирования
`a`	Ссылка
`div`, `p`	Параграф
`br`	Разрыв (перевод) строки
Основные запросы API

getПоиск карты лояльности по данным профиля пользователя

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

putОбновление разрешенных пользователем каналов коммуникации

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

postОбновление персональных данных пользователя

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

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

postВыпуск карты с номером, указанным пользователем

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

getРезервирование новой анонимной карты

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

postВыпуск карты по номеру ранее зарезервированной анонимной карты

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

getЗапрос информации о карте лояльности по ее номеру

getЗапрос истории покупок по номеру карты за указанный период

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

getЗапрос специальных акций по номеру карты

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

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

get
Поиск карты лояльности по данным профиля пользователя

put
Обновление разрешенных пользователем каналов коммуникации

post
Обновление персональных данных пользователя

post
Выпуск карты с номером, указанным пользователем

get
Резервирование новой анонимной карты

post
Выпуск карты по номеру ранее зарезервированной анонимной карты

get
Запрос информации о карте лояльности по ее номеру

get
Запрос истории покупок по номеру карты за указанный период

get
Запрос специальных акций по номеру карты
