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

CardsMobile Loyalty API

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

Если программа лояльности партнера допускает у пользователя наличие нескольких карт лояльности (активных или нет), выбор карты, которая будет доступна пользователю для выпуска в приложении «Кошелёк», реализуется на стороне партнера.
Request
Response
Path Parameters
email
optional
string
Адрес электронной почты пользователя.
msisdn
optional
string
Номер телефона пользователя без ведущего "+". До 150ти символов, начиная с 1-3х-значного кода страны.
200: OK
Верните сведения о карте в случае если найдена карта, удовлетворяющая параметрам поиска, или пустое тело ответа, если такой карты не найдено:
А. Карта найдена:
Б. Карта не найдена:
{
  "card": { // карта лояльности пользователя
    "cardNumber": "", // номер карты в информационной системе партнера
    "cardState" : "", // состояние карты (active / inactive)
    "barcode": { // штрих-код карты
      "barcodeNumber": "", // значение штрих-кода
      "barcodeType": "" // тип штрих-кода (EAN_8 / EAN_13 / CODE_128 / UPC_A / QR_CODE)
    }
  }
}
422: Unprocessable Entity
В случае ошибки обработки запроса верните HTTP-код 422 с кодом и описанием ошибки:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
Правила обработки запроса:
Параметры поиска комбинируются по условию логического ИЛИ.
Если переданным условиям поиска соответствует несколько различных карт лояльности, разрешение конфликта происходит на стороне партнера. Допускается вернуть ошибку; в этом случае пользователю будет рекомендовано обратиться в службу поддержки партнера.
Неизвестные партнеру условия должны игнорироваться.
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
В случае успеха обработки запроса верните HTTP-код 200:
​
422: Unprocessable Entity
В случае ошибки обработки запроса верните HTTP-код 422 с кодом и описанием ошибки:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
Пример запроса:
{
  "allow": [ // разрешенные каналы связи
    "sms",
    "email"
  ],
  "deny": [ // запрещенные каналы связи (отписка пользователя)
    "call"
  ]
}
post
Обновление персональных данных пользователя
/v1/card/{cardNumber}
Передача партнеру изменений персональных данных пользователя, владеющего картой лояльности партнера.
Request
Response
Path Parameters
cardNumber
required
string
Номер карты лояльности
Body Parameters
phone
optional
string
Номер телефона без ведущего +
additionalParameters
optional
object
(conditional) JSON-объект с дополнительными параметрами, требуемыми для выпуска карты
locality
optional
string
Название населенного пункта пребывания на момент выпуска карты
countryCode
optional
string
ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2)
sex
optional
string
Пол (м / ж)
email
optional
string
Адрес электронной почты
birthDate
optional
string
Дата рождения в формате YYYY-MM-DD
surname
optional
string
Фамилия
firstname
optional
string
Имя
patronymic
optional
string
Отчество
200: OK
В случае успеха обработки запроса верните HTTP-код 200:
​
422: Unprocessable Entity
В случае ошибки обработки запроса верните HTTP-код 422 с кодом и описанием ошибки:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
Этот запрос следует ожидать:
В ходе сценария выпуска карты — в случае если номер карты был найден в базе данных партнера (см. Поиск карты лояльности по данным профиля пользователя). При этом, если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных — они будут переданы в объекте additionalParameters. Перечень и формат представления таких параметров должен быть предварительно согласован с партнером.
После выпуска карты — в случае обновления пользователем данных своего профиля в «Кошельке» (в запросе будут переданы только измененные персональные данные).
post
Выпуск карты с номером, указанным пользователем
/v1/card/provided/{cardNumber}
Для выпуска происходит передача партнеру персональных данных пользователя.
Request
Response
Path Parameters
cardNumber
required
string
Номер карты, указанный пользователем
Body Parameters
additionalParameters
optional
object
(conditional) JSON-объект с дополнительными параметрами, требуемыми для выпуска карты
locality
optional
string
Название населенного пункта пребывания на момент выпуска карты
countryCode
optional
string
ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2)
sex
optional
string
Пол (м / ж)
phone
optional
string
Номер телефона без ведущего +
email
optional
string
Адрес электронной почты
birthDate
optional
string
Дата рождения в формате YYYY-MM-DD
surname
optional
string
Фамилия
firstname
optional
string
Имя
patronymic
optional
string
Отчество
200: OK
Если найдена анонимная карта с указанным номером, верните HTTP-код 200:
​
422: Unprocessable Entity
В случае ошибки обработки запроса верните HTTP-код 422 с кодом и описанием ошибки:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
Номер карты, использующийся в запросе, сообщается пользователем приложения и никак не валидируется на стороне CardsMobile.
В случае если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных — они будут переданы в объекте additionalParameters. Перечень и формат представления таких параметров должен быть предварительно согласован с партнером.
get
Резервирование новой анонимной карты
/v1/card/anonymous
Запрос у партнера новой, не привязанной ни к какому клиенту, карты лояльности.

Резервирование происходит в случае, если поиск карты по данным профиля пользователя не принес результатов (пользователь не является клиентом программы лояльности). Вслед за этим запросом стоит ожидать запрос на выпуск по номеру ранее зарезервированной анонимной карты.
Request
Response
​
200: OK
Если номер карты зарезервирован — верните его значение, или пустое тело ответа, если нет:
ОК (зарезервирован):
NOK (например, если эмиссия приостановлена):
2337658900
Правила обработки запроса:
Реализация системы партнера должна гарантировать, что выданный номер карты будет оставаться зарезервированным (недоступным для повторного использования) в течение 1 часа.
post
Выпуск карты по номеру ранее зарезервированной анонимной карты
/v1/card/anonymous/{cardNumber}
В этот запрос передается номер анонимной карты, предварительно полученный запросом "Резервирование новой анонимной карты". Для выпуска происходит передача партнеру персональных данных пользователя.
Request
Response
Path Parameters
cardNumber
required
string
Зарезервированный номер анонимной карты
Body Parameters
additionalParameters
optional
object
(conditional) JSON-объект с дополнительными параметрами, требуемыми для выпуска карты
locality
optional
string
Название населенного пункта пребывания на момент выпуска карты
countryCode
optional
string
ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2)
sex
optional
string
Пол (м / ж)
phone
optional
string
Номер телефона без ведущего +
email
optional
string
Адрес электронной почты
birthDate
optional
string
Дата рождения в формате YYYY-DD-MM
surname
optional
string
Фамилия
firstname
optional
string
Имя
patronymic
optional
string
Отчество
200: OK
В случае успеха обработки запроса верните HTTP-код 200:
​
422: Unprocessable Entity
В случае ошибки обработки запроса верните HTTP-код 422 с кодом и описанием ошибки:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
В случае если выпуск карты требует передачи каких-либо дополнительных параметров помимо персональных данных — они будут переданы в объекте additionalParameters. Перечень и формат представления таких параметров должен быть предварительно согласован с партнером.
Правила обработки запроса:
Информация о балансе карты должна быть доступна сразу же после ее привязки.
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": "" // дата, до которой бонусы действительны
        },
        {
          "description": "",
          "amount": "",
          "validUntil": ""
        }
      ]
    }
  }
}
Пример запроса:
GET /v1/card/2337658900
Отображение экрана баланса в приложении:
«Кошелёк»: карта лояльности, экран «Баланс» 
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
В случае ошибки обработки запроса верните HTTP-код 422 с кодом и описанием ошибки:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
Пример запроса:
GET /v1/card/2337658900/purchases?startDate=2019-01-01
Обратите внимание:
date, item, amount, quantity — обязательные поля (не допускается пустых значений).
location, bonuses — могут содержать пустые значения (в частности, если поля не предусматриваются программой лояльности).
get
Запрос списка акций по номеру карты
/v1/card/{cardNumber}/specials
Вызывается для отображения специальных предложений по карте.
Request
Response
Path Parameters
cardNumber
required
string
Номер карты лояльности
200: OK
В ответе необходимо передать список акций, или пустой массив, если акций не запланировано:
А. Список акций:
Б. Нет акций:
[
    {
      "name": "", // название акции
      "startDate": "", // дата начала акции YYYY-MM-DD
      "endDate": "", // дата окончания акции YYYY-MM-DD
      "description": "", // Подробное описание акции. Возможно использование тегов HTML для форматирования описания
      "assets": { // графические ресурсы акции для отображения в «Кошельке»
        "image": "", // ссылка на файл на хостинге партнера
      }
    }
  ]
422: Unprocessable Entity
В случае ошибки обработки запроса верните HTTP-код 422 с кодом и описанием ошибки:
{
 "code": "123",
 "description": "Недоступен сервер баз данных"
}
Параметры ответа:
startDate, endDate
На стороне сервера CardsMobile ожидается, что даты начала и окончания акции будут сформированы партнером исходя из региона присутствия клиента на момент выпуска карты (передается в поле locality — см. сценарии выпуска), и соответствующего часового пояса.
description
В подробном описании акции допускается использование тегов HTML-разметки для форматирования описания:
Tags
Format
b, strong
Bold
i, em, cite, dfn
Italics
u
Underline
sub
Subtext
sup
Supertext
big
Big
small
Small
tt
Monospace
h1 ... h6
Headlines
img
Image
font
Font face and color
blockquote
For longer quotes
a
Link
div, p
Paragraph
br
Linefeed
Отображение списка акции в «Кошельке»:
«Кошелёк»: Общий список акций партнера
«Кошелёк»: Подробное описание акции

Cardsmobile Loyalty API - Previous

Обзор сценариев Loyalty API

Next - Cardsmobile Loyalty API

Дополнительные сценарии

Last updated Thu Jun 13 2019 13:44:40 GMT+0000 (UTC)

Tags	Format
b, strong	Bold
i, em, cite, dfn	Italics
u	Underline
sub	Subtext
sup	Supertext
big	Big
small	Small
tt	Monospace
h1 ... h6	Headlines
img	Image
font	Font face and color
blockquote	For longer quotes
a	Link
div, p	Paragraph
br	Linefeed

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

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

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

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

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

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

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

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

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

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

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

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

Параметры ответа:

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

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

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

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

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

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

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

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

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