# Инвойсбокс API — Подключение к API > Раздел документации целиком. Полное оглавление: https://docs.invoicebox.ru/llms.txt ## Подключение к API - [Авторизация](https://docs.invoicebox.ru/raw/api/auth.md) (раздел «Подключение к API») - [Выборки и фильтры](https://docs.invoicebox.ru/raw/api/filters.md) (раздел «Подключение к API») - [Использование веб-сокетов](https://docs.invoicebox.ru/raw/api/websockets.md) (раздел «Подключение к API») - [Подключение к API](https://docs.invoicebox.ru/raw/api/api.md) - [Логирование и отладка](https://docs.invoicebox.ru/raw/api/debug.md) (раздел «Подключение к API») - [Мониторинг](https://docs.invoicebox.ru/raw/api/monitoring.md) (раздел «Подключение к API») - [Ограничения](https://docs.invoicebox.ru/raw/api/limits.md) (раздел «Подключение к API») - [Работа в Postman](https://docs.invoicebox.ru/raw/api/postman.md) (раздел «Подключение к API») --- # Авторизация # Авторизация Для всех запросов к API обязательно должен присутствовать авторизационный токен, который можно получить после регистрации вашей организации в системе. В зависимости от [версии биллинга](/docs/api) и API, которые вы используете, авторизационный токен будет выглядеть следующим образом: Пример токена `v3`: `b37c4c689295904ed21eee5d9a48d42e` Пример токена `l3`: `29078-API:b37c4c689295904ed21eee5d9a48d42e` > [!IMPORTANT] > Для проверки интеграции и методов, а также проведения тестовых платежей вы можете воспользоваться параметрами демонстрационного магазина: > > Токен: `b37c4c689295904ed21eee5d9a48d42e` > > Идентификатор магазина: `ffffffff-ffff-ffff-ffff-ffffffffffff` > [!WARNING] > Авторизационный токен должен храниться в защищённом виде и месте. Используя токен, возможно получить доступ к методам API и данным от имени организации. Токен не следует хранить в общедоступных местах или передавать третьим лицам. При возможной компрометации значения токена (если вы считаете, что токен мог быть получен третьими лицами), вы должны незамедлительно изменить его в личном кабинете или сообщить об этом в [службу поддержки](https://www.invoicebox.ru/ru/contacts). Проверить токен и работу авторизации можно этим методом: #### 🌐 HTTP ```http GET /v3/security/api/auth/auth Accept: application/json User-Agent: MyApp 1.0 Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e ``` #### 🧊 CURL ```bash curl -L -X GET '{baseUrl}/v3/security/api/auth/auth' \ -H 'Accept: application/json' \ -H 'User-Agent: MyApp 1.0' \ -H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e' ``` {baseUrl} - [базовый URL](/docs/api) Если передан корректный токен, то ответ будет содержать HTTP код `200 OK` и идентификатор пользователя #### Пример ответа ```json { "data": { "userId": "01771533-8e75-3234-8e3d-9213ae2d7c52", "profile": null, "accessToken": null }, "extendedData": [] } ``` Если передан некорректный токен, то ответ будет содержать HTTP код `401 Unauthorized` и ошибку #### Пример ответа ```json { "error": { "message": "Unauthorized", "code": "unauthorized" } } ``` Если токен не передан, ответ придёт с HTTP-кодом `200 OK` и данными анонимного пользователя. > [!IMPORTANT] > Проверяйте не только код ответа. `200` с `userId: null` означает, что токен не передан или не > распознан, — это не успешная авторизация. Признак рабочего токена — непустой `userId`. > Этой же проверкой удобно следить за доступом — см. [мониторинг](/docs/api/monitoring/). #### Пример ответа ```json { "data": { "userId": null, "profile": null, "accessToken": null }, "extendedData": [] } ``` --- --- # Выборки и фильтры # Фильтры на выборки Запросы на получение списка сущностей поддерживают возможность применения следующих фильтров: - по соответствию поля заданному значению, например `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 элементов. > [!IMPORTANT] > Подчёркивание обязательно. Параметры `page` и `pageSize` без него API молча игнорирует: в ответ > приходит первая страница с тридцатью элементами, и `metaData.page` остаётся равным 1. Если вы > листаете выборку в цикле, сверяйте `metaData.page` с запрошенным номером — иначе цикл будет читать > одну и ту же страницу. ```http GET /v3/filter/api/order/order?_pageSize=5&_page=2 ``` ### Формат ответа выборки Выборка отвечает не массивом, а объектом с тремя свойствами: ```json { "data": [ /* найденные объекты */ ], "metaData": { "totalCount": 5965, "page": 1, "pageSize": 30 }, "extendedData": [] } ``` - `data` — сами объекты; когда ничего не нашлось, это пустой массив, а не отсутствующее поле; - `metaData.totalCount` — сколько записей подходит под фильтр целиком, а не на текущей странице: по нему считают число страниц; - `metaData.page` и `metaData.pageSize` — что сервер понял из запроса. Это же и проверка: если вы просили вторую страницу, а в ответе `page: 1`, значит параметры не приняты (частая причина — забытое подчёркивание); - `extendedData` — служебное поле, у выборок заказов пустое. Разбирать ответ нужно именно так: `response.data`, а не сам ответ как массив. Это общий формат всех выборок — заказов, возвратов, отгрузок, счетов. --- --- # Использование веб-сокетов # Использование веб-сокетов Инвойсбокс API поддерживает работу с веб-сокетами, для случаев, когда необходимо получить [уведомление](/docs/merchant/notification) об изменении статуса заказа (оплате), а также статусе интеграции без наличия публичного сервиса (домена, IP адреса), по которому система Инвойсбокс могла бы передать такое уведомление. Роли здесь перевёрнуты по сравнению с обычным уведомлением: магазин не принимает запрос, а сам держит соединение, и Инвойсбокс вызывает его метод по этому соединению. ```mermaid sequenceDiagram participant M as Магазин participant G as ws-gate Инвойсбокс participant B as Покупатель M->>G: подключение wss://…/v3/gate/rpc?token=… G-->>M: соединение установлено B->>G: оплата заказа на платёжной странице G->>M: вызов onOrderStatusChange M-->>G: ответ {"status":"success"} Note over M,G: без ответа уведомление придёт повторно ``` ### Точка подключения Основной адрес: `ws-gate.invoicebox.ru` При подключении [авторизационный токен](/docs/api/auth/) передается в query параметре token, например, `wss://ws-gate.invoicebox.ru/v3/gate/rpc?token=b37c4c689295904ed21eee5d9a48d42e` > [!IMPORTANT] > Для подключения к серверу веб-сокетов используется только версия API `/v3/`. ### Обработка уведомления об оплате заказа После поступления оплаты по заказу, при условии наличия активного WebSocket соединения с системой Инвойсбокс, система Инвойсбокс вызовет метод `onOrderStatusChange` с аргументом в виде объекта [OrderNotification](/docs/merchant/notification/status/#ordernotification) #### Пример уведомления ``` json { "jsonrpc" : "2.0", "id" : "01823fdac4b7a7b5a3ac", "method" : "onOrderStatusChange", "params": [ { "id" : "01823fda-667f-6ddb-02a3-c4b7a7b5a3ac", "description" : "Описание заказа", "currencyId" : "RUB", "amount" : 1487.52, "vatAmount" : 247.92, "basketItems" : [ ], "merchantId" : "0302756d-9d83-60c9-0356-c228562c7581", "status" : "completed", "subtype" : "order", "createdAt" : "2023-07-27T13:30:53+00:00", "merchantOrderId" : "1658928653", "expirationDate" : "2023-07-29T00:00:00+00:00", "metaData" : { "@type" : "LodgingReservation", "name" : "park inn" }, "fileIds" : { } } ] } ``` ### Обработка диагностической информации Для контроля корректности подключения устройств к сервису, а также их правильной настройки, система Инвойсбокс может вызывать метод `getStatus`. #### Пример запроса ``` json { "jsonrpc" : "2.0", "id" : "01823fdac4b7a7b5a3ac", "method" : "getStatus", "params": { "logQuantity" : 40 } } ``` #### Пример ответа ``` json { "jsonrpc" : "2.0", "id" : "01823fdac4b7a7b5a3ac", "method" : "getStatus", "result": { "version" : "2.1", "type" : "device", "settings" : { ... }, "log" : [ "Line 1", "Line 2", "Line 3" ] } } ``` --- --- # Подключение к API # Подключение к 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/`. Нужно выделенное тестовое окружение — [свяжитесь с нами](https://www.invoicebox.ru/ru/contacts). ### Форматы данных Тело запроса, если оно требуется, должно быть в формате `json`, кодировка `UTF-8`. > [!IMPORTANT] > Наименования параметров, заголовков и свойств объектов во всех запросах чувствительны к регистру. ### Заголовки В запросах необходимо передавать HTTP-заголовки: | Наименование | Значение | Комментарий | |---------------|------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Content-Type | application/json | Обязательно | | Accept | application/json | Обязательно | | User-Agent | идентификатор приложения | Обязательно. Идентификатор приложения формируется в следующем формате: наименование приложения/версия (версия модуля, если применимо) {иные идентификаторы}. Пример заголовка и идентификатора для CMS Битрикс: User-Agent: Bitrix/21.0 (Инвойсбокс 3.0) | | Authorization | `Bearer <токен>` | Обязательно для всех запросов. [Как получить токен](/docs/api/auth/) | | X-Signature | подпись запроса | Обязательно в случае использование механизма подписи запроса | ### Часовой пояс Сервера Инвойсбокс хранят даты в нулевом часовом поясе (UTC). Задача преобразования дат и времени в нужный часовой пояс лежит на стороне клиента. Однако, как правило, свойства сущностей API для приёма и передачи времени используют формат ATOM, позволяющий получать и передавать часовой пояс. Важно не забывать передавать и обрабатывать такие данные. ### Структура ответа Все ответы возвращаются в формате `json`. В случае положительного ответа данные приходят в свойстве `data` основного объекта. Кроме `data` ответ содержит `metaData` и `extendedData`. Для коллекций в `metaData` приходят `totalCount`, `pageSize` и `page` — по ним считается число страниц: перебирайте страницы, пока `page × pageSize < totalCount`. Не путайте это `metaData` с одноимённым полем заказа, куда магазин кладёт свои данные, — см. [создание заказа](/docs/merchant/order/create/). > [!IMPORTANT] > Имена в запросе и в ответе отличаются подчёркиванием. Запрашивают страницу параметрами `_page` и > `_pageSize`, а в ответе те же величины лежат в `metaData` без подчёркивания — `page` и `pageSize`. > Скопировать имя из ответа в запрос не получится: без подчёркивания параметр игнорируется, и придёт > первая страница. Подробно — [выборки и фильтры](/docs/api/filters/#постраничный-вывод). #### Пример ответа на получение единичной сущности ```json { "data" : { "id" : 1, "title" : "New title" } } ``` #### Пример ответа на получение коллекции сущностей ```json { "data" : [ { "id" : 1, "title": "Apple" }, { "id" : 2, "title" : "Orange" }, { "id" : 3, "title" : "Passion fruit" } ] } ``` #### В случае ошибки, код ответа HTTP будет >= 400, а ответ будет содержать свойство error ```json { "error":{ "message" : "Error", "code" : "unauthorized" } } ``` > > [!IMPORTANT] > Если запрос не соответствует описанному формату данных (контракту) метода - вернётся ошибка. ## Разделы API Эта страница — про общие правила: адреса, заголовки, форматы, ошибки. Сами методы разложены по разделам: | Раздел | Что внутри | С чего начать | |---|---|---| | [Приём платежей](/docs/merchant) | Заказы, возвраты, отгрузки, уведомления, документы, онлайн-касса — основной раздел, 68 страниц | [Создание заказа](/docs/merchant/order/create/) | | [Проведение платежей](/docs/payment) | Работа со счетами и платёжными инструментами | [Получение счёта](/docs/payment/) | | [Инвойсбокс.Бизнес](/docs/business) | Подтверждение оплаты из гарантийного фонда покупателя | [Обзор раздела](/docs/business/) | | [Маркетплейс](/docs/marketplace) | Витрина поставщиков и мини-приложения на платёжной странице | [Размещение магазина](/docs/marketplace/) | | [Партнёрское API](/docs/partner) | Подключение магазинов партнёром, приглашения, вознаграждение | [Обзор раздела](/docs/partner/) | | [Справочники](/docs/dictionary) | Коды ошибок, ставки НДС, единицы измерения, признаки предмета расчёта | [Коды ошибок](/docs/dictionary/error/) | Если вы ещё не выбирали способ интеграции, посмотрите [сценарии по отраслям](/docs/scenarios/) или соберите [платёжный виджет](/widgets/) — он работает без разработки. ## Читайте также - [Схемы и SDK: OpenAPI 3.1 и коллекция Postman](/schemas/) --- --- # Логирование и отладка # Логирование и отладка В ответе для каждого запроса к Инвойсбокс API будет присутствовать заголовок `X-Request-Id` — уникальный идентификатор запроса. Чтобы отладить работу вашего приложения и в дальнейшем получить от службы поддержки более детальное описание проблемы, сохраните или залогируйте этот идентификатор. Зная этот идентификатор, служба технической поддержки Инвойсбокс поможет найти и решить вашу проблему. --- --- # Мониторинг # Автоматическое тестирование интеграции и мониторинг Организация мониторинга доступности API платёжной системы — это важный шаг для поддержания стабильной и надёжной работы вашего сервиса. Если API временно недоступен, это может повлиять на обработку платежей, что, в свою очередь, может вызвать неудобства для ваших клиентов и повлиять на бизнес-процессы. Мониторинг позволяет своевременно обнаруживать и устранять возможные проблемы, минимизируя простои и обеспечивая бесперебойную работу вашего сервиса. Доступность API и корректность подключения проверяет запрос [авторизации](/docs/api/auth/). Доступность сервиса определяется HTTP ответом с кодом `200` и наличием заполненного параметра `userId` в структуре ответа. > [!IMPORTANT] > Для организации системы мониторинга доступности API и проверки корректности подключения можно настроить автоматизированные > запросы авторизации с определенной периодичностью. Это можно реализовать с помощью специализированных инструментов > мониторинга, таких как Prometheus, Grafana, Zabbix или облачных решений вроде AWS CloudWatch или Google Cloud Monitoring. > В рамках мониторинга система будет отправлять тестовые запросы авторизации к API, проверяя не только доступность сервиса, > но и корректность ответа, включая статус коды, время ответа и содержимое данных. В случае отклонений от ожидаемых > параметров система сможет оперативно уведомлять ответственных специалистов через email, SMS или мессенджеры, > что позволит быстро реагировать на возможные сбои и минимизировать их влияние на бизнес-процессы. --- --- # Ограничения # Ограничения Число и частота запросов к API Инвойсбокс ограничены. Параметры ограничения запросов могут быть изменены для каждой учётной записи или диапазонов IP индивидуально. Ограничения по умолчанию: - 100 запросов за 30 секунд для одной учётной записи - 500 запросов за 30 секунд для одного IP-адреса Если число запросов превышено, API вернёт ошибку с HTTP-кодом 429 (Too Many Requests). ## Читайте также - [Запросы мониторинга считаются в общий лимит учётной записи](/docs/api/monitoring/) --- --- # Работа в Postman # Работа в Postman [Postman](https://www.postman.com/downloads/) — это инструмент для работы с API, который позволяет отправлять запросы к сервисам и работать с их ответами. Для быстрого старта и упрощения работы, вы можете импортировать коллекцию Инвойсбокс API в Postman. Коллекция - это набор готовых запросов в соответствии с API. Имеется как [десктопное приложение](https://www.postman.com/downloads/), так и [веб версия](https://www.postman.com) Вы можете [скачать готовую коллекцию](https://www.postman.com/bold-space-873341/workspace/invoicebox-api-v3/collection/25303565-616ade6c-e654-4199-b80a-354e0592d5e2?action=share&creator=25303565) (набор запросов) Инвойсбокс API или создать собственную. 1. Для начала работы с Postman зарегистрируйтесь в сервисе. Для работы с API достаточно бесплатной учётной записи — на ней будет ограничение до 1000 запросов в месяц. Postman 2. Затем перейдите в рабочее пространство и создайте новую коллекцию Postman 3. Выберите blank collection Postman 4. Далее, для удобства нужно указать токен идентификации (магазина) для всей коллекции, чтобы не указывать его отдельно для каждого запроса Postman 5. Теперь возможно создать новый запрос Postman 6. Укажите метод, URL запроса, заполните заголовки и тело запроса Postman ---