Link Поиск Меню Развернуть Документ

Подключение к API

API Инвойсбокс представляет собой набор HTTP ресурсов, к которым можно обращаться следующими HTTP методами: GET, POST, PUT, DELETE.

Базовые URL

Если вы зарегистрировали магазин через приложение Инвойсбокс или по адресу app.invoicebox.ru, то следует использовать следующие адреса:

  • https://api.invoicebox.ru - для продуктового окружения.
  • https://api.stage.invbox.ru - для тестового окружения. Используется только в том случае, если для магазина было оформлено отдельное тестовое окружение.

Если вы зарегистрировали магазин в личном кабинете Инвойсбокс.Бизнес по адресу business.invoicebox.ru, то следует использовать следующую версию API в запросах: /l3/. Для остальных случаев - текущая версия /v3/.

Форматы данных

Тело запроса, если оно требуется, должно быть в формате json, кодировка UTF-8. :warning: Наименования параметров, заголовков и свойств объектов во всех запросах чувствительны к регистру.

Заголовки

В запросах необходимо передавать HTTP-заголовки:

Наименование Значение Комментарий
Content-Type application/json Обязательно
Accept application/json Обязательно
User-Agent идентификатор приложения Обязательно. Идентификатор приложения формируется в следующем формате: наименование приложения/версия (версия модулия, если применимо) {иные идентификаторы}. Пример заголовка и идентификатора для CMS Битрикс: User-Agent: Bitrix/21.0 (Invoicebox 3.0)
X-Signature подпись запроса Обязательно в случае использование механизма подписи запроса

Структура ответа

Все ответы возвращаются в формате json. В случае положительного ответа, данные приходят в свойстве data основного объекта.

Пример запроса получения единичной сущности:

{
  "data": {
    "id": 1,
    "title":
    "New title"
  }
}

Пример запроса получения коллекции сущностей:

{
  "data": [
      {
        "id": 1,
        "title": "Apple"
      },
      {
        "id": 2,
        "title":
        "Orange"
      },
      {
        "id": 3,
        "title":
        "Passion fruit"
      }
    ]
}

В случае ошибки, код ответа HTTP будет >= 400, а ответ будет содержать свойство error:

{
  "error":{
    "message": "Error",
    "code": "unauthorized"
  }
}

Аутентификация

Для всех запросов к API обязательно должен присутствовать авторизационный токен, который можно получить после регистрации Магазина. Пример: Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e

Тестовый Токен: b37c4c689295904ed21eee5d9a48d42e, тестовый Магазин: ffffffff-ffff-ffff-ffff-ffffffffffff

:warning: Авторизационный токен используется для аутентификации в сервисе, он должен храниться в защищенном виде и месте.

Для проверки работы аутентификации можно выполнить тестовый метод:

GET /v3/security/api/auth/auth
Accept: application/json
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e

Если данные верны, то в ответ будет содержать HTTP код 200 и тело:

{
  "data": {
    "userId": "01771533-8e75-3234-8e3d-9213ae2d7c52"
  }
}

Фильтры на выборки:

Запросы на получение списка сущностей поддерживают возможность применения следующих фильтров:

  • по соответствию поля заданному значению, например status=created
  • по массиву значений: status[]=created&status[]=completed
  • с применением операторов сравнения:
Оператор Описание Типы значений Пример
_eq равно все типы status[_eq]=created, эквивалент status=created
_ne не равно все типы status[_ne]=created
_gt строго больше int, float amount[_gt]=1000
_ge больше или равно int, float amount[_ge]=1000
_lt строго меньше int, float amount[_lt]=1000
_le меньше или равно int, float amount[_le]=1000
_start начинается с string name[_start]=John

Сортировки выборок

Для сортировки данных используется параметр _order. Ключом которого является имя свойства объекта, а значение - порядок сортировки. Сортировку можно проводить по нескольким полям, например: _order[categoryId]=asc&_order[name]=desc

Постраничный вывод

Для постраничного получения данных необходимо задать два параметра pageSize - количество элементов на странице и page - номер страницы, которую необходимо получить, например pageSize=5&page=2 если не указывается pageSize, то по умолчанию оно принимает значение 30.

Читать далее »