Основные сценарии

Cardsmobile Loyalty API
get
Поиск карты лояльности по данным профиля пользователя
/v1/card
Пользователь приложения «Кошелёк» и карта лояльности клиента соотносятся как «один-к-одному» и представляют собой единую сущность. 

Если программа лояльности партнера допускает у пользователя наличие нескольких карт лояльности (активных или нет), то выбор карты, которая будет доступна пользователю для выпуска в Кошельке, реализуется на стороне партнера.
Request
Response
Query Parameters
msisdn
optional
string
Номер телефона пользователя без ведущего "+". До 15-ти символов, начиная с 1-3х-значного кода страны.
email
optional
string
Адрес электронной почты пользователя.
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
Правила обработки запроса:
Параметры поиска комбинируются по условию логического ИЛИ.
Если переданным условиям поиска соответствует несколько различных карт лояльности, разрешение конфликта происходит на стороне партнера. Допускается вернуть ошибку; в этом случае пользователю будет рекомендовано обратиться в службу поддержки партнера.
Неизвестные партнеру условия должны игнорироваться.
put
Обновление разрешенных пользователем каналов коммуникации
/v1/card/{cardNumber}/communication
Запрос передается при выпуске карты (пользователь выбирает способы коммуникации на экране «Кошелька»). Возможные значения — call, email, sms — передаются внутри массива.
Request
Response
Path Parameters
cardNumber
required
string
Номер карты лояльности
Body Parameters
allow
required
array
Разрешенные каналы коммуникации
deny
required
array
Запрет на коммуникацию с использованием указанных каналов связи (отписка пользователя)
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
​
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
Пример запроса:
PUT /v1/card/2337658900/communication
{
  "allow": [ // разрешенные каналы связи
    "sms",
    "email"
  ],
  "deny": [ // запрещенные каналы связи (отписка пользователя)
    "call"
  ]
}
post
Обновление персональных данных пользователя
/v1/card/{cardNumber}
Передача партнеру изменений персональных данных пользователя, владеющего картой лояльности партнера. Как правило, при выпуске карты в теле сообщения всегда передаются значения полей: phone, email, surname, firstname, sex, birthDate.
Request
Response
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
object
(conditional) JSON-объект с дополнительными параметрами, требуемыми для выпуска карты
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
​
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
Пример запроса:
POST /v1/card/2337658900
{
  "phone" : "71111111111",
  "email" : "user@domain",
  "surname": "Иванов",
  "firstname": "Иван",
  "sex": "М",
  "birthDate": "1990-01-01"
}
Этот запрос следует ожидать:
В ходе сценария выпуска карты — если номер карты был найден в базе данных партнера (см. Поиск карты лояльности по данным профиля пользователя). Если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных, они будут переданы в объекте additionalParameters. Перечень и формат представления таких параметров предварительно согласуется с Cardsmobile.
После выпуска карты — при обновлении пользователем данных своего профиля в «Кошельке» (в запросе будут переданы только измененные персональные данные).
post
Выпуск карты с номером, указанным пользователем
/v1/card/provided/{cardNumber}
Для выпуска происходит передача партнеру персональных данных пользователя. Как правило, в теле сообщения всегда передаются значения следующих полей: phone, email, surname, firstname, sex, birthDate.
Request
Response
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
object
(conditional) JSON-объект с дополнительными параметрами, требуемыми для выпуска карты
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
Резервирование новой анонимной карты
/v1/card/anonymous
Запрос у партнера новой, не привязанной ни к какому клиенту, карты лояльности.

Резервирование происходит в случае, если поиск карты по данным профиля пользователя не принес результатов (пользователь не является клиентом программы лояльности). Вслед за этим запросом стоит ожидать запрос на выпуск по номеру ранее зарезервированной анонимной карты.
Request
Response
​
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — номер зарезервированной карты, либо, если резервирование не выполнено, — пустое:
ОК (зарезервирован):
NOK (например, если эмиссия приостановлена):
2337658900
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа содержит сведения (код и описание) о произошедшей ошибке:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
Пример запроса:
GET /v1/card/anonymous
Правила обработки запроса:
Реализация системы партнера должна гарантировать, что выданный номер карты будет оставаться зарезервированным (недоступным для повторного использования) в течение часа.
post
Выпуск карты по номеру ранее зарезервированной анонимной карты
/v1/card/anonymous/{cardNumber}
В этот запрос передается номер анонимной карты, предварительно полученный запросом "Резервирование новой анонимной карты". Для выпуска происходит передача партнеру персональных данных пользователя. Как правило, в теле сообщения всегда передаются значения следующих полей: phone, email, surname, firstname, sex, birthDate.
Request
Response
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
object
(conditional) JSON-объект с дополнительными параметрами, требуемыми для выпуска карты
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
Запрос карты лояльности по ее номеру
/v1/card/{cardNumber}
Вызывается при переходе пользователя на экран выпущенной карты, или при переходе к меню Баланс. Основной метод для получения баланса мобильной карты лояльности. Полученные данные будут выведены на экран «Кошелька».
Request
Response
Path Parameters
cardNumber
required
string
Номер карты лояльности
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).
Отображение экрана баланса в приложении:
«Кошелёк» для iOS: карта лояльности, экран «Баланс» 
get
Запрос истории покупок по номеру карты за указанный период
/v1/card/{cardNumber}/purchases
В запросе передаются даты начала и окончания периода, полученные от «Кошелька».
Request
Response
Path Parameters
cardNumber
required
string
Номер карты лояльности
startDate
required
string
Начало периода: YYYY-DD-MM
endDate
optional
string
Окончание периода: YYYY-DD-MM. Может отсутствовать (в таком случае равно текущей дате)
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
Запрос специальных акций по номеру карты
/v1/card/{cardNumber}/specials
Вызывается при переходе пользователя на экран выпущенной карты. Позволяет приложению «Кошелёк» получить и отобразить для пользователя на экране перечень специальных акций, доступных ему как владельцу карты лояльности.
Request
Response
Path Parameters
cardNumber
required
string
Номер карты лояльности
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа содержит информацию обо всех доступных для указанной карты специальных акций (в виде массива объектов). Если специальных акций для указанной акции не имеется, поле personalOffers содержит пустой массив:
А. Список специальных акций для карты:
Б. Специальных акций нет:
{
  "personalOffers": [
   {  // Информация об акции
     "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
Разрыв (перевод) строки
Пример ответа с информацией о специальных акциях:
{
 "personalOffers": [
  {
    "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 API - Previous
Обзор сценариев Loyalty API
Next - Cardsmobile Loyalty API
Дополнительные сценарии
Last updated -4
Тег HTML	Формат текста
`b`, `strong`	Полужирный
`i`, `em,` `cite`, `dfn`	Курсивный
`u`	Подчеркнутый
`sub`	Нижний индекс
`sup`	Верхний индекс
`big`	Увеличенный размер
`small`	Уменьшенный размер
`tt`	Моноширинный
`h1`, ..., `h6`	Заголовок уровня 1 — 6
`img`	Изображение
`font`	Параметры шрифта (семейство, размер, цвет)
`blockquote`	Блок цитирования
`a`	Ссылка
`div`, `p`	Параграф
`br`	Разрыв (перевод) строки
Основные сценарии

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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