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

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

Для каждого метода используется свой тип HTTP-запрос:

Получить коллекцию ресурсов — запрос GET
Получить ресурс — запрос GET
Создать ресурс — запрос POST
Изменить ресурс — запрос PUT
Удалить ресурс — запрос DELETE

Базовые URL

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

https://api.invoicebox.ru - для продуктового окружения или магазинов в тестовом режиме.

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

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

Тело запроса, если оно требуется, должно быть в формате json, кодировка UTF-8.

Наименования параметров, заголовков и свойств объектов во всех запросах чувствительны к регистру.

Заголовки

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

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

Часовой пояс

Сервера Инвойсбокс хранят даты в нулевом часовом поясе (UTC). Задача преобразования дат и времени в нужный часовой пояс лежит на стороне клиента. Однако, как правило, свойства сущностей API для приёма и передачи времени используют формат ATOM, позволяющий получать и передавать часовой пояс. Важно не забывать передавать и обрабатывать такие данные.

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

Все ответы возвращаются в формате 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"
  }
}

Если запрос не соответствует описанному формату данных (контракту) метода - вернётся ошибка.