API для работы с картами

Версия документа: 1.0
Версия API: 0.1

Общие положения

В этом документе описан протокол взаимодействия с системой для получения информации по банковским картам.

Общие правила формирования запроса

Общей конечной точкой для всех запросов является /api/getinfo. Единым методом запроса является POST, в теле которого размещается информация о вызываемом методе и параметрах этого метода. В теле сообщения передается JSON. Все строковые данные кодируются в UTF-8. Ответ на запрос приходит также к формате JSON в кодировке UTF-8.

В каждом запросе присутствует 2 дополнительных заголовка:

  • заголовок BS-sid - ID сервиса, обращающегося к API;
  • заголовок BS-key - секретный ключ сервиса.

Если key относится не к тому sid, то ядро отвечает на запрос с кодом 403.

Во многих методах можно указать список интересующих контейнеров. Запрос в общем виде имеет следующий вид:

POST /api/getinfo
Content-Encoding: UTF-8
Content-Type: application/json
BS-sid: 0
BS-key: somekey
 
{
  "method": "foo",
  "scope": [
    "bar"
  ],
  "ids": [
    "id1",
    "id2"
  ],
  "version": "1.0"
}
  • «method» - это вызываемый метод. Его название написано в описании каждого из доступных методов. Передается строкой.
  • «scope» - список контейнеров с информацией, которая будет передана в ответе. К примеру, если интересует баланс карт, то в scope для метода «getcardinfobyuser» должно быть передано значение «balance». Параметр scope передается только списком. Если интересует только 1 контейнер, следует передать список с одним элементом. Элементы списка - строки.
  • «ids» - список id пользователей Бонусной системы. Если запрашивается информация только об одном пользователе, следует передать один элемент списка. Элементы списка - строки.
  • «version» - версия API. По умолчанию вызываются методы из последней версии.

Методы

Получение балансов карт

Запрос

Метод: getcardinfobyuser

Для получения балансов карт пользователей бонусной системы необходимо отправить запрос на /api/getinfo. В теле запроса необходимо указать следующие параметры:

Название параметра Тип поля Описание Обязательность Значение по умолчанию
method строка Название вызываемого метода Да -
scope список Список возвращаемых контейнеров (контейнер - строка) Да []
ids список Список пользователей, по которым нужно вернуть информацию (id - строка) Да []
version строка Версия API Нет latest

Возможные значения scope:

Значение Описание Тип значения в ответе
balance Значение баланса пользователя в десятичном формате. Дробная часть отделена точкой float

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

POST /api/getinfo
Content-Encoding: UTF-8
Content-Type: application/json
BS-sid: 0
BS-key: somekey

{
  "method": "getcardinfobyuser",
  "scope": [
    "balance"
  ],
  "ids": [
    "id1",
    "id2"
  ]
}
Ответ

В теле ответа содержится JSON-сериализованная информация о картах пользователей. Пример JSON ответа:

{
  "result": {
      "id1": {
        "cards": [
          {
            "masked_card": "card1",
            "balance": 123.19
          },
          {
            "masked_card": "card2",
            "balance": 513.84
          }
        ]
      },
      "id2": {
        "cards": [
          {
            "masked_card": "card1",
            "balance": 15187.48
          }
        ]
      }
    },
  "error": null
}

На верхнем уровне находится поле result, в котором находится список с id пользователей бонусной системы, указанных в параметре «ids». В объекте cards пользователя содержится список его карт. Значением поля masked_card является номер его карты, значением поля balance - значение баланса.

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

Запрос информации по карте по ID пользователя, которого нет в базе, вернёт пустое значение параметра result.

В случае, если запрос выполнился с ошибкой, её описание будет доступно по ключу error.

Получение кэшбэка системы

Запрос

Метод: getsystemfee

Путь запроса: /api/getinfo. В теле запроса необходимо указать следующие параметры:

Название параметра Тип поля Описание Обязательность Значение по умолчанию
method строка Название вызываемого метода Да -
refund число 1 - учитывать транзакции покупок и возвратов, 0 учитывать только транзакции покупок Да -
tsp список Список номеров ТСП, по которым вернуть размер кэшбэка системы (id - строка, число) Нет []
from строка Дата начала выборки транзакций в формате гггг-мм-дд (включая указанную дату) Нет -
to строка Дата окончания выборки транзакций в формате гггг-мм-дд (не включая указанную дату) Нет -
version строка Версия API Нет latest

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

POST /api/getinfo
Content-Encoding: UTF-8
Content-Type: application/json
BS-sid: 0
BS-key: somekey

{
  "method": "getsystemfee",
    "refund":0,
    "tsp": [
    "id1",
    "id2"
  ],
    "from":"2019-05-06",
    "to":"2019-05-11"
}
Ответ

В теле ответа содержится JSON-сериализованная информация о транзакциях с кэшбэком системы. Пример JSON ответа:

{
  "result": {
      <id пользователя 1>: {
         <id транзакции 1>: {
            "sum": "1.00",
            "cashback": "0.06",
            "tsp": "ООО ТСП 1",
            "date": "2019-05-06 12:33:30"
          },
          <id транзакции 2>: {
            "sum": "10.00",
            "cashback": "0.6",
            "tsp": "ООО ТСП 2",
            "date": "2019-05-08 11:17:35"
          },
      },
      <id пользователя 2>: {
        <id транзакции 8>: { ... }
      }  
      },
  "error": null
}

На верхнем уровне находится поле result, в котором содержатся словари с ключами - номерами участников в системе. В каждом словаре с ключом-номером участника, содержатся вложенные словари транзакций, ключ которых - идентификатор транзакции, а в значении - словарь со следующими параметрами:

  • «sum» - сумма транзакции в рублях, при возврате, отрицательная
  • «cashback» - кэшбэк системы в рублях, при возврате, отрицательный
  • «tsp» - наименование ТСП
  • «date» - дата транзакции в формате «гггг-мм-дд чч:мм:сс»

Если ключ словаря с транзакциями null, то транзакции совершены по непривязанной карте, выпущенной для бонусной системы.

В ответе будет присутствовать информация только по тем ТСП, которые зарегистрированы в бонусной системе.

Запрос по ТСП, которых нет в базе, вернет пустые значения в параметрах result и error.

В случае, если запрос выполнился с ошибкой, её описание будет доступно по ключу error.