Подключение к 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. Наименования параметров, заголовков и свойств объектов во всех запросах чувствительны к регистру.
Заголовки
В запросах необходимо передавать 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
Авторизационный токен используется для аутентификации в сервисе, он должен храниться в защищенном виде и месте.
Для проверки работы аутентификации можно выполнить тестовый метод:
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.