Версия документа: 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. В теле запроса необходимо указать следующие параметры:

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

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

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,
            "card_id": 2048,
            "issue_date": null
          },
          {
            "masked_card": "card2",
            "balance": 513.84,
            "card_id": 123,
            "issue_date": null
          }
        ]
      },
      "id2": {
        "cards": [
          {
            "masked_card": "card1",
            "balance": 15187.48,
            "card_id": 456,
            "issue_date": "2020-02-14"
          }
        ]
      }
    },
  "error": null
}

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

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

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

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

Метод: getsystemfee

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

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

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.