Подключение к API
Инвойсбокс API — это набор HTTP-ресурсов, к которым можно обращаться
следующими HTTP методами: GET, POST, PUT, DELETE.
Для каждого метода используется свой тип HTTP-запрос:
- Получить коллекцию ресурсов — запрос
GET - Получить ресурс — запрос
GET - Создать ресурс — запрос
POST - Изменить ресурс — запрос
PUT - Удалить ресурс — запрос
DELETE
Базовые URL
Если вы зарегистрировали магазин через приложение Инвойсбокс или по адресу app.invoicebox.ru, то следует использовать следующие адреса:
https://api.invoicebox.ru- для продуктового окружения или магазинов в тестовом режиме.
Какую версию брать
Новые интеграции делают на /v3/ — независимо от того, где зарегистрирован магазин.
Версия /l3/ осталась для тех, кто интегрировался раньше через личный кабинет
Инвойсбокс.Бизнес (business.invoicebox.ru): она поддерживает все методы и продолжает работать, но в
новой интеграции её брать не нужно. Если вы переписываете старую интеграцию — это повод перейти на
/v3/.
Нужно выделенное тестовое окружение — свяжитесь с нами.
Форматы данных
Тело запроса, если оно требуется, должно быть в формате json, кодировка UTF-8.
Важно
Наименования параметров, заголовков и свойств объектов во всех запросах чувствительны к регистру.
Заголовки
В запросах необходимо передавать HTTP-заголовки:
| Наименование | Значение | Комментарий |
|---|---|---|
| Content-Type | application/json | Обязательно |
| Accept | application/json | Обязательно |
| User-Agent | идентификатор приложения | Обязательно. Идентификатор приложения формируется в следующем формате: наименование приложения/версия (версия модуля, если применимо) {иные идентификаторы}. Пример заголовка и идентификатора для CMS Битрикс: User-Agent: Bitrix/21.0 (Инвойсбокс 3.0) |
| Authorization | Bearer <токен> | Обязательно для всех запросов. Как получить токен |
| X-Signature | подпись запроса | Обязательно в случае использование механизма подписи запроса |
Часовой пояс
Сервера Инвойсбокс хранят даты в нулевом часовом поясе (UTC). Задача преобразования дат и времени в нужный часовой пояс лежит на стороне клиента. Однако, как правило, свойства сущностей API для приёма и передачи времени используют формат ATOM, позволяющий получать и передавать часовой пояс. Важно не забывать передавать и обрабатывать такие данные.
Структура ответа
Все ответы возвращаются в формате json. В случае положительного ответа данные приходят в свойстве
data основного объекта.
Кроме data ответ содержит metaData и extendedData. Для коллекций в metaData приходят
totalCount, pageSize и page — по ним считается число страниц: перебирайте страницы, пока
page × pageSize < totalCount. Не путайте это metaData с одноимённым полем заказа, куда магазин
кладёт свои данные, — см. создание заказа.
Важно
Имена в запросе и в ответе отличаются подчёркиванием. Запрашивают страницу параметрами _page и
_pageSize, а в ответе те же величины лежат в metaData без подчёркивания — page и pageSize.
Скопировать имя из ответа в запрос не получится: без подчёркивания параметр игнорируется, и придёт
первая страница. Подробно — выборки и фильтры.
Пример ответа на получение единичной сущности
{
"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
Эта страница — про общие правила: адреса, заголовки, форматы, ошибки. Сами методы разложены по разделам:
| Раздел | Что внутри | С чего начать |
|---|---|---|
| Приём платежей | Заказы, возвраты, отгрузки, уведомления, документы, онлайн-касса — основной раздел, 68 страниц | Создание заказа |
| Проведение платежей | Работа со счетами и платёжными инструментами | Получение счёта |
| Инвойсбокс.Бизнес | Подтверждение оплаты из гарантийного фонда покупателя | Обзор раздела |
| Маркетплейс | Витрина поставщиков и мини-приложения на платёжной странице | Размещение магазина |
| Партнёрское API | Подключение магазинов партнёром, приглашения, вознаграждение | Обзор раздела |
| Справочники | Коды ошибок, ставки НДС, единицы измерения, признаки предмета расчёта | Коды ошибок |
Если вы ещё не выбирали способ интеграции, посмотрите сценарии по отраслям или соберите платёжный виджет — он работает без разработки.