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

Выпуск и обслуживание карт лояльности

Документация перемещена

Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:

https://developers.koshelek.app

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

GET https://<base-URL>/v1/card

Пользователь приложения «Кошелёк» и карта лояльности клиента соотносятся как «один-к-одному» и представляют собой единую сущность.

Если программа лояльности партнера допускает наличие нескольких карт лояльности (активных или нет) у одного пользователя, то логика выбора карт, доступных пользователю для выпуска в Кошельке, реализуется на стороне партнера.

Query Parameters

NameTypeDescription

msisdn

string

Номер телефона пользователя без префикса +. До 15-ти символов, начиная с 1-3х-значного кода страны

email

string

Адрес электронной почты пользователя

birthDate

string

Дата рождения пользователя в формате

YYYY-MM-DD

{
   "card": { // карта лояльности пользователя
      "cardNumber": "", // номер карты в информационной системе партнера
      "cardState" : "", // состояние карты ("active" / "inactive")
      "barcode": { // штрихкод карты
         "barcodeNumber": "", // номер штрихкода
         "barcodeType": ""    // тип штрихкода ("EAN_8" / "EAN_13" / "CODE_128" / "UPC_A" / "QR_CODE")
    }
  }
}

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

GET /v1/card?msisdn=79216668899&email=sample@domain.com&birthDate=1990-01-01

Правила обработки запроса

  • Параметры поиска комбинируются по условию логического оператора ИЛИ.

  • Неизвестные партнеру условия поиска должны игнорироваться.

  • Если условиям поиска соответствует несколько различных карт лояльности, разрешение конфликта происходит на стороне партнера. Допускается вернуть ошибку; в этом случае пользователю будет рекомендовано обратиться в службу поддержки партнера.

  • Если переданным условиям поиска соответствует заблокированная карта и при наличии заблокированной карты партнер запрещает выпуск карты (новой или с номером, указанным пользователем), то в ответ на этот запрос необходимо вместо данных заблокированной карты возвращать ошибку 422: Unprocessable Entity.

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

PUT https://<base-URL>/v1/card/{cardNumber}/communication

Запрос передается при выпуске карты (пользователь выбирает способы коммуникации на экране Кошелька). Возможные значения (call, email, sms) передаются внутри массива.

Path Parameters

NameTypeDescription

cardNumber*

string

Номер карты лояльности

Request Body

NameTypeDescription

allow*

array

Разрешенные каналы коммуникации

deny*

array

Запрет на коммуникацию с использованием указанных каналов связи (отписка пользователя)

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

PUT /v1/card/2337658900/communication
{
   "allow": [ // разрешенные каналы связи
      "sms",
      "email"
   ],
   "deny": [ // запрещенные каналы связи
      "call"
   ]
}

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

POST https://<base-URL>/v1/card/{cardNumber}

Передача партнеру изменений персональных данных пользователя, владеющего картой лояльности. Как правило, при выпуске карты в теле сообщения всегда передаются значения полей: phone, email, surname, firstname, sex, birthDate.

Path Parameters

NameTypeDescription

cardNumber*

string

Номер карты лояльности

Request Body

NameTypeDescription

phone

string

Номер телефона без префикса +

email

string

Адрес электронной почты

surname

string

Фамилия

firstname

string

Имя

sex

string

Пол («м» или «ж»)

birthDate

string

Дата рождения в формате YYYY-MM-DD

patronymic

string

Отчество

locality

string

Название населенного пункта пребывания на момент выпуска карты

countryCode

string

ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2)

additionalParameters

array

Массив JSON-объектов

AdditionalParameter

с дополнительными параметрами, требуемыми для выпуска карты

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

Дополнительные параметры запроса передаются в виде массива 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.

Path Parameters

NameTypeDescription

cardNumber*

string

Номер карты, указанный пользователем

Request Body

NameTypeDescription

phone

string

Номер телефона без префикса +

email

string

Адрес электронной почты

surname

string

Фамилия

firstname

string

Имя

sex

string

Пол («м» или «ж»)

birthDate

string

Дата рождения в формате YYYY-MM-DD

patronymic

string

Отчество

locality

string

Название населенного пункта пребывания на момент выпуска карты

countryCode

string

ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2)

additionalParameters

array

Массив JSON-объектов

AdditionalParameter

с дополнительными параметрами, требуемыми для выпуска карты

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

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

Запрос у партнера номера новой карты лояльности, не привязанной ни к одному клиенту программы лояльности.

Резервирование происходит в случае, если поиск карты по данным профиля пользователя не принес результатов (пользователь не является клиентом программы лояльности). Вслед за этим запросом стоит ожидать запрос на выпуск по номеру ранее зарезервированной анонимной карты (ниже).

2337658900

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

GET /v1/card/anonymous

Правило обработки запроса

Реализация системы со стороны партнера должна гарантировать, что выданный номер карты будет зарезервирован (недоступен для повторного использования) в течение часа.

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

POST https://<base-URL>/v1/card/anonymous/{cardNumber}

В этот запрос передается номер анонимной карты, предварительно полученный запросом резервирования новой анонимной карты. Для выпуска происходит передача партнеру персональных данных пользователя. Как правило, в теле сообщения всегда передаются значения следующих полей: phone, email, surname, firstname, sex, birthDate.

Path Parameters

NameTypeDescription

cardNumber*

string

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

Request Body

NameTypeDescription

phone

string

Номер телефона без префикса +

email

string

Адрес электронной почты

surname

string

Фамилия

firstname

string

Имя

sex

string

Пол («м» или «ж»)

birthDate

string

Дата рождения в формате YYYY-MM-DD

patronymic

string

Отчество

locality

string

Название населенного пункта пребывания на момент выпуска карты

countryCode

string

ISO-код страны пребывания на момент выпуска карты (ISO 3166-1 alpha-2)

additionalParameters

array

Массив JSON-объектов

AdditionalParameter

с дополнительными параметрами, требуемыми для выпуска карты

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

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}

Вызывается для запроса состояния и баланса карты по ее номеру. Информация по карте запрашивается в момент выпуска карты по номеру, а также для запроса баланса. Полученные в ответе метода параметры передаются на экран баланса карты пользователя в Кошельке.

Path Parameters

NameTypeDescription

cardNumber*

string

Номер карты лояльности

{
   "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": ""   // дата, до которой бонусы действительны
           }
         ]
      }  
   }
}

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

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

В запросе передаются даты начала и окончания периода, полученные от Кошелька.

Path Parameters

NameTypeDescription

cardNumber*

string

Номер карты лояльности

startDate*

string

Начало периода: YYYY-MM-DD

endDate

string

Окончание периода: YYYY-MM-DD. Может отсутствовать (в таком случае равно текущей дате)

[
   {
      "date": "",     // дата операции YYYY-MM-DD
      "item": "",     // наименование товара
      "amount": "",   // стоимость товара в копейках (Число. Со знаком "-" - возврат покупки)
      "quantity": "", // кол-во единиц товара (число)
      "location": "", // место проведения операции
      "bonuses": ""   // начисленные "+" и списанные "-" бонусы за покупку (числа)
   }
]

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

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

Вызывается при переходе пользователя на экран выпущенной карты. Позволяет приложению «Кошелёк» получить и отобразить для пользователя на экране перечень специальных акций, доступных ему как владельцу карты лояльности.

Path Parameters

NameTypeDescription

cardNumber*

string

Номер карты лояльности

[
    {  // информация об акции
        "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. Не обязательно
        }
    }
    // аналогичные объекты {...} в массиве для остальных акций (через запятую)
]

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

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"
        }
    }
]

Last updated