Основные запросы API
Выпуск и обслуживание карт лояльности
Документация перемещена
Информация на этой странице не обновляется и может быть устаревшей.
Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:
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"
}
}
]