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

M
Last updated 3 months ago

CardsMobile Loyalty API

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

/v1/card
Пользователь «Кошелька» и карта лояльности клиента соотносятся как 1 к 1 и представляют собой единую сущность. Если программа лояльности партнера допускает у пользователя наличие нескольких карт лояльности (активных или нет), выбор карты, которая будет доступна пользователю для выпуска в приложении «Кошелёк», реализуется на стороне партнера.
Request
Response
Body 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
В случае ошибки обработки запроса верните 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=2017-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

Отображение списка акции в «Кошельке»:

«Кошелёк»: Общий список акций партнера
«Кошелёк»: Подробное описание акции