2. Затем перейдите в рабочее пространство и создайте новую коллекцию
3. Выберите blank collection
4. Далее, для удобства нужно указать токен идентификации (магазина) для всей коллекции, чтобы не указывать его отдельно для каждого запроса
5. Теперь возможно создать новый запрос
6. Укажите метод, URL запроса, заполните заголовки и тело запроса
---
---
# Вход через Инвойсбокс ID
# Вход через Инвойсбокс ID
Инвойсбокс ID — единая учётная запись Инвойсбокса. Внешний сервис может пускать по ней своих
пользователей: человек нажимает «Войти», подтверждает вход на `id.invoicebox.ru` и возвращается к вам
уже авторизованным. Пароль, второй фактор и восстановление доступа остаются на стороне Инвойсбокса —
вам не нужно ни хранить пароли, ни делать формы регистрации.
## Что даёт готовый вход
- **Не нужно строить свой контур входа.** Регистрация, восстановление пароля, второй фактор, блокировка
после неудачных попыток, письма с подтверждением — всё это уже работает и поддерживается.
- **Пароли не попадают в ваш сервис.** Их нельзя утечь оттуда, где их нет: вы храните только сессию,
а требования к хранению секретов остаются на стороне Инвойсбокса.
- **Один вход на все продукты.** Пользователь, у которого уже есть учётная запись Инвойсбокса, входит в
ваш сервис без новой регистрации — и не заводит ещё один пароль.
- **Вызовы идут от имени человека.** Токен привязан к пользователю, поэтому в логах и в правах видно,
кто именно выставил счёт или запросил документы, — в отличие от общего сервисного токена магазина.
- **Стандарт, а не самодельный протокол.** OAuth 2.0 с PKCE поддерживают готовые библиотеки почти для
любого языка: подключение сводится к двум запросам и одному адресу возврата.
## Когда это нужно
- Сервис показывает пользователю его заказы, счета или документы из Инвойсбокса.
- Вы делаете кабинет для покупателей или партнёров и не хотите вести свою базу паролей.
- Нужно, чтобы вызовы API шли от имени конкретного человека, а не от сервисного токена магазина.
Если сервису нужен только приём платежей, вход не требуется: заказы создаются
[токеном магазина](/docs/api/auth/), а покупателю достаточно платёжной страницы.
## Что понадобится
| Что | Откуда взять |
|---|---|
| Идентификатор приложения (`applicationId`) | **только через службу поддержки** — см. ниже |
| Адрес возврата (`redirectUri`) | ваш адрес, его нужно прислать вместе с заявкой |
| Адрес Инвойсбокс ID | `https://id.invoicebox.ru` |
| Адрес API для обмена кода | `https://api.invoicebox.ru` |
## Как получить идентификатор приложения
Самостоятельной регистрации приложений пока нет. Идентификатор выдаёт
[служба поддержки](https://www.invoicebox.ru/ru/contacts) — напишите ей и укажите:
1. **название сервиса** и кратко, зачем нужен вход;
2. **адреса возврата** (`redirectUri`) — все, которые будете использовать, включая адрес для
разработки. Инвойсбокс ID вернёт пользователя только на заранее известный адрес: незарегистрированный
адрес — это ошибка, а не предупреждение;
3. контакт разработчика, с которым можно уточнять детали.
Секрет приложения запрашивать не нужно: приложения Инвойсбокс ID публичные, а подлинность обмена кода
подтверждает [PKCE](/docs/id/connect/) — секрет, который пришлось бы хранить в браузере или в мобильном
приложении, всё равно не был бы секретом.
## Что в разделе
- [Подключение](/docs/id/connect/) — поток авторизации по шагам, с кодом.
- [Справочник запросов](/docs/id/reference/) — параметры адреса авторизации, обмен кода, профиль, выход.
- [Сессия и безопасность](/docs/id/session/) — где держать токен, зачем `state`, какие ошибки бывают.
---
---
# Подключение
# Подключение
Инвойсбокс ID работает по OAuth 2.0, поток Authorization Code с расширением PKCE. Пользователь
подтверждает вход на стороне Инвойсбокса, ваш сервис получает одноразовый код и обменивает его на
токен — уже со своего сервера.
```mermaid
sequenceDiagram
participant U as Пользователь
participant S as Ваш сервис
participant ID as Инвойсбокс ID
participant API as API Инвойсбокс
U->>S: нажимает «Войти»
S->>S: создаёт verifier и challenge, запоминает state
S->>ID: переход на id.invoicebox.ru с applicationId и challenge
U->>ID: подтверждает вход
ID->>S: возврат на redirectUri с code и state
S->>API: POST /auth/token — code и verifier
API-->>S: accessToken
S->>API: GET /auth/auth — профиль по токену
API-->>S: userId и данные пользователя
```
## Шаг 1. Подготовьте PKCE
PKCE защищает обмен кода без секрета приложения: сервис создаёт случайную строку `codeVerifier`,
передаёт в Инвойсбокс ID только её хеш, а при обмене показывает исходную строку. Перехваченный код без
`codeVerifier` бесполезен.
```js
const b64url = (buf) =>
btoa(String.fromCharCode(...new Uint8Array(buf)))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
const random = (len = 64) => {
const arr = new Uint8Array(len);
crypto.getRandomValues(arr);
return b64url(arr.buffer).slice(0, len);
};
const codeVerifier = random(64);
const state = random(32);
const codeChallenge = b64url(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier)));
// verifier и state понадобятся после возврата — держите их в sessionStorage
sessionStorage.setItem('ib_pkce_verifier', codeVerifier);
sessionStorage.setItem('ib_oauth_state', state);
```
`state` — случайная строка, которую Инвойсбокс ID вернёт без изменений. Сравнив её после возврата, вы
убеждаетесь, что пришли из своего же запроса, а не по чужой ссылке.
## Шаг 2. Отправьте пользователя на Инвойсбокс ID
```js
const params = new URLSearchParams({
applicationId: 'ваш-идентификатор-приложения',
redirectUri: `${location.origin}/auth/callback/`,
state,
codeChallenge,
codeChallengeMethod: 'S256',
});
location.href = `https://id.invoicebox.ru/?${params}`;
```
`redirectUri` должен точно совпадать с тем, который вы прислали в
[службу поддержки](https://www.invoicebox.ru/ru/contacts) при получении идентификатора приложения:
Инвойсбокс ID возвращает пользователя только на заранее известный адрес.
## Шаг 3. Примите возврат
Инвойсбокс ID вернёт пользователя на `redirectUri` с параметрами `code` и `state`. Страница возврата
должна сверить `state`, забрать `codeVerifier` и отдать оба значения **на свой сервер** — обмен кода в
браузере оставил бы токен в JavaScript, откуда его достанет любой сторонний скрипт.
```js
const url = new URL(location.href);
const code = url.searchParams.get('code');
const returned = url.searchParams.get('state');
if (!code || returned !== sessionStorage.getItem('ib_oauth_state')) {
// чужой или повторно открытый адрес — вход не начинаем
location.replace('/');
} else {
await fetch('/api/auth/exchange', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ code, codeVerifier: sessionStorage.getItem('ib_pkce_verifier') }),
});
sessionStorage.removeItem('ib_pkce_verifier');
sessionStorage.removeItem('ib_oauth_state');
}
```
## Шаг 4. Обменяйте код на токен
Обмен делает ваш сервер:
```http
POST /v3/security/api/auth/token
Content-Type: application/json
Accept: application/json
{
"applicationId": "ваш-идентификатор-приложения",
"redirectUri": "https://ваш-сервис.ru/auth/callback/",
"code": "полученный-код",
"codeVerifier": "сохранённый-verifier"
}
```
В ответе приходит `accessToken` в свойстве `data`. Полный разбор ответа и остальных запросов — в
[справочнике](/docs/id/reference/).
Секрет приложения в запросе не нужен: приложения Инвойсбокс ID публичные, подлинность обмена
подтверждает `codeVerifier`.
## Шаг 5. Проверьте, кто вошёл
Токен без проверки ничего не значит: вызовите метод профиля и убедитесь, что `userId` не пустой.
```http
GET /v3/security/api/auth/auth
Authorization: Bearer полученный-токен
Accept: application/json
```
`200` с `userId: null` означает, что токен не передан или не распознан — это не успешный вход, см.
[авторизацию](/docs/api/auth/).
Дальше токен нужно положить в серверную сессию и не отдавать в браузер — как это сделать, описано в
[сессии и безопасности](/docs/id/session/).
## Читайте также
- [Справочник запросов](/docs/id/reference/)
- [Сессия и безопасность](/docs/id/session/)
---
---
# Справочник запросов
# Справочник запросов
## Адрес авторизации
Пользователя отправляют на `https://id.invoicebox.ru/` с параметрами в строке запроса.
| Параметр | Обязательный | Что означает |
|---|---|---|
| `applicationId` | да | идентификатор приложения, выданный службой поддержки |
| `redirectUri` | да | адрес возврата; должен совпадать с зарегистрированным |
| `state` | да | случайная строка; вернётся без изменений, по ней сверяется подлинность возврата |
| `codeChallenge` | да | SHA-256 от `codeVerifier` в base64url |
| `codeChallengeMethod` | да | `S256` |
Пример:
```
https://id.invoicebox.ru/?applicationId=my-service&redirectUri=https%3A%2F%2Fmy-service.ru%2Fauth%2Fcallback%2F&state=8f2c…&codeChallenge=k7Yb…&codeChallengeMethod=S256
```
После входа пользователь возвращается на `redirectUri` с параметрами `code` и `state`.
## Обмен кода на токен
- метод: `POST`
- ресурс: `/v3/security/api/auth/token`
- тело запроса — объект ниже
- вызывается **с сервера**: токен не должен попадать в браузер
| Свойство | Обязательное | Тип | Описание |
|---|---|---|---|
| `applicationId` | да | string | идентификатор приложения |
| `redirectUri` | да | string | тот же адрес, что в запросе авторизации |
| `code` | да | string | код из параметров возврата |
| `codeVerifier` | да | string | исходная строка, от которой считался `codeChallenge` |
| `clientSecret` | нет | string | только если для приложения выпущен секрет; публичным клиентам не нужен |
```http
POST /v3/security/api/auth/token
Content-Type: application/json
Accept: application/json
{
"applicationId": "my-service",
"redirectUri": "https://my-service.ru/auth/callback/",
"code": "e3b0c44298fc1c14",
"codeVerifier": "s9Zx1kQd…"
}
```
Ответ:
```json
{
"data": {
"accessToken": "b37c4c689295904ed21eee5d9a48d42e"
}
}
```
Токен может прийти строкой или вложенным объектом — в реализациях Инвойсбокса разбор устроен терпимо:
берётся `data.accessToken`, а если там объект, то `accessToken` внутри него. Код обмена одноразовый:
повторный запрос с тем же `code` завершится ошибкой.
## Профиль пользователя
- метод: `GET`
- ресурс: `/v3/security/api/auth/auth`
- заголовок: `Authorization: Bearer <токен>`
```json
{
"data": {
"userId": "01771533-8e75-3234-8e3d-9213ae2d7c52",
"profile": {
"firstName": "Пётр",
"lastName": "Смирнов",
"email": "buh@example.invbox.ru"
}
}
}
```
> [!IMPORTANT]
> Код `200` не означает успешную авторизацию. Ответ с `userId: null` приходит и тогда, когда токен не
> передан или не распознан. Признак рабочего токена — непустой `userId`.
Этим же запросом удобно проверять, жива ли сессия, перед показом страниц пользователя.
## Завершение сессии
- метод: `DELETE`
- ресурс: `/v3/security/api/auth/logout`
- заголовок: `Authorization: Bearer <токен>`
Запрос завершает сессию на стороне Инвойсбокса. Свои куки сервис удаляет сам — если оставить их, человек
останется «войденным» в интерфейсе с уже недействительным токеном.
## Читайте также
- [Подключение](/docs/id/connect/)
- [Сессия и безопасность](/docs/id/session/)
- [Авторизация запросов к API](/docs/api/auth/)
---
---
# Сессия и безопасность
# Сессия и безопасность
## Где держать токен
Токен доступа — это право действовать от имени человека. Он не должен попадать в JavaScript: любой
сторонний скрипт на странице, любое расширение браузера и любая XSS-уязвимость немедленно превращаются
в кражу доступа.
Рабочая схема:
1. код обменивает **сервер**, а не браузер;
2. полученный токен сервер кладёт в куку с флагами `HttpOnly`, `Secure` и `SameSite=Lax`;
3. браузер к API напрямую не ходит — запросы идут через ваш сервер, который подставляет токен.
```
Set-Cookie: sid=<токен>; Path=/; HttpOnly; SameSite=Lax; Secure; Max-Age=43200
```
Срок жизни сессии выбирает сервис. Удобный вариант — 12 часов со скользящим продлением: пока человек
работает, сессия продлевается, а забытая на чужом компьютере закрывается сама.
Если интерфейсу нужно показать, что сессия скоро истечёт, кладите рядом **вторую** куку без `HttpOnly` —
с одной лишь отметкой времени. Токен при этом остаётся недоступным для скриптов.
## Зачем `state` и PKCE
| Что | От чего защищает |
|---|---|
| `state` | подмена возврата: без сверки злоумышленник может привести пользователя по своей ссылке с чужим кодом |
| `codeVerifier` (PKCE) | перехват кода: код без исходной строки не обменивается на токен |
| зарегистрированный `redirectUri` | угон кода на чужой адрес |
Все три проверки обязательны. `state` и `codeVerifier` держите в `sessionStorage` — они нужны ровно до
возврата и не должны жить дольше вкладки. После обмена удаляйте оба.
## Требования к адресу возврата
- Адрес присылается в [службу поддержки](https://www.invoicebox.ru/ru/contacts) вместе с заявкой на
идентификатор приложения. Незарегистрированный адрес не сработает.
- Боевой адрес — только `https`. Для разработки запросите отдельный адрес и отдельный идентификатор
приложения, чтобы боевой не пришлось отдавать на локальную машину.
- Адрес в запросе авторизации и в обмене кода должен совпадать посимвольно, включая завершающий слэш.
- Не ведите возврат на страницу, которая сама по себе перенаправляет пользователя дальше по адресу из
параметра: так открывается дыра в чужой сайт. Куда вернуть человека после входа, храните у себя —
и принимайте только внутренние пути.
## Ошибки при входе
| Что произошло | Что видно | Что делать |
|---|---|---|
| `redirectUri` не зарегистрирован или не совпал | возврат не происходит, Инвойсбокс ID показывает ошибку | сверить адрес с тем, что зарегистрирован, вплоть до слэша |
| `state` не совпал | ваша страница возврата не должна продолжать вход | начать вход заново; повторный переход по старой ссылке — нормальная причина |
| код уже использован | обмен отвечает ошибкой | код одноразовый: повторный обмен не делают, нужен новый вход |
| токен не принят | `200` с `userId: null` | считать, что входа нет: очистить куки и предложить войти снова |
| Инвойсбокс ID недоступен | обмен не завершился | показать человеку, что вход временно недоступен, и не создавать пустую сессию |
## Читайте также
- [Подключение](/docs/id/connect/)
- [Справочник запросов](/docs/id/reference/)
- [Безопасность интеграции](/docs/security/)
---
---
# Платёжные инструменты для B2B
# Платёжные инструменты для B2B
Покупатель-организация платит не так, как физлицо: деньги идут через банк, а не с карты, и продавцу
приходится ждать. Инвойсбокс предлагает пять инструментов, которые по-разному решают одну задачу —
сократить это ожидание, не ломая привычный корпоративной бухгалтерии порядок.
Инструмент выбирается в договоре и настройках магазина, а не в каждом запросе:
[создание заказа](/docs/merchant/order/create/) выглядит одинаково для всех пяти.
## Чем они отличаются
| Инструмент | Что делает покупатель | Когда продавец видит подтверждение | Кому подходит |
|---|---|---|---|
| Классическая оплата по счёту | Получает счёт, оплачивает из своего банка | Часы или дни — по мере прохождения платежа | Поставки с длинным циклом, вариант по умолчанию |
| Ускоренная классическая | Выбирает свой банк и подтверждает готовое платёжное поручение в интернет-банке | Минуты | Постоянные покупатели, которым нужен расчёт в один шаг |
| Обещанный платёж | Подтверждает картой, затем в течение 5 дней платит переводом | Около минуты | Товары со сроком: билеты, бронирования, заказы на кассе |
| Гарантийный фонд | Организация пополняет баланс, сотрудник подтверждает покупку кодом | Секунды | Регулярные закупки: такси, питание, расходники |
| Гарантийный фонд с овердрафтом | То же, но баланс может уходить в минус в пределах лимита | Секунды | Проверенные корпоративные клиенты с большим оборотом |
## Классическая и ускоренная оплата по счёту
Классическая — это обычный банковский перевод. Система выставляет счёт, он уходит покупателю
автоматически или через менеджера магазина, покупатель платит из своего банка. Перевод идёт до трёх
банковских дней; когда деньги приходят, система ставит отметку об оплате и сообщает магазину
[уведомлением о смене статуса](/docs/merchant/notification/status/). Этот способ доступен по
умолчанию для заказов, у которых срок оплаты не меньше восьми часов.
Ускоренная — надстройка над тем же переводом. Сигнал об оплате приходит мгновенно, а деньги могут
поступить позже; факт оплаты фиксируется по сигналу, поэтому продавец не ждёт зачисления. Так
работают СБП, [Запрос о платеже](/docs/scenarios/rtp/) по QR-коду и банк-клиент, где покупатель
подтверждает уже сформированный платёж на сайте своего банка.
## Обещанный платёж
Инструмент для случаев, когда товар нельзя держать: место в самолёте, номер в отеле, заказ на кассе АЗС.
1. Покупатель подтверждает заказ картой — личной, кредитной или корпоративной. Инвойсбокс блокирует
на ней сумму счёта вместе с банковской комиссией. Подтверждение занимает около минуты, и продавец
сразу выдаёт товар или услугу.
2. Сразу после блокировки покупателю уходит счёт от лица организации или ИП со сроком оплаты пять
суток — так расход правильно ложится в бухгалтерию.
3. Оплатил в срок — блокировка снимается полностью, вместе с комиссией.
4. Не оплатил — сумма списывается с карты, и заказ считается оплаченным картой.
Каждый шаг сопровождается письмом покупателю; при списании с карты выдаётся чек. Для продавца всё
выглядит как обычная оплата: приходит уведомление о смене статуса, заказ считается оплаченным.
## Отсрочка за счёт системы
Отсрочка доступна постоянным покупателям, заключившим договор с Инвойсбоксом. Допустимая сумма
рассчитывается автоматически: в её пределах покупатель подтверждает оплату заказов и рассчитывается
в течение 30 дней. Комиссии и правила риск-менеджмента определяет договор.
Для продавца отсрочка не меняет ничего: деньги приходят в обычный срок, риск неплатежа берёт на себя
система.
## Гарантийный фонд
Организация заранее пополняет баланс в Инвойсбоксе, а сотрудники тратят его в пределах своих
полномочий, подтверждая каждую покупку кодом. Продавец получает подтверждение за секунды: деньги
уже лежат на балансе организации, ждать банковский перевод не нужно.
Отсрочка добавляется сверх фонда: если на балансе 10 000 ₽, а покупка стоит 15 000 ₽, система
подтвердит оплату и даст отсрочку на недостающие 5 000 ₽. Лимит рассчитывается индивидуально.
Механику подтверждения покупки описывают методы
[подтверждения оплаты](/docs/merchant/guarantee/): проверка кода, списание, отмена.
> [!NOTE]
> Не путайте гарантийный фонд с [холдированием средств](/docs/scenarios/guarantee/): фонд —
> это предоплаченный баланс организации, а холдирование — резерв на карте покупателя под
> заказ с плавающей суммой.
## Что настраивается, а что приходит в запросе
| Что | Где определяется |
|---|---|
| Набор доступных инструментов | Договор и настройки магазина в личном кабинете |
| Сроки и лимиты | Договор; типовые значения — на странице [сроков и условий](/docs/terms/) |
| Состав и сумма заказа | [Создание заказа](/docs/merchant/order/create/) |
| Тип плательщика | Поле `customer.type` в запросе: `legal` для организаций и ИП |
| Способ оплаты | Выбирает покупатель на [платёжной странице](/docs/merchant/payment-page/) |
## Что дальше
- [Схема с юрлицами](/docs/merchant/schema/legal/) — какие документы формируются и когда.
- [Сроки и условия расчётов](/docs/terms/) — когда деньги оказываются на счёте продавца.
- [Сценарии по отраслям](/docs/scenarios/) — как эти инструменты выглядят в жизни.
---
# Онлайн касса (ФЗ-54)
# Онлайн касса (ФЗ-54)
Электронный чек оформляет система «Инвойсбокс» (ООО «ОРЦ») в момент получения оплаты от Покупателя. Данные о чеке отправляются через
ОФД в ФНС. ОФД отправляет чек по адресу электронной почты Покупателя.
> [!IMPORTANT]
> В соответствии с 54-ФЗ, чек должен выдаваться/оформляться в момент расчёта. Поскольку ООО «ОРЦ» (система «Инвойсбокс») уполномочено
получать оплаты за товары и услуги, момент расчёта с покупателем наступает у ООО «ОРЦ», соответственно, обязательства по оформлению
чеков возникает у ООО «ОРЦ». Чеки оформляет система «Инвойсбокс» (ООО «ОРЦ») на собственных ККТ.
В соответствии с 54-ФЗ, среди обязательных данных, в чеке также указываются номенклатура товара, стоимость, наименование поставщика,
ИНН, адрес интернет-магазина в сети Интернет. Дополнительно, может быть передана информация о [маркированном товаре](/docs/merchant/honest-sign/).
> [!IMPORTANT]
> Очень важно, что бы при оформлении заказа вы полностью указывали номенклатуру так как она будет отражена в чеке в соответствии с 54-ФЗ.
Номенклатура должна быть отражена в том же виде, что и в вашей отчётности. Если номенклатура отражена неправильно, покупатель вправе
направить жалобу в ФНС.
> [!WARNING]
> Номенклатура в чеке должна быть конкретизирована до уровня чёткого понимания того, что Покупатель оплатил в вашем магазине.
> Нельзя просто написать: Заказ/бронь №ХХХХ, нужно чётко указать наименование товара или услуги, например: "Полёт в Аэротрубе заказ № ХХХХ", "[Проездной билет на автобус, 90 дней](https://troika.invoicebox.ru)" или "[Бронирование отеля с 01.06.2023 по 14.06.2023, отель Ромашка, 1 взрослый](https://hotelotel.ru)".
---
---
# Честный знак
# Честный знак
## Как передать маркировку в заказ
Товарная группа указывается в позиции корзины при
[создании заказа](/docs/merchant/order/create/#basketitem): поле `categoryType` со значением
`honestSign` и поле `category` с кодом группы из таблицы ниже — например, `milk` для молочной
продукции. Если у магазина свой справочник категорий, в `categoryType` передаётся
`merchantHonestSignMap`.
Без этих полей заказ создастся, но сведения о маркировке в чек не попадут.
[Честный знак](https://xn--80ajghhoc2aj1c8b.xn--p1ai/) — это национальная система маркировки и прослеживания продукции.
Специальный цифровой код гарантирует подлинность и качество товара. Основная задача системы — повышение уровня безопасности
россиян, борьба с контрафактом и некачественными аналогами.
Система Инвойсбокс может получать, обрабатывать и передавать необходимую информацию о маркировке товара в системах Честный знак и ЭДО
в соответствии с бизнес-требованиями поставщика товаров (магазина).
## Справочник "Список поддерживаемых товарных групп"
| Код | Наименование | Описание | Сочетание |
|-----|--------------|--------------------------------------------------------------------------|-----------|
| 1 | lp | Предметы одежды, бельё постельное, столовое, туалетное и кухонное | 2 |
| 2 | shoes | Обувные товары | 2 |
| 3 | tobacco | Табачная продукция | 1 |
| 4 | perfumery | Духи и туалетная вода | 2 |
| 5 | tires | Шины и покрышки пневматические резиновые новые | 2 |
| 6 | electronics | Фотокамеры (кроме кинокамер), фотовспышки и лампывспышки | 2 |
| 8 | milk | Молочная продукция | 3 |
| 9 | bicycle | Велосипеды и велосипедные рамы | 2 |
| 10 | wheelchairs | Медицинские изделия | 2 |
| 12 | otp | Альтернативная табачная продукция | 1 |
| 13 | water | Упакованная вода | 4 |
| 14 | furs | Товары из натурального меха | |
| 15 | beer | Пиво, напитки, изготавливаемые на основе пива, слабоалкогольные напитки | 5 |
| 16 | ncp | Никотиносодержащая продукция | 1 |
| 17 | bio | Биологически активные добавки к пище | 2 |
| 19 | antiseptic | Антисептики и дезинфицирующие средства | 2 |
| 21 | seafood | Морепродукты | 3 |
| 22 | nabeer | Безалкогольное пиво | 4 |
| 23 | softdrinks | Соковая продукция и безалкогольные напитки | 4 |
---
---
# Данные для интеграции
# Где взять данные для интеграции с Инвойсбокс
**Все интеграционные данные находятся в [личном кабинете](https://business.invoicebox.ru/Login)**
Проведение тестовых платежей будет доступно после регистрации и создания магазина
> [!NOTE]
> Интеграция нужна не всегда: счёт можно выставить вручную прямо в кабинете — с QR-кодом для оплаты
> через СБП и отчётными документами. Это бесплатно, подробности и регистрация — на странице
> [бесплатного выставления счёта](https://www.invoicebox.ru/ru/free-invoice).
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## API V2
Во вкладке "Мои продажи" -> "Мои магазины" необходимо выбрать нужный магазин и перейти во вкладку "Интеграция (API)".
Отсюда потребуются:
1) Идентификатор магазина
2) Региональный код
3) API ключ
4) API пароль
5) API пользователь (нужен не для всех модулей)
**Не забудьте сохранить введённые данные**
### Тестовые данные
1) Идентификатор магазина - 207
2) Региональный код магазина - 78054
3) API пользователь - 78054-API
4) API Пароль - LM936s#3jz0
5) API ключ - LdjmgMS1WMS0nAIklbDkvuKT7WxaJIoC
## API L3
Во вкладке "Мои продажи" -> "Мои магазины" необходимо выбрать нужный магазин и перейти во вкладку "Интеграция (API)".
Отсюда потребуются:
1) Идентификатор магазина
2) API ключ
3) API токен
**Не забудьте сохранить введённые данные**
### Тестовые данные
## API L3
1) Идентификатор магазина - 91cb0d9a-bc9b-4420-bf2d-fd44bc9f8657
2) API ключ - QrUSjD1ZlsMbg2RNCXibRX6sKZ7FWzBh
3) API токен - 25622-API:1b3a082f38ae682ed9d2aaa5c7bb2735c43b9c7282418545bc2235a9b4bf23ad
## API V3
1) Идентификатор магазина - ffffffff-ffff-ffff-ffff-ffffffffffff
2) API ключ - 098f6bcd4621d373cade4e832627b4f6
3) API токен - b37c4c689295904ed21eee5d9a48d42e
## URL для уведомлений
Также необходимо заполнить графу "URL уведомления", сюда сервер Инвойсбокс будет отправлять запрос для подтверждения оплаты заказа.
Это URL указан в инструкции, если используется модуль для CMS.
При интеграции по API вам нужно будет указать свой адрес
О том, как работает обработка уведомлений можно узнать [здесь](https://docs.invoicebox.ru/docs/merchant/notification)
---
# Приём платежей
# Методы для организации приёма платежей
Описываемые методы предназначены для интернет-магазинов, веб-сервисов и приложений, с его помощью можно произвести
интеграцию с платёжным решением системы «Инвойсбокс». Обратите внимание, что далее будут описаны базовые
функции протокола.
### Какие функции позволяют реализовать описываемые методы?
1. Создавать заказы и направлять счета для покупателей;
2. Получать информацию и управлять сформированными заказами;
3. Получать информацию об оплате заказов;
4. Возвращать деньги покупателям по оплаченным заказам;
### Готовые библиотеки и компоненты
Описываемые методы реализованы в [SDK](/docs/merchant/sdk), готовых [модулях для CMS](/docs/merchant/cms),
[модулях для CRM](/docs/merchant/crm) и [модулях для ERP](/docs/merchant/erp). Для быстрого старта, вы также
можете воспользоваться [платёжными виджетами](/docs/merchant/widget).
### Кто может подключиться
Инвойсбокс работает с организациями и индивидуальными предпринимателями.
Самозанятые на налоге на профессиональный доход не обслуживаются.
Договор запрещает принимать оплату за ряд товаров и услуг. Коротко: всё, что нарушает
законодательство России; наркотики, стероиды и контролируемые вещества; лекарственная атрибутика;
алкоголь и табак; краденое, включая цифровое; материалы сексуального характера; нарушение авторских,
патентных и смежных прав; оружие, боеприпасы и регулируемые ножи; персональные данные третьих лиц;
финансовые пирамиды и схемы быстрого обогащения; рента и лотерейные контракты; обмен валюты и
обналичивание чеков; реструктуризация кредитов; финансирование политических партий; вероятные
подделки; программы и медиа без прав на распространение.
Полный перечень — в пункте 5 договора. Если ваш случай близок к границе, спросите менеджера до
интеграции, а не после.
### Что доступно на бесплатном тарифе
Без оплаты работают выставление счёта, оплата по счёту на расчётный счёт поставщика и мгновенная
оплата через СБП по QR-коду. При этом поступление оплаты по счёту магазин отслеживает сам и сам же
оформляет отчётные документы.
На платном тарифе прохождение платежей и оформление документов для покупателя происходит
автоматически — это и есть основная разница. Условия: https://www.invoicebox.ru/ru/free-invoice
### Перед началом работы
Для работы с методами понадобятся:
- **идентификатор магазина** — выдаётся при подключении к Инвойсбоксу;
- **API-токен и ключ проверки подписи** — без токена не пройдёт ни один запрос, ключом проверяется
подпись уведомлений; где их взять — [данные для интеграции](/docs/merchant/integrationdata/);
- **адрес для уведомлений** — куда Инвойсбокс будет присылать
[уведомление о смене статуса заказа](/docs/merchant/notification/status/).
Как передавать токен в запросах — в разделе [авторизации](/docs/api/auth/). Если чего-то из этого нет,
запросите у своего менеджера или у службы поддержки.
---
---
# Платёжная страница
# Платёжная страница
Платёжная страница — единственное, что покупатель видит от Инвойсбокса. Магазин
[создаёт заказ](/docs/merchant/order/create/) и переадресует на неё покупателя; тот выбирает способ
оплаты, платит и возвращается обратно на сайт магазина.
Адрес страницы приходит в ответе на создание заказа — поле `paymentUrl`
[в OrderResponse](/docs/merchant/order/create/#orderresponse). Его открывают переадресацией или
кодируют в QR-коде, если покупатель платит на месте.
## Что видит покупатель
Набор способов зависит от того, кем он платит. Тип задаётся полем `customer.type` при создании заказа
либо выбирается на самой странице, если магазин разрешил выбор.
| Способ оплаты | Физическое лицо | Организация или ИП | Что формируется по итогу |
|---|---|---|---|
| Банковская карта | да | да | Фискальный чек, [онлайн-касса](/docs/merchant/fz54/) |
| СБП по QR-коду | да | да | Фискальный чек |
| СБП B2B | нет | да | Счёт и закрывающие документы |
| Оплата по счёту | нет | да | Счёт, затем акт, счёт-фактура и УПД после оплаты |
| Отсрочка платежа | нет | да | Те же документы, деньги продавцу приходят сразу ([сроки](/docs/terms/)) |
| [Обещанный платёж](/docs/merchant/payment-instruments/) | нет | да | Подтверждение картой, оплата переводом в течение 5 дней |
| [Гарантийный фонд](/docs/merchant/payment-instruments/) | нет | да | Списание с баланса организации, подтверждение кодом |
Реквизиты организации страница проверяет на месте: при неверном ИНН покупатель увидит
сообщение об ошибке, а неправильно заполненные поля будут подсвечены — оплатить с
некорректным ИНН не получится.
Физлицо получает чек, организация — комплект документов. Отсюда простое правило: если в вашем сценарии
важны закрывающие документы, передавайте `customer.type: legal` и реквизиты организации.
## Что настраивается магазином
- **Возврат покупателя.** Адреса `itransfer_url_return` и `itransfer_url_returnsuccess` в
[виджете](/widgets/constructor/) либо соответствующие поля заказа в API.
- **Срок жизни счёта.** Поле `expirationDate`: по его истечении неоплаченный заказ можно
[отменить](/docs/merchant/order/delete/).
- **Язык страницы.** Поле `languageId` при создании заказа: `ru` или `en`.
- **Дополнительные услуги.** Если магазин подключён к [маркетплейсу](/docs/marketplace/), покупателю
на странице оплаты предлагаются сопутствующие предложения партнёров.
## Как узнать об оплате
Возврат покупателя на страницу «спасибо» ничего не доказывает: этот адрес открывается в браузере и его
можно набрать руками. Единственный надёжный сигнал —
[уведомление о смене статуса заказа](/docs/merchant/notification/status/). По нему запускайте отгрузку,
выдачу услуги и всё остальное. Для сверки пригодится
[получение заказа](/docs/merchant/order/get/).
## Что дальше
- [Платёжные инструменты для B2B](/docs/merchant/payment-instruments/) — чем отличаются способы оплаты для организаций и ИП.
- [Схемы документооборота](/docs/merchant/schema/) — какие документы формируются в каждой схеме.
- [Готовые модули CMS](/docs/merchant/cms) — если не хочется собирать переадресацию руками.
---
---
# Уведомление о смене статуса
# Уведомление по умолчанию
Если в настройках Магазина была активирована опция отправки автоматических уведомлений о смене
статуса Заказа, то при поступлении оплаты в пользу Заказа, система «Инвойсбокс»
осуществит запрос на специальный URL, который указан в настройках Магазина.
На указанный URL будет осуществлен `POST` запрос с `Content-Type: application/json` в теле которого будет находиться объект [OrderNotification](#ordernotification).
## OrderNotification
Повторяет структуру [OrderResponse](/docs/merchant/order/create/#orderresponse), основные поля:
| Свойство | Обязательное | Тип | Описание |
|------------------------|--------------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| id | да | string(36) | Идентификатор заказа в системе «Инвойсбокс», например: `01771534-1a57-f184-dee3-ebeb91dded75` |
| status | да | string(50) enum | Статус заказа: `created`, `hold`, `completed`, `expired`, `canceled`. Оплаченным считается только `completed` — перечень и переходы на странице [работы с заказом](/docs/merchant/order/) |
| merchantId | да | string(36) | Идентификатор магазина, например: `01771534-1a57-f184-dee3-ebeb91dded76` |
| merchantOrderId | да | string(100) | Идентификатор заказа в учётной системе магазина, например: `O-12345` |
| merchantOrderIdVisible | нет | string(100) | Номер заказа, отображаемый на платежной странице. Если не заполнено, показывается значение из merchantOrderId например `111TN22-33` |
| amount | да | float | Сумма заказа, например: `19658.45` |
| customer | да | [Customer](/docs/merchant/order/create/#customer) | Информация о заказчике |
| currencyId | да | string(3) enum | Валюта заказа, например: `RUB`, `USD`,`EUR`, `GBP` |
| createdAt | да | datetime | Дата создания заказа, например: `2026-12-22T00:00:00+00:00` |
Заказ считается оплаченным, если его статус равен `completed`. В этом случае Магазин должен сверить
сумму Заказа в запросе с суммой Заказа в своей системе учёта. Если не совпадает, в обработке запроса
нужно отказать и вернуть ошибку.
Перечень статусов закрытый: кроме пяти перечисленных, других не бывает. Статусов вида `refunded` или
`partial_refund` в заказе нет — возврат оформляется [отдельным заказом](/docs/merchant/refund/create/)
со своими статусами (`draft`, `created`, `completed`, `canceled`), а сам заказ после возврата остаётся
`completed`.
# Формат ответа
В случае успешности обработки запроса веб-сервис Магазина должен вернуть объект [NotificationSuccess](#notificationsuccess), а в случае осознанной ошибки обработки (например, неверная сумма, заказ не найден, ошибка подписи и т.п.) - [NotificationError](#notificationerror).
> [!IMPORTANT]
> **И успешный, и осознанно-ошибочный ответ должны возвращаться с HTTP-кодом 200.** HTTP-код 200 сам по себе не означает успех — успехом считается только связка **HTTP 200 + `{"status":"success"}`** в теле. Связка **HTTP 200 + `{"status":"error", "code": ...}`** — это тоже штатный, ожидаемый ответ, просто сигнализирующий об осознанной ошибке обработки (см. [NotificationErrorCode](#notificationerrorcode)).
>
> Любой ответ с HTTP-кодом, отличным от 200 (а также ответ без валидного JSON в теле), система «Инвойсбокс» трактует не как конкретный код ошибки из тела, а как **техническую недоступность веб-сервиса Магазина** — то есть равносильно `out_of_service`, независимо от того, что написано в `code`. Такие запросы будут повторены ещё до 10 раз в течение суток (см. [NotificationErrorCode](#notificationerrorcode)).
>
> Другими словами: `code` в теле ответа имеет смысл, только если HTTP-код равен 200. Если веб-сервис Магазина вернул, например, HTTP 400 или 401 — тело ответа не разбирается, и запрос будет повторён как при `out_of_service`, даже если в теле был указан другой код ошибки (например, `signature_error`).
## NotificationSuccess
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------|-----------------------------------------------------------------------|
| status | да | string(50) | В случае успешной обработки допустимо только одно значение - `success` |
Пример объекта NotificationSuccess:
```json
{
"status" : "success"
}
```
## NotificationError
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------------|---------------------------------------------------------------------------------------------------------------------|
| status | да | string(50) enum | В случае ошибки обработки запроса допустимо только одно значение - `error` |
| code | нет | string(100) enum | Код ошибки - значение из справочника [NotificationErrorCode](#notificationerrorcode), по умолчанию `out_of_service` |
| message | нет | string(500) | Детальное описание ошибки в текстовом формате |
Пример объекта NotificationError:
```json
{
"status" : "error",
"code" : "order_wrong_amount",
"message" : "Сумма заказа не соответствует сумме оплаты"
}
```
## NotificationErrorCode
| Код ошибки | Описание |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `out_of_service` | Техническая ошибка обработки запроса веб сервером Магазина, при получении этого кода ошибки система «Инвойсбокс» будет пытаться повторить этот запрос еще 10 раз в течение последующих суток. |
| `order_wrong_amount` | Сумма заказа в Магазине не соответствует сумме заказа в уведомлении |
| `order_already_paid` | Заказ уже оплачен другим инструментом оплаты |
| `order_not_found` | Заказ не найден в учётной системе Магазина |
| `shipping_unavailable` | [Услуга не может быть оказана или товар не может быть доставлен](/docs/merchant/notification/shipping-unavailable/) |
| `full_refund_required` | То же самое что `shipping_unavailable` с автоматическим формированием возврата или отмены оплаты |
| `signature_error` | Ошибка проверки подписи запроса |
> [!IMPORTANT]
> Обратите внимание, в случае, если аналогичный запрос с тем же идентификатором (id) уже был обработан ранее
> успешно в вашей системе, то в этом случае следует вернуть статус успешной обработки уведомления status = `success`.
>
> В случае, если заказ в вашей системе был оплачен ранее уведомлением с другим идентификатором (id) или иным платёжным инструментом,
> то следует вернуть ошибку status = `error`, code = `order_already_paid`.
## Время выполнения запроса
Существует лимит ожидания ответа от веб-сервера Магазина на запросы уведомления, который составляет 20 секунд.
Запросы отрабатывающие дольше этого значения считаются ошибочными.
## Подпись запроса
При обработке запроса уведомления Магазину необходимо проверить его целостность.
Для этого необходимо сформировать подпись тела входящего запроса и сравнить со значением из заголовка `X-Signature`.
Если эти значения не совпадают, необходимо сформировать ответ [NotificationError](#notificationerror) с
[NotificationErrorCode](#notificationerrorcode) `signature_error` и вернуть его с **HTTP-кодом 200** — как и для
любого другого [NotificationError](#notificationerror) (см. [Формат ответа](#формат-ответа)). Возврат HTTP 400/401/403
вместо 200 приведёт к тому, что «Инвойсбокс» не разберёт `code` из тела ответа и обработает запрос как
техническую ошибку `out_of_service`, а не как `signature_error`. Электронная подпись формируется путем
криптографического преобразования содержимого тела запроса с использованием ключа и алгоритма выбранных в настройках уведомлений.
Ключ свой у каждого магазина, а не общий на учётную запись: если магазинов несколько, проверяйте
подпись ключом того магазина, чей `merchantId` пришёл в теле уведомления.
По умолчанию используется алгоритм `sha1` и метод `hmac`. Ключ можно получить в настройках интеграции магазина в ЛК Инвойсбокс.
#### Пример проверки подписи на языке PHP
```php
$value) {
if (strtolower($header) === 'x-signature') {
$xSignature = $value;
break;
}
}
if (!$xSignature) {
// Ошибка, подпись запроса не получена.
// HTTP-код ответа здесь не задаётся явно, поэтому используется код 200 по
// умолчанию — это обязательно, иначе "Инвойсбокс" не разберёт code из тела.
header("Content-Type: application/json");
die('{"status":"error","code":"out_of_service"}');
}
$payload = file_get_contents("php://input");
$apiKey = ""; // Согласованный ключ для подписи
$calcSignature = hash_hmac("sha1", $payload, $apiKey);
// hash_equals, а не !=: обычное сравнение отвечает тем быстрее, чем раньше строки
// разошлись, и по этому времени подпись можно подобрать
if (!hash_equals($calcSignature, $xSignature)) {
// Ошибка, подпись запроса неверная.
// HTTP-код ответа — 200 по умолчанию (см. выше), а не 400/401.
header("Content-Type: application/json");
die('{"status":"error","code":"signature_error"}');
}
```
#### Пример проверки подписи на языке Python
```python
import hashlib
import hmac
from flask import Flask, request, jsonify
app = Flask(__name__)
# Проверьте правильность пути и метода в декораторе @app.route()
# - его нужно подстроить под ваше веб-приложение.
@app.route("/invoicebox_callback", methods=['POST'])
def invoicebox_callback():
x_signature = request.headers.get('x-signature')
if not x_signature:
# Ошибка, подпись запроса не получена.
# HTTP-код должен быть 200 — иначе "Инвойсбокс" не разберёт code из тела
# и посчитает ответ технической ошибкой (out_of_service).
response = jsonify({'status': 'error', 'code': 'out_of_service'})
response.headers["Content-Type"] = "application/json"
return response, 200
# Согласованный ключ для подписи
api_key = ""
payload = request.data
calc_signature = hmac.new(api_key.encode(), payload, hashlib.sha1).hexdigest()
# compare_digest, а не !=: обычное сравнение выдаёт по времени, сколько символов совпало
if not hmac.compare_digest(calc_signature, x_signature):
# Ошибка, подпись запроса неверная.
# HTTP-код должен быть 200, а не 400/401 — см. раздел "Формат ответа".
response = jsonify({'status': 'error', 'code': 'signature_error'})
response.headers["Content-Type"] = "application/json"
return response, 200
# Подпись верна: здесь отмечаем заказ оплаченным в своей учётной системе —
# идемпотентно, потому что то же уведомление может прийти повторно.
# mark_order_paid(request.get_json())
return jsonify({'status': 'success'}), 200
```
[Для удобства, смотрите также PHP SDK](/docs/merchant/sdk/php/)
## Как проверить свой обработчик
Тратить деньги для проверки не нужно: **на демо-магазине оплата подтверждается на платёжной
странице автоматически**. Достаточно довести заказ до платёжной страницы, и уведомление уйдёт
так же, как в бою.
1. Укажите адрес обработчика в личном кабинете: «Мои продажи» → «Мои магазины» →
«Интеграция (API)», поле «URL уведомления». Адрес должен быть публичным и работать по
HTTPS — на `localhost` уведомление не придёт.
2. [Создайте заказ](/docs/merchant/order/create/) своим токеном на своём магазине.
3. Откройте `paymentUrl` из ответа. На демо-магазине оплата подтвердится сама.
4. Обработчик получит уведомление того же формата, что в бою; ответьте
`200 {"status":"success"}` — иначе уведомление придёт повторно.
### Если своего магазина ещё нет
Посмотреть на живое уведомление можно и без него. Заказы, созданные кнопкой «Выполнить» в
документации, уходят с адресом уведомлений портала: что прислал Инвойсбокс — статус, сумма, тело
запроса и результат проверки подписи — видно в [песочнице на быстром старте](/quickstart/#уведомление).
Ключ подписи демо-магазина — `5a3797956281681be7cbb33ffc390ea1`, метод `hash_hmac`, алгоритм `sha1`.
С ними тот же расчёт повторяется на вашей стороне: сравните свою подпись с той, что пришла в
заголовке `X-Signature`.
Свой обработчик всё равно нужно проверить на своём магазине — адрес уведомлений задаётся либо в
личном кабинете, либо полем `notificationUrl` при создании заказа.
Если обработчика ещё нет, а посмотреть на смену статуса хочется, статус заказа можно прочитать
запросом: [Получение заказа](/docs/merchant/order/get/).
## Система мониторинга и автоматическое тестирование интеграции
В системе мониторинга «Инвойсбокс» реализовано автоматическое тестирование работоспособности интеграции.
Для проверки корректности интеграции, система может направлять тестовое уведомление, в котором в качестве идентификатора заказа в учётной системе магазина будет
передано пустое значение, в качестве идентификатора заказа в системе «Инвойсбокс» будет передано значение `ffffffff-ffff-ffff-ffff-ffffffffffff`.
При получении такого запроса, система учёта магазина должна проверить корректность подписи запроса, сверить идентификатор магазина с настройками и вернуть ответ по результатам проверки.
---
---
# 1С Битрикс
# Описание модуля 1С Битрикс
Затем добавьте новую платёжную систему в настройках магазина
На открывшейся странице:
1. Выберите "Обработчик": «Инвойсбокс» (invoicebox);
2. Выберите версию платёжной системы: Инвойсбокс v2 или Инвойсбокс v3;
3. Если требуется измените "Заголовок" и "Название";
2. Выберите версию платёжной системы: Инвойсбокс l3(текущий) или Инвойсбокс v3(новый);
3. Если требуется, измените "Заголовок" и "Название";
4. **(обязательно)** Укажите кодировку "UTF-8";
5. **(обязательно)** Снимите, если установлены, 2 чекбокса "Разрешить печать чеков" и "Открывать в новом окне".
В блоке «Настройка обработчика ПС» настройте следующие параметры:
- В случае выбора в типе платежной системы версии Инвойсбокс v3, требуется заполнить поля из блока «Настройки подключения к Инвойсбокс v3»:
- Идентификатор магазина - укажите идентификатор магазина, полученный при заключении договора;
- В случае выбора в типе платежной системы версии Инвойсбокс l3(текущий), требуется заполнить поля из блока «Настройки подключения к Инвойсбокс v3»:
- Идентификатор магазина - укажите идентификатор магазина, полученный при заключении договора;
- Авторизационный токен - формируется в момент регистрации магазина в системе «Инвойсбокс» и направляется по электронной почте в письме «Об активации в системе «Инвойсбокс». Если письмо не пришло, вы можете сформировать его автоматически в личном кабинете (в разделе Настройки);
- Ключ для проверки подписи запроса — ключ можно получить в настройках интеграции магазина в ЛК Инвойсбокс;
- Тип позиции у товаров каталога, Тип позиции у доставки — выберите один из двух вариантов (Товар или Сервис), данные поля необходимы для чека;
- В случае выбора в типе платёжной системы версии Инвойсбокс v2 **(не рекомендуется)**, требуется заполнить поля из блока «Настройки подключения к Инвойсбокс v2»:
- ID магазина — укажите идентификатор магазина, полученный при заключении договора;
- Региональный код магазина — укажите региональный код магазина, полученный при заключении договора;
- API ключ — укажите ключ безопасности, полученный при заключении договора;
- URL страницы для отправки уведомлений — этот параметр обычно не требуется редактировать, т. к. он устанавливается по умолчанию и значение обязательно должно быть в виде http(s)://адрес_сайта/bitrix/tools/invoicebox/notification.php;
- Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Модуль amoCRM предоставляет простую возможность подключить вашу CRM систему к «Инвойсбокс» для оформления счетов
клиентам.
# Установка расширения Инвойсбокс из амоМаркета
Модуль находится во вкладке амоМаркет -> Счета и эквайринги -> Инвойсбокс
В настройках самого модуля необходимо указать апи-токен, id магазина и ключ. Все данные отправляются после заключения договора.
Нужны три значения: токен, идентификатор магазина и ключ проверки подписи. Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
Брать актуальные данные [здесь](https://docs.invoicebox.ru/docs/merchant/integrationdata/)
## Выставление счетов
2. Создаём новый контакт, который будет выступать в роли плательщика во вкладке "списки" -> "контакты"
**Обязательно нужно указать номер телефона и email. Без этих данных счёт на оплату не будет сформирован!**
**При добавлении компании ИНН обязателен!**
3. После создаём счёт по вкладке "списки" -> "счета / покупки"
Необходимо указать:
- Цену
- Название
- Количество
- НДС. Допустимые значения: 0, 10%, 20%
4. Ссылка на оплату будет сформирована внутри счёта.
5. Сначала идёт переход на страницу Amocrm, а оттуда на платёжную страницу Инвойсбокс
## Читайте также
- [Допустимые ставки НДС](/docs/dictionary/tag1199/)
---
# iiko
# Описание модуля iiko
iiko - специализированная система ERP-класса, предназначенная для автоматизации ресторанного бизнеса.
Модуль (плагин) Инвойсбокс для iiko предоставляет простую возможность организации приёма оплаты от организаций и
индивидуальных предпринимателей в залах ресторана.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке, пожалуйста,
обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Требования
- Минимальная версия `iiko 7.9.7` так как плагин использует `Front API v7`
- Наличие лицензии `api payment (21016318)`
- Запуск iikoFront от имени администратора
- НДС должен быть включен в стоимость блюд
## Установка модуля (плагина)
[Скачайте](https://repo.open-s.info/Plugins/iiko/BeOpen.Front.Plugin.InvoiceBox/) и распакуйте архив с модулем в папку `C:\Program Files\iiko\iikoRMS\Front.Net\Plugins`
## Настройка модуля (плагина)
Перейдите в папку `C:\Program Files\iiko\iikoRMS\Front.Net\Plugins\BeOpen.Plugins.Invoicebox`
и с помощью блокнота откройте конфигурационный файл `BeOpen.Plugins.Invoicebox.dll.config`.
В конфигурационном файле модуля укажите следующие значения параметров:
- **WS** – адрес вебсокета, к которому требуется подключиться: `ws-gate.invoicebox.ru` (см. [использование веб-сокетов](/docs/api/websockets/))
- **TimeWebSocketSecond** – частота проверки подключения к веб-сокету в секундах: `10`
- **Url** – базовый URL Инвойсбокс API: `https://api.invoicebox.ru` (см. [подключение к API](/docs/api))
- **RoundPolicy** - политика округления, рекомендуется `none`
- **PartnerId** – идентификатор (GUID) Магазина в системе Инвойсбокс. Если ваша организация ещё не зарегистрирована в системе Инвойсбокс, см. ниже функцию регистрации в настройках iikoFront
- **PaymentType** – идентификатор (GUID) типа оплаты. При запуске iikoFront с плагином (модулем), в лог будут выведены все типы оплат, выберите нужный.
Лог плагина находится в папке: `%appdata%\iiko\CashServer\Logs`, название файла: `plugin-BeOpen.Plugins.Invoicebox.log`.
#### Пример заполненного конфигурационного файла
``` xml
Плагин при старте проверяет, есть ли тип заказа invoicebox, и в случае, если его нет, выдает ошибку *«Для запуска платина invoicebox, создайте в системе тип заказа invoice_box, и сделайте доступным для данного терминала».*
В iikoOffice переходим в раздел “Сотрудники” - “Должности” и нажимаем “Добавить”, создаем должность по примеру:
Созданную должность назначаем системному пользователю плагина. Это необходимо, чтобы другой сотрудник ресторана без указанной должности, не смог добавить в заказ тип оплаты invoicebox.
В iikoOffice переходим в раздел “Розничные продажи” - “Типы оплат” и нажимаем “добавить”.
Тип оплаты - внешний, название выбираете по желанию клиента. В поле безналичный тип выбираем InvoiceboxPayment после первого старта плагина.
## Настройка в iikoFront
Перезапустите iikoFront, откройте вкладку дополнений в главном меню.
Если ваша организация ещё не зарегистрирована в Инвойсбокс, нажмите "Инвойсбокс: Регистрация в системе" и в открывшемся
окне укажите электронный адрес администратора. Дождитесь получения письма от системы Инвойсбокс.
Если ваша организация уже зарегистрирована, нажмите "Инвойсбокс: активация кассы", укажите код активации кассы.
## Логика работы
Путь одного заказа целиком: от пречека на кассе до уведомления, по которому iiko закрывает стол.
```mermaid
sequenceDiagram
participant O as Официант в iikoFront
participant P as Плагин Инвойсбокса
participant I as API Инвойсбокс
participant G as Гость
O->>P: печать пречека, тип оплаты «Инвойсбокс»
P->>I: создание заказа с составом и суммой
I-->>P: paymentUrl
P->>O: QR-код на пречеке
G->>I: оплата по QR-коду на платёжной странице
I->>P: уведомление о смене статуса
P->>O: заказ закрыт, стол свободен
```
Если в заказе указан тип заказа Инвойсбокс (invoicebox), заказ проходит проверку и на пречеке формируется QR-код.
**Передача состава заказа**
При формировании QR-кода в систему Инвойсбокс передается состав заказа и его сумма.
Для каждого блюда в заказе указываются его наименование, цена позиции, номинал и сумма НДС, количество и сумма с учётом скидки, модификаторы и их цена.
**Оплата**
После того, как гость перейдёт по QR-коду и произведёт оплату, в заказ в iikoFront будет добавлена оплата на сумму заказа с типом из конфигурационного файла и заказ будет закрыт.
**Ограничения**
QR-код НЕ будет напечатан в случае, если в заказе есть:
1. Бесплатные блюда и модификаторы
2. Надбавка
3. Блюда с составными модификаторами
Не поддерживаются предоплаты (QR-код будет сформирован на полную сумму заказа)
Поддерживается только НДС, включенный в стоимость
При каждой печати пречека запрос отправляется заново и создается новый QR-код.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке, пожалуйста,
обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts). Для ускорения процесса
диагностики, пожалуйста, приложите к обращению файл лога модуля (плагина), который находится в папке: `%appdata%\iiko\CashServer\Logs`,
название файла: `plugin-BeOpen.Plugins.Invoicebox.log`.
---
# Схема взаимодействия
# Схема партнёрского взаимодействия
Половина отказов при создании заказа — это расхождение сумм. Правило простое:
- `amount` заказа равен сумме `totalAmount` всех позиций корзины;
- `vatAmount` заказа равен сумме `totalVatAmount` всех позиций;
- в позиции `amount` — цена одной единицы, `totalAmount` — за всё количество (`quantity × amount`);
- `amountWoVat` — цена единицы без НДС; сумма без НДС и сумма НДС вместе дают `totalAmount`;
- строгость сверки задаёт `orderSetting.roundPolicy` (по умолчанию `none`).
Если суммы не сходятся, API отвечает ошибкой `wrong_total_vat_amount` — расшифровка и остальные коды
в [справочнике ошибок](/docs/dictionary/error/).
Ставка НДС передаётся кодом в поле `vatCode` позиции: с 2026 года основная ставка — 22 %
(`RUS_VAT22` — НДС в цене, `RUS_VAT22_ADDED` — НДС сверху). Полный перечень — в
[справочнике ставок](/docs/dictionary/tag1199/).
## Фискальные поля позиции
Чек формирует онлайн-касса, а данные для него берутся из позиций корзины. Реквизиты чека,
которые в 54-ФЗ называются тегами, передаются обычными полями:
| Реквизит чека | Поле позиции | Справочник |
|---|---|---|
| Признак предмета расчёта (тег 1212) | `type` | [значения](/docs/dictionary/tag1212/) |
| Признак способа расчёта (тег 1214) | `paymentType` | значения в таблице [BasketItem](#basketitem) |
| Ставка НДС | `vatCode` | [ставки НДС](/docs/dictionary/tag1199/) |
| Единица измерения | `measureCode` | [ОКЕИ](/docs/dictionary/okei/) |
Как устроена фискализация и когда чек попадает покупателю — [онлайн-касса](/docs/merchant/fz54/).
## Пока заказ не оплачен
Созданный заказ не высечен в камне:
- сумму и состав можно [изменить](/docs/merchant/order/update/) — новый заказ создавать не нужно;
- ненужный заказ [отменяют](/docs/merchant/order/delete/);
- когда наступает время из `expirationDate`, заказ сам переходит в статус `expired`: оплатить по
прежней ссылке нельзя, нужен новый заказ. О переходе магазин узнаёт из
[уведомления о смене статуса](/docs/merchant/notification/status/) — обработайте этот статус, иначе
заказ останется в вашей системе «ждущим оплаты» навсегда.
## Повтор после сбоя и таймаута
Сеть обрывается на самом неудачном месте: запрос ушёл, ответ не вернулся, и магазин не знает,
создан ли заказ.
Сразу о главном: **по умолчанию уникальность `merchantOrderId` не проверяется**. Номер можно передать
любой, в том числе уже использованный, — и на тот же номер создастся второй заказ. Значит слепой
повтор после таймаута приводит к двум счетам на одну покупку, а идемпотентности у создания заказа нет
ни полной, ни частичной.
Порядок действий, который от этого защищает:
1. Сохраните `merchantOrderId` до отправки запроса и не меняйте его при повторах — он строится из
номера покупки в вашей системе, а не из случайного числа.
2. Если ответ не пришёл (таймаут, обрыв, `5xx`), **не отправляйте создание заново**. Сначала спросите,
есть ли заказ — созданный заказ виден в выборке сразу, поэтому пустой ответ означает, что заказа
нет, и ждать не нужно:
```http
GET /v3/filter/api/order/order?merchantOrderId=O-12345
```
3. Заказ нашёлся — сверьте `merchantId`, сумму и состав с тем, что отправляли, и берите из него `id`
и `paymentUrl`.
4. По номеру нашлось несколько заказов — остановите автоматическую обработку и разберитесь вручную.
Выбирать «последний по `createdAt`» нельзя: скорее всего дубль создал предыдущий неудачный повтор,
и лишние счёта нужно отменить, а не тихо выбрать один из них.
5. Заказ не нашёлся — повторите создание с тем же номером.
6. Новый номер генерируйте только для новой покупки. Новый номер после неудачи — это второй заказ на
ту же покупку: покупатель увидит два счёта, а магазин — двойную выручку в отчётах.
> [!IMPORTANT]
> Проверку уникальности можно включить на стороне Инвойсбокса: это настройка магазина, и меняет её
> [служба поддержки](https://www.invoicebox.ru/ru/contacts) по обращению. С включённой проверкой
> повторный номер вернёт ошибку `merchant_order_id_duplicate` — это страховка от второго заказа, а не
> замена порядку выше: ответ первого запроса повтор всё равно не вернёт, `id` и `paymentUrl` придётся
> получить выборкой. Если номера заказов у вас и так уникальны, проверку стоит попросить включить.
### Что можно повторять
| Что случилось | Чтение (GET) | Создание, возврат, отмена |
|---|---|---|
| Таймаут или обрыв связи | повторить сразу | результат неизвестен: сначала выборка по `merchantOrderId`, повтор — только если операции нет |
| `5xx` | повторить с задержкой | то же: запрос мог дойти и выполниться |
| `429` — превышен [лимит частоты](/docs/api/limits/) | повторить с растущей задержкой | повторить с растущей задержкой: до операции запрос не дошёл |
| Прочие `4xx` | не повторять | не повторять: причина в данных запроса, а не в связи |
Задержку увеличивайте от попытки к попытке (например, 1, 2, 4, 8 секунд) и добавляйте случайный
разброс, чтобы повторы нескольких процессов не сошлись в одну секунду. Заголовка `Retry-After` в
ответах нет — паузу выбирает магазин.
### Возврат и отмена
Правило то же, меняется только запрос, которым вы проверяете результат.
**Возврат.** У каждого возврата свой `merchantOrderId` — по нему и ищите:
```http
GET /v3/filter/api/order/refund-order?merchantOrderId=R-12345
```
Нашёлся — возврат создан, работайте с ним. Не нашёлся — повторяйте создание с тем же номером. Новый
номер после неудачи означает второй возврат по тому же заказу.
**Отмена заказа.** Прочитайте заказ и посмотрите статус: `canceled` — отмена прошла, повторять
нечего. Любой другой статус — отмену можно повторить, она идемпотентна по смыслу: отменить уже
отменённый заказ нельзя, и API ответит ошибкой, а не отменит что-то ещё.
## CreateOrderRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|------------------------|--------------|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|
| description | да | string(1000) | Описание заказа | `Оплата номера в отеле` |
| merchantId | да | string(36) | Идентификатор магазина. В примерах на этой странице стоит демо-магазин — свой возьмите в личном кабинете, вкладка «Интеграция (API)» | `ffffffff-ffff-ffff-ffff-ffffffffffff` |
| merchantOrderId | да | string(100) | Идентификатор заказа в учётной системе магазина, должен быть уникальным | `O-12345` |
| merchantOrderIdVisible | нет | string(100) | Номер заказа, отображаемый на платежной странице. Если не заполнено, показывается значение из merchantOrderId | `111TN22-33` |
| amount | да | float | Сумма заказа, ограничений нет | `19658.45` |
| vatAmount | да | float | Сумма НДС | `156.56` |
| currencyId | да | string(3) enum | Код валюты заказа в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` |
| languageId | нет | string(2) enum | Язык интерфейса платежной страницы | `ru`, `en` |
| expirationDate | да | datetime | Срок действия заказа | `2026-12-22T00:00:00+00:00` |
| basketItems | да | array of [BasketItem](#basketitem) | Корзина заказа | |
| metaData | нет | object | [Дополнительные данные заказа](/docs/merchant/order/metadata/) | |
| customer | да | [Customer](#customer) | Информация о заказчике | |
| notificationUrl | нет | string(1000) | URL для отправки [уведомлений](/docs/merchant/notification) об изменениях статуса заказа, по умолчанию используется URL из настроек магазина | |
| successUrl | нет | string(1000) | Ссылка для перехода на сайт Магазина в случае успешной оплаты | `https://shop.example.com/order/4412?result=success` |
| failUrl | нет | string(1000) | Ссылка для перехода на сайт Магазина в случае ошибки оплаты | `https://shop.example.com/order/4412?result=fail` |
| returnUrl | нет | string(1000) | Ссылка для возврата на сайт Магазина (кнопка «вернуться в магазин» на платёжной странице) | `https://shop.example.com/order/4412?result=return` |
| invoiceSetting | нет | [InvoiceSetting](#invoicesetting) | Дополнительные настройки параметров оплаты | |
| orderSetting | нет | [OrderSetting](#ordersetting) | Дополнительные настройки параметров заказа | |
| parentId | нет | string(36) | Идентификатор базового заказа, применимо для создания [корректирующих заказов](/docs/merchant/refund/correction/) | `01771534-196a-1105-839a-82422289d6d9` |
| orderContainerId | нет | string(36) | Идентификатор основного заказа, применимо для добавления заказа к уже существующему счёту | `01771534-196a-1105-839a-82422289d6d9` |
| shopId | нет | string(36) | Идентификатор связанного магазина/маркетплейса | `06581534-196a-1105-839a-82422289d6d8` |
| userAccountId | нет | string(36) | Идентификатор программы лояльности | `06581534-196a-1105-839a-82422289d6d7` |
| processable | нет | bool | Признак процессингового заказа: `true` — расчёты проходят в биллинге Инвойсбокса (по умолчанию), `false` — [непроцессинговый заказ](/docs/merchant/order/non-processable-order/): оплату принимает магазин, а Инвойсбокс формирует документы | `true`, `false` |
| subtype | нет | string(36) | Подтип заказа, возможные значения `order` - обычный заказ (по умолчанию). `hold` - заказ с холдированием | `order`, `hold` |
## OrderResponse
Повторяет свойства объекта [CreateOrderRequest](#createorderrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------|--------------|-----------------------------|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| id | да | string(36) | Идентификатор заказа в системе Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded75` |
| paymentUrl | да | string(1000) | Ссылка для перехода на платёжный шлюз для оплаты заказа | |
| createdAt | да | datetime | Дата создания заказа | `2026-12-22T00:00:00+00:00` |
| status | да | string(50) enum | Статус заказа: `created` — ожидает оплаты, `completed` — успешная оплата, `hold` — средства захолдированы | `completed`, `hold` |
| paidAt | нет | datetime | Дата оплаты заказа (если оплачен) | `2026-12-22T00:00:00+00:00` |
| paymentInfo | нет | [PaymentInfo](#paymentinfo) | Информация об оплате и плательщике | `{"maskedPan": "220024**0954", "expiration": "202601", "paymentSystem": "MIR", "cardholderName": "CARDHOLDER NAME"}` |
| holdTill | нет | datetime | Дата и время списания холдированных средств (для заказов с подтипом `hold`) | `2026-08-03T12:00:00+03:00` |
> [!IMPORTANT]
> В зависимости от сценария использования API, ссылка для перехода на платёжный шлюз (paymentUrl) может быть получена для
> переадресации пользователя в браузере или же закодирована в QR-коде для дальнейшего его сканирования камерой или приложением
> Инвойсбокс.
## Customer
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------------|--------------|-----------------|-------------------|------------------------------------------------------|
| type | нет | string(10) enum | Тип заказчика | `legal` - юр. лицо, `private` - физ лицо |
| name | нет | string(500) | Наименование или имя | `ООО «Ромашка»` |
| phone | нет | string(100) | Номер телефона | `79001112233` |
| email | нет | string(100) | Электронная почта | `buh@example.invbox.ru` |
| vatNumber | нет | string(20) | ИНН | `7701234560` |
| taxRegistrationReasonCode | нет | string(9) | КПП | `770101001` |
| registrationAddress | нет | string(1000) | Юр. адрес, включая почтовый индекс | `190000, Санкт-Петербург, Невский пр. 147, офис 321` |
Примеры выше собраны на плательщика-организацию: `type` = `legal`, ИНН в `vatNumber`, КПП в
`taxRegistrationReasonCode`. По этим реквизитам покупателю уходят закрывающие документы. У ИП КПП нет —
поле остаётся пустым. Если платит физлицо, укажите `type` = `private`: ИНН, КПП и юридический адрес
тогда не нужны, а из документов формируется только [фискальный чек](/docs/merchant/fz54/).
## BasketItem
Корзина заказа. Пожалуйста, внимательно ознакомьтесь с требованиями по [заполнению наименования номенклатуры](/docs/merchant/fz54/).
| Свойство | Обязательное | Тип | Описание |
|-------------------|----------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| sku | да | string(36) | Артикул, например: `5fe0adcfa7fb4` |
| name | да | string(300) | Наименование, например `Бронирование номера` |
| type | да | string(10) | Идентификатор типа позиции, [в соответствии со справочником](/docs/dictionary/tag1212) или `service` - Услуга, `commodity` - Товар |
| groupName | нет | string(500) | Наименование группы позиций заказа, используется для формирования отчетных документов |
| measure | да | string(10) | Единица измерения словом, например `шт.`. Достаточно передать одно из двух полей — единицу или код: второе сервер заполнит сам по справочнику [ОКЕИ](/docs/dictionary/okei/) |
| measureCode | да | string(4) | Код единицы измерения по [ОКЕИ](/docs/dictionary/okei/), например `796`. Парное поле к `measure`: см. строку выше |
| originCountry | нет | string(20) | Страна происхождения товара, например, `Россия` |
| originCountryCode | нет | string(4) | Код страны происхождения, например, Россия `643` |
| grossWeight | нет | float | Вес брутто, например `125.45` |
| netWeight | нет | float | Вес нетто, например `125.45` |
| quantity | да | float | Количество, например `3` |
| amount | да | float | Стоимость единицы, например `100.55`, ограничений нет |
| amountWoVat | да | float | Стоимость единицы без учета НДС |
| totalAmount | да | float | Стоимость всех единиц с НДС, например`123.55` |
| totalVatAmount | да | float | Итого сумма НДС, например `23` |
| excise | нет | float | Сумма акциза, например, `10.00` |
| gtdNumber | нет | string(23) | Номер грузовой транспортной накладной |
| vatCode | да | string(20) enum | Код ставки НДС Инвойсбокс, см. [справочник - ставки НДС](/docs/dictionary/tag1199/) |
| serviceDate | нет | date | Дата оказания услуги, если тип позиции = Услуга, например, 2023-11-16 |
| paymentType | да | string(20) enum | Признак способа расчёта (тег 1214): `full_prepayment`, `prepayment`, `advance`, `full_payment`. В контракте поле помечено необязательным: если его не передать, сервер подставит значение из настроек магазина. Передавайте явно — так состав чека не зависит от настройки, которую можно поменять в кабинете |
| categoryType | при наличие category | string(20) enum | Справочник категории товаров: `merchantHonestSignMap` (Справочник категорий магазина) или `honestSign` ([Честный знак](/docs/merchant/honest-sign/)) |
| category | нет | string(20) enum | Товарная группа в справочнике категорий товаров магазина или системы [Честный знак](/docs/merchant/honest-sign/): `milk`, `water` и т.д. |
| metaData | нет | object | [Дополнительные данные элемента корзины](/docs/merchant/order/metadata/) |
---
## InvoiceSetting
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-------------------------|--------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| customerLocked | нет | bool | Запретить изменение реквизитов плательщика (всех) | true - запретить изменения, по умолчанию false |
| customerLockedFields | нет | array
[МПС (EgoPay)](https://ips.su) — платёжное решение [Сирена Трэвел](https://sirena-travel.ru), позволяет
оплачивать билеты не только ТКП, но и BSP. При этом МПС поддерживает прямой процессинг в BSP.
## Решения на базе интеграции
- [Автоматизация продаж авиабилетов юридическим лицам и ИП (b2b)](/docs/scenarios/air-carriers).
## Настройка интеграции
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# Оформление возврата
# Оформление возврата
Оформить возврат средств возможно только по оплаченному заказу. Перед оплатой, пожалуйста, воспользуйтесь
[методом удаления заказа](/docs/merchant/order/delete/). Схема оформления возврата по оплаченному заказу следующая:
- Получить список доступных для возврата позиций
- Создание возвратного заказа
#### Пример запроса и ответа
``` json
GET /v3/billing/api/order/refund-order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
```
Ответ:
``` json
[
{
"id": "01859552-5136-da7a-62c0-c0ee2dfe1485",
"description": "Возврат средств заказа",
"currencyId": "RUB",
"amount": 1476.2,
"vatAmount": 0,
"basketItems": [
{
"sku": "70633118938830",
"name": "ТАРИФ ПЛАЦКАРТЫ 70633118938830",
"measure": "шт",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 1,
"amount": 518.5,
"amountWoVat": 518.5,
"totalAmount": 518.5,
"totalVatAmount": 0,
"vatCode": "RUS_VAT0",
"type": "service",
"paymentType": "full_prepayment",
"metaData": {
"@type": "TrainReservation",
"provider": {
"name": "Grand Service Express",
"@type": "Organization",
"taxID": "5544332219"
},
"underName": {
"name": "МУЛЛАЯНОВ АЛЬБЕРТ РИНАТОВИЧ",
"@type": "Person"
},
"bookingTime": "2023-01-09T09:46:00+03:00",
"reservationId": "70633118938830",
"reservationFor": {
"@type": "TrainTrip",
"arrivalTime": "2023-01-27T09:20:00+03:00",
"trainNumber": "092МА",
"departureTime": "2023-01-25T23:52:00+03:00",
"arrivalStation": {
"name": "Симферополь",
"@type": "TrainStation"
},
"departureStation": {
"name": "Москва Казанская (Казанский вокзал)",
"@type": "TrainStation"
}
},
"reservedTicket": {
"fare": 518.5,
"@type": "trainTicket",
"gender": "male",
"vatValue": {
"vatCode": "RUS_VAT0",
"totalVatAmount": 0
},
"coachType": "Плацкартный",
"underName": {
"name": "МУЛЛАЯНОВ АЛЬБЕРТ РИНАТОВИЧ",
"@type": "Person"
},
"coachNumber": "04",
"nationality": "RUS",
"paymentType": "Безналичный расчёт",
"serviceClass": "3Э",
"ticketNumber": "70633118938830",
"ticketedSeat": {
"@type": "Seat",
"seatNumber": "038"
},
"ticketIssueTime": "2023-01-27T09:20:00+03:00",
"idDocumentNumber": "********8015"
},
"reservationStatus": "https://schema.org/ReservationConfirmed"
}
},
{
"sku": "70633118938830/1",
"name": "ТАРИФ БИЛЕТА 70633118938830",
"measure": "шт",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 1,
"amount": 957.7,
"amountWoVat": 957.7,
"totalAmount": 957.7,
"totalVatAmount": 0,
"vatCode": "RUS_VAT0",
"type": "service",
"paymentType": "full_prepayment",
"metaData": {
"@type": "TrainReservation",
"provider": {
"name": "Grand Service Express",
"@type": "Organization",
"taxID": "5544332219"
},
"underName": {
"name": "МУЛЛАЯНОВ АЛЬБЕРТ РИНАТОВИЧ",
"@type": "Person"
},
"bookingTime": "2023-01-09T09:46:00+03:00",
"reservationId": "70633118938830",
"reservationFor": {
"@type": "TrainTrip",
"arrivalTime": "2023-01-27T09:20:00+03:00",
"trainNumber": "092МА",
"departureTime": "2023-01-25T23:52:00+03:00",
"arrivalStation": {
"name": "Симферополь",
"@type": "TrainStation"
},
"departureStation": {
"name": "Москва Казанская (Казанский вокзал)",
"@type": "TrainStation"
}
},
"reservedTicket": {
"fare": 957.7,
"@type": "trainTicket",
"gender": "male",
"vatValue": {
"vatCode": "RUS_VAT0",
"totalVatAmount": 0
},
"coachType": "Плацкартный",
"underName": {
"name": "МУЛЛАЯНОВ АЛЬБЕРТ РИНАТОВИЧ",
"@type": "Person"
},
"coachNumber": "04",
"nationality": "RUS",
"paymentType": "Безналичный расчёт",
"serviceClass": "3Э",
"ticketNumber": "70633118938830",
"ticketedSeat": {
"@type": "Seat",
"seatNumber": "038"
},
"ticketIssueTime": "2023-01-27T09:20:00+03:00",
"idDocumentNumber": "********8015"
},
"reservationStatus": "https://schema.org/ReservationConfirmed"
}
}
],
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"status": "created",
"shipmentStatus": "unshipped",
"subtype": "refund",
"createdAt": "2023-01-09T06:57:58+00:00",
"merchantOrderId": "/10004-00000-00003-50371",
"orderContainerId": "01859547-cacb-80bd-25fd-31c8cee2f841",
"parentId": "01859547-cad6-4652-18ab-5534cfa6ed0e",
"processable": true
}
]
```
## Получается список доступных для возврата позиций:
- метод: `GET`
- ресурс: `/v3/billing/api/order/order/:uuid/refund-basket-item` - где `:uuid` это идентификатор заказа
- тело ответа - array of [BasketItem](/docs/merchant/order/create/#basketitem)
## Частичный возврат
Возвращать всю сумму заказа не обязательно. Возврат — это отдельный заказ со своей корзиной: в
`basketItems` перечисляются только те позиции и количества, которые возвращаются, а `amount` и
`vatAmount` считаются по ним. Из заказа на 10 000 ₽ можно вернуть 3 000 ₽, оформив возврат на одну
позицию.
Возвратов по одному заказу может быть несколько. Каждому нужен свой `merchantOrderId`: по нему
Инвойсбокс отличает новый возврат от повторно отправленного и не проводит один и тот же дважды.
Какие позиции ещё доступны к возврату, показывает метод из раздела ниже.
## Создание возвратного заказа
- метод: `POST`
- ресурс: `/v3/billing/api/order/refund-order`
- тело запроса - объект [CreateRefundOrderRequest](#createrefundorderrequest)
- тело ответа - объект [RefundOrderResponse](#refundorderresponse)
## CreateRefundOrderRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-----------------|--------------|-------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|
| parentId | да | string(36) | Идентификатор базового заказа | `01771534-196a-1105-839a-82422289d6d9` |
| merchantOrderId | да | string(100) | Идентификатор возвратного заказа в учётной системе магазина, для каждого отдельного возврата значение должно быть уникальным | `O-12345` |
| amount | да | float | Сумма заказа | `19658.45` |
| vatAmount | да | float | Сумма НДС | `156.56` |
| basketItems | да | array of [BasketItem](/docs/merchant/order/create/#basketitem) | Корзина заказа | |
| description | да | string(1000) | Описание заказа | `Оплата номера в отеле` |
| status | нет | string(50) enum | Статус заказа, по умолчанию `created`, так же возможен статус `draft` для создания [корректирующих заказов](/docs/merchant/refund/correction/) | `created` |
| subtype | нет | string(20) enum | Вид возврата: `refund` — обычный (по умолчанию), `secured` — [с обеспечением](#возврат-с-обеспечением) | `secured` |
> [!IMPORTANT]
> При формировании нескольких возвратов в рамках одного заказа передавайте уникальный идентификатор возвратного заказа (возврата) merchantOrderId
для каждого отдельного возврата. В случае, если будет передан уже существующий идентификатор, будет возвращена ошибка. Подобный механизм предупреждает инциденты
случайных двойных возвратов.
## Возврат с обеспечением
Обычный возврат уходит в выплату сразу после создания: покупатель получает деньги, а магазин
рассчитывается с Инвойсбоксом потом. Возврат с обеспечением меняет порядок на обратный — сначала
деньги вносит магазин, и только потом стартует выплата покупателю. Такой возврат создаётся тем же
методом с полем `subtype`:
``` json
{
"parentId": "01771534-196a-1105-839a-82422289d6d9",
"merchantOrderId": "R-4412-1",
"subtype": "secured",
"amount": 12000,
"vatAmount": 0,
"description": "Возврат за отменённое бронирование № 4412",
"basketItems": []
}
```
### Как это работает
1. Возврат создаётся в статусе `created`, как обычный, но в выплату не уходит.
2. Инвойсбокс выставляет магазину **обеспечительный заказ** на сумму возврата. В ответе на создание
возврата приходит его идентификатор — `securityOrderId`.
3. Магазин оплачивает обеспечительный заказ. Счёт под него не выставляется: способ оплаты магазин
выбирает на платёжной странице сам, как покупатель в обычном заказе.
4. После оплаты обеспечения возврат идёт штатным путём — `processing`, затем `completed`.
Статусы возврата при этом обычные: вид возврата виден только в `subtype`. Отдельных уведомлений
у обеспечения нет — приходят те же события, что и всегда: о создании возврата, об оплате
обеспечительного заказа и о завершении возврата.
### Что нужно знать заранее
- **Обеспечительный заказ оформлен на организацию магазина.** Плательщиком подставляются название,
ИНН и КПП вашей организации; телефон и почту вы указываете на платёжной странице — что подтвердите
там, то и попадёт в счёт. Позиция в корзине называется «Обеспечительный платёж», НДС не облагается.
- **Найти заказ по возврату и обратно** можно тремя путями: по `securityOrderId` возврата, по номеру
заказа в учётной системе (там лежит идентификатор возврата) и по артикулу позиции — он тоже равен
идентификатору возврата.
- **Пока обеспечение не оплачено, возврат можно отменить** — вместе с ним отменится и обеспечительный
заказ. После оплаты отмена запрещена: деньги уже получены, и возврат обязан доехать до выплаты.
- **Изменить сумму нельзя.** Обеспечительный заказ выставлен на исходную сумму, и правка развела бы
её с суммой возврата. По той же причине с обеспечением не сочетается статус `draft`, то есть
[корректирующие возвраты](/docs/merchant/refund/correction/).
- **Остаток по корзине** резервируется так же, как у обычного возврата.
> [!IMPORTANT]
> Возврат с обеспечением требует настройки на стороне Инвойсбокса. Если она не сделана, запрос
> создания возврата вернёт ошибку — обеспечительный заказ выставить не из чего, а возврат без него
> завис бы навсегда. Сам возврат к этому моменту уже создан: отмените его и повторите после
> настройки. Если планируете такие возвраты, договоритесь о настройке заранее.
## RefundOrderResponse
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-----------------|--------------|------------------------------------|-------------------------------------------------|----------------------------------------|
| id | да | string(36) | Идентификатор заказа в системе Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded75` |
| parentId | да | string(36) | Идентификатор базового заказа | `01771534-196a-1105-839a-82422289d6d9` |
| description | да | string(1000) | Описание заказа | `Оплата номера в отеле` |
| merchantOrderId | да | string(100) | Идентификатор возврата в учётной системе магазина, свой у каждого возврата | `R-12345` |
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76` |
| amount | да | float | Сумма заказа | `19658.45` |
| vatAmount | да | float | Сумма НДС | `156.56` |
| currencyId | да | string(3) enum | Валюта заказа | `RUB` |
| basketItems | да | array of [BasketItem](/docs/merchant/order/create/#basketitem) | Корзина заказа | |
| createdAt | да | datetime | Дата создания заказа | `2026-12-22T00:00:00+00:00` |
| status | да | string(50) enum | Статус заказа | `completed` |
| paidAt | нет | datetime | Дата осуществления возврата (если возвращен) | `2026-12-22T00:00:00+00:00` |
| subtype | нет | string(20) enum | Вид возврата: `refund` или `secured` | `secured` |
| securityOrderId | нет | string(36) | Идентификатор обеспечительного заказа, только у возврата с обеспечением | `019e51e2-3970-9852-e8c8-803c16ac9c74` |
---
---
# Физические лица
## Покупатели - физические лица
### Процесс создания заказа и оплаты счёта
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
participant Онлайн касса
rect rgba(43, 170, 93, 0.13)
Покупатель->>Магазин: Создаёт заказ
Магазин->>Инвойсбокс: Вызов метода создания заказа
Инвойсбокс->>Магазин: Идентификатор заказа и ссылка на оплату
Магазин->>Покупатель: Перенаправление на платёжную страницу
Покупатель-->>Инвойсбокс: Взаимодействие с платёжной страницей, получение счёта
Покупатель->>Инвойсбокс: Оплата счёта
Инвойсбокс->>Покупатель: Перенаправление покупателя на сайт магазина
Инвойсбокс->>Онлайн касса: Чек "предоплата 100%"
Инвойсбокс->>Покупатель: Предоставление чека "предоплата 100%"
Инвойсбокс->>Магазин: Уведомление об успешной оплате
end
1. Покупатель оформляет заказ на сайте Магазина и выбирает способ оплаты через систему «Инвойсбокс».
1. Магазин создает в системе «Инвойсбокс» заказ [через метод API](/docs/merchant/order/create/).
1. Система возвращает ссылку на платёжную страницу для оплаты заказа.
1. Магазин перенаправляет покупателя по полученной ссылке.
1. Покупатель заполняет необходимые для оплаты сведения и получет счёт для оплаты.
1. Покупатель оплачивает счёт.
1. Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
1. Система «Инвойсбокс» формирует и регистрирует чек "предоплата 100%" в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "предоплата 100%" покупателю (физическому лицу).
1. Система «Инвойсбокс» оповещает Магазин об успешной оплате заказа.
### Процесс отгрузки и оформления чека "полный расчёт"
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
participant Онлайн касса
rect rgba(15, 123, 119, 0.13)
Магазин->>Инвойсбокс: Вызов метода отгрузки по заказу
Инвойсбокс->>Онлайн касса: Чек "полный расчёт"
Инвойсбокс->>Покупатель: Предоставление чека "полный расчёт"
end
1. В случае, если Магазин оказывает услугу или продаёт товар, Магазин направляет запрос отгрузки в систему «Инвойсбокс» по факту оказания услуги или факту отгрузки товара курьерской службой/службе доставки или покупателю. Если услуга оказывается онлайн, отгрузка по заказу может быть установлена автоматически.
1. Система «Инвойсбокс» формирует и регистрирует чек "полный расчёт" в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "полный расчёт" покупателю (физическому лицу).
### Процесс оформления возврата
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
participant Онлайн касса
rect rgba(107, 70, 193, 0.13)
Покупатель->>Магазин: Обращается за возвратом по заказу
Магазин-->Инвойсбокс: Получение списка позиций в заказе
Магазин->>Инвойсбокс: Вызов метода оформления возврата
Инвойсбокс->>Покупатель: Осуществление возврата денежных средств
Инвойсбокс->>Онлайн касса: Чек "возврат"
Инвойсбокс->>Покупатель: Предоставление чека "возврат"
end
1. Покупатель обращается в Магазин для оформления возврата заказа.
1. Опционально, Магазин запрашивает [через метод API](/docs/merchant/refund/get/) доступные к возврату позиции в заказе.
1. Магазин создает возврат в системе «Инвойсбокс» [через метод API](/docs/merchant/refund/create/).
1. Система «Инвойсбокс» возвращает денежных средств покупателю.
1. Система «Инвойсбокс» формирует и регистрирует чек "возврат" в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "возврат" покупателю (физическому лицу).
## Читайте также
- [Магазин направляет запрос отгрузки через метод API](/docs/merchant/order/shipment_create/)
---
---
# Схемы взаимодействия
# Схемы взаимодействия
В зависимости от типа покупателя, схема взаимодействия системы «Инвойсбокс» и Магазина могут отличаться незначительно
в части предоставления отчётных документов. Для покупателя - [физического лица](/docs/merchant/schema/private), отчётный документ
по оплате — фискальный чек, зарегистрированный в [онлайн кассе](/docs/merchant/fz54/) и ОФД.
Для покупателя — [организации и индивидуального предпринимателя](/docs/merchant/schema/legal) отчётными документами могут быть:
акт, ТОРГ-12, накладная, счёт-фактура, отчёт о переводе средств, универсальный передаточный документ (УПД), маршрутная квитанция и
другие.
Перечень необходимых документов и порядок их предоставления покупателю (схема документооборота) согласовываются на этапе заключения
договора между Магазином и системой «Инвойсбокс».
1. [Покупатели - физические лица](/docs/merchant/schema/private)
1. [Покупатели - организации и индивидуальные предприниматели](/docs/merchant/schema/legal)
1. [Комиссионная торговля](/docs/merchant/schema/commission)
1. [Запрос о платеже](/docs/merchant/schema/rtp)
---
---
# PHP SDK
# Описание SDK
PHP SDK — готовая библиотека для серверного взаимодействия с Инвойсбокс API. Библиотека поддерживает
все необходимые методы API для организации приёма платежей.
## Требования
PHP 7.4+ (или более поздняя версия)
## Установка с помощью Composer
1. Установите Composer, менеджер пакетов
2. В консоли выполните следующую команду:
```bash
composer require invoicebox/sdk-php
```
Пропишите в файле composer.json вашего проекта:
1. Добавьте строку "invoicebox/sdk-php": "^1.0" в список зависимостей вашего проекта в файле composer.json
```json
"require": {
"php": ">=7.4",
"invoicebox/sdk-php": "^1.0"
```
2. Обновите зависимости вашего проекта. В консоли, в папке с файлом composer.json выполните следующую команду:
```bash
composer update
```
3. Подготовьте код своего проекта, чтобы активировать автоматическую загрузку зависимостей:
```php
require __DIR__ . '/vendor/autoload.php';
```
## Установка SDK вручную
1. Скачайте архив [Инвойсбокс PHP SDK](https://github.com/invoicebox/sdk-php) и распакуйте его в необходимую папку вашего проекта.
2. Подготовьте код своего проекта, чтобы активировать автоматическую загрузку зависимостей:
```php
require __DIR__ . '/vendor/autoload.php';
```
## Пример создания заказа
```php
$client = new InvoiceboxClient(
'*auth токен*',
'v3',
null,
HttpClient::create(),
);
/**
* Проверка авторизации (необязательный шаг, для тестирования наличия доступа)
*/
$result = $client->checkAuth();
if ($result->getUserId()) {
echo "Успешная авторизация \n";
}
// Покупатель юр.лицо
//$customer = new LegalCustomer(
// 'OOO TEST',
// '78121111111',
// 'test@test.test',
// '7804445210',
// '123321, Улица, 1, 1'
//);
// Покупатель физ.лицо
$customer = new PrivateCustomer(
'name',
'78121111111',
'test@test.test',
);
$basketItems[] = new BasketItem(
"12312", /* Идентификатор заказа (необходим для создания возврата) */
'Тест',
'шт.',
'796',
1.0,
1000.00,
1000,
1000.00,
0,
VatCode::VATNONE,
BasketItemType::COMMODITY,
PaymentType::FULL_PREPAYMENT
);
$request = new CreateOrderRequest(
'Описание заказа',
'ffffffff-ffff-ffff-ffff-ffffffffffff', // id магазина
strval(random_int(1,2000)),
1000.00,
0,
'RUB',
new \DateTime('tomorrow'),
$basketItems,
);
$result = $client->createOrder($request);
if ($result->getPaymentUrl()) {
echo sprintf('Заказ успешно создан - ссылка на оплату - %s', $result->getPaymentUrl());
}
/* Redirect to: $result->getPaymentUrl() */
```
## Читайте также
- [Формат уведомления и коды ответов](/docs/merchant/notification/status/)
---
---
# retailCRM
# Описание модуля retailCRM
Модуль RetailCRM предоставляет простую возможность подключить вашу CRM систему к «Инвойсбокс» для оформления счетов
клиентам.
# Установка расширения Инвойсбокс из маркетплейса
Модуль находится во вкладке настройки -> маркетплейс -> Инвойсбокс
После установки в настройках самого модуля необходимо указать апи-токен, id магазина и ключ. Все данные отправляются после заключения договора.
Нужны три значения: токен авторизации, идентификатор магазина и секретный ключ. Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
Найти актуальные данные можно [здесь](https://docs.invoicebox.ru/docs/merchant/integrationdata/)
## Выбор платёжной системы по умолчанию для retailCRM
Для удобства можно добавить платёжную системы по умолчанию для счетов. Для этого нужно перейти в "настройки -> справочники -> типы оплат -> invoicebox (invoicebox payment system)"
и включить пункт "по умолчанию в системе"
## Выставление счетов
1. Создаём новый заказ через заказы -> новый заказ
2. Указываем клиента, состав заказа, тип доставки (по необходимости)
3. Сохраняем заказ
4. Генерируем ссылку на оплату, если выбрана системы оплаты по умолчанию. Либо выбираем invoicebox (Инвойсбокс payment system) через выпадающее меню кнопки "добавить оплату"
**Обязательно нужно указать номер телефона и email. Без этих данных счёт на оплату не будет сформирован!**
**При добавлении компании ИНН обязателен!**
После оплаты заказа можно отследить его статус на вкладке заказов
---
# Создание группы заказов
# Создание группы заказов
Группа заказов от разных поставщиков с единым приёмом оплаты создаётся одним запросом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/order-container`
- тело запроса - объект [OrderContainerRequest](#ordercontainerrequest)
- тело ответа - объект [OrderContainerResponse](#ordercontainerresponse)
- Возможные [ошибки](/docs/dictionary/error/)
> > [!NOTE]
> Каждый заказ внутри группы заказов имеет базовую структуру, описанную в документации [Создание заказа](/docs/merchant/order/create/). Перед использованием данного метода рекомендуется ознакомиться с основной документацией по созданию заказа.
#### Пример запроса
``` json
POST /v3/billing/api/order/order-container
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"merchantId": "019e207b-b0fe-ae2f-43e7-17054f15913d",
"originalCurrencyId": "RUB",
"originalAmount": 246,
"originalVatAmount": 11.72,
"merchantOrderIdVisible": "zakaz-123",
"returnUrl": "https://marketplace.com#return",
"successUrl": "https://marketplace.com#success",
"failUrl": "https://marketplace.com#fail",
"customer": {
"vatNumber": "7736642031",
"phone": "79045173703",
"email": "gb@invbox.ru",
"taxRegistrationReasonCode": "770901001",
"name": "ООО ЮРлицо",
"registrationAddress": "101000, г. Москва, Лубянский проезд, д.19",
"isLegal": true,
"type": "legal"
},
"orders": [
{
"basketItems": [
{
"sku": "1",
"name": "Позиция заказа магазина маркетплейса",
"type": "service",
"paymentType": "full_payment",
"measureCode": "796",
"quantity": 1,
"vatCode": "RUS_VAT5",
"amount": 123,
"amountWoVat": 117.14,
"totalAmount": 123,
"totalVatAmount": 5.86
}
],
"expirationDate": "2026-05-25T17:11:28+03:00",
"merchantOrderId": "222222/333",
"description": "Оплата заказа магазина маркетплейса",
"amount": 123,
"vatAmount": 5.86,
"merchantId": "019e2094-8403-89f0-1a75-953e2103cfc2",
"currencyId": "RUB"
},
{
"basketItems": [
{
"sku": "1",
"name": "Комиссия маркетплейса",
"type": "service",
"paymentType": "full_payment",
"measureCode": "796",
"quantity": 1,
"vatCode": "RUS_VAT5",
"amount": 123,
"amountWoVat": 117.14,
"totalAmount": 123,
"totalVatAmount": 5.86
}
],
"expirationDate": "2026-05-25T17:11:28+03:00",
"merchantOrderId": "1111/2222",
"description": "Оплата заказа комиссии маркетплейса",
"amount": 123,
"vatAmount": 5.86,
"merchantId": "019e207b-b0fe-ae2f-43e7-17054f15913d",
"currencyId": "RUB"
}
]
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"originalCurrencyId": "01771534-1a57-f184-dee3-ebeb91dded75",
"originalAmount": 100.5,
"originalVatAmount": 100.5,
"expirationDate": "2026-08-03T12:00:00+03:00",
"customer": {
"type": "string",
"name": "string",
"phone": "string",
"email": "string",
"vatNumber": "string",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"registrationAddress": "string",
"taxRegistrationReasonCode": "string"
},
"invoiceSetting": {
"customerLocked": false,
"customerLockedFields": {},
"customerHiddenFields": {},
"paymentMethodIdLocked": false,
"paymentMethodId": 1,
"savePaymentData": false,
"clientId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentToken": "string",
"paymentMethodCode": "string",
"paymentMethodAutosubmit": false,
"bankDetailId": 1
},
"status": "string",
"returnUrl": "string",
"successUrl": "string",
"failUrl": "string",
"paymentUrl": "string",
"paymentUrlType": "redirect",
"paymentPageUrl": "string",
"payerUserId": "01771534-1a57-f184-dee3-ebeb91dded75",
"payerCounterpartyId": "01771534-1a57-f184-dee3-ebeb91dded75",
"systemCounterpartyId": "01771534-1a57-f184-dee3-ebeb91dded75",
"processable": false,
"merchantOrderIdVisible": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"sourceId": "l3"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## OrderContainerRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|------------------------|--------------|---------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|
| merchantId | да | string(36) | Идентификатор основгонго магазина (маркетплейса или агрегатора) | `019e207b-b0fe-ae2f-43e7-17054f15913d` |
| originalCurrencyId | да | string(3) enum | Код валюты группы заказов в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`, `EUR`, `GBP` |
| originalAmount | да | float | Общая сумма группы заказов | `246.00` |
| originalVatAmount | да | float | Общая сумма НДС группы заказов | `11.72` |
| orders | да | array of [Order](/docs/merchant/order/create/#createorderrequest) | Массив заказов, входящих в группу. Структура каждого заказа описана в [документации по созданию заказа](/docs/merchant/order/create/) | |
| customer | нет | [Customer](/docs/merchant/order/create/#customer) | Информация о заказчике (если не указана, плательщик сам заполнит на платежной странице) | |
| merchantOrderIdVisible | нет | string(100) | Идентификатор группового заказа, отображаемый на платежной странице | `zakaz-123` |
| returnUrl | нет | string(1000) | Ссылка для возврата на сайт Магазина | |
| successUrl | нет | string(1000) | Ссылка для перехода на сайт Магазина в случае успешной оплаты | |
| failUrl | нет | string(1000) | Ссылка для перехода на сайт Магазина в случае ошибки оплаты | |
| expirationDate | нет | datetime | Срок действия группы заказов | `2026-05-25T17:11:28+03:00` |
| languageId | нет | string(2) enum | Язык интерфейса платежной страницы | `ru`, `en` |
| invoiceSetting | нет | [InvoiceSetting](/docs/merchant/order/create/#invoicesetting) | Дополнительные настройки параметров оплаты | |
## OrderContainerResponse
Ответ содержит информацию о созданной группе заказов, включая идентификаторы созданных заказов и ссылки на оплату. Объект повторяет свойства объекта [OrderContainerRequest](#ordercontainerrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------|--------------|---------------------------------------------------------|---------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| id | да | string(36) | Идентификатор группы заказов в системе Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded75` |
| paymentUrl | да | string(1000) | Ссылка для перехода на платёжный шлюз для оплаты заказа | |
| createdAt | да | datetime | Дата создания заказа | `2026-12-22T00:00:00+00:00` |
| status | да | string(50) enum | Статус заказа, `pending` - Ожидает оплаты, `completed` - успешная оплата | `completed`, `pending`, |
| paidAt | нет | datetime | Дата оплаты заказа (если оплачен) | `2026-12-22T00:00:00+00:00` |
---
# Создание заказа с холдированием
# Холдирование (блокировка) средств на карте
Холдирование (предавторизация) средств на карте покупателя работает так:
1. [Создать заказ](/docs/merchant/order/create/) с подтипом `subtype` = `hold`.
В таком заказе все позиции корзины `basketItems` должны быть с типом оплаты `paymentType` равным `full_prepayment` (предоплата 100%).
2. После оплаты такого заказа, средства на карте будут заблокированы до даты, указанной в параметре `holdTill` в [ответе на запрос](/docs/merchant/order/create/#orderresponse) создания заказа.
3. До этой даты магазину нужно сообщить по API об успешной отгрузке товаров или факта оказания услуги [методом создания отгрузки](/docs/merchant/order/shipment_create).
Можно осуществить сколько угодно отгрузок с указанием позиций заказа. На каждую такую отгрузку будут оформлены отчётные документы (фискальный чек).
Как только во всех отгрузках будет указаны все позиции из заказа, то заблокированные средства на карте спишутся.
4. Так же есть возможность списать средства, оказав только часть услуг или отгрузив только часть товаров из заказа, для этого
необходимо [создать отгрузку](/docs/merchant/order/shipment_create) с флагом `final` = `true`.
После такой отгрузки заказ считается выполненным, остаток средств на карте будет разблокирован.
---
# Создание заказа агентом
# Создание заказа с использованием реквизитов продавца
При интеграции с банками и крупными платёжными агрегаторами (далее — Агент) заказ создаётся в особом режиме: идентификационные данные магазина Инвойсбокс не нужны, вместо них передаются реквизиты юрлица. Отличий два:
- ИНН и КПП вместо идентификатора магазина
- авторизационные данные агента вместо авторизационных данных магазина
Заказ в этом режиме создаётся отдельным методом:
- метод: `POST`
- ресурс: `/v3/adapter/api/subagent/order`
> [!IMPORTANT]
> Метод обслуживается отдельным модулем: его схема не входит в публикуемый набор, поэтому консоль «Выполнить» для него недоступна. Перед интеграцией сверьте контракт с технической поддержкой.
- тело запроса - объект [CreateAgentOrderRequest](#createagentorderrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса
``` json
POST /v3/billing/api/order/order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"seller": {
"type": "counterparty",
"vatNumber": "232323232323",
"taxRegistrationReasonCode": "232323232323"
},
"merchantOrderId": "m-1608560079",
"amount": 366.00,
"successUrl": "https://shop.example.com/order/4412?result=success",
"failUrl": "https://shop.example.com/order/4412?result=fail",
"returnUrl": "https://shop.example.com/order/4412?result=return",
"vatAmount": 66.00,
"basketItems": [
{
"sku": "5fe0adcfa7fb4",
"name": "Бронирование номера",
"measure": "шт.",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 3,
"amount": 122.00,
"amountWoVat": 100.00,
"totalAmount": 366.00,
"totalVatAmount": 66.00,
"vatCode": "RUS_VAT22",
"type": "service",
"paymentType": "full_prepayment"
}
],
"metaData": {
"@type": "LodgingReservation",
"reservationId": "abc456",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "John Smith"
},
"reservationFor": {
"@type": "LodgingBusiness",
"name": "Hilton San Francisco Union Square",
"address": {
"@type": "PostalAddress",
"streetAddress": "333 O'Farrell St",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94102",
"addressCountry": "US"
},
"telephone": "415-771-1400"
},
"checkinTime": "2017-04-11T16:00:00-08:00",
"checkoutTime": "2017-04-13T11:00:00-08:00"
},
"expirationDate": "2026-12-22T00:00:00+00:00",
"languageId": "ru",
"currencyId": "RUB",
"description": "Оплата номера в отеле",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"phone": "79001112233",
"email": "buh@example.invbox.ru",
"vatNumber": "7701234560",
"taxRegistrationReasonCode": "770101001",
"registrationAddress": "190000, Санкт-Петербург, Невский пр. 147, офис 321"
}
}
```
Ответ:
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderId": "O-12345",
"status": "created",
"amount": 19658.45,
"vatAmount": 3276.41,
"currencyId": "RUB",
"createdAt": "2026-08-01T10:00:00+03:00",
"expirationDate": "2026-08-04T10:00:00+03:00",
"paymentUrl": "https://pay.invoicebox.ru/order/01771534-1a57-f184-dee3-ebeb91dded75"
}
}
```
## CreateAgentOrderRequest
Объект включает в себя все поля [CreateOrderRequest](/docs/merchant/order/create/#createorderrequest) а так же:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------|--------------|-------------------|-----------------|-----------------------------------------------------------------------------------------------------|
| seller | да | [Seller](#seller) | Данные продавца | `{"type": "counterparty", "vatNumber":"232323232323", "taxRegistrationReasonCode": "232323232323"}` |
## Seller
Повторяет свойства объекта [CreateOrderRequest](/docs/merchant/order/create/#createorderrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------------|--------------|------------|--------------------------------------------------|-----------------|
| type | да | string(36) | Тип продавца, доступные значения: `counterparty` | `counterparty` |
| countryId | да | string(3) | Страна, доступные значения: `RUS` | `RUS` |
| vatNumber | да | string(20) | ИНН | `7710044140` |
| taxRegistrationReasonCode | нет для ИП | string(9) | КПП | `770201001` |
Если продавец не найден в системе Инвойсбокс, то будет возвращена ошибка.
---
# WordPress
# Описание модуля WooCommerce
Плагин WordPress для Woocommerce предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает два режима работы - с системой «Инвойсбокс» версии 2, а также с обновлённой версией 3.
Версию вашего подключения уточняйте у вашего персонального менеджера или в службе поддержки системы.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка модуля
1. Зайдите в административную часть вашего сайта, перейдите на страницу «Плагины» → «Добавить новый»;
2. В списке доступных решений найдите модуль «InvoiceBox: Payment module for WooCommerce» ([InvoiceBox, invoicebox payment](https://ru.wordpress.org/plugins/invoicebox-payment-gateway/)), установите и активируйте его.
## Настройка модуля
В административном разделе сайта перейдите на страницу «Woocommerce» → «Настройки» → «Платежи» и нажмите на кнопку «Управление» у метода Инвойсбокс Payment для физ.лиц и Инвойсбокс Legal Payment для юр.лиц.
В настройках платёжной системы настройте следующие параметры:
1. “Название” и “Описание”. Значения данных полей будут показываться клиенту при выборе способа оплаты.
2. Выберите язык, на котором будет отображаться интерфейс платёжной страницы. Также изменится логотип платежной системы на странице оформления заказа (будет написан на кириллице или латинице)
3. Выберите версию API, которая будет использоваться
4. Для проверки настроек включите тестовый режим и проведите тестовый платёж в интернет-магазине. После успешного тестирования обязательно отключите тестовый режим.
5. В выпадающем списке выберите статус "В обработке". После того, как платежная система пришлёт сообщение об успешном прохождении оплаты, статус заказа изменится на указанный в этом поле (например “в обработке” или “выполнен”)
6. Поле "Email, куда отправлять сообщения об ошибках". Заполните это поле, если хотите получать оповещения в случае возникновения ошибок.
7. Выберите ставку НДС. Обратите внимание, что если в WooCommerce выключен расчёт налогов, то НДС будет рассчитываться по выбранному в этом поле значению. Если расчёт налогов включён - значение из настроек Инвойсбокс будет игнорироваться, а расчёт будет производиться по ставкам из настроек Woocommerce.
8. В поле "Тип оплаты" выберите вариант full_prepayment (в случае, если он не выбран по умолчанию)
9. Поле "Тип товара по умолчанию": выберите тип товара, который будет использоваться по умолчанию. Если на сайте присутствуют разные типы товаров, дополнительный вариант можно указать ниже в графе "Мета-поле, где задан тип для отдельного товара" (см. подробнее в пункте “Настройка мета-полей”)
10. Поле “Единица измерения по умолчанию”": выберите единицу измерения, которая будет использоваться по умолчанию. Если на сайте используются разные единицы измерения, дополнительный вариант можно указать ниже в графе "Мета-поле, где задана единица измерения для отдельного товара" (см. подробнее в пункте “Настройка мета-полей”). Также дополнительно указывается код единицы измерения (если выбран русский язык - проверяется по справочнику ОКЕИ). **Примечание: для русского языка важно точное соответствие значению справочнику ОКЕИ (пример - в единице измерения “шт” не должно быть точки в конце)**.
11. Поле “Страна-производитель товара по умолчанию”: выберите страну-производителя, которая будет использоваться по умолчанию. Если на сайте присутствуют товары из нескольких стран, дополнительный вариант можно указать ниже в графе "Мета-поле, где задана страна-производитель товара" (см. подробнее в пункте “Настройка мета-полей”).
12. Если выбрана третья версия API, есть возможность передавать дополнительные данные (например, бронирование билетов или мест проживания). Для этого нужно указать
мета-поле заказа, из которого плагин будет брать информацию. Подробнее о формате передаваемых данных написано в [разделе метаданные](/docs/merchant/order/metadata/).
Это поле должно создаваться и заполняться “на лету” из кода сразу после создания заказа перед оплатой, поэтому для его настройки может понадобиться помощь разработчика.
13. Далее нужно заполнить данные для доступа к API:
- идентификатор магазина (v2 и v3)
- региональный код магазина (v2)
- имя пользователя API (v2)
- пароль API (v2)
- ключ API (v2 и v3)
- токен (v3).
**Имя пользователя API и пароль API направляются после активации магазина в системе Инвойсбокс на электронную почту, указанную при регистрации.
Идентификатор магазина, региональный код магазина, ключ API находятся в личном кабинете Инвойсбокс в разделе "Настройки магазина".
Для теста плагина можно воспользоваться данными специально созданных магазинов для 2й и 3й версии апи (доступы к магазинам различаются).**
## Доступы для 2й версии API
- Поле “Идентификатор магазина” - вписываем нужное значение или тестовое значение “207”, если включен тестовый режим
- Поле “Региональный код магазина” - вводим нужное значение в поле или тестовое значение “78054”, если включен тестовый режим
- Поля “Имя пользователя” и “Пароль API”. Данные для теста: логин “78054-API” и пароль “LM936s#3jz0“
- Поле “Ключ API”. Значение для теста: LdjmgMS1WMS0nAIklbDkvuKT7WxaJIoC
- Нажимаем “Сохранить изменения”
## Доступы для 3й версии API:
- Поле «Идентификатор магазина». Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
- Поля «Токен» и «Ключ API» — значения там же, в данных для интеграции. соответственно
- Нажимаем “Сохранить изменения”
**Вы сможете отслеживать ошибки, включив функцию логирования. Данные об операциях и ошибках вносятся в логи WooCommerce (меню - WooCommerce - Статус - Журналы)**
**Чтобы настроить приём платежей от юридических лиц, повторите все шаги для способа оплаты Инвойсбокс Legal Payment**
Зайдите в свой личный кабинет на Инвойсбокс и в разделе “Мои магазины - Настройки - Интеграция API - URL уведомления” заполните настройки:
- Тип уведомления: Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных);
- URL уведомления: https://ВАШ_ДОМЕН/wc-api/wc_invoicebox_gateway
> [!WARNING]
> URL уведомления должен работать только по HTTPS: уведомления об оплате содержат данные заказов и подпись запроса.
## Настройка мета-полей
Мета-поле используется для установки дополнительных параметров товара (страна-производитель, единица измерения и тип товара и т.д.)
Возможно, сайт уже настроен таким образом, что эти поля в товарах есть (их добавляют некоторые плагины, либо это может быть дописанный код в теме). Об их наличии и том, какие значения записать в настройки плагина Инвойсбокс, можно уточнить у разработчиков сайта.
Если нужные поля отсутствуют, их можно создать самостоятельно с помощью плагина Advanced Custom Fields :
Далее в инструкции показано, как настроить рекомендуемые к заполнению поля. Обо всех остальных возможностях плагина вы можете прочесть в документации по ссылке [advanced custom fields](https://www.advancedcustomfields.com/resources/)
1. Установите и активируйте плагин Advanced Custom Fields [advanced custom fields](https://ru.wordpress.org/plugins/advanced-custom-fields/)
2. В меню выберите пункт “Добавить группу полей”
3. Добавьте новое поле
4. Произвольно назовите группу полей, а в условиях отображения выберите “Тип записи - равно - Товар”
В строке "Имя поля" - введите значение предыдущей строки латиницей (обязательно!). В строке "Тип поля" в выпадающем списке выберите "Текст"
5. Чтобы создать мета-поле "Тип товара", добавьте новое поле, заполните ярлык и имя, а в типе поля выберите “Выбор (select)”..
- Далее скопируйте и вставьте в пункт “Варианты” следующий текст:
- commodity : товар
- service : услуга
6. Сохраните группу полей.
7. Перейдите в любой товар в административной панели и убедитесь, что на странице товара появилась вкладка с новыми полями.
8. Впишите идентификаторы, которые вы задавали в “имени поля” на странице настроек плагина и сохраните настройки.
## Частые вопросы
1. Что такое мета-поле?
Мета-поля WordPress (произвольные поля) – это метаданные, которые используются для добавления дополнительной информации, относящихся к редактируемой записи, странице или товару.
2. Нужны ли какие-то дополнительные плагины для работы плагина Инвойсбокс?
Да. Для работы требуется плагин [WooCommerce](https://ru.wordpress.org/plugins/woocommerce/). Так же для настройки передачи дополнительных данных в платёжную систему может понадобиться плагин [advanced custom fields](https://ru.wordpress.org/plugins/advanced-custom-fields/)/ (см. подробности в пункте “Настройка мета-полей”).
3. Можно ли изменить время на оплату счёта?
Да. В настройках платёжной системы есть параметры для изменения времени на оплату
---
[Проект на github](https://github.com/InvoiceBox/WooCommerce-2)
---
# SportCRM
# Описание модуля SportCRM
[SportCRM](https://sportcrm.club) — это облачная система для организации и контроля тренировочных и соревновательных процессов
в спортивных клубах. Помогает контролировать работу администраторов, тренеров и партнёров по франшизе. Модуль Инвойсбокс
предоставляет простую возможность приёма оплаты для спортивных клубов и полное соответствие ФЗ-54 без лишних хлопот.
## Настройка модуля
Зайдите в SportCRM в раздел Управление > Настройки > Филиалы.
В выпадающем окне выберите Инвойсбокс
Укажите в настройках Идентификатор Магазина (v2), Региональный код, API ключ, которые можно получить в [личном кабинете Инвойсбокс](https://business.invoicebox.ru).
Также пропишите URL уведомления, которые сгенерирует SportCRM. Тип уведомления надо выбрать Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных).
## Читайте также
- [Онлайн касса (ФЗ-54)](/docs/merchant/fz54/)
---
# Bnovo
# Описание модуля Bnovo
Bnovo - система управления для гостиничного бизнеса. Модуль Инвойсбокс для Bnovo предоставляет
простую возможность отелям и иным участникам гостиничного бизнеса организации приёма оплаты как
от организаций и индивидуальных предпринимателей, так и от частных лиц за бронироания.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Настройка модуля
1. Зайдите в Bnovo в раздел Меню **бургер > Bnovo Финансы > Настройки > Прием онлайн-оплаты > Добавить шлюз** и
заполните заявку на подключение.
2. После настройки шлюза с стороны Bnovo, дождитесь письмо на электронную почту, что шлюз подключен.
3. После настройки шлюза совершите тестовое бронирование с платежом.
---
# Проверка возможности оплаты
# Проверка возможности подтверждения оплаты
Проверка, можно ли подтверждать оплату, — отдельный вызов:
- метод: `POST`
- ресурс: `/v3/billing/api/order/{uuid}/payment-method-action/validate`
- тело запроса - объект [ValidateRequest](#validaterequest)
- тело ответа - объект [ValidateResponse](#validateresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
POST /v3/billing/api/order/{uuid}/payment-method-action/validate
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"paymentMethodId": "39363265",
"languageId": "ru",
"customer": {
"name": "ООО Компания",
"email": "email@gmail.com",
"type": "legal",
"phone": "79611234567",
"vatNumber": "1233123",
"registrationAddress": "123123123"
}
}
```
Ответ:
``` json
{
"data": {
"type": "none",
"result": "available",
"resultData": {
"url": "",
"method": "POST",
"arguments": []
}
}
}
```
## ValidateRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|------------------------|--------------|------------------------------------------|-------------------------------------------------|------------|
| paymentMethodId | да | string(36) | Идентификатор инструмента подтверждения оплаты | |
| languageId | нет | string(2) enum | Язык плательщика | `ru`, `en` |
| customer | да | [Customer](/docs/merchant/order/create/#customer) | Информация о плательщике | |
## ValidateResponse
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------|--------------------------------------|
| data | да | [PaymentResponse](/docs/merchant/guarantee/validate/#paymentresponse) | Информация об оплате |
## PaymentResponse
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|-----------------------------|
| result | да | enum | Статус проверки (см. ниже) |
| resultNote | нет | string | Комментарий |
Возможные статусы:
- notRegistered - Организация или ИП не зарегистрировано в системе
- notEnoughMoney - Недостаточно средств для подтверждения оплаты заказа
- available - Подтверждение оплаты заказа доступно
---
---
# Услуга не может быть оказана
# Услуга не может быть оказана или товар не может быть доставлен
Как правило, система «Инвойсбокс» уведомляет Магазин о факте оплаты счёта асинхронно от действий
покупателя на платёжной странице. Т.е. покупатель подтверждает оплату заказа в интерфейсе «Инвойсбокс»,
возвращается на страницу магазина, а уведомление об оплате счёта асинхронно передаётся системой
«Инвойсбокс» в магазин по API.
В некоторых сценариях, требуется контролировать факт успешной доставки уведомления об оплате до
Магазина и уведомлять покупателя о таком процессе. Например, по факту оплаты требуется подтвердить
наличие товара на складе и зарезервировать его, или же, по факту оплаты требуется забронировать
места/номера/время и оформить билет. Такие сценарии как правило используются совместно с
гарантийными оплатами (предавторизация денежных средств на банковской карте или использование
гарантийного фонда до момента подтверждения возможности оказания услуги и дальнейшее списание
средств или отмена).
> [!IMPORTANT]
> Использование сценария требует включения настройки платёжной страницы Магазина "Контроль отгрузки на
> платёжной странице". В случае, если у вас возникнут сложности при самостоятельной настройке,
> пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Пример сценария
Покупатель подтверждает оплату счёта на [платёжной странице](/docs/merchant/payment-page/). Платёжная страница
отображает покупателю загрузчик (лоадер ⌛). Система «Инвойсбокс» уведомляет Магазин о факте оплаты счёта и ожидает
ответ.
Система Магазина выполняет свою логику по резервированию товара или бронированию услуги.
### ✅ Позитивный сценарий
Система Магазина успешно резервирует товар или бронирует услугу. В этом случае, в ответ на запрос
«Инвойсбокс», система Магазина возвращает статус `success`.
Покупателю на платёжной странице отображается информация об успешном подтверждении оплаты, покупатель
перенаправляется в Магазин на страницу успешной оплаты заказа.
### ❌ Негативный сценарий
При попытке резервирования товара или бронирования услуги, система Магазина получает ошибку. В
этом случае, в ответ на запрос «Инвойсбокс», система Магазина возвращает статус `error` с кодом
`shipping_unavailable` (Услуга не может быть оказана или товар не может быть доставлен).
Покупателю на платёжной странице отображается информация о невозможности оказания услуги, а также
дальнейшие инструкции о том, как и когда платёж будет отменён. Покупатель перенаправляется в Магазин
на страницу ошибки при оплате заказа.
### Отмена оплаты и возврат денежных средств
Обратите внимание, негативный ответ на уведомление об оплате счёта, не инициирует процессы возврата.
Магазин должен самостоятельно инициировать процессы возврата в случае невозможности поставки товара
или оказания услуги. Если требуется формирование автоматического возврата/разблокирования средств, необходимо
вместо `shipping_unavailable` использовать код `full_refund_required`
В случае, если оплата заказа была подтверждена с использованием гарантийного платежа, Магазин может
вызвать [метод отмены заказа](/docs/merchant/order/delete/) для полного возврата средств покупателю
(отмены гарантийной оплаты, reverse).
В случае, если оплата заказа была подтверждена с использованием иных платёжных инструментов, Магазин
может вызвать [метод возврата по заказу](/docs/merchant/refund) для полного или частичного возврата
средств покупателю.
---
---
# ТАИС (TravelShop)
# Описание интеграции ТАИС (TravelShop)
[TravelShop](https://ors.aero/travelshop) — это гибкий модуль онлайн-продаж авиационного контента для онлайн-трэвел
агентств и авиакомпаний. Модуль настраивается под особенности вашего бизнеса: сценарии продажи,
оформление и правила работы с клиентами задаются на вашей стороне.
## Решения на базе интеграции
- [Автоматизация продаж авиабилетов юридическим лицам и ИП (b2b)](/docs/scenarios/air-carriers).
## Настройка интеграции
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# Получение возвратов
# Получение списка возвратов
Возвраты читаются одним запросом:
- метод: `GET`
- ресурс: `/v3/filter/api/order/refund-order`
- тело ответа - коллекция объектов [RefundOrderResponse](/docs/merchant/refund/create/#refundorderresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
В запросе можно применять фильтры и сортировку.
Пример запроса с фильтром по идентификатору возврата
```http
GET /v3/filter/api/order/refund-order?id=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по идентификатору заказа (по которому оформлялся возврат)
```http
GET /v3/filter/api/order/refund-order?parentId=d6f1ccb2-2e32-43c2-8a42-5a835dd88607
```
Пример запроса возвратов с фильтром по [статусу](/docs/merchant/refund)
```http
GET /v3/filter/api/order/refund-order?status=completed
```
Пример запроса возвратов с фильтром по идентификатору магазина
```http
GET /v3/filter/api/order/refund-order?merchantId=2ce417f1-8702-4517-bb56-11cd305d2594
```
Пример запроса возвратов с фильтром по идентификатору заказа в учётной системе магазина
```http
GET /v3/filter/api/order/refund-order?merchantOrderId=ORD123456
```
---
#### Пример запроса и ответа
``` json
GET /v3/filter/api/order/refund-order?status=completed
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
User-Agent: MyApp 1.0
Accept: application/json
```
Ответ (по схеме):
``` json
{
"data": [
{
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string",
"currencyId": "RUB",
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"status": "string",
"shipmentStatus": "string",
"subtype": "string",
"processingStatus": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderIdVisible": "string",
"expirationDate": "2026-08-03T12:00:00+03:00",
"metaData": {},
"customerData": {},
"notificationUrl": "string",
"orderSetting": {
"roundPolicy": "string",
"disableValidate": false
},
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"shopId": 1,
"sourceId": "l3",
"paidAt": "2026-08-03T12:00:00+03:00",
"orderContainerId": "01771534-1a57-f184-dee3-ebeb91dded75",
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"processable": false,
"userAccountId": "01771534-1a57-f184-dee3-ebeb91dded75"
}
],
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
---
# Организации и ИП
## Покупатели - организации и индивидуальные предприниматели
### Процесс создания заказа и оплаты счёта
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Покупатель->>Магазин: Создаёт заказ
Магазин->>Инвойсбокс: Вызов метода создания заказа
Инвойсбокс->>Магазин: Идентификатор заказа и ссылка на оплату
Магазин->>Покупатель: Перенаправление на платёжную страницу
Покупатель-->>Инвойсбокс: Взаимодействие с платёжной страницей, получение счёта
Покупатель->>Инвойсбокс: Оплата счёта
Инвойсбокс->>Покупатель: Перенаправление покупателя на сайт магазина
Инвойсбокс->>Магазин: Уведомление об успешной оплате
end
1. Покупатель оформляет заказ на сайте Магазина и выбирает способ оплаты через систему «Инвойсбокс».
1. Магазин создает в системе «Инвойсбокс» заказ [через метод API](/docs/merchant/order/create/).
1. Система возвращает ссылку на платёжную страницу для оплаты заказа.
1. Магазин перенаправляет покупателя по полученной ссылке.
1. Покупатель заполняет необходимые для оплаты сведения и получет счёт для оплаты.
1. Покупатель оплачивает счёт.
1. Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
1. Система «Инвойсбокс» оповещает Магазин об успешной оплате заказа.
### Процесс отгрузки и оформления отчётных документов
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(15, 123, 119, 0.13)
Магазин->>Инвойсбокс: Вызов метода отгрузки по заказу
Инвойсбокс->>Покупатель: Предоставление отчётных документов
Магазин-->>Покупатель: Предоставление отчётных документов (если требуется)
end
1. В случае, если Магазин оказывает услугу или продаёт товар, Магазин направляет запрос отгрузки в систему «Инвойсбокс» по факту оказания услуги или факту отгрузки товара курьерской службой/службе доставки или покупателю. Если услуга оказывается онлайн, отгрузка по заказу может быть установлена автоматически.
1. Система «Инвойсбокс» формирует отчёт о переводе средств, а также дополнительный набор отчётных документов по доверенности от магазина, если требуется. При оказании услуг формируется акт, при продаже товаров - формируется ТОРГ-12. Система «Инвойсбокс» направляет пакет отчётных документов покупателю по электронной почте, оригиналы по почте и с помощью ЭДО.
1. Магазин направляет покупателю пакет отчётных документов, если это предусмотрено процессом.
### Процесс оформления возврата
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(107, 70, 193, 0.13)
Покупатель->>Магазин: Обращается за возвратом по заказу
Магазин-->Инвойсбокс: Получение списка позиций в заказе
Магазин->>Инвойсбокс: Вызов метода оформления возврата
Инвойсбокс->>Покупатель: Осуществление возврата денежных средств
Инвойсбокс->>Покупатель: Предоставление отчётных документов
Магазин-->>Покупатель: Предоставление отчётных документов (если требуется)
end
1. Покупатель обращается в Магазин для оформления возврата заказа.
1. Опционально, Магазин запрашивает [через метод API](/docs/merchant/refund/get/) доступные к возврату позиции в заказе.
1. Магазин создает возврат в системе «Инвойсбокс» [через метод API](/docs/merchant/refund/create/).
1. Система «Инвойсбокс» возвращает денежных средств покупателю.
1. Система «Инвойсбокс» формирует набор отчётных документов по доверенности от магазина, если требуется (например, при [комиссионной торговле](/docs/merchant/schema/commission/)). При оказании услуг формируется акт, при продаже товаров - формируется ТОРГ-12. Система «Инвойсбокс» направляет пакет отчётных документов покупателю по электронной почте, оригиналы по почте и с помощью ЭДО.
1. Магазин направляет покупателю пакет отчётных документов, если это предусмотрено процессом.
---
---
# Отмена возврата
# Отмена возврата
Возврат в статусе `created` (создан) можно отменить:
- метод: `DELETE`
- ресурс: `/v3/billing/api/order/refund-order/:uuid` - где `:uuid` это идентификатор возврата
- тело запроса - отсутствует
- тело ответа — пустой ответ (HTTP 200); статус возврата меняется на `cancel`
#### Пример запроса и ответа
#### 🌐 HTTP
```http
DELETE /v3/billing/api/order/refund-order/c5041a79-24a6-42d1-b0ce-4abb94982cd9
Accept: application/json
User-Agent: MyApp 1.0
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
```
#### 🧊 CURL
```bash
curl -L -X DELETE '{baseUrl}/v3/billing/api/order/refund-order/c5041a79-24a6-42d1-b0ce-4abb94982cd9' \
-H 'Accept: application/json' \
-H 'User-Agent: MyApp 1.0' \
-H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e'
```
{baseUrl} - [базовый URL](/docs/api)
В зависимости от сценария использования и настроек магазина, может быть применена разная логика при вызове метода.
По умолчанию, отменить возврат возможно только в статусах `draft` (черновик) или `created` (создан).
---
Ответ: HTTP 200 с пустым телом. Отмена состоялась, если статус возврата
сменился на `cancel` — его видно [методом получения возврата](/docs/merchant/refund/get/).
---
# Документооборот
# Документооборот
Вторая половина работы Инвойсбокса: принять оплату мало, корпоративному покупателю нужны документы.
Их формирует и отправляет Инвойсбокс — магазину не нужен свой оператор ЭДО и не нужно собирать
комплекты вручную.
## Какие документы формируются
| Документ | Когда появляется | Кому нужен |
|---|---|---|
| Счёт на оплату | сразу после [создания заказа](/docs/merchant/order/create/) | покупателю, чтобы провести платёж через банк |
| Фискальный чек | в момент оплаты, регистрируется в [онлайн-кассе](/docs/merchant/fz54/) | покупателю-физлицу, по 54-ФЗ |
| Акт или ТОРГ-12 | после оплаты и подтверждения отгрузки | бухгалтерии покупателя-организации |
| Счёт-фактура | после оплаты, если продавец на общей системе налогообложения | для вычета НДС |
| УПД | вместо связки «акт + счёт-фактура», если так удобнее сторонам | бухгалтерии обеих сторон |
Состав комплекта зависит от схемы работы: см. [схемы документооборота](/docs/merchant/schema/) —
[с юрлицами](/docs/merchant/schema/legal/), [с физлицами](/docs/merchant/schema/private/)
и [с комиссией](/docs/merchant/schema/commission/).
## Что запускает формирование
Документы привязаны к событиям заказа, а не к календарю:
1. Заказ создан — формируется счёт.
2. Оплата подтверждена — регистрируется чек, магазину уходит
[уведомление о смене статуса](/docs/merchant/notification/status/).
3. Отгрузка подтверждена — формируются акт или накладная. Если отгрузка идёт частями, документ
создаётся на каждую [отгрузку](/docs/merchant/order/shipment_create/).
4. Возврат оформлен — формируются корректирующие документы; при удержании части суммы
используйте [возврат с корректировкой](/docs/merchant/refund/correction/).
О движении документов в ЭДО магазин узнаёт из [событий ЭДО](/docs/merchant/documentflow/edo_events/):
документ отправлен, получен, подписан, отклонён.
## Как покупатель получает документы
Способ выбирает сам покупатель — магазину для этого ничего делать не нужно.
| Путь | Когда срабатывает |
|---|---|
| Автоматически по ЭДО | покупатель заранее настроил обмен с Инвойсбоксом и запросил документы для себя на [платёжной странице](/docs/merchant/payment-page/) — комплект уходит сразу после оплаты |
| По ссылке из письма | после оплаты покупателю приходит письмо со ссылкой на сервис запроса документов: там он выбирает электронные файлы, бумажные оригиналы почтой или обмен по ЭДО |
| Из личного кабинета | покупатель заходит в кабинет Инвойсбокса и запрашивает комплект в любом виде в любой момент |
Магазин видит документы покупателя в информации о своём заказе — отдельно запрашивать
их не нужно.
**Когда документы становятся доступны.** По умолчанию — после оплаты заказа. Но момент
зависит от схемы документооборота: что продаётся и на каких условиях. Например, документы
на товары могут появляться после отгрузки покупателю или выполнения других условий
договора — см. [схемы документооборота](/docs/merchant/schema/).
## Кто подписывает и куда уходит
Документы подписываются электронной подписью Инвойсбокса как оператора расчётов и уходят
покупателю через его оператора ЭДО. Оператор определяется по реквизитам организации; если у покупателя
ЭДО нет, документы доступны в личном кабинете и отправляются на почту.
## Что дальше
- [События ЭДО](/docs/merchant/documentflow/edo_events/) — как получать статусы документов в свою систему.
- [Сроки и условия](/docs/terms/) — когда документы формируются и когда приходят деньги.
- [Схемы документооборота](/docs/merchant/schema/) — какой комплект получается в вашей схеме.
---
---
# События документооборота
### Обработка событий документооборота
---
В жизненном цикле документооборота по заказу возникают события, которые необходимо обрабатывать магазином (например: расхождения данных, подписание или отклонение документов).
Такие события отправляются в формате JSON на `URL`, предоставленный магазином.
---
### **Формат объекта события**
Каждое событие содержит общую структуру:
```json
{
"eventName": "название_события",
"eventData": { ... } // Данные, специфичные для типа события
}
```
| Поле | Тип | Обязательность | Описание |
|---------------|---------|----------------|-------------------------------------------------|
| `eventName` | string | Да | Тип события (см. ниже возможные значения). |
| `eventData` | object | Да | Объект с данными, зависящими от типа события. |
---
### **Типы событий**
---
#### **1. Документ подписан (`document_signed`)**
Уведомление о успешном подписании документа (например, счета или акта).
**Структура `eventData`:**
```json
{
"documentType": "invoice",
"documentId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
```
| Поле | Тип | Обязательность | Описание | Пример значения |
|-----------------|---------|----------------|-------------------------------------------|------------------------------------------|
| `documentType` | string | Да | Тип документа: `invoice`, `act`, `order`. | `"invoice"` |
| `documentId` | string | Да | UUID документа. | `"6ba7b810-9dad-11d1-80b4-00c04fd430c8"` |
---
#### **2. Документ отклонен (`document_rejected`)**
Уведомление об отклонении документа (например, из-за ошибок или несогласия сторон).
**Структура `eventData`:**
```json
{
"documentType": "invoice",
"documentId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
}
```
| Поле | Тип | Обязательность | Описание | Пример значения |
|-----------------|---------|----------------|-------------------------------------------|------------------------------------------|
| `documentType` | string | Да | Тип документа: `invoice`, `act`, `order`. | `"invoice"` |
| `documentId` | string | Да | UUID документа. | `"6ba7b810-9dad-11d1-80b4-00c04fd430c8"` |
| `rejectReason` | string | Да | Причина отклонения. | `"Несоответствие данных в счете"` |
---
#### **3. Расхождение данных (`data_mismatch`)**
Уведомление о несоответствии данных между заказом/отгрузкой и документом ЭДО.
**Структура `eventData`:**
```json
{
"sourceType": "shipment",
"sourceId": "550e8400-e29b-41d4-a716-446655440000",
"compareType": "edo",
"compareId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "mismatch",
"details": [
{
"type": "value",
"field": "quantity",
"sku": "product_123",
"sourceValue": 2,
"compareValue": 3
}
]
}
```
| Поле | Тип | Обязательность | Описание |
|------------------|---------|----------------|-------------------------------------------------------------------------|
| `sourceType` | string | Да | Тип источника: `order`, `shipment`, `refund`. |
| `sourceId` | string | Да | UUID источника (например, отгрузки). |
| `compareType` | string | Да | Тип сравнения: только `edo`. |
| `compareId` | string | Да | UUID документа ЭДО. |
| `status` | string | Да | Статус: только `mismatch`. |
| `details` | array | Да | Массив расхождений (см. таблицу ниже). |
**Поля объектов в массиве `details`:**
| Поле | Тип | Обязательность | Описание |
|------------------|---------|----------------|-------------------------------------------------------------------------|
| `type` | string | Да | Тип расхождения: `value`, `missing`, `extra`. |
| `field` | string | Условно | Поле (для `type: value`): `quantity`, `price`, `vatRate`. |
| `sku` | string | Да | SKU товара. |
| `sourceValue` | number | Условно | Значение из источника (для `type: value`). |
| `compareValue` | number | Условно | Значение из ЭДО (для `type: value`). |
---
### **Пример полного события**
```json
{
"eventName": "data_mismatch",
"eventData": {
"sourceType": "shipment",
"sourceId": "550e8400-e29b-41d4-a716-446655440000",
"compareType": "edo",
"compareId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "mismatch",
"details": [
{
"type": "missing",
"sku": "product_456",
"sourceValue": null,
"compareValue": null
}
]
}
}
```
---
# OpenCart 2.x
# Описание модуля OpenCart 2.x
[OpenCart](https://www.opencart.com/) — платформа электронной коммерции, ориентированная на создание интернет-магазинов.
Бесплатное свободное программное обеспечение, поддерживаются дополнения - модули и шаблоны.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Для установки и настройки платёжного модуля Инвойсбокс:
1. Пройдите по ссылке к плагину на сайте OpenCart. [OpenCart - Платёжный модуль Инвойсбокс](https://www.opencart.com/index.php?route=marketplace/extension/info&member_token=5a2149467743eb9a98246d974109dc4c&extension_id=43952)
2. Авторизуйтесь или зарегистрируйте новый аккаунт. Это нужно для скачивания плагина.
3. Скачайте архив с плагином.
**Важно: название архива с модулем должно заканчиваться на .ocmod.zip.**
**Важно: сайт должен работать на версии php не менее 7.3.**
4. В административной панели зайдите в раздел Настройки - Управление магазином - FTP и заполните данные для ftp-доступа к сайту.
5. В административной панели зайдите в раздел Модули/Расширения → Установка расширений и загрузите файл install.ocmod.zip.
6. Перейдите в раздел Модули/Расширения → Модификаторы. Очистите и обновите кэш модификаторов, нажав на соответствующие кнопки в правом верхнем углу экрана.
7. Заходим в раздел Модули/расширения → Модули/расширения.
8. Открываем селект и выбираем Оплата.
9. Находим Инвойсбокс и нажимаем на кнопку “активировать”.
## Настройка модуля
1. Зайдите в раздел Модули/расширения → Модули/расширения.
2. В выпадающем списке выберете "Оплата".
3. Найдите модуль “Инвойсбокс” и перейдите в редактирование.
4. Перейдите в раздел "настройка платежей". Выберите версию API, заполните необходимые данные:
- идентификатор магазина (v2, v3 новая и v3 текущая)
- региональный код магазина (v2)
- имя пользователя API (v2)
- пароль API (v2)
- ключ API (v2, v3 новая и v3 текущая)
- токен (v3 новая и v3 текущая)
В пункте 5 будут даны тестовые данные для 2й версии, а в пункте 6 - для 3й версии (новой), для получения данных для 3 версии текущего АПИ рекомендуется написать на почту [c-support@invoicebox.ru](mailto:c-support@invoicebox.ru).
5. Доступы для 2й версии API:
- Поле “Магазин” - вставьте нужное или тестовое значение “207” (если включен тестовый режим)
- Поле “Региональный код магазина” - введите нужное или тестовое значение “78054” (если включен тестовый режим)
- Заполните поля “Имя пользователя” и “Пароль”. Данные для теста: логин “78054-API” и пароль “LM936s#3jz0“.
- Поле “Ключ”. Значение для теста: LdjmgMS1WMS0nAIklbDkvuKT7WxaJIoC.
- Нажмите кнопку “Сохранить” в правом верхнем углу экрана
- 
6. Доступы для 3й версии API:
- Поле «Идентификатор магазина». Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
- Поля «Токен» и «Ключ API» — значения там же, в данных для интеграции.
- Нажмите кнопку “Сохранить” в правом верхнем углу экрана
7. Выберите налоговый режим, в котором работает магазин. См. раздел “настройка налогового режима”.
8. Убедитесь, что заполнены значения полей “Единица измерения” и “Код единицы измерения”. Стандартные значения “шт” и “796”. Индивидуальные значения для каждого товара задаются в атрибутах товара.
9. Если нужно допускать заказ к оплате только после проверки модератором, выберите режим отложенной оплаты и статус, при переводе заказ в который, пользователю будет посылаться ссылка на оплату. Подробнее - в разделе “Специфические настройки”.
10. Заполните значения полей SKU в товарах. Если они будут не заполнены, оплату за товар нельзя будет вернуть. Для этого:
1. Зайдите в раздел Каталог → Товары и нажмите на редактирование товара.
2. Далее зайдите в раздел “Данные” и нажмите кнопку справа “двойная стрелка”.
3. Найдите поле “Артикул” и при отсутствии актуальных артикулов заполните строку любыми числами. Главное, чтобы у каждого товара был свой уникальный артикул.
11. Значения остальных полей описано в разделе “Специфические настройки”.
12. Не забудьте в настройках модуля поставить статус “включено”.
При оформлении заказа обязательно нужно добавить корректный номер телефона.
Возникшую при оплате ошибку можно узнать в истории заказа в админ-панели.
Настройка налогового режима
В налогах важны три пункта:
показываются они клиенту или нет
ставка НДС
формат цен
Формат цен задается в “Система - Локализация - Валюта”. Для каждой валюты проставьте в поле “количество знаков после запятой” значение 2.
Ставка НДС задаётся в меню “Система - Локализация - Налоги - Налоговые ставки”.
Допускаются ставки НДС 0%, 10%, 20%. В типе нужно выставить “процент”, а в “ставке” - нужное число.
Показ налогов настраивается в 3х местах: в модуле “Инвойсбокс”, в настройках, в модуле “Учитывать в заказе”.
Корректными являются такие варианты:
1. Налоги уже учтены в стоимости и не показываются клиенту.
- Модуль “Инвойсбокс”:
- “Система - Настройки - Опции”:
- Модули/расширения - Учитывать в заказе/Всего заказов-Отчеты - Налоги / Налоговый отчет:
2. Налоги считаются поверх указанной стоимости товара и показываются клиенту:
- Модуль “Инвойсбокс”:
- Система - Настройки - Опции:
- Модули/расширения - Учитывать в заказе - Налоги:
### Обновление модуля
При обновлении модуля необходимо в начале удалить модификатор модуля
И очистить кеш
После этого провести ту же процедуру, что и при первой установке модуля
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале «Инвойсбокс», но деньги с вашей карты списаны не будут.
Статус заказа после оплаты - после успешной оплаты заказа, заказу будет установлен выбранный статус.
Статус заказа после подтверждения - при нажатии на кнопку "Подтвердить" на последнем этапе оформления заказа, заказу будет установлен выбранный статус.
Статус заказа после неудачной оплаты - Если «Инвойсбокс» вернёт покупателя после неудачного платежа, заказу будет установлен выбранный статус.
Статус заказа для отсроченной оплаты - после проверки заказа менеджер магазина выставит этот статус, покупатель будет уведомлен по электронной почте и сможет оплатить заказ. Также, ссылка на оплату появится в личном кабинете покупателя в разделе "Мои заказы".
**БУДЬТЕ ВНИМАТЕЛЬНЫ!** Если этот статус совпадёт со "статус заказа после подтверждения" - режим отсроченной оплаты будет отключён и покупатели будут перенаправляться на сайт «Инвойсбокс» для оплаты сразу после нажатия на кнопку "Оформить заказ".
Режим отсроченной оплаты - при включённом режиме отсроченной (отложенной) оплаты покупатель сможет оплатить заказ только после проверки заказа менеджером магазина. Если вам необходимо, чтобы у покупателя была возможность произвести оплату сразу после оформления заказа без подтверждения менеджером - не включайте эту опцию.
Название - Название метода оплаты на странице оформления заказа.
Инструкция по оплате - выводится при подтверждении заказа. Если поле не заполнено - инструкция выводиться не будет.
В поле "Тип оплаты" выберите вариант full_prepayment (если он не выбран по умолчанию).
Поле "Тип товара по умолчанию"- выберите тип товара, который будет использоваться по умолчанию. Если на сайте присутствуют разные типы товаров, у каждого товара свой тип можно задать в атрибутах.
Поля “Страна-производитель товара по умолчанию” и “Код страны-производителя товара по умолчанию” : выберите страну-производителя, которая будет использоваться по умолчанию. Если на сайте присутствуют товары из нескольких стран, у каждого товара свою страну можно задать в атрибутах.
Если выбрана третья версия API, есть возможность передавать дополнительные данные (например, бронирование билетов или мест проживания).
Для передачи этих данных понадобится помощь разработчика. Сохранять информацию нужно в таблицу `oc_invoicebox_meta`. Подробнее о формате
передаваемых данных можете узнать в [разделе метаданные](/docs/merchant/order/metadata/).
Причины возникновения ошибок при загрузке:
Проверьте, оканчивается ли архив с модулем на “.ocmod.zip”
Проверьте версию php на сайте. Версия должна быть не менее 7.3.
Причины возникновения ошибок при оплате:
Если при оплате возникает ошибка, в первую очередь стоит зайти в административную панель, в раздел заказов и открыть новый заказ. Чаще всего причина будет указана там.
Проверьте, корректно ли указаны единицы измерения. Они должны быть указаны либо в каждом товаре, либо в настройках модуля (если в товаре нужных атрибутов нет, значения берутся из модуля). Частая ошибка - “шт.” вместо “шт”. Код для “шт” - 796.
Проверьте, корректно ли в товарах указан тип товара в самом товаре. Допустимые значения “commodity” и “service”. Либо оставьте поле пустым, чтобы значение бралось из настроек модуля.
Проверьте, правильно ли выставлены настройки налогов. См. раздел “настройка налогового режима”.
Проверьте, корректно ли заполнены доступы от API.
Проверьте, не включена ли опция “тестовое окружение”, если для магазина в Инвойсбокс не создавалось тестовое окружение. Если вы используете тестовые данные доступа из этой инструкции, настройка “тестовое окружение” должна быть отключена.
Проверьте в настройках модуля, включен ли он.
Если включен режим отложенной оплаты, убедитесь, что статус заказа для отсроченной оплаты не совпадает со статусом заказа после подтверждения.
Причины возникновения ошибок при возврате:
Если при оплате возникает ошибка, в первую очередь стоит посмотреть в истории заказа - иногда точная ошибка может быть указана там.
Проверьте, что используется та же версия API, что и при оплате заказа (нельзя переключаться со 2й на 3ю и наоборот).
Убедитесь, что общая сумма возврата не превышает допустимую для этого заказа (если по этому заказу уже был возврат, остаток будет указан в предупреждении на странице возврата).
Убедитесь, что сумма возврата по каждому товару не больше суммы оплаты по этому товару.
Убедитесь, что у каждого товара заполнено поле SKU (Артикул) - с пустым полем сделать возврат для товара нельзя.
#### Настройка в личном кабинете Инвойсбокс
Без этого шага магазин не узнает об оплате: заказ так и останется неоплаченным в панели управления,
даже если деньги пришли.
1. Войдите в личный кабинет и откройте «Мои продажи» → «Мои магазины» → «Интеграция (API)».
2. Выберите тип уведомления — уведомление о смене статуса заказа.
3. В поле «URL уведомления» укажите адрес обработчика модуля на вашем сайте. Адрес показывает сам
модуль в своих настройках; он должен быть доступен снаружи и работать по HTTPS.
4. Сохраните изменения.
Как устроено уведомление и как проверить подпись — [Уведомление о смене статуса
заказа](/docs/merchant/notification/status/).
## Часто задаваемые вопросы:
Вопрос: При выборе способа оплаты, заказ исчезает из панели управления магазином, даже если клиент его оплатил
Ответ: Проверьте корректность указания ссылка уведомления об оплате в личном кабинете системы Инвойсбокс. Заказ отображается в панели управления магазином только в том случае, если система оплаты корректно передала магазину информацию об оплате заказа.
---
# Запрос кода подтверждения
# Запрос кода подтверждения
Код подтверждения запрашивается и уходит покупателю одним вызовом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/{uuid}/payment-method-action/send-code`
- тело запроса - объект [CodeRequest](#coderequest)
- тело ответа - объект [CodeResponse](#coderesponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
POST /v3/billing/api/order/{uuid}/payment-method-action/send-code
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"paymentMethodId": "39363265",
"languageId": "ru",
"customer": {
"name": "ООО Компания",
"email": "email@gmail.com",
"type": "legal",
"phone": "79611234567",
"vatNumber": "1233123",
"registrationAddress": "123123123"
}
}
```
Ответ:
``` json
{
"data": {
"type": "none",
"result": "success",
"resultData": {
"publicCode": "aaaaaaa123",
"leftAttempt" : 5
}
}
}
```
## CodeRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|------------------------|--------------|------------------------------------------|-------------------------------------------------|------------|
| paymentMethodId | да | string(36) | Идентификатор инструмента подтверждения оплаты | |
| languageId | нет | string(2) enum | Язык плательщика | `ru`, `en` |
| customer | да | [Customer](/docs/merchant/order/create/#customer) | Информация о плательщике | |
## CodeResponse
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------|--------------------------------------|
| data | да | [PaymentResponse](/docs/merchant/guarantee/code/#paymentresponse) | Информация об оплате |
## PaymentResponse
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|----------------------------------------------|
| type | да | enum | Тип действия: none |
| result | да | enum | Статус проверки (см. ниже) |
| resultData | да | object | [Code](/docs/merchant/guarantee/code/#code) |
Возможные статусы:
- error - ошибка
- codeAlreadySent - код уже был отправлен ранее, срок повторной отправки кода не истёк
- success - успешно
## Code
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|---------------------------------------------|
| publicCode | да | string | Публичный идентификатор кода |
| leftAttempt | да | int | Количество оставшихся попыток отправки кода |
---
---
# Не процессинговые заказы
# Не процессинговые заказы
Заказ считается не процессинговым, если:
- При создании заказа был указан флан `processable` в значении `false`
- Если отсутствует действующий договор с магазином
Если при создании заказ помечен процессинговым, но действующего контракта с магазином нет,
то заказ становится не процессинговым. По не процессинговым заказам не происходит движения денежных средств
в рамках биллинга.
У не процессинговых заказов имеется возможность [смены статуса](/docs/merchant/order/order-status-update/).
## Возможные статусы заказа
1. `created` - Заказ создан, но еще не оплачен
2. `completed` - Заказ оплачен
3. `expired` — срок действия заказа истёк: указанное в `expirationDate` время уже прошло. Оплатить по прежней ссылке нельзя, нужен новый заказ
4. `canceled` - Заказ отменён магазином до его оплаты
---
---
# Работа с заказом
# Работа с заказом
Заказ — основной объект при работе Магазина с системой «Инвойсбокс».
Текущий раздел описывает возможные манипуляции с заказом.
## Возможные статусы заказа
Заказ живёт по одной схеме независимо от способа оплаты: из `created` он уходит либо в оплату, либо в
`expired` по сроку, либо в `canceled` по решению магазина. Холдирование добавляет промежуточное
состояние.
```mermaid
stateDiagram-v2
[*] --> created: создание заказа
created --> completed: оплата
created --> hold: оплата с холдированием
hold --> completed: отгрузка закрыла все позиции
hold --> canceled: отмена, резерв снят
created --> expired: истёк expirationDate
created --> canceled: отмена магазином
completed --> completed: возврат оформляется отдельным заказом
```
Возврат не меняет статус исходного заказа: он создаётся
[отдельной операцией](/docs/merchant/refund/create/) со своим жизненным циклом.
1. `created` - Заказ создан, но еще не оплачен
2. `hold` - По заказу удержаны (захолдированы) денежные средства до момента списания или отмены холда
3. `completed` - Заказ оплачен
4. `expired` — срок действия заказа истёк: указанное в `expirationDate` время уже прошло. Оплатить по прежней ссылке нельзя, нужен новый заказ
5. `canceled` - Заказ отменён магазином до его оплаты
---
# Возврат с комиссией/штрафом
# Возврат с комиссией/штрафом
Иногда при возврате нужно удержать штраф, комиссию за возврат или сервисный сбор — и провести удержание в финансовой отчётности.
Такой возврат происходит в два этапа через корректировочный заказ на комиссию, штраф или сервисный сбор:
- [Формирование возврата](#формирование-возврата)
- [Формирование корректировочного заказа](#формирование-корректировочного-заказа)
Сумма возврата из первого шага пересчитывается на сумму корректировочного заказа — её и получает покупатель.
### Процесс оформления возврата через корректировочный заказ
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
participant Онлайн касса
rect rgba(107, 70, 193, 0.13)
Покупатель->>Магазин: Обращается за возвратом по заказу
Магазин-->Инвойсбокс: Получение списка позиций в заказе
Магазин->>Инвойсбокс: Вызов метода оформления возврата
Магазин->>Инвойсбокс: Вызов метода создания корректировочного заказа
Инвойсбокс->>Покупатель: Осуществление возврата денежных средств
Инвойсбокс->>Онлайн касса: Чек "ВОЗВРАТ 100%"
Инвойсбокс->>Покупатель: Предоставление чека "ВОЗВРАТ 100%"
Инвойсбокс->>Онлайн касса: Чек "ОПЛАТА 100%" по корректировочному заказу
Инвойсбокс->>Покупатель: Предоставление чека "ОПЛАТА 100%"
end
1. Покупатель обращается в Магазин для оформления возврата заказа.
1. Опционально, Магазин запрашивает [через метод API](/docs/merchant/refund/get/) доступные к возврату позиции в заказе.
1. Магазин формирует возврат в системе «Инвойсбокс» [через метод API](/docs/merchant/refund/create/).
1. Магазин формирует корректировочный заказ в системе «Инвойсбокс» с указанием позиции комиссии, штрафа или сервисного сбора [через метод API](/docs/merchant/refund/create/).
1. Система «Инвойсбокс» возвращает денежных средств покупателю на сумму возврата за минусом суммы корректировочного заказа.
1. Система «Инвойсбокс» формирует и регистрирует чек "ВОЗВРАТ 100%" в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "ВОЗВРАТ 100%" покупателю (физическому лицу).
1. Система «Инвойсбокс» формирует и регистрирует чек "ОПЛАТА 100%" по корректировочному заказу в [онлайн кассе](/docs/merchant/fz54/) (при оплате физическим лицом).
1. Система «Инвойсбокс» направляет чек "ОПЛАТА 100%" покупателю (физическому лицу).
### Формирование возврата
Сформируйте возврат со специальным статусом **draft** и получите его **идентификатор** (id) через метод API [создания возврата](/docs/merchant/refund/create/)
### Формирование корректировочного заказа
Сформируйте корректировочный заказ с указанием новых позиций (штрафов, комиссий, сервисных сборов) со ссылкой на возврат из пункта 1. через поле `parentId`,
т.е. укажите в поле `parentId` полученный идентификатор `id` возврата.
Корректировочный заказ создаётся своим методом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/correction-order`
- тело запроса — объект CorrectionOrderRequest: `parentId`, `amount`, `vatAmount`, `description`, `basketItems` (все обязательные)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
- Возможные [ошибки](/docs/dictionary/error/)
---
#### Пример запроса и ответа
``` json
POST /v3/billing/api/order/correction-order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string",
"currencyId": "RUB",
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"status": "string",
"shipmentStatus": "string",
"subtype": "string",
"processingStatus": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderIdVisible": "string",
"expirationDate": "2026-08-03T12:00:00+03:00",
"metaData": {},
"customerData": {},
"notificationUrl": "string",
"orderSetting": {
"roundPolicy": "string",
"disableValidate": false
},
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"shopId": 1,
"sourceId": "l3",
"paidAt": "2026-08-03T12:00:00+03:00",
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"returnUrl": "string",
"successUrl": "string",
"failUrl": "string",
"paymentUrl": "string",
"paymentUrlType": "redirect",
"paymentPageUrl": "string",
"customer": {
"type": "string",
"name": "string",
"phone": "string",
"email": "string",
"vatNumber": "string",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"registrationAddress": "string",
"taxRegistrationReasonCode": "string"
},
"languageId": "01771534-1a57-f184-dee3-ebeb91dded75",
"contactId": 1,
"contactCounterpartyId": 1,
"processable": false,
"userAccountId": "01771534-1a57-f184-dee3-ebeb91dded75",
"invoiceSetting": {
"customerLocked": false,
"customerLockedFields": {},
"customerHiddenFields": {},
"paymentMethodIdLocked": false,
"paymentMethodId": 1,
"savePaymentData": false,
"clientId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentToken": "string",
"paymentMethodCode": "string",
"paymentMethodAutosubmit": false,
"bankDetailId": 1
},
"orderContainerId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentInfo": {},
"holdTill": "2026-08-03T12:00:00+03:00",
"additionalOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"shipmentTotalAmount": "string",
"shipmentTotalVatAmount": "string"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
---
# Комиссионная торговля
## Комиссионная торговля
Магазин может продавать товары не напрямую покупателю, а через Инвойсбокс. Порядок действий и перечень документов
зависят от систем налогообложения, которые применяют собственник товара (комитент) и Инвойсбокс (комиссионер).
По договору комиссии:
1. Собственник товара — это комитент.
2. Инвойсбокс — это комиссионер.
Комиссионер (Инвойсбокс) продаёт товары от своего имени или от имени комитента (магазина). При этом комитент и
комиссионер могут использовать разные налоговые режимы — общий (ОСНО) или упрощённый (УСН).
Предлагаем изучить схему взаимодействия и документооборота в рамках комиссионной торговли для клиентов — организаций
и индивидуальных предпринимателей (B2B).
### Процесс отгрузки и оформления отчётных документов
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Магазин->>Инвойсбокс: Передача документа через ЭДО: УПД (ДОП)
opt Проверка документа ЭДО
Инвойсбокс-->Магазин: Уведомление о несоответствии
Магазин-->Инвойсбокс: Вызов метода обновления заказа
end
Магазин->>Инвойсбокс: Вызов метода отгрузки товара
opt Полная отгрузка товара
Инвойсбокс->>Покупатель: Передача документа через ЭДО: УПД (СЧФДОП)
Покупатель->>Инвойсбокс: Подпись документа через ЭДО
Инвойсбокс->>Магазин: Уведомление о смене статуса заказа
Магазин->>Инвойсбокс: Передача документа через ЭДО: УПД (СЧФ)
end
opt Частичная отгрузка товара
Магазин->>Инвойсбокс: Передача документа через ЭДО: УКД (ДИС)
opt Проверка документа ЭДО
Инвойсбокс-->Магазин: Уведомление о несоответствии
Магазин-->Инвойсбокс: Вызов метода обновления отгрузки
end
Инвойсбокс->>Покупатель: Возврата денежных средств (при переплате)
Инвойсбокс->>Покупатель: Передача документа через ЭДО: УКД КСЧФ (ДИС)
Покупатель->>Инвойсбокс: Подпись документа через ЭДО
Инвойсбокс->>Магазин: Уведомление о смене статуса заказа
Магазин->>Инвойсбокс: Передача документа через ЭДО: УПД (СЧФ)
end
Магазин->>Инвойсбокс: Документооборот завершён, заказ закрыт
end
1. После [оплаты товара](/docs/merchant/schema/legal), Магазин передаёт через ЭДО в «Инвойсбокс» документ **УПД (ДОП)**.
1. Система «Инвойсбокс» производит проверку полученного документа и при наличие расхождений уведомляет об этом Магазин.
1. Магазин обновляет данные заказа в системе «Инвойсбокс» [через метод API](/docs/merchant/order/update/).
1. Магазин создает в системе «Инвойсбокс» отгрузку [через метод API](/docs/merchant/order/shipment_create/).
1. Если произведена полная отгрузка товара, то система «Инвойсбокс» передаёт через ЭДО Покупателю документ **УПД (СЧФДОП)**.
1. Покупатель подписывает полученный документ в ЭДО.
1. Система «Инвойсбокс» оповещает Магазин о смене статуса заказа.
1. Магазин передаёт через ЭДО в «Инвойсбокс» документ **УПД (СЧФ)**.
1. Если произведена частичная отгрузка товара, то Магазин передаёт через ЭДО в «Инвойсбокс» документ **УКД (ДИС)**.
1. Система «Инвойсбокс» производит проверку полученного документа и при наличие расхождений уведомляет об этом Магазин.
1. Магазин обновляет данные отгрузки в системе «Инвойсбокс» [через метод API](/docs/merchant/order/shipment_update/).
1. Система «Инвойсбокс» возвращает денежных средств покупателю при наличие переплаты.
1. Система «Инвойсбокс» передаёт через ЭДО Покупателю документ **УКД (КСЧФДИС)**.
1. Покупатель подписывает полученный документ в ЭДО.
1. Система «Инвойсбокс» оповещает Магазин о смене статуса заказа.
1. Магазин передаёт через ЭДО в «Инвойсбокс» документ **УПД (СЧФ)**.
1. Документооборот завершён, заказ закрыт
### Процесс возврата товара и оформления отчётных документов
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(107, 70, 193, 0.13)
Инвойсбокс->>Покупатель: Передача документа через ЭДО: УКД (КСЧФДИС)
Покупатель->>Инвойсбокс: Подпись документа через ЭДО
Инвойсбокс->>Магазин: Уведомление о смене статуса возврата
Магазин->>Инвойсбокс: Передача документа через ЭДО: УКД (КСЧФ)
opt Проверка документа ЭДО
Инвойсбокс-->Магазин: Уведомление о несоответствии
Магазин-->Инвойсбокс: Вызов метода отмены возврата или переотправка УКД (КСЧФ)
end
opt Оформление счёта для возврата средств
Инвойсбокс->>Магазин: Оформление счёта для возврата средств
end
Магазин->>Инвойсбокс: Осуществление возврата денежных средств
Инвойсбокс->>Покупатель: Осуществление возврата денежных средств
Магазин->>Инвойсбокс: Документооборот завершён, возврат закрыт
end
1. После [оформления возврата](/docs/merchant/refund/create/), система «Инвойсбокс» передаёт через ЭДО Покупателю документ **УКД (КСЧФДИС)**.
1. Покупатель подписывает полученный документ в ЭДО.
1. Система «Инвойсбокс» оповещает Магазин о смене статуса возврата
1. Магазин передаёт через ЭДО в «Инвойсбокс» документ **УКД (КСЧФ)**.
1. Система «Инвойсбокс» производит проверку полученного документа и при наличие расхождений уведомляет об этом Магазин.
1. Магазин отменяет возврат в системе «Инвойсбокс» [через метод API](/docs/merchant/refund/delete/) или переотправляет документ через ЭДО: **УКД (КСЧФ)**.
1. «Инвойсбокс» оформляет счёт на возврат для Магазина.
1. Магазин возвращает денежных средств в «Инвойсбокс».
1. Система «Инвойсбокс» возвращает денежных средств покупателю.
1. Документооборот завершён, возврат закрыт.
---
---
# OpenCart 3.x
# Описание модуля OpenCart 3.x
[OpenCart](https://www.opencart.com/) — платформа электронной коммерции, ориентированная на создание интернет-магазинов.
Бесплатное свободное программное обеспечение, поддерживаются дополнения - модули и шаблоны.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Для установки и настройки платёжного модуля Инвойсбокс:
1. Пройдите по ссылке к плагину на сайте OpenCart [OpenCart - Платежный модуль Invoicebox](https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=43891)
2. Авторизуйтесь или зарегистрируйте новый аккаунт. Это нужно для скачивания плагина.
3. Скачайте архив с плагином.
4. В административной панели зайдите в раздел Модули/Расширения → Установка расширений и загрузите файл с расширением ".ocmod.zip."
5. Перейдите в раздел Модули/Расширения → Модификаторы. Очистите и обновите кэш модификаторов, нажав на соответствующие кнопки в правом верхнем углу экрана.
6. Перейдите на главную страницу административной панели и сбросьте кэш.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Настройка модуля
1. Зайдите в раздел Модули/расширения → Модули/расширения.
2. В выпадающем списке выберете "Оплата".
3. Найдите модуль “Инвойсбокс” и перейдите в редактирование.
4. Перейдите в раздел "настройка платежей". Выберите версию API, заполните необходимые данные:
- идентификатор магазина (v2 и v3 старый и новый)
- региональный код магазина (v2)
- имя пользователя API (v2)
- пароль API (v2)
- ключ API (v2 и v3 старый и новый)
- токен (v3 старый и новый)
В пункте 5 будут даны тестовые данные для 2й версии API, а в пункте 6 - для 3й (новой), для получения доступов для 3й версии текущей необходимо обратиться на почту [c-support@invoicebox.ru](mailto:c-support@invoicebox.ru)
5. Доступы для 2й версии API:
1. Поле “Магазин” - вставьте нужное или тестовое значение “207” (если включен тестовый режим)
2. Поле “Региональный код магазина” - введите нужное или тестовое значение “78054” (если включен тестовый режим)
3. Заполните поля “Имя пользователя” и “Пароль”. Данные для теста: логин “78054-API” и пароль “LM936s#3jz0“
4. Поле “Ключ”. Значение для теста: LdjmgMS1WMS0nAIklbDkvuKT7WxaJIoC
5. Нажмите кнопку “Сохранить” в правом верхнем углу экрана
6. Доступы для 3й версии API (новой) :
1. Поле «Идентификатор магазина». Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
2. Поля «Токен» и «Ключ API» — значения там же, в данных для интеграции.
3. Нажмите кнопку “Сохранить” в правом верхнем углу экрана
7. Выберите налоговый режим, в котором работает магазин.
Настройка налогового режима
В налогах важны три пункта:
- показываются они клиенту или нет
- ставка НДС
- формат цен
Формат цен задается в “Система - Локализация - Валюта”. Для каждой валюты проставьте в поле “количество знаков после запятой” значение 2.
Ставка НДС задаётся в меню “Система - Локализация - Налоги - Налоговые ставки”.
Допускаются ставки НДС 0%, 10%, 20%. В типе нужно выставить “процент”, а в “ставке” - нужное число.
Показ налогов настраивается в 3х местах: в модуле “Инвойсбокс”, в настройках, в модуле “Учитывать в заказе”.
Корректными являются такие варианты:
1. Налоги уже учтены в стоимости и не показываются клиенту.
“Система - Настройки - Опции”:
Модули/расширения - Учитывать в заказе-Отчеты - Налоги / Налоговый отчет:
2. Налоги считаются поверх указанной стоимости товара и показываются клиенту:
Модуль “Инвойсбокс”:
Система - Настройки - Опции:
Модули/расширения - Учитывать в заказе - Налоги:
**Убедитесь, что заполнены значения полей “Единица измерения” и “Код единицы измерения”. Стандартные значения “шт” и “796”. Индивидуальные значения для каждого товара задаются в атрибутах товара.**
Если нужно допускать заказ к оплате только после проверки модератором, выберите режим отложенной оплаты и статус, при переводе заказ в который, пользователю будет посылаться ссылка на оплату.
Режим отсроченной оплаты - при включённом режиме отсроченной (отложенной) оплаты покупатель сможет оплатить заказ только после проверки заказа менеджером магазина. Если вам необходимо, чтобы у покупателя была возможность произвести оплату сразу после оформления заказа без подтверждения менеджером - не включайте эту опцию.
Статус заказа для отсроченной оплаты - после проверки заказа менеджер магазина выставит этот статус, покупатель будет уведомлен по электронной почте и сможет оплатить заказ. Также, ссылка на оплату появится в личном кабинете покупателя в разделе "Мои заказы".
**БУДЬТЕ ВНИМАТЕЛЬНЫ!** Если этот статус совпадёт со значением в графе "статус заказа после подтверждения" - режим отсроченной оплаты будет отключён и покупатели будут перенаправляться на сайт «Инвойсбокс» для оплаты сразу после нажатия на кнопку "Оформить заказ".
Заполните значения полей SKU в товарах. Если они будут не заполнены, оплату за товар нельзя будет вернуть. Для этого:
1. Зайдите в раздел Каталог → Товары и нажмите на редактирование товара.
2. Далее зайдите в раздел “Данные” и нажмите кнопку справа “двойная стрелка”.
3. Найдите поле “Артикул” и при отсутствии актуальных артикулов заполните строку любыми числами. Главное, чтобы у каждого товара был свой уникальный артикул.
**Значения остальных полей:**
4.
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале «Инвойсбокс», но деньги с вашей карты списаны не будут.
Статус заказа после оплаты - после успешной оплаты заказа, заказу будет присвоен выбранный статус.
Статус заказа после подтверждения - при нажатии на кнопку "Подтвердить" на последнем этапе оформления заказа, заказу будет присвоен выбранный статус.
Статус заказа после неудачной оплаты - в случае неудачного платежа, заказу будет установлен выбранный статус.
Название - Название метода оплаты на странице оформления заказа.
Инструкция по оплате - отображается при подтверждении заказа. Если поле не заполнено - инструкция выводиться не будет.
В поле "Тип оплаты" выберите вариант full_prepayment (если он не выбран по умолчанию).
Поле "Тип товара по умолчанию"- выберите тип товара, который будет использоваться по умолчанию. Если на сайте присутствуют разные типы товаров, у каждого товара свой тип можно задать в атрибутах.
Поля “Страна-производитель товара по умолчанию” и “Код страны-производителя товара по умолчанию” : выберите страну-производителя, которая будет использоваться по умолчанию. Если на сайте присутствуют товары из нескольких стран, у каждого товара свою страну можно задать в атрибутах.
Если выбрана третья версия API, есть возможность передавать дополнительные данные (например, бронирование билетов или мест проживания). Для передачи этих данных понадобится помощь разработчика. Сохранять информацию нужно в таблицу `oc_invoicebox_meta`.
Подробнее о формате передаваемых данных можете узнать в [разделе метаданные](/docs/merchant/order/metadata/).
**Не забудьте в настройках модуля поставить статус “включено”.**
При оформлении заказа обязательно нужно добавить корректный номер телефона.
**Url для уведомлений**
https://ваш_домен/index.php?route=extension/payment/invoicebox/callback
Возникшую при оплате ошибку можно узнать в истории заказа в админ-панели.
**Url для уведомлений** https://ваш_домен/index.php?route=extension/payment/invoicebox/callback
> [!WARNING]
> URL уведомления должен работать только по HTTPS: уведомления об оплате содержат данные заказов и подпись запроса.
### Причины возникновения ошибок при оплате
Если при оплате возникает ошибка, в первую очередь стоит зайти в административную панель, в раздел заказов и открыть новый заказ. Чаще всего причина будет указана там.
1. Проверьте, корректно ли указаны единицы измерения. Они должны быть указаны либо в каждом товаре, либо в настройках модуля (если в товаре нужных атрибутов нет, значения берутся из модуля). Частая ошибка - “шт.” вместо “шт”. Код для “шт” - 796.
2. Проверьте, корректно ли в товарах указан тип товара в самом товаре. Допустимые значения “commodity” и “service”. Либо оставьте поле пустым, чтобы значение бралось из настроек модуля. Путь до настройки: Каталог → Товары → Настройки товара → Атрибуты
3. Проверьте, правильно ли выставлены настройки налогов. См. раздел “настройка налогового режима”.
4. Проверьте, корректно ли заполнены доступы от API.
5. Проверьте, не включена ли опция “тестовое окружение”, если для магазина в Инвойсбокс не создавалось тестовое окружение. Если вы используете тестовые данные доступа из этой инструкции, настройка “тестовое окружение” должна быть отключена.
6. Проверьте в настройках модуля, включен ли он.
7. Если включен режим отложенной оплаты, убедитесь, что статус заказа для отсроченной оплаты не совпадает со статусом заказа после подтверждения.
### Причины возникновения ошибок при возврате
Если при оплате возникает ошибка, в первую очередь стоит посмотреть в истории заказа - иногда точная ошибка может быть указана там.
1. Проверьте, что используется та же версия API, что и при оплате заказа (нельзя переключаться со 2й на 3ю и наоборот).
2. Убедитесь, что общая сумма возврата не превышает допустимую для этого заказа (если по этому заказу уже был возврат, остаток будет указан в предупреждении на странице возврата).
3. Убедитесь, что сумма возврата по каждому товару не больше суммы оплаты по этому товару.
4. Убедитесь, что у каждого товара заполнено поле SKU (Артикул) - с пустым полем сделать возврат для товара нельзя.
### Часто задаваемые вопросы
Вопрос: При выборе способа оплаты, заказ исчезает из панель управления магазином, даже если клиент его оплатил
Ответ: Проверьте корректность указания ссылка уведомления об оплате в личном кабинете системы Инвойсбокс. Заказ отображается в панели управления магазином только в том случае, если система оплаты корректно передала магазину информацию об оплате заказа.
---
# Получение заказа
# Получение заказа
Заказы читаются одним запросом:
- метод: `GET`
- ресурс: `/v3/filter/api/order/order`
- тело ответа - коллекция объектов [OrderResponse](/docs/merchant/order/create/#orderresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
В запросе можно применять фильтры и сортировку.
Пример запроса с фильтром по идентификатору заказа
```http
GET /v3/filter/api/order/order?id=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по [статусу](/docs/merchant/order)
```http
GET /v3/filter/api/order/order?status=completed
```
Пример запроса с фильтром по дате (время создания заказа)
```http
GET /v3/filter/api/order/order?createdAt[_ge]=2021-01-27T00:00:00
```
Пример запроса с фильтром по дате (срок действия заказа)
```http
GET /v3/filter/api/order/order?expirationDate[_ge]=2021-01-27T00:00:00
```
Пример запроса с фильтром по дате (время оплаты заказа)
```http
GET /v3/filter/api/order/order?paidAt[_ge]=2021-01-27T00:00:00
```
Пример запроса с фильтром по идентификатору заказа в учётной системе магазина
```http
GET /v3/filter/api/order/order?merchantOrderId=ORD123456
```
---
#### Пример запроса и ответа
``` json
GET /v3/filter/api/order/order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
```
Ответ:
``` json
{
"data": [
{
"id": "01857270-9281-af42-5b20-5fd792455718",
"description": "Оплата заказа №1433",
"currencyId": "RUB",
"amount": 1100,
"vatAmount": 0,
"basketItems": [
{
"sku": "11094",
"name": "Брелок, Категория",
"measure": "шт",
"measureCode": "796",
"quantity": 1,
"amount": 1100,
"amountWoVat": 1100,
"totalAmount": 1100,
"totalVatAmount": 0,
"vatCode": "RUS_VAT0",
"type": "commodity",
"paymentType": "full_prepayment"
}
],
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"status": "expired",
"shipmentStatus": "unshipped",
"subtype": "order",
"createdAt": "2023-01-02T12:24:18+00:00",
"merchantOrderId": "1433",
"merchantOrderIdVisible": "1433",
"expirationDate": "2023-01-03T12:24:16+00:00",
"notificationUrl": "https://demo.invoicebox.ru/api/integration/invoicebox-v3",
"successUrl": "https://demo.invoicebox.ru/order/1433",
"failUrl": "https://demo.invoicebox.ru/order/1433",
"paymentUrl": "https://pay.invoicebox.ru/order/01857270-9272-7a9e-d511-a5cd34b6ee62",
"paymentPageUrl": "https://pay.invoicebox.ru/order/01857270-9272-7a9e-d511-a5cd34b6ee62",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"phone": "79001112233",
"email": "buh@example.invbox.ru"
},
"languageId": "ru",
"processable": true,
"orderContainerId": "01857270-9272-7a9e-d511-a5cd34b6ee62"
}
],
"metaData": {
"totalCount": 5965,
"page": 1,
"pageSize": 30
},
"extendedData": []
}
```
## Читайте также
- [Выборка поддерживает фильтры, сортировку и постраничный вывод](/docs/api/filters/)
---
# Работа с возвратом
# Работа с возвратом
Как правило, возврат оформляет Магазин, если покупатель хочет вернуть товар или отказался от услуги.
Возврат всегда связан с операцией оплаты, сумма средств с которой будет возвращена покупателю.
Возвращать можно как полную сумму оплаты, так и её часть. Денежные средства обычно возвращаются
через тот платёжный инструмент, через который поступила оплата.
Деньги уходят покупателю после того, как возврат оформлен в системе «Инвойсбокс».
Текущий раздел описывает возможные операции с возвратами.
## Возможные статусы возврата
1. `draft` - Черновик возврата, который возможно скорректировать
2. `created` - Возврат сформирован
3. `completed` - Возврат осуществлён
4. `canceled` - Возврат отменён
---
# Запрос о платеже
## Запрос о платеже
Счёт через сервис Запрос о платеже (RtP) может быть направлен как плательщиками - физическими лицами (B2C),
так и организациям (B2B). Оплата может быть совершена с использованием QR-кода СБП или
[СБП B2B](https://www.invoicebox.ru/ru/products/sbp-b2b), а также множество альтернативных способов оплаты
на [платёжной странице](/docs/merchant/payment-page/) Инвойсбокс.
### Выставление счёта через Запрос о платеже
Счёт через Запрос о платеже выставляет метод [создания заказа](/docs/merchant/order/create/) — с дополнительными
настройками счёта (InvoiceSetting):
### InvoiceSetting
| Свойство | Обязательное | Значение |
|-------------------------|--------------|----------|
| paymentMethodCode | да | `invoice-rtp` |
| paymentMethodAutosubmit | да | `true` |
Также обязательно предварительное заполнение данных покупателя (Customer):
### Customer
| Свойство | Обязательное | Значение |
|---------------------------|--------------|--------------------------------|
| type | да | legal |
| name | да | Наименование организации |
| phone | да | Номер моб. телефона покупателя |
| email | да | Адрес эл. почты покупателя |
| vatNumber | да | ИНН организации |
| taxRegistrationReasonCode | да | КПП организации |
| registrationAddress | да | Юридический адрес |
При передаче указанных значений, система Инвойсбокс:
1. В случае, если покупатель зарегистрирован в сервисе Запрос о платеже (НСПК), вернёт ссылку для оплаты,
которую можно отобразить в том числе в виде QR-кода.
1. В случае, если покупатель не зарегистрирован в сервисе Запрос о платеже (НСПК), вернёт ссылку на
платёжную страницу Инвойсбокс, где покупатель завершит регистрацию, а также получит ссылку для оплаты, в том числе,
в виде QR-кода.
Информация о факте оплаты будет направлена по API [стандартным уведомлением](/docs/merchant/notification/).
---
---
# Tilda
# Описание модуля Tilda
[Tilda](https://tilda.cc/) — блочный конструктор сайтов, не требующий навыков программирования. Позволяет создавать
сайты, интернет-магазины, посадочные страницы, блоги и email-рассылки. Сайты на платформе собираются из готовых блоков,
которые автоматически адаптируются под мобильные устройства и выделены в смысловые категории (например, обложка сайта,
меню, форма, текст, изображение).
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Для установки платёжного модуля системы «Инвойсбокс» в сервисе Tilda на тарифах Personal или Business:
1. Зайдите в административную часть интернет-магазина в Tilda. Перейдите в раздел «Мои сайты» → «Редактировать сайт» → «Настройки сайта» → «Платёжные системы»;
2. Найдите пункт «Универсальная платёжная система», перейдите в него. В шаблоне настроек выберите пункт «Инвойсбокс»
3. Заполните необходимые настройки:
- Идентификатор Магазина;
- API Ключ;
- URL страницы успеха и отказа;
- Выберите галку «Отключить тестовый режим».
Если вам требуется добавить способ оплаты по счёту для организаций и ИП, в настройках платёжного модуля раскройте раздел
«Расширенные настройки», далее, в блоке «Список дополнительных полей» удалите поле `itransfer_body_type`, сохраните
настройки.
Если раздел "Расширенные настройки" отсутствует, добавить его можно в настройках профиля Тильды, поставив галку
"Участвовать в тестировании новых функций".
Идентификатор Магазина и API Ключ доступны в [личном кабинете](https://business.invoicebox.ru) на сайте «Инвойсбокс»,
для просмотра необходимо перейти в раздел «Мои продажи» → «Мои магазины» → нажать на иконку «шестерёнки» и справа от
названия магазина и перейти в раздел «Смотреть детали» (API ключ необходимо скопировать во вкладке «Интеграция (API)»)
4. Нажмите на кнопку «Добавить»;
5. Далее необходимо произвести настройки в личном кабинете системы «Инвойсбокс».
Перейдите в раздел «Мои продажи» → «Мои магазины» → Нажмите на иконку «шестерёнки» справа от названия магазина и
перейдите в раздел «Смотреть детали»
Во вкладке «Интеграция (API)» укажите следующие настройки:
- Тип уведомления: `Оплата/HTTP/Tilda`;
- URL уведомления: `https://forms.tildacdn.com/payment/custom/invoicebox/`
Платформа Tilda Publishing не несет на себе обязательств за работу и безопасность сторонних платёжных интеграций.
#### Читать пользовательское соглашение
```
Выражая свое намерение на интеграцию с сервисом Настраиваемая платежная система (далее – НПС) и/или совершая действия по подключению и дальнейшему использованию выбранного платежного ресурса (далее – Платежная система), юридическое лицо или индивидуальный предприниматель, направившие заявку на интеграцию (далее - заявитель), и Пользователь Платформы Тильда Паблишинг (далее – Пользователь) настоящим подтверждают свое согласие с нижеследующим:
1. Администрация Платформы Тильда Паблишинг (далее – Администрация) прикладывает все усилия, чтобы обеспечить Пользователей точной и достоверной информацией.
1.1. В обязанности Администрации не входит контроль легальности передаваемой заявителями информации, а также определение их законных прав и/или обязанностей.
1.2. Направляя заявку на интеграцию, заявитель гарантирует и подтверждает, что он обладает необходимым правовым статусом, достаточным для осуществления предусмотренной заявкой деятельности по обеспечению совершения платежных операций, включая необходимые разрешения, наличие которых обусловлено требованиями законодательства РФ, национального законодательства.
1.3. Заявитель гарантирует правомерность использования заявленной Платежной системы, и подтверждает, что ее интеграция и дальнейшее применение не ущемляет права и законные интересы третьих лиц, в том числе на результаты интеллектуальной деятельности.
2. В соответствии с действующим законодательством Администрация отказывается от каких-либо заверений и гарантий, предоставление которых может иным образом подразумеваться, и ответственности в отношении использования Платежных систем, интегрированных в НПС.
2.1. Администрация Платформы не гарантирует безопасность использования Платежных систем и бесперебойность их работы.
2.2. Администрация Платформы предоставляет только необходимые вычислительные мощности, позволяющие произвести интеграцию той или иной Платежной системы в НПС с целью ее дальнейшего использования Пользователями Платформы на своих проектах.
2.3. Администрация не является субъектом или иным заинтересованным лицом в отношениях, возникающих между заявителем, Пользователем Платформы и третьими лицами.
2.4. Администрация Платформы не несет ответственности за: а) любые действия и/или бездействия поставщиков услуг, сервисов, сетей, программного обеспечения или оборудования; б) убытки (прямой/косвенный ущерб, упущенная выгода), которые могут возникнуть в результате использования Платежных систем, включая, но не ограничиваясь, ущерб, причиненный любым устройствам и носителям информации и/или программному обеспечению Пользователя, а также приостановку его хозяйственной деятельности.
3. Пользователь несет единоличную ответственность за выбор и дальнейшее использование Платежной системы, а также любые действия, связанные с электронной торговлей.
3.1. Пользователь самостоятельно следит за соблюдением любых применимых к нему и его деятельности законов.
3.2. Пользователь соглашается, что использование выбранной им Платежной системы может сопровождаться взиманием дополнительной платы.
3.3. Пользователь осуществляет использование выбранной им Платежной системы исключительно на свой риск и под свою ответственность, принимая во внимание возможность распространения на него действия юридических и финансовых условий, регулирующих деятельность заявителей, с которыми Пользователю рекомендуется ознакомиться, прежде чем использовать выбранную Платежную систему.
4. Действуя во исполнение требований закона/ требований (уведомлений, претензий) уполномоченных органов и/или их должностных лиц, Администрация Платформы вправе в любой момент приостановить или заблокировать доступ к той или иной Платежной системе или удалить ее из НПС - вне зависимости от того, встроены ли соответствующая Платежная система в проект Пользователя на соответствующий момент времени, без возникновения каких-либо обязательств перед самим Пользователем и/или его клиентами.
```
## Читайте также
- [Где взять идентификатор магазина и API ключ](/docs/merchant/integrationdata/)
---
# Обработка уведомлений
# Обработка уведомлений
Система «Инвойсбокс» уведомляет Магазин о факте оплаты счёта несколькими способами. В первую очередь,
все уведомления о платежах направляются по электронной почте магазина или SMS. Ежедневно система
«Инвойсбокс» также направляет сводный реестр платежей (Переводов) за прошедшие сутки.
Если Магазину требуется получать уведомления о платежах в автоматическом режиме, например, для передачи
статуса оплаты заказа в CMS или иную систему учёта, система «Инвойсбокс» может направлять такие
уведомления по заранее заданным параметрам (ссылке). Система «Инвойсбокс» поддерживает множество
форматов уведомлений, в том числе форматы сторонних платёжных решений.
Если в системе Магазина отсутствует возможность реализации сервиса (ссылки) для получения информации
об оплате заказа, существует возможность реализации механизма уведомлений через [веб-сокеты](/docs/api/websockets/).
В текущем разделе описаны базовые форматы уведомлений.
---
# Изменение заказа
Заказ меняется, пока не оплачен:
- метод: `PUT`
- ресурс: `/v3/billing/api/order/order/:uuid` - где `:uuid` это идентификатор заказа
- тело запроса - объект [UpdateOrderRequest](#updateorderrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/order/019fc671-6d37-77e0-6080-fec092bf521f
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"amount": 15000,
"vatAmount": 0,
"basketItems": [
{
"sku": "5fe0adcfa7fb4",
"name": "Бронирование номера, продление на сутки",
"measure": "шт.",
"measureCode": "796",
"quantity": 1,
"amount": 15000,
"amountWoVat": 15000,
"totalAmount": 15000,
"totalVatAmount": 0,
"vatCode": "RUS_VAT0",
"type": "service",
"paymentType": "full_prepayment"
}
]
}
```
Суммы заказа и корзины обязаны сходиться — правило описано в разделе
[как считаются суммы](/docs/merchant/order/create/#как-считаются-суммы).
Ответ:
``` json
{
"id": "019fc671-6d37-77e0-6080-fec092bf521f",
"description": "Оплата бронирования № 4412",
"currencyId": "RUB",
"amount": 12000,
"vatAmount": 0,
"basketItems": [
{
"sku": "room-deluxe",
"name": "Проживание в номере «Делюкс», 2 ночи",
"measure": "шт",
"measureCode": "796",
"quantity": 1,
"amount": 12000,
"amountWoVat": 12000,
"totalAmount": 12000,
"totalVatAmount": 0,
"vatCode": "RUS_VAT0",
"type": "service",
"paymentType": "full_prepayment"
}
],
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"status": "created",
"shipmentStatus": "unshipped",
"subtype": "order",
"createdAt": "2026-08-03T07:05:50+00:00",
"merchantOrderId": "portal-6c2fcf273e55-docs-example-1785740749696",
"merchantOrderIdVisible": "portal-6c2fcf273e55-docs-example-1785740749696",
"expirationDate": "2026-08-04T07:05:49+00:00",
"internalProperty": {},
"tags": [
"agent"
],
"sourceId": "v3",
"returnUrl": "https://shop.example.com/order/4412?result=return",
"successUrl": "https://shop.example.com/order/4412?result=success",
"failUrl": "https://shop.example.com/order/4412?result=fail",
"paymentUrl": "https://pay.invoicebox.ru/order/019fc671-6c80-eed3-ce48-9bb53f679353",
"paymentPageUrl": "https://pay.invoicebox.ru/order/019fc671-6c80-eed3-ce48-9bb53f679353",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"phone": "79001112233",
"email": "buh@example.invbox.ru",
"countryId": "RUS"
},
"languageId": "ru",
"processable": true,
"orderContainerId": "019fc671-6c80-eed3-ce48-9bb53f679353"
}
```
## UpdateOrderRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|-------------------------------------------------------|-----------------------------------------------------------|-----------------------------------------|
| description | нет | string | Описание заказа | `Оплата номера в отеле` |
| amount | нет | float | Сумма заказа | `19658.45` |
| vatAmount | нет | float | Сумма НДС | `156.56` |
| expirationDate | нет | datetime | Срок действия заказа | `2026-12-22T00:00:00+00:00` |
| basketItems | нет | array of [BasketItem](/docs/merchant/order/create/#basketitem) | Корзина заказа | |
| metaData | нет | object | [Дополнительные данные заказа](/docs/merchant/order/metadata/) | |
| customer | нет | [Customer](/docs/merchant/order/create/#customer) | Информация о заказчике | |
| shopId | нет | string(36) | Идентификатор связанного магазина/маркетплейса | `06581534-196a-1105-839a-82422289d6d9` |
---
---
# Гарантийный фонд: подтверждение оплаты
# Гарантийный фонд: подтверждение оплаты заказа
Постоянный покупатель, заключивший договор, держит в системе гарантийный фонд и подтверждает оплату
счёта в его пределах — не переходя на платёжную страницу Инвойсбокса. Магазин делает это тремя
методами подряд:
1. [Проверка возможности оплаты](/docs/merchant/guarantee/validate/) — хватает ли средств фонда;
2. [Запрос кода подтверждения](/docs/merchant/guarantee/code/) — код уходит покупателю;
3. [Подтверждение оплаты заказа](/docs/merchant/guarantee/pay/) — заказ переходит в оплаченный.
Общая картина — в [схеме взаимодействия](/docs/merchant/guarantee/schema/). Не путайте этот механизм
с [холдированием](/docs/scenarios/guarantee/): там сумма блокируется на банковской карте, здесь
списывается с фонда организации.
Для использования описываемых методов, в сервисе Магазина должны быть приняты меры безопасности
в виде использования таких инструментов как Google reCaptcha, Yandex SmartCaptcha, Huawei Safety Detect и пр.
---
# Аспро Корпоративный сайт
# Описание модуля Аспро
[Аспро: Корпоративный сайт](https://aspro.ru/marketplace/solutions/aspro.allcorp/) — готовое решение для создания сайта компании.
Начиная с версии 1.1.0 решения, появилась возможность подключать прямую интеграцию с системой Инвойсбокс. Система позволяет
принимать платежи на сайте. При этом вам не нужно покупать сторонние модули, поскольку в решении добавлен специальный
компонент для работы с платёжной системой.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Чтобы подключить систему Инвойсбокс, в административной части сайта перейдите в Аспро (1) → Аспро: Allcorp3 (2) → Настройки (3) и
перейдите на вкладку:
На вкладке «Корзина» найдите поле «Платёжная система», выберите «Интернет-эквайринг Инвойсбокс (приём платежей)» и нажмите «Применить».
Для настройки платёжной системы выполните тестовый заказ. На странице успешного оформления заказа в режиме вкладки перейдите в
настройки параметров компонента платёжной системы Инвойсбокс. Нажмите на стрелку рядом с шестерёнкой (1), выберите «Аспро: Платёжная
платформа Инвойсбокс» (2) и «Редактировать параметры компонента» (3).
В параметрах компонента доступны следующие поля:
1. Идентификатор магазина
2. Региональный код магазина
3. Подпись безопасности — API ключ. Подпись, идентификатор и код получаются при заключении договора с «Инвойсбокс» и находятся в [личном кабинете](https://business.invoicebox.ru/Login/).
4. Номер заказа. Значение по умолчанию `«={$_REQUEST["RESULT_ID"]}»` **менять не нужно**.
5. Стоимость заказа. Значение по умолчанию «={$totalSumm}» **менять не нужно**.
6. Код валюты. По умолчанию используются рубли. Этот код указывается в соответствии со стандартом [ISO 4217](/docs/dictionary/iso4217/): RUB — российский рубль, EUR — евро, USD — доллар США и т. д.
7. Тестовый режим. **Параметр неактуален**, его необходимо отключить. По-умолчанию магазин находится в тестовом режиме, для перевода магазина в боевой режим обратитесь к вашему менеджеру или [напишите нам](https://www.invoicebox.ru/ru/contacts/feedback.html).
---
# Отмена заказа
# Отмена заказа
Заказ отменяется, пока не оплачен полностью:
- метод: `DELETE`
- ресурс: `/v3/billing/api/order/order/:uuid` - где `:uuid` это идентификатор заказа
- тело запроса - отсутствует
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse) со статусом status = `canceled`
#### Пример запроса и ответа
#### 🌐 HTTP
```http
DELETE /v3/billing/api/order/order/c5041a79-24a6-42d1-b0ce-4abb94982cd9
Accept: application/json
User-Agent: MyApp 1.0
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
```
#### 🧊 CURL
```bash
curl -L -X DELETE '{baseUrl}/v3/billing/api/order/order/c5041a79-24a6-42d1-b0ce-4abb94982cd9' \
-H 'Accept: application/json' \
-H 'User-Agent: MyApp 1.0' \
-H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e'
```
{baseUrl} - [базовый URL](/docs/api)
В зависимости от сценария использования и настроек магазина, может быть применена разная логика при вызове метода.
По умолчанию, отменить заказ возможно только до момента получения системой Инвойсбокс
информации об отгрузке по заказу (информация о факте оказания услуги или поставки товара). После получения информации
об отгрузке системой Инвойсбокс, для отмены заказа и возврата средств, пожалуйста, воспользуйтесь
[методом оформления возврата](/docs/merchant/refund).
> [!IMPORTANT]
> В случае, если оплата заказа подтверждена с использованием гарантийных платёжных инструментов (Обещанный платёж, Гарантийный фонд,
> Овердрафт и т.д.) и у заказа нет информации об успешной отгрузке, отмена заказа инициирует полный возврат гарантийного платежа
> плательщику. Гарантийный платёж и его отмена не будут отражены в реестрах и финансовых отчётах магазина.
### Сценарий отмены заказа без невозможности оказания услуги
Пример использования метода отмены заказа для осуществления отмены гарантийного платежа в случае невозможности оказать
услугу или поставить товар покупателю. Например, при получении информации об оплате заказа произошла ошибка оформления
купленного билета или на складке не оказалось выбранного товара.
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Покупатель->>Магазин: Создает заказ
Магазин->>Инвойсбокс: Вызов метода создания заказа
Инвойсбокс->>Магазин: Идентификатор заказа и ссылка на оплату
Магазин->>Покупатель: Перенаправление на платёжную страницу
Покупатель-->>Инвойсбокс: Взаимодействие с платёжной страницей, получение счёта
Покупатель->>Инвойсбокс: Оплата счёта через предавторизацию средств на карте или гарантийный фонд
Инвойсбокс->>Покупатель: Перенаправление покупателя на сайт магазина
Инвойсбокс->>Магазин: Уведомление об успешной оплате
Магазин->>Инвойсбокс: Ошибка оказания услуги/поставки товара, status = shipping_unavailable
Магазин->>Инвойсбокс: Вызов метода отмены заказа
Инвойсбокс->>Покупатель: Возврат оплаченных средств
end
1. Покупатель оформляет заказ на сайте Магазина и выбирает способ оплаты через систему «Инвойсбокс».
1. Магазин создает в системе «Инвойсбокс» заказ [через метод API](/docs/merchant/order/create/).
1. Система возвращает ссылку на платёжную страницу для оплаты заказа.
1. Магазин перенаправляет покупателя по полученной ссылке.
1. Покупатель заполняет необходимые для оплаты сведения и получет счёт для оплаты.
1. Покупатель оплачивает счёт, система Инвойсбокс предавторизует сумму оплаты на карте плательщика или гарантийном фонде.
1. Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
1. Система «Инвойсбокс» [оповещает Магазин](/docs/merchant/notification) об успешной оплате заказа.
1. Магазин отвечает системе «Инвойсбокс» на уведомление ошибкой оказания услуги/поставки товара, возвращая статус `shipping_unavailable`
1. Магазин вызывает в системе «Инвойсбокс» [метод отмены заказа](/docs/merchant/order/delete/).
1. Если в заказе имеется статус `shipping_unavailable` и предавторизованный платёж, система «Инвойсбокс» отменяет оплату и заказ, возвращает средства плательщику. Если в заказе иной статус - возвращается ошибка.
---
Ответ:
``` json
{
"data": {
"id": "c5041a79-24a6-42d1-b0ce-4abb94982cd9",
"merchantOrderId": "O-12345",
"status": "canceled",
"amount": 12000,
"currencyId": "RUB",
"createdAt": "2026-08-01T10:00:00+03:00"
}
}
```
---
# SDK
# Готовые библиотеки (SDK)
Для интеграции с Инвойсбокс API вы можете использовать готовые библиотеки (SDK) для серверного или клиентского
взаимодействия с Инвойсбокс и для встраивания платёжных форм на сайт, в мобильное или иное приложение.
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты.
| Платформа/язык разработки | Детали
| -----------------------------------| ---------------------------------------
|  | [Смотреть »](/docs/merchant/sdk/php)
---
# Подтверждение оплаты заказа
# Подтверждение оплаты заказа
Оплата заказа подтверждается одним вызовом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/{uuid}/payment-method-action/pay`
- тело запроса - объект [PayRequest](#payrequest)
- тело ответа - объект [PayResponse](#payresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
POST /v3/billing/api/order/{uuid}/payment-method-action/pay
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"paymentMethodId": "39363265",
"languageId": "ru",
"customer": {
"name": "ООО Компания",
"email": "email@gmail.com",
"type": "legal",
"phone": "79611234567",
"vatNumber": "1233123",
"registrationAddress": "123123123"
},
"customerPaymentData" : {
"publicCode" : "string",
"code" : "string"
}
}
```
Ответ:
``` json
{
"data": {
"type": "none",
"result": "success",
"resultData": {}
}
}
```
## PayRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|------------------------|--------------|------------------------------------------|-------------------------------------------------|------------|
| paymentMethodId | да | string(36) | Идентификатор инструмента подтверждения оплаты | |
| languageId | нет | string(2) enum | Язык плательщика | `ru`, `en` |
| customer | да | [Customer](/docs/merchant/order/create/#customer) | Информация о плательщике | |
| customerPaymentData | да | [customerPaymentData](/docs/merchant/guarantee/validate/#validaterequest) | Данные ддя подтверждения оплаты заказа | |
#CustomerPaymentData
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|----------------------------------------------------|
| publicCode | да | string | Публичный идентификатор кода |
| code | да | string | Полученный плательщиком от системы Инвойсбокс код |
## PayResponse
| Свойство | Обязательное | Тип | Описание |
|----------|--------------|------------|--------------------------------------|
| data | да | [PaymentResponse](/docs/merchant/guarantee/pay/#paymentresponse) | Информация об оплате |
## PaymentResponse
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|------------------------------------------|
| type | да | enum | Тип действия к выполнению: none, message |
| result | да | enum | Статус проверки (см. ниже) |
| resultData | да | object | Объект, в зависимости от типа действия (type) и результата (result), см. ниже |
## Message
| Свойство | Обязательное | Тип | Описание |
|-------------|--------------|------------|---------------------|
| title | да | string | Заголовок сообщения |
| message | да | string | Сообщние |
Если type = message, требуется отобразить пользователю информацию от системы Инвойсбокс. Информация будет передана
в объекте resultData и будет содеражать вложенный объект message, пример:
``` json
{
"message": {
"title": "Недостаточно средств",
"message": "Для подтверждения выбранного заказа недостаточно средств. Пожалуйста, восстановите баланс гарантийного фонда."
}
}
```
Возможные статусы:
- alreadyPaid - Оплата заказа уже подтверждена
- wrongCode - Передан неверный код, повторите попытку оплаты
- limitReached - Превышено кол-во попыток оплаты
- notEnoughMoney - Недостаточно средств на счету
- error - Непредвиденная ошибка
- success - Оплата прошла
---
---
# Создание отгрузки
# Создание отгрузки
## Что делает отгрузка
Отгрузка фиксирует факт поставки товара или оказания услуги. По ней формируются отчётные документы и
[фискальный чек](/docs/merchant/fz54/), а у заказов с холдированием — списываются заблокированные на
карте средства.
- Отгрузок по заказу может быть несколько: например, поставка партиями. На каждую оформляются свои
документы.
- Сумма всех отгрузок не превышает сумму заказа.
- Когда в отгрузках закрыты все позиции заказа, деньги списываются целиком. Если часть заказа не
состоялась, последнюю отгрузку отправляют с `final` = `true`: заказ считается выполненным, а остаток
резерва разблокируется — подробнее в [холдировании](/docs/merchant/order/hold/).
Отгрузка создаётся одним запросом:
- метод: `POST`
- ресурс: `/v3/billing/api/order/shipment`
- тело запроса - объект [CreateShipmentRequest](#createshipmentrequest)
- тело ответа - объект [ShipmentResponse](#shipmentresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса
``` json
POST /v3/billing/api/order/shipment
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"orderId": "0187c6db-1637-c1ca-bef7-f6706799c41e",
"basketItems": [
{
"sku": "01GZ3DP5HADMSBAXRKVCES5FJX",
"name": "iPhone 5s",
"measure": "шт",
"measureCode": "796",
"originCountry": "Россия",
"originCountryCode": "643",
"grossWeight": 1010.55,
"netWeight": 1000.66,
"quantity": 1,
"amount": 122.00,
"amountWoVat": 100.00,
"totalAmount": 122.00,
"totalVatAmount": 22.00,
"vatCode": "RUS_VAT22",
"type": "commodity",
"paymentType": "full_prepayment"
}
]
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": 1,
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"createdAt": "2026-08-03T12:00:00+03:00",
"type": "string",
"status": "draft",
"amount": 100.5,
"vatAmount": 100.5,
"final": false,
"documentNumber": "string",
"description": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## CreateShipmentRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------------------------------|---------------------------------------------------------|----------------------------------------|
| orderId | да | string(36) | Id заказа | `01771534-1a57-f184-dee3-ebeb91dded75` |
| documentNumber | нет | string(36) | Номер документа (накладная, счёт-фактура и пр.) | `123` |
| documentDate | нет | date | Дата документа | `2023-12-12` |
| basketItems | да | array of [BasketItem](#basketitem) | Корзина заказа | |
| type | нет | string, enum | Тип отгрузки, по умолчанию `shipment` | `shipment`, `cancel` |
| final | нет | bool | Завершающая ли отгрузка по заказу, по умолчанию `false` | `true`, `false` |
## ShipmentResponse
Повторяет свойства объекта [CreateShipmentRequest](#createshipmentrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------|-------------------------------------------------|-----------------------------------------|
| id | да | int | Идентификатор отгрузки в системе Инвойсбокс | `2` |
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76 ` |
## BasketItem
Корзина заказа. Пожалуйста, внимательно ознакомьтесь с требованиями по [заполнению наименования номенклатуры](/docs/merchant/fz54).
| Свойство | Обязательное | Тип | Описание |
|-------------------|--------------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sku | да | string(500) | Артикул, например: `5fe0adcfa7fb4` |
| name | да | string(500) | Наименование, например `Бронирование номера` |
| groupName | нет | string(500) | Наименование группы позиций заказа, используется для формирования отчетных документов |
| measure | да | string(10) | Единица измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `шт.` |
| measureCode | да | string(4) | Код единицы измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `796` |
| originCountry | нет | string(20) | Страна происхождения товара, например, `Россия` |
| originCountryCode | нет | string(4) | Код страны происхождения, например, Россия `643` |
| grossWeight | нет | float | Вес брутто, например `125.45` |
| netWeight | нет | float | Вес нетто, например `125.45` |
| quantity | да | float | Количество, например `3` |
| amount | да | float | Стоимость единицы, например `100.55` |
| amountWoVat | да | float | Стоимость единицы без учёта НДС |
| totalAmount | да | float | Стоимость всех единиц с НДС, например`123.55` |
| totalVatAmount | да | float | Итого сумма НДС, например `23` |
| excise | нет | float | Сумма акциза, например, `10.00` |
| vatCode | да | string(20) enum | Код процента НДС, допустимые значения: `VATNONE` - не облагается,`VATNONE` - не облагается, `RUS_VAT0` - 0%, `RUS_VAT10` - 10/110, `RUS_VAT10_ADDED` - 10%, `RUS_VAT20` - 20/120, `RUS_VAT20_ADDED` - 20% `RUS_VAT22` - 22/122, `RUS_VAT22_ADDED` - 22% |
| type | да | string(10) или int | Тип позиции, [в соответствии со справочником](/docs/dictionary/tag1212) или service - сервис, commodity - товар |
| paymentType | да | string(20) enum | Тип оплаты, допустимые значения: `full_prepayment`, `prepayment`, `advance`, `full_payment` |
| metaData | нет | object | [Дополнительные данные элемента корзины](/docs/merchant/order/metadata/) |
---
---
# Платёжные виджеты на сайт
# Платёжные виджеты на сайт
Виджет принимает оплату без разработки: вы вставляете на страницу готовый код, и покупатель
платит, не уходя с сайта. Разработка не нужна, знания веб-технологий тоже: состав заказа и настройки
задаются в конструкторе.
Если сумму и состав определяет только ваш сервер или заказы рождаются в учётной системе, виджета
недостаточно — смотрите [интеграцию по API](/docs/merchant/order/create/) или
[готовые модули CMS](/docs/merchant/cms/). Сравнение путей — в разделе [Виджеты](/widgets/).
## Как это работает
1. **Собрать.** Настройки, живой предпросмотр и готовый код — в
[конструкторе](/widgets/constructor/). Понадобятся идентификатор магазина и региональный код: они
приходят в письме при регистрации, а для пробы конструктор подставит демо-магазин.
2. **Скопировать код.** Один блок с кнопкой — вставляется в любую вёрстку.
3. **Вставить на страницу.** Примеры для обычного сайта, Тильды, WordPress, 1С-Битрикс и мобильного
приложения — в [инструкции по вставке](/widgets/embed/).
## Что подготовить на сайте
| Страница | Зачем нужна |
|---|---|
| Страница с виджетом | здесь стоит код и покупатель вводит свои данные; подойдёт любая, даже главная |
| Страница завершения | сюда виджет вернёт покупателя и после успешной оплаты, и после неудачной. Её адрес указывается в настройках виджета — полезно описать на ней, что делать дальше |
## Настройки виджета
Все параметры задаются в [конструкторе](/widgets/constructor/); ниже — что каждый из них меняет. Если код виджета придётся править руками — например, подставлять номер заказа из своей системы, — смотрите [справочник параметров](/widgets/reference/): там перечислены поля кода, состав заказа и значения, которые они принимают.
| Настройка | Что задаёт | Когда нужна |
|---|---|---|
| Что оплачивают | заранее заданный состав заказа либо свободная сумма | состав — для товаров и услуг с известной ценой; свободная сумма — для пополнения баланса и абонентской платы |
| Текст на кнопке | подпись кнопки виджета | набор текстов расширяется по запросу в [поддержку](https://www.invoicebox.ru/ru/contacts) |
| Дополнительные поля | что покупатель заполнит сам: номер заказа, фамилия и имя, телефон, почта, количество | хотя бы одно из двух — почта или телефон — обязательно: по ним уходят счёт и документы |
| Тип плательщика | физическое лицо, организация или ИП, выбор покупателем | для оплаты от организаций и ИП выбирайте второй вариант: тогда формируется счёт и закрывающие документы |
| Код товара или услуги | ваш идентификатор заказа, договора или артикула | обязателен: по нему вы узнаёте платёж в своей системе |
| Ссылка возврата | адрес страницы завершения оплаты | заполняется всегда, иначе покупателю некуда вернуться |
| Оплачиваемые позиции | название, количество, цена и ставка НДС каждой позиции | минимум одна позиция; ставки — в [справочнике](/docs/dictionary/tag1199/) |
| Выбор одной позиции | покупатель выбирает один вариант из списка | удобно для тарифов: перечислите варианты, покупатель отметит нужный |
| Открывать в новом окне | форма открывается в новой вкладке или в текущей | снимите отметку, если хотите оставить покупателя на странице |
## Что важно знать до вставки
Сумма и состав заказа приходят из браузера покупателя и не подписаны — их можно изменить в браузере
до отправки. Это осознанное упрощение ради быстрого старта, но оно накладывает обязанность: получив
[уведомление об оплате](/docs/merchant/notification/status/), сверяйте сумму с той, которую ожидали.
Если цену определяет только ваш сервер, надёжнее создавать заказы
[через API](/docs/merchant/order/create/). Подробно — [Безопасность виджета](/widgets/security/).
Прежний конструктор на [widget.invoicebox.ru](https://widget.invoicebox.ru/?utm_source=docs)
продолжает работать: код, собранный там и в конструкторе портала, одинаковый.
### Примеры виджетов
Ниже — живые виджеты в песочнице портала: та же форма, что увидит покупатель на вашем сайте.
Собраны они на демо-магазине документации, поэтому оплата ничего не спишет. Свой виджет
собирается в [конструкторе](/widgets/constructor/) — настройки слева, код справа.
**Счёт организации или ИП.** Состав задан заранее, покупатель вводит только реквизиты. Так выставляют счёт за услуги по договору.
**Оплата товара с количеством.** Покупатель меняет количество, сумма пересчитывается на месте.
**Выбор из нескольких позиций.** Покупатель выбирает тариф или товар из списка.
**Пополнение баланса.** Сумму вводит покупатель — подходит для депозитов и абонентской платы.
---
---
# Модули для CMS
# Готовые модули для CMS
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей для платформ с открытым исходным кодом.
| Система управления сайтом (CMS) | Версия | Лицензия CMS/Модуля | Детали
|------------------------------------------------------------------|---------------|-------------------------------| ---------------------------------
| 
| > 16.x | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/1c-bitrix/)
| | > 1.2.x | Платная | [Смотреть »](/docs/merchant/cms/aspro/)
| | > 6.1.x | Бесплатный | [Смотреть »](/docs/merchant/cms/woocommerce/)
| | Все | Условно-бесплатный/Бесплатный | [Смотреть »](/docs/merchant/cms/tilda/)
| 
| InSales | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/insales/)
| 
| VirtualityCMS | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/vicms/)
| 
| --- | --- |
| 
| --- | --- |
| 
| --- | --- |
| 
| --- | --- |
| 
| --- | --- |
| 
| --- | --- |
| 
| > 5.* | Бесплатный |[Смотреть »](/docs/merchant/cms/joomshopping/)
| | Virtuema rt | Бесплатный |[Смотреть »](/docs/merchant/cms/virtuemart/)
| 
| --- | --- |
| 
| --- | --- |
| | 2.X | Бесплатный |[Смотреть »](/docs/merchant/cms/opencartv2/)
| | 3.X | Бесплатный |[Смотреть »](/docs/merchant/cms/opencartv3/)
| 
| --- | --- |
| 
| 8.X | Бесплатный |[Смотреть »](/docs/merchant/cms/prestashop/)
| 
| --- | --- |
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
## Читайте также
- [Требования к разработке расширений](/docs/merchant/cms/requirements/)
---
# Получение отгрузки
# Получение отгрузки
Отгрузки читаются одним запросом:
- метод: `GET`
- ресурс: `/v3/billing/api/order/shipment`
- тело ответа - коллекция объектов [ShipmentResponse](/docs/merchant/order/shipment_create/#shipmentresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
В запросе можно применять фильтры и сортировку.
#### Пример запроса и ответа
```http
GET /v3/billing/api/order/shipment?id=371723
```
Пример запроса с фильтром по id заказа
```http
GET /v3/billing/api/order/shipment?orderId=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по id магазина
```http
GET /v3/billing/api/order/shipment?merchantId=21827364-196a-1178-839a-82469489d6d7
```
---
Ответ:
``` json
{
"data": [
{
"id": 616095,
"orderId": "019e51e2-3970-9852-e8c8-803c16ac9c74",
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"basketItems": [
{
"sku": "baaa27aee304c4",
"name": "Мягкая игрушка Винни Пух",
"measure": "шт",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 1,
"amount": 14162,
"amountWoVat": 11608.2,
"totalAmount": 14162,
"totalVatAmount": 2553.8,
"vatCode": "RUS_VAT22",
"type": "commodity",
"paymentType": "full_payment"
}
],
"createdAt": "2026-05-22T23:10:55+00:00",
"type": "shipment",
"status": "completed",
"amount": 14162,
"vatAmount": 2553.8,
"final": true
}
]
}
```
---
# Модули для CRM
# Готовые модули для CRM
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей для платформ с открытым исходным кодом.
| Система управления клиентами (CRM) | Версия | Лицензия CRM/Модуля | Детали
|-----------------------------------------------|------------|---------------------| ---------------------------------
|  | любая | Платная/Бесплатный | [Смотреть »](/docs/merchant/crm/amocrm/)
|  | любая | Платная | [Смотреть »](/docs/merchant/crm/sportcrm/)
|  | любая | Платная/Бесплатный | [Смотреть »](/docs/merchant/crm/retailcrm/)
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
---
# Изменение отгрузки
# Изменение отгрузки
Отгрузка меняется по своему идентификатору:
- метод: `PUT`
- ресурс: `/v3/billing/api/order/shipment/:uuid` - где `:uuid` это идентификатор отгрузки
> [!NOTE]
> Идентификатор заказа при изменении не передаётся — отгрузка уже связана с заказом. Признак завершающей отгрузки задаётся при создании.
- тело запроса - объект [UpdateShipmentRequest](#updateshipmentrequest)
- тело ответа - объект [ShipmentResponse](#shipmentresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/shipment/{id}
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"amount": 100.5,
"vatAmount": 100.5,
"documentNumber": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": 1,
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"createdAt": "2026-08-03T12:00:00+03:00",
"type": "string",
"status": "draft",
"amount": 100.5,
"vatAmount": 100.5,
"final": false,
"documentNumber": "string",
"description": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## UpdateShipmentRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------------------------------|---------------------------------------------------------|----------------------------------------|
| documentNumber | нет | string(36) | Номер документа (накладная, счёт-фактура и пр.) | `123` |
| documentDate | нет | date | Дата документа | `2023-12-12` |
| basketItems | да | array of [BasketItem](#basketitem) | Корзина заказа | |
| type | нет | string, enum | Тип отгрузки, по умолчанию `shipment` | `shipment`, `cancel` |
## ShipmentResponse
Повторяет свойства объекта [CreateShipmentRequest](#updateshipmentrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------|-------------------------------------------------|-----------------------------------------|
| id | да | int | Идентификатор отгрузки в системе Инвойсбокс | `2` |
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76 ` |
## BasketItem
Корзина заказа. Пожалуйста, внимательно ознакомьтесь с требованиями по [заполнению наименования номенклатуры](/docs/merchant/fz54).
| Свойство | Обязательное | Тип | Описание |
|-------------------|--------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sku | да | string(500) | Артикул, например: `5fe0adcfa7fb4` |
| name | да | string(500) | Наименование, например `Бронирование номера` |
| groupName | нет | string(500) | Наименование группы позиций заказа, используется для формирования отчетных документов |
| measure | да | string(10) | Единица измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `шт.` |
| measureCode | да | string(4) | Код единицы измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `796` |
| originCountry | нет | string(20) | Страна происхождения товара, например, `Россия` |
| originCountryCode | нет | string(4) | Код страны происхождения, например, Россия `643` |
| grossWeight | нет | float | Вес брутто, например `125.45` |
| netWeight | нет | float | Вес нетто, например `125.45` |
| quantity | да | float | Количество, например `3` |
| amount | да | float | Стоимость единицы, например `100.55` |
| amountWoVat | да | float | Стоимость единицы без учёта НДС |
| totalAmount | да | float | Стоимость всех единиц с НДС, например`123.55` |
| totalVatAmount | да | float | Итого сумма НДС, например `23` |
| excise | нет | float | Сумма акциза, например, `10.00` |
| vatCode | да | string(20) enum | Код процента НДС, допустимые значения: `VATNONE` - не облагается,`VATNONE` - не облагается, `RUS_VAT0` - 0%, `RUS_VAT10` - 10/110, `RUS_VAT10_ADDED` - 10%, `RUS_VAT20` - 20/120, `RUS_VAT20_ADDED` - 20% `RUS_VAT22` - 22/122, `RUS_VAT22_ADDED` - 22% |
| type | да | string(10) или int | Тип позиции, [в соответствии со справочником](/docs/dictionary/tag1212) или service - сервис, commodity - товар |
| paymentType | да | string(20) enum | Тип оплаты, допустимые значения: `full_prepayment`, `prepayment`, `advance`, `full_payment` |
| metaData | нет | object | [Дополнительные данные элемента корзины](/docs/merchant/order/metadata/) |
---
---
# Virtuemart
# Virtuemart (joomla)
Расширение Virtuemart для Joomla предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает 1 режим работы, API «Инвойсбокс» версии 2
> [!NOTE]
> Модуль работает по API версии 2. Вторая версия поддерживается, но для новых магазинов
> рекомендуется третья — см. [Приём платежей](/docs/merchant/). Версию своего подключения уточните
> у персонального менеджера.
Для модуля необходима версия joomla 3+, но рекомендуется использовать 4ую и выше.
Скачать модуль можно по этой [ссылке](https://github.com/InvoiceBox/Virtuemart-3)
Также полезно будет установить [русификатор для расширения](https://virtuemart.net/community/translations/virtuemart/ru-RU)
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Устанавливается расширение через админ панель, в пункте "загрузить и установить"
1. Перейдите в компонент "Virtuemart" —> "Способы оплаты";
2. Добавьте новый метод оплаты "Invoicebox" и заполните поля. Нажмите «Сохранить»;
3. Зайти в раздел Администрирование -> Способы оплаты, добавить новый метод оплаты с процессором invoicebox;
4. Заполнить настройки на вкладке "Общее";
5. Перейдите во вкладку "Конфигурация" и заполните следующие поля:
- "Идентификатор магазина"
- "Региональный код магазина"
- "Ключ безопасности магазина"
6. Выберите необходимые статусы заказа;
7. Нажмите на кнопку "Сохранить".
### Настройка в личном кабинете Инвойсбокс
Без этого шага магазин не узнает об оплате: заказ так и останется неоплаченным в панели управления,
даже если деньги пришли.
1. Войдите в личный кабинет и откройте «Мои продажи» → «Мои магазины» → «Интеграция (API)».
2. Выберите тип уведомления — уведомление о смене статуса заказа.
3. В поле «URL уведомления» укажите адрес обработчика модуля на вашем сайте. Адрес показывает сам
модуль в своих настройках; он должен быть доступен снаружи и работать по HTTPS.
4. Сохраните изменения.
Как устроено уведомление и как проверить подпись — [Уведомление о смене статуса
заказа](/docs/merchant/notification/status/).
## Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Принятая валюта - выберите валюту рубли.
Страны - если этот параметр не важен, не изменяйте его, если вы продаете на несколько стран, то возможно вам стоит ограничить показать платежного плагина, и выбрать только для "России".
Минимальная сумма - минимальная сумма заказа, при которой возможен платеж данным платежным плагином.
Максимальная сумма - максимальная сумма заказа, при которой возможен платеж данным платежным плагином.
Плата за транзакцию - дополнительный фиксированный сбор при выборе данного платежного метода.
Плата или возврат процента от общей суммы - дополнительный сбор в процентах при выборе данного платежного метода.
Налог - налоговые правила для данного платежного метода.
---
# Модули для ERP
# Готовые модули для ERP-систем
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей.
| ERP-система | Версия | Лицензия ERP/Модуля | Детали
| ---------------------------------------| ---------| ------------------------------------------------------- | ---------------------------------
|  | >= 7.9.7 | Платная/Платный/Наличие лицензии api payment (21016318) | [Смотреть »](/docs/merchant/erp/iiko/)
|  | --- | Платная/Платный | [Смотреть »](/docs/merchant/erp/bnovo/)
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
---
# Смена магазина
Для управления выплатами и реквизитами, по которым их следует осуществить,
вы можете воспользоваться методом смены магазина. Изменить магазин можно как
у оплаченного заказа, так и у не оплаченного. При этом, изначальный магазин
должен иметь специальный тип, позволяющий в дальнейшем вносить такие изменения
в заказ.
- метод: `PUT`
- ресурс: `/v3/billing/api/order/order/order-merchant-move`
- тело запроса - объект [UpdateOrderMerchantRequest](#updateordermerchantrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/order/order-merchant-move
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string",
"currencyId": "RUB",
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"status": "string",
"shipmentStatus": "string",
"subtype": "string",
"processingStatus": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderIdVisible": "string",
"expirationDate": "2026-08-03T12:00:00+03:00",
"metaData": {},
"customerData": {},
"notificationUrl": "string",
"orderSetting": {
"roundPolicy": "string",
"disableValidate": false
},
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"shopId": 1,
"sourceId": "l3",
"paidAt": "2026-08-03T12:00:00+03:00",
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"returnUrl": "string",
"successUrl": "string",
"failUrl": "string",
"paymentUrl": "string",
"paymentUrlType": "redirect",
"paymentPageUrl": "string",
"customer": {
"type": "string",
"name": "string",
"phone": "string",
"email": "string",
"vatNumber": "string",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"registrationAddress": "string",
"taxRegistrationReasonCode": "string"
},
"languageId": "01771534-1a57-f184-dee3-ebeb91dded75",
"contactId": 1,
"contactCounterpartyId": 1,
"processable": false,
"userAccountId": "01771534-1a57-f184-dee3-ebeb91dded75",
"invoiceSetting": {
"customerLocked": false,
"customerLockedFields": {},
"customerHiddenFields": {},
"paymentMethodIdLocked": false,
"paymentMethodId": 1,
"savePaymentData": false,
"clientId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentToken": "string",
"paymentMethodCode": "string",
"paymentMethodAutosubmit": false,
"bankDetailId": 1
},
"orderContainerId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentInfo": {},
"holdTill": "2026-08-03T12:00:00+03:00",
"additionalOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"shipmentTotalAmount": "string",
"shipmentTotalVatAmount": "string"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## UpdateOrderMerchantRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|-----------------|-------------------------------------------|----------------------------------------|
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76` |
| orderId | да | string(36) | Идентификатор заказа в системе Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded75` |
---
---
# Joomshopping
# JoomShopping
Расширение JoomShopping для Joomla предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает 1 режим работы, API «Инвойсбокс» версии 2
> [!NOTE]
> Модуль работает по API версии 2. Вторая версия поддерживается, но для новых магазинов
> рекомендуется третья — см. [Приём платежей](/docs/merchant/). Версию своего подключения уточните
> у персонального менеджера.
Для модуля необходима версия Joomla 3+, но рекомендуется использовать 4ую и выше.
Скачать модуль можно по этой [ссылке](https://github.com/InvoiceBox/JoomShopping-4)
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка плагина
В админ-панели пройдите в "Компоненты" —> "JoomShoppping" —> "Установка и Обновление". Выберите файл "invoicebox_joomshoppping_5.zip" и нажмите на кнопку "Загрузить".
## Настройка модуля
1. Перейдите в компонент "JoomShoppping" —> "Опции" —> "Способ оплаты";
2. Выберите способ оплаты "InvoiceBox" (Инвойсбокс) и перейдите во вкладку "Конфигурация" и заполните следующие поля:
- "Идентификатор магазина"
- "Региональный код магазина"
- "Ключ безопасности магазина"
3. Выберите необходимые статусы заказа в опции "Статус заказа для успешных транзакций";
4. Нажмите на кнопку "Сохранить".
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Изображения URL - ссылка на картинку, которая выводится вместе с платежной системой.
Цена - дополнительный сбор (в процентах или фиксированная сумма) при выборе данного платежного метода.
Выберите налог - налоговые правила для данного платежного метода.
### Настройка панели Инвойсбокс:
1. Для настройки панели управления Инвойсбокс, перейдите по [ссылке](https://login.invoicebox.ru/)
2. Авторизуйтесь и пройдите в раздел "Мои магазины". "Начало работы" -> "Настройки" -> "Мои магазины";
3. Пройдите по вкладку "Уведомления по протоколу" -> выберите "Тип уведомления" "Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных)"
4. В поле "URL уведомления" укажите:
`<домен_сайта>/index.php?option=com_jshopping&controller=checkout&task=step7&act=notify&js_paymentclass=pm_invoicebox&no_lang=1&tmpl=component`
5. Сохраните изменения.
---
# Смена статуса заказа
Изменение статуса возможно только у [не процессинговых заказов](/docs/merchant/order/non-processable-order/),
а именно у заказов со свойством `processable = false`. Для изменения статуса, вы можете воспользоваться соответствующим
методом.
- метод: `PUT`
- ресурс: `/v3/billing/api/order/:uuid/status` - где `:uuid` это идентификатор заказа
- тело запроса - объект [UpdateOrderStatusRequest](#updateorderstatusrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/c5041a79-24a6-42d1-b0ce-4abb94982cd9/status
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"status": "completed"
}
```
Ответ:
``` json
{
"data": {
"id": "c5041a79-24a6-42d1-b0ce-4abb94982cd9",
"merchantOrderId": "O-12345",
"status": "completed",
"amount": 19658.45,
"currencyId": "RUB",
"paidAt": "2026-08-01T12:31:00+03:00"
}
}
```
## UpdateOrderStatusRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------|--------------|------------|-------------------------------------------|---------------------------------------------------|
| status | да | enum(4) | Статус заказа | `created`, `completed`, `expired`, `canceled` |
---
---
# Интеграции с PSS/GDS
# Готовые интеграции с PSS/GDS
Обращаем ваше внимание, что представленный перечень отлаженных интеграций неполный и содержит только наиболее актуальные варианты.
| PSS/GDS | Наименование | Детали
| ------------------------------------| ---------------------------| --------------------------------------------
|  | Сирена-Тревел/МПС (EgoPay) | [Смотреть »](/docs/merchant/pss/mps/)
|  | ТАИС TravelShop | [Смотреть »](/docs/merchant/pss/tais/)
Если вы не нашли подходящую интеграцию, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы
поможем вам соориентироваться.
---
# InSales
# Расширение Инвойсбокс для InSales
**Расширение доступно на тарифах Омни и Премиум.**
1. Чтобы подключить расширение Инвойсбокс, напишите на [почту](mailto:c-support@invbox.ru) и указать в письме номер личного кабинета InSales
2. После добавления, расширение будет доступно в личном кабинете в разделе "Расширения"
3. Нужно ввести данные для интеграции, которые будут находиться в [личном кабинете](https://business.invoicebox.ru) после регистрации и заключения договора.
Потребуется: Идентификатор магазина, Авторизационный токен (API токен в ЛК) и Ключ для проверки подписи запроса (API ключ в ЛК)
Данные для тестирования
- Идентификатор магазина
- Авторизационный токен
- Ключ для проверки подписи запроса
Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Ставка НДС должна совпадать с вашим режимом налогообложения и ставкой указанной в настройках магазина.
Остальные настройки заполняются по умолчанию, если они не заполнены в магазине.
4. В пункте “настройка” - “оформление заказа” - “оплата” появится новый вид оплаты “Инвойсбокс”
5. В настройках нужно привязать способ оплаты к способам доставки, а также выставить тип плательщиков: физ.лицо и/или юр.лицо. Если ни один способ доставки не будет привязан, то вид оплаты не появится на странице оформления заказа. По желанию сменить название и установить наценку
6. Для включения возможности оплаты юр.лицам передите в "настройки" -> "оформление заказа" -> "перейти к редактированию полей клиента" и включить пункт "Организация". ИНН — обязательное поле
Остальные настройки будут заполнены автоматически и не требуют изменений.
7. В случае успешной оплаты, покупатель будет переадресован на страницу нового заказа со статусом “оплачен”.
В случае возникновения ошибки при оплате, покупатель будет перенаправлен в магазин на страницу оформления заказа , где у него будет возможность заново перейти к оплате
---
# Prestashop
# Описание платёжного модуля для Prestashop
Платёжный модуль для интеграции платёжной системы «Инвойсбокс» и PrestaShop v8.1.2.
Реализована поддержка платёжного API. Протестировано на CMS PrestaShop v8.1.2.
Скачать модуль можно по [ссылке](https://github.com/InvoiceBox/PrestaShop-1.7)
Модуль поддерживает работы с 2 версией АПИ
Версию вашего подключения уточняйте у вашего персонального менеджера или в [службе поддержки](https://www.invoicebox.ru/ru/contacts) системы.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка модуля
1. В админ панели сайта выбираем пункт "Модули"->"Module manager"->"Загрузить модуль"
2. Далее необходимо настроить модуль
3. Здесь необходимо указать 3 обязательных параметра: id магазина для версии API v2, региональный код и ключ подписи запроса для обработки уведомлений об оплате.
4. Все необходимые параметры находится в [личном кабинете](business.invoicebox.ru/login) Инвойсбокс
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
### Настройка панели Инвойсбокс:
1. Авторизуйтесь в [личном кабинете](business.invoicebox.ru/login) Инвойсбокс
2. Пройдите в раздел "Мои магазины". "Начало работы" -> "Настройки" -> "Мои магазины";
3. Пройдите по вкладку "Уведомления по протоколу" -> выберите "Тип уведомления" "Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных)"
4. В поле "URL уведомления" укажите:
`<домен_сайта>/modules/invoicebox/callback.php`
5. Сохраните изменения.
---
---
# Рекуррентные платежи
# Рекуррентные платежи
При оплате заказа физическим лицом есть возможность применить рекуррентные платежи. Это позволит
сохранить токен банковской карты пользователя, для последующего списания с неё средств без участия
клиента, например, для списания средств по подписке.
## Почему для организаций регулярность устроена иначе
Списание по сохранённой карте работает, и дело не в поддержке. Владелец карты — всегда физическое
лицо: даже корпоративная карта оформлена на сотрудника. Значит расход ложится на человека, и потом
ему отчитываться перед бухгалтерией — сохранить чек, обосновать трату, приложить её к отчёту. Для
регулярных корпоративных расходов это неудобно, и чем больше сотрудников, тем неудобнее.
Поэтому организациям и ИП адресована подписка — шаблон платежа: правила, по которым покупателю
уходит счёт. Правило задаёт период, конкретный день или условие — например, снижение баланса до
порога. Дальше есть два пути:
- **заказы создаёт ваша система** — по своему расписанию вызывает
[создание заказа](/docs/merchant/order/create/), и счёт уходит покупателю как обычно;
- **заказ-подписка** — создаётся один раз с параметрами периода и условий, клиент подписывается на
неё, и счета приходят ему в нужное время без новых вызовов с вашей стороны.
Счёт по подписке доходит покупателю привычным каналом: письмом, ссылкой или
[Запросом о платеже](/docs/scenarios/rtp/) в приложение банка.
> [!NOTE]
> Параметры заказа-подписки настраиваются при подключении: публичного описания полей в контракте пока
> нет, поэтому состав правил уточняйте у [технической поддержки](https://www.invoicebox.ru/ru/contacts).
> Как только описание появится, оно встанет на эту страницу.
## Привязка карты
### Схема получения токена карты
## Данные бронирования авиабилетов
Для передачи данных бронирования авиаперелётов, в поле заказа `metaData`
необходимо передать объект [ReservationPackage](https://schema.org/ReservationPackage) с перечнем
дочерних объектов [FlightReservation](https://schema.org/FlightReservation). Для каждого из сегментов полёта,
а также для каждого из пассажиров передаётся отдельный объект [FlightReservation](https://schema.org/FlightReservation).
#### Пример объекта ReservationPackage
``` json
{
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "FlightReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "Андрей Макаров"
},
"reservationFor": {
"@type": "Flight",
"flightNumber": "NDJ37S",
"provider": {
"@type": "Airline",
"name": "Aeroflot",
"iataCode": "SU"
},
"seller": {
"@type": "Airline",
"name": "Aeroflot",
"iataCode": "SU"
},
"departureAirport": {
"@type": "Airport",
"name": "Москва (Шерементьево)",
"iataCode": "SVO"
},
"departureTime": "2022-03-04T20:15:00+03:00",
"departureGate": "11",
"departureTerminal": "C",
"arrivalAirport": {
"@type": "Airport",
"name": "Санкт-Петербург (Пулково)",
"iataCode": "LED"
},
"arrivalTime": "2022-03-05T21:30:00+03:00",
"arrivalGate": "11",
"arrivalTerminal": "1"
},
"airplaneSeat": "1A",
"airplaneSeatClass": {
"@type": "AirplaneSeatClass",
"name": "Business"
},
"ticketNumber": "111-1231231239",
"ticketToken": "qrCode:AB34",
"checkinUrl": "https://checkmytrip.ru/onlinecheckin.html",
"reservedTicket": {
"@type": "flightTicket",
"underName": {
"@type": "Person",
"name": "MAKAROV ANDREY"
},
"fareBase": 57.00,
"fareReservation": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}]
}
```
## Данные бронирования железнодорожных билетов
Для передачи данных бронирования железнодорожных билетов, в полях элементов корзины `metaData`
необходимо передать объект [TrainReservation](https://schema.org/TrainReservation) с перечнем
дочерних объектов.
#### Пример объекта элемента корзины (билета) TrainReservation
``` json
{
"@type": "TrainReservation",
"bookingTime": "2021-05-15T12:22:01",
"reservationId": "74345932763286",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"reservationFor": {
"@type": "TrainTrip",
"departureStation": {
"@type": "TrainStation",
"name": "Moscow Kievskyi"
},
"departureTime": "2021-06-04T10:30:00+01:00",
"arrivalStation": {
"@type": "TrainStation",
"name": "St. Petersburg Central"
},
"arrivalTime": "2021-06-04T03:10:00+01:00",
"trainName" : "ГСЭ",
"trainNumber": "425*СА"
},
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"provider": {
"@type": "Organization",
"name": "Sapsan",
"taxID": "2323232323"
},
"reservedTicket": {
"@type": "trainTicket",
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"gender": "male",
"nationality": "RUS",
"idDocumentNumber": "***** 3456",
"idDocumentDate": "2015-01-01",
"coachNumber": "04",
"coachType": "Плацкартный",
"serviceClass": "3Э",
"ticketedSeat": {
"@type": "Seat",
"seatNumber": "038"
},
"ticketNumber": "74363372056286",
"ticketStatus": "Оформлен",
"ticketIssueTime": "2021-05-15T12:30:21+01:00",
"fareBase": 57.00,
"fareReservation": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}
```
#### Пример объекта элемента корзины (услуги) TrainReservation
``` json
{
"@type": "TrainReservation",
"bookingTime": "2021-05-15T12:22:01",
"reservationId": "74345932763286",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"reservationFor": {
"@type": "TrainTrip",
"departureStation": {
"@type": "TrainStation",
"name": "Moscow Kievskyi"
},
"departureTime": "2021-06-04T10:30:00+01:00",
"arrivalStation": {
"@type": "TrainStation",
"name": "St. Petersburg Central"
},
"arrivalTime": "2021-06-04T03:10:00+01:00",
"trainName" : "ГСЭ",
"trainNumber": "425*СА"
},
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"provider": {
"@type": "Organization",
"name": "Sapsan",
"taxID": "2323232323"
},
"reservedTicket": {
"@type": "baggageCheck",
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"idDocumentNumber": "***** 3456",
"idDocumentDate": "2015-01-01",
"ticketNumber": "44363452345662",
"declaredName": "Велосипед",
"declaredValue": 100.00,
"note": "Малогабаритный багаж в специализированном купе",
"fare": 57.00,
"valueFee": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}
```
## Данные бронирования места проживания
Для передачи данных бронирования места проживания (отель, хостел, апартаменты и пр.), в поле заказа `metaData`
необходимо передать объект [ReservationPackage](https://schema.org/ReservationPackage) с перечнем
дочерних объектов [LodgingReservation](https://schema.org/LodgingReservation).
#### Пример объекта ReservationPackage
``` json
{
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "LodgingReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "Андрей Макаров"
},
"reservationFor": {
"@type": "LodgingBusiness",
"name": "Гранд Отель Европа",
"address": {
"@type": "PostalAddress",
"streetAddress": "ул. Михайловская, д. 1/7",
"addressLocality": "Санкт-Петербург",
"addressRegion": "Санкт-Петербург",
"postalCode": "191186",
"addressCountry": "ru"
},
"telephone": "+7 (812) 329-6000"
},
"checkinTime": "2021-02-21T16:00:00-08:00",
"checkoutTime": "2021-02-23T11:00:00-08:00"
}]
}
```
## Данные подписки
Для передачи данных о подписке, в полях элементов корзины `metaData`
необходимо передать объект [PaymentPlan](https://schema.org/) с перечнем
дочерних объектов.
#### Пример объекта элемента корзины (подписки) PaymentPlan
``` json
{
"@context": "https://schema.org",
"@type": "PaymentPlan",
"name": "Pro-подписка на сервис Экспресс Клиент",
"description": "Доступ к премиум-функциям в течение 1 года с ежемесячными платежами",
"billingPeriod": "P1M",
"billingIncrement": "1",
"contractStartDate": "2025-01-01",
"contractEndDate": "2026-01-01",
"price": "2990.00",
"priceCurrency": "RUB",
"provider": {
"@type": "Organization",
"name": "Экспресс Клиент",
"url": "https://expressclient.ru"
}
}
```
---
---
# Требования
# Требования к разработке расширений «Инвойсбокс» для систем управления сайтами
## Используемый протокол обмена данными (API)
Расширение (далее, модуль «Инвойсбокс») системы управления сайтом (далее, CMS) Интернет-магазина (далее, магазина)
для передачи информации о заказе и составе корзины должен опираться на описание протокола, расположенное по адресу:
[Инвойсбокс API v3](https://docs.invoicebox.ru).
Перед отправкой данных заказа в API, модуль должен проверять корректность данных, в частности, формат данных должен
соответствовать описанному в API. В случае наличия ошибок в расчёте, отсутствия необходимых сведений и других ошибок,
модуль должен отобразить соответствующее сообщение пользователю, данные не должны отправляться в платёжный шлюз.
В модуле должны быть предусмотрены следующие функции:
1. Оформление заказа/переход на платёжную страницу системы «Инвойсбокс»;
2. Callback-скрипт для получения информации об оплате заказа;
3. Функции оформления возврата по заказу.
## Множество способов оплаты
В тех CMS, где это технически возможно, модуль должен поддерживать оформление двух способов оплаты, а именно -
оплата для физических лица (банковские карты, интернет банки и т.д.), а также оплата для юридических лиц
(оплата по счёту для организаций и ИП). В настройках модуля должна быть предусмотрена возможность выбора
используемых способов оплаты.
При выборе способа оплаты для организаций и ИП, по API должны передаваться данные организации - ИНН, КПП,
наименование, юридический адрес (при наличие данных в заказе).
Т.е. в результате установки модуля, в CMS должно появится два способа оплаты. Там где это невозможно,
способ оплаты выбирается на странице платёжного шлюза системы «Инвойсбокс».
## Идентификация модуля
Важно обратить внимание на формирование идентификатора приложения и модуля при работе с API.
В API v3 идентификатор приложения передаётся в HTTP-заголовке User-Agent.
В API v2, в параметрах платёжной формы, в обязательном порядке должно присутствовать поле с идентификатором
приложения - itransfer_cms_name.
## Параметры заказа (счёта)
Модуль обязательно должен передавать тип позиции в заказе - товар или услуга, для API V3 - более детальное
значение [см. справочник](/docs/dictionary/tag2108/);
## Callback для получения информации об оплате
Смена статуса заказа в CMS магазина происходит по факту получения информации об оплате в формате,
описанном по адресу:
Для API v3: [Уведомление по умолчанию](/docs/merchant/notification/status/);
Для API v2: [HTTP-уведомления о переводах](https://www.invoicebox.ru/ru/integration/webapi/notify/defaulthttp/).
При получении информации об оплате, модуль должен сверить подпись запроса, идентификатор магазина, валюту заказа,
сумму оплаты с суммой заказа. В случае расхождения, статус заказа менять не нужно, модуль должен
вернуть детальное описание ошибки в соответствии с форматом ответа API.
В модуле должно быть реализовано получение тестового запроса с информацией об оплате, при котором модуль
должен выдать успешный ответ в случае корректной передачи подписи запроса и идентификатора магазина.
Тестовый запрос используется для проверки корректность установки модуля и не должен приводить к смене статуса
какого-либо из заказов.
Для API v3, описание тестового запроса расположено на странице [уведомление по умолчанию](/docs/merchant/notification/status/) (раздел Система мониторинга и автоматическое тестирование интеграции);
Для API v2, в тестовом запросе передаётся номер счёта (ucode) равный: 00000-00000-00000-00000.
## Настройки модуля
Обязательным набором настроек модуля, которые пользователь может менять, являются:
- Идентификатор магазина (для API v2, v3);
- Региональный код магазина (для API v2);
- API ключ магазина (для API v2, v3);
- Включить/выключить тестовый режим (для API v2);
- Описание способа оплаты (текст, который отображается в описании способа оплаты в процессе выбора способа оплаты при оформлении заказа в магазине, для API v2, v3).
Опционально, в настройках модуля может быть предусмотрен статус, на который следует изменить статус заказа, при получении информации
об оплате, а также адрес эл. почты администратора магазина, на который следует отправлять отчёты, в случае возникновения ошибок в работе модуля.
При наличие технической возможности CMS, модуль должен поддерживать несколько настроек таким образом, чтобы для каждой группы товара
или отдельного товара можно было бы задать параметр - какие настройки использовать для оплаты. Это требования необходимо там, где
разные товары и услуги могут быть оплачены от разных организаций.
Модуль должен поддерживать 2 языка – русский и английский.
## Прочие сведения
Логотип системы для использования в модуле: [Логотипы системы «Инвойсбокс»](https://www.invoicebox.ru/ru/press.html)
Комплект модуля
В состав модуля должны входить следующие элементы:
- Файлы модуля (архив ZIP), включая файл version.txt, в котором должна быть отражена версия модуля;
- Информация о модуле – версия(ии) CMS для которой модуль предназначен, версия(ии) CMS, на которой модуль был протестирован;
- Логотип CMS (SVG);
- Пошаговая инструкция по установке модуля включая шаги, необходимые для установки модуля, изображения, сопровождающие описательную часть;
- Пошаговая инструкция по настройке модуля, необходимые для настройки модуля, изображения, сопровождающие описательную часть;
- URL, которую следует указать в личном кабинете системы «Инвойсбокс» для передачи информации об оплате.
Исходные коды модуля должны быть загружены на github:
- [github.com/InvoiceBox](https://github.com/InvoiceBox).
Информация о модуле и инструкции должны быть размещены на ресурсах:
- [Документаиця. Готовые модули для CMS](https://docs.invoicebox.ru/docs/merchant/cms).
## phpSDK
Для упрощенной разработки и поддержания модулей в актуальном состоянии, рекомендуется использование [phpSDK](/docs/merchant/sdk/php/).
## Общие требования к обновлению старых версий модулей
1. Обновление модулей в соответствии с актуальными версиями CMS;
2. Обновление логотип и наименование платёжной системы - Инвойсбокс, Инвойсбокс (б, b - маленькие);
3. Обновление инструкций по установке и настройке модулей;
4. Реализация функций возврата платежа, если такие функции поддерживает CMS;
---
[Проект на github](https://github.com/InvoiceBox/)
---
# Схема взаимодействия
# Схема взаимодействия с платёжным инструментом
| Массив идентификаторов программ лояльностей, котоыре принимает точка | [`01771534-1a57-f184-dee3-ebeb91dded71`,`01771534-1a57-f184-dee3-ebeb91dded72`] |
## ShopResponse
Повторяет свойства объекта [CreateShopRequest](#createshoprequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-------------------|--------------|-----------------|----------------------------------------------------------------------|---------------------------------------------------------------------------------|
| id | да | int | Идентификатор магазина | 12 |
| token | да | string(64) | Токен магазина | `95e5396611d261986cec0915a9f85799` |
| type | да | string(50) enum | Тип магазина | `shop`,`marketplace`,`external`,`offline`,`brand` |
| alias | да | string(20) | Алиас магазина | `1694158899` |
| shopUrl | да | string(64) | Ссылка на магазин | `https://1694158899.expressclient.ru` |
| accountProgramIds | нет | array | Массив идентификаторов программ лояльностей, которые принимает точка | [`01771534-1a57-f184-dee3-ebeb91dded71`,`01771534-1a57-f184-dee3-ebeb91dded72`] |
---
# Обновление точки продаж
# Обновление точки продаж
Точка продаж меняется по своему идентификатору:
- метод: `PUT`
- ресурс: `/v3/marketplace/api/shop/:id` - где `:id` это идентификатор точки продаж
- тело запроса - объект [UpdateShopRequest](#updateshoprequest)
- тело ответа - объект [ShopResponse](#shopresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса
``` json
PUT /v3/marketplace/api/shop/1
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"description": "Это наш тестовый магазин",
"notificationEmail": "test@test.me",
"jivositeId": "321314123123",
"yandexMetrikaId": 432141251234,
"deliveryInfo": "Когда хотим, тогда и доставляем",
"registrationAddress": "Санкт-Петербург, улица Рубинштейна, дом 12",
"lat": 59.931228,
"lon": 30.345557,
"brandId": 123,
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded76",
"externalUpdate": true
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": 1,
"title": "string",
"description": "string",
"shortDescription": "string",
"seoTitle": "string",
"seoKeywords": "string",
"seoDescription": "string",
"categoryId": 1,
"shopDeliveryId": 1,
"alias": "string",
"shopUrl": "string",
"minOrderSum": 100.5,
"stockMode": "string",
"priceMode": "string",
"notificationEmail": "string",
"defaultPriceId": 1,
"imagePath": "string",
"imageId": 1,
"ogImagePath": "string",
"ogImageId": 1,
"mode": "string",
"jivositeId": "01771534-1a57-f184-dee3-ebeb91dded75",
"orderFlow": "string",
"yandexMetrikaId": 1,
"deliveryInfo": "string",
"shopIds": {},
"accountProgramIds": {},
"type": "string",
"orderLifetime": 1,
"modelId": 1,
"manualProperties": {},
"compiledProperties": {},
"properties": {},
"imageIds": {},
"modelIds": {},
"hours": {
"mon": {},
"tue": {},
"wed": {},
"thu": {},
"fri": {},
"sat": {},
"sun": {}
},
"address": "string",
"lat": 100.5,
"lon": 100.5,
"distance": 100.5,
"externalId": "01771534-1a57-f184-dee3-ebeb91dded75",
"brandId": 1,
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"cityId": 1,
"active": false,
"priority": 1,
"merchantCategoryId": 1,
"status": "string",
"contactEmail": "string",
"contactPhone": "string",
"contactVkLink": "string",
"contactTgLink": "string",
"contactOkLink": "string"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## UpdateShopRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------|--------------|-----------------|-------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| description | нет | string(2000) | Описание магазина | `Это наш первый тестовый магазин` |
| shopUrl | нет | string(64) | Ссылка на магазин | `https://1694158899.expressclient.ru` |
| minOrderSum | нет | float | Минимальная сумма заказа | 99.99 |
| notificationEmail | нет | string(500) | Email для отправки уведомлений | `test@test.me` |
| yandexMetrikaId | нет | int | | 12332134222 |
| deliveryInfo | нет | string(1000) | Описание доставки | `Не доставляем по выходным и праздникам` |
| type | нет | string(50) enum | Тип магазина | `shop`,`marketplace`,`external`,`offline`,`brand` |
| registrationAddress | нет | string(200) | Адрес магазина | `Санкт-Петербург, улица Рубинштейна, дом 12` |
| lat | нет | float | Широта нахождения магазина | 59.931228 |
| lon | нет | float | Долгота нахождения магазина | 30.345557 |
| brandId | нет | int | Идентификатор магазина с типом brand | 123 |
| merchantId | нет | string(36) | Идентификатор магазина Инвойсбокс, работает только в связвке с полем externalUpdate | `01771534-1a57-f184-dee3-ebeb91dded76` |
| accountProgramIds | нет | array | Массив идентификаторов программ лояльностей, которые принимает точка | [`01771534-1a57-f184-dee3-ebeb91dded71`,`01771534-1a57-f184-dee3-ebeb91dded72`] |
## ShopResponse
Повторяет свойства объекта [UpdateShopRequest](#updateshoprequest):
---
# Акции и спецпредложения
# Управление акциями и спецпредложениями магазина
Магазин может управлять набором акций и спецпредложений, которые будут отображены в маркетплейсе.
Для добавления или изменения спецпредложения, отправьте следующий запрос:
- метод: `POST`
- ресурс: `/v3/billing/api/merchant/special-offer`
- тело запроса - объект [CreateSpecialOfferRequest](#createspecialofferrequest)
- тело ответа - объект [SpecialOfferResponse](#specialofferresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
POST /special-offer
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"merchantId" : "ffffffff-ffff-ffff-ffff-ffffffffffff",
"externalId" : "1234",
"active" : true,
"startAt" :"2023-01-01T12:00:00Z",
"finishAt" :"2029-01-01T23:59:59Z",
"name" : "Скидка на День Рождения",
"description" : "Скидка 15% на всё меню в день рождения",
"tags" : [
"birthday"
]
}
```
``` json
{
"data":{
"id" : 123,
"merchantId" : "ffffffff-ffff-ffff-ffff-ffffffffffff",
"externalId" : "1234",
"active" : true,
"startAt" : "2023-01-01T12:00:00Z",
"finishAt" : "2029-01-01T23:59:59Z",
"name" : "Скидка на День Рождения",
"description" : "Скидка 15% на всё меню в день рождения",
"tags" : [
"birthday"
]
}
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": 1,
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"externalId": "01771534-1a57-f184-dee3-ebeb91dded75",
"active": false,
"startAt": "2026-08-03T12:00:00+03:00",
"finishAt": "2026-08-03T12:00:00+03:00",
"name": "string",
"description": "string",
"tags": {}
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## CreateSpecialOfferRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-----------------|--------------|-----------------|---------------------------------------------------------------------|----------------------------------------|
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76` |
| externalId | да | string(36) | Идентификатор спецпредложения во внтуренней системе учёта магазина | `1234` |
| active | да | bool | Флаг активности спецпредложения | `true` |
| startAt | да | datetime | Время начала действия спецпредложения | `2023-01-01T12:00:00Z` |
| finishAt | да | datetime | Время окончания действия спецпредложения | `2029-01-01T23:59:59Z` |
| description | да | string(1000) | Описание | `Скидка 15% на всё меню в день рождения` |
| tags | да | array of string | Теги | `birthday` |
## SpecialOfferResponse
Повторяет свойства объекта [CreateSpecialOfferRequest](#createspecialofferrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------------|--------------|-------|--------------------------------------------------|-----------------|
| id | да | int | Идентификатор спецпредложения в маркетплейсе | `123` |
---
---
# Маркетплейс
# Размещение магазина/точки продаж в маркетплейсе Инвойсбокс
Маркетплейс — это Витрина Инвойсбокс: каталог поставщиков, зарегистрированных в системе.
Магазин публикует информацию о себе на ресурсах Инвойсбокса и может продавать через
[мини-приложения](/docs/marketplace/mini-apps) — и в самом каталоге, и на
[платёжной странице](/docs/merchant/payment-page/) в качестве дополнительных услуг.
Пример: транспортная компания продаёт трансфер пассажиру, который в этот момент оплачивает
авиабилет. Так работает любая пара категорий, если нет конфликта интересов. Магазин самостоятельно
принимает решение о размещении информации в маркетплейсе. Чтобы разместить информацию, добавьте
точку продаж и опишите её: название, описание, адрес, координаты, ссылки, фотографии, логотип и прочее.
Маркетплейс представлен на платёжной странице Инвойсбокс, в сервисе маркетплейс Инвойсбокс и приложении
Инвойсбокс.
Точка продаж в рамках маркетплейса может предлагать товары или услуг как напрямую, так и в качестве
сервиса дополнительных услуг в процессе основной покупки на платёжной странице Инвойсбокс. Например,
такие услуги как транфсер или такси могут являться дополнительными услугами при продаже
[авиабилетов](/docs/scenarios/air-carriers) или [железнодорожных](/docs/scenarios/railway-carriers) билетов.
Точка продаж в рамках маркетплейса может являтся как офлайн точкой с конктерным физическим адресом,
так и онлайн точкой. Онлайн точка может иметь [мини-приложение](/docs/marketplace/mini-apps/) (форма
продажи), с помощью которого покупатель сможет оформить заказ непосредственно из маркетплейса Инвойсбокс.
См. [схему взаимодействия](/docs/marketplace/mini-apps/schema/).
Через API для работы с маркетплейсом, возможно добавлять и управлять точками продаж.
## Кросс-продажи на платёжной странице
Второй источник продаж — чужая покупка. Пока покупатель оплачивает авиабилет, ему можно предложить
трансфер; пока оплачивает поездку — страховку. Мини-приложение точки продаж показывается прямо на
[платёжной странице](/docs/merchant/payment-page/), и покупателю не нужно никуда уходить.
Отличие от продажи в самом каталоге — в том, чем заканчивается оформление:
| Где продаёте | Что создаёт мини-приложение | Чем заканчивается |
|---|---|---|
| Витрина Инвойсбокса | свой [заказ](/docs/merchant/order/create/) | покупатель платит отдельным счётом |
| Платёжная страница чужой покупки | [обновление переданного заказа](/docs/merchant/order/update/) | услуга попадает в счёт, который покупатель уже оплачивает |
Оба режима по шагам — в [схеме взаимодействия](/docs/marketplace/mini-apps/schema/); методы, которыми
мини-приложение говорит с родительским окном, — в [MiniApp SDK](/docs/marketplace/mini-apps/miniapp-sdk/).
Чтобы предложение выглядело предложением, а не строкой в списке, точке продаж пригодятся
[акции и спецпредложения](/docs/marketplace/special-offer/): срок действия, описание и признак
активности задаются одним запросом.
Пара категорий подбирается по смыслу: трансфер к билету, страховка к поездке, доставка к заказу.
Условие одно — между продавцами нет конфликта интересов. Как это выглядит со стороны площадки,
разобрано в кейсе [маркетплейса и сплит-корзины](/docs/scenarios/marketplace-split/).
## Читайте также
- [Что можно сделать через API: добавить точку продаж](/docs/marketplace/create/)
---
---
# Общая информация
# Описание работы мини-приложения
Как правило, мини-приложение состоит из двух основных компонентов - интерфейса приложения (frontend)
и серверной части (backend).
Интерфейс мини-приложения отвечает за взаимодействие с покупателем и интерфейсом Инвойсбокс (родительским окном).
Для взаимодействия интерфейса мини-приложения с интерфейсом Инвойсбокс, вы можете использовать [MiniApp SDK](/docs/marketplace/mini-apps/miniapp-sdk/).
Серверная часть мини-приложения отвечает за передачу данных между мини-приложением, магазином и системой Инвойсбокс.
Серверная часть мини-приложения взаимодействует с системой Инвойсбокс через [методы API](/docs/api).
> [!WARNING]
> Обратите внимание, сервер, на котором расположено мини-приложение, должен отправлять заголовки, которые разрешают
запускать контент мини-приложения на сторонних ресурсах в iframe. [Читать подробнее](/docs/marketplace/mini-apps/frame/) о
настройках заголовков.
Мини-приложение может быть инициализировано в двух основных режимах:
- В качестве формы основного заказа (тип мини-приложения - `order`)
- В качестве формы заказа дополнительной услуги (тип мини-приложения - `suborder`)
В случае, если мини-приложение инициализируется в маркетплейсе или приложении Инвойсбокс, оно представляет
из себя форму основного заказа. При инициализации, мини-приложение может получить
от интерфейса Инвойсбокс сведения о покупателе (имя, адрес эл. почты, номер телефона), а также идентификатор
точки продаж.
Через интерфейс мини-приложения, покупатель выбирает необходимые товары и услуги, оформляет покупку.
Мини-приложение, в соответствии со своими внутренними процессами, формирует заказ и через серверную часть
передаёт в систему Инвойсбокс информацию о заказе, а в ответ получает ссылку для переадресации покупателя
на платёжную форму. Получив ссылку, мини-приложение передаёт её родительскому окну для инициализации процесса
оплаты заказа покупателем. После подтверждения оплаты заказа, покупатель может быть возвращён в мини-приложение
магазина для продолжения процесса оформления покупки.
В случае, если мини-приложение инициализируется на платёжной странице Инвойсбокс, оно представляет из
себя форму заказа дополнительной услуги. Отличие от основной формы заказа: родительское окно передаст мини-приложению идентификатор основного заказа. Оформленный
заказ в мини-приложении будет добавлен и в конечном счёте оплачен покупателем одним платежом.
---
---
# Схема взаимодействия
# Схема взаимодействия магазина, мини-приложения и маркетплейса Инвойсбокс
Мини-приложение работает в одном из двух режимов, и от режима зависит почти всё: кто открывает платёжную
страницу, куда возвращается покупатель и в какой момент магазин узнаёт об оплате. Ниже — обе схемы
по отдельности.
## Мини-приложение как форма основного заказа
Покупатель приходит из Витрины, оформляет покупку в мини-приложении и оплачивает её отдельным счётом.
```
- targetKey - ключ (название свойства) по которому будет осуществлен поиск
- targetValues - массив возможных значений, если хотя бы одно значение из этого массива совпадет со значемием в метаданных, функция вернет `true`, в противном случае `false`
Пример использования
```ts
/*
если метаданные содержат поле iataCode: "SU" или iataCode: "LED", метод вернет true
*/
invoiceboxMinapp
.matchMetaDataValues("iataCode", ["SU", "LED"])
.then((isMatch) => {
if (isMatch) {
// do something
}
});
```
### Метод getMetaDataValues
Для того, чтобы получить нужную информацию из метаданных, воспользуйтесь методом `getMetaDataValues`.
```ts
getMetaDataValues(targetKey: string | string[]): Promise
```
- targetKey - ключ (название свойства) или массив ключей по котороым будет осуществлен поиск
Пример использования
```ts
invoiceboxMinapp
.getMetaDataValues(["flightNumber", "departureTime"])
.then(console.log);
/*
['NDJ37S', '2022-03-04T20:15:00+03:00']
*/
```
### Метод onHeightChange
Для управления высотой мини-приложения на платёжной странице используется метод `onHeightChange`.
Мини-приложение может задать высоту, которая требуется для корректного отображения мини-приложения
на платёжной странице.
```ts
onHeightChange(height: number): void;
```
Пример использования
```ts
const Conatiner = ({ children }: { children: ReactNode }) => {
const [elRef, setElRef] = useState(null);
useEffect(() => {
if (!elRef) return;
const observer = new ResizeObserver(() => {
invoiceboxMinapp.onHeightChange(elRef.offsetHeight);
});
observer.observe(elRef);
return () => observer.disconnect();
}, [elRef, child]);
return 
### Оплата бронирований с любым тайм-лимитом
Способы оплаты Инвойсбокс для организаций и ИП позволяют корпоративным клиентам оплачивать электронные
билеты с любым тайм-лимитом (от одной минуты), открывая возможность покупки билетов по промо- и бюджетным тарифам
так же, как при покупке с помощью банковской карты.
Подтверждение оплаты приходит авиакомпании за считанные минуты — с той же скоростью, что при оплате
картой. Короткий тайм-лимит перестаёт быть причиной отказывать корпоративному клиенту в оплате по счёту.
Постоянные корпоративные клиенты могут получить отсрочку до 30 дней, при этом авиаперевозчик гарантированно
получает денежные средства на следующий рабочий день после подтверждения оплаты бронирования.
### Отчётность по правилам авиакомпании
Отчёты приходят перевозчику в том формате, который принят у него: состав полей и разбивку можно
расширить или собрать по требованиям авиакомпании при подключении. Бухгалтерии и отделу
взаиморасчётов не приходится переделывать выгрузки под новый способ оплаты.
### Обработка возвратов
Сервис Инвойсбокс поддерживает как автоматизированное оформление возвратов, так и в ручном режиме через
личный кабинет. Денежные средства по возврату зачисляются клиенту до двух рабочих дней — срок зависит от способа оплаты.
### Автоматизированный документооборот
Отчётные документы формируются автоматически после подтверждения оплаты, а оригиналы уходят
[каналами ЭДО](/docs/merchant/documentflow/) или в бумажном виде почтой. Состав документов зависит от
вида перевозки.
| Что продано | Отчётные документы |
|---|---|
| Регулярная перевозка | отчёт о переводе средств и маршрут-квитанция электронного билета |
| Чартер, грузоперевозка | акт, счёт-фактура или УПД |
Для регулярных перевозок акт и счёт-фактура не выпускаются: расходы клиент подтверждает
маршрут-квитанцией, а расчёты — отчётом о переводе средств. Поэтому в квитанции важно, чтобы был
выделен НДС.
### Работа с динамическим ценообразованием
Схема интеграции предполагает возможность изменения стоимости бронирования до момента его оплаты. На каждом этапе
оплаты от формирования счёта до его оплаты негативные сценарии отрабатываются как автоматически с использованием
информирования клиента, так и с привлечением специалистов службы клиентской поддержки.
Штатные ситуации — недоплата, просрочка тайм-лимита, отмена брони — отрабатываются автоматически: клиент получает
уведомление, а система бронирования — [сообщение о смене статуса заказа](/docs/merchant/notification/status/).
Комиссию за приём оплаты можно разделить между перевозчиком и покупателем в нужной пропорции или целиком
переложить на покупателя — тогда в счёте она идёт отдельной строкой.
Специалист поддержки Инвойсбокс подключается там, где автоматика бессильна: нестандартное билетооформление,
спорная оплата, ручной возврат.
### Схема взаимодействия с клиентом
- После того, как заказ/бронь сформирована, клиент переходит на страницу выбора способа оплаты. Как правило, мы
предлагаем перевозчику разместить на сайте дополнительный способ: "Оплата по счёту для организаций и ИП".
- Если клиент выбирает способ оплаты "Оплата по счёту для организаций и ИП", система бронирования
[создаёт заказ](/docs/merchant/order/create/) в Инвойсбокс, передавая состав перелёта и данные бронирования.
Номер брони (PNR) и тайм-лимит удобно положить в [метаданные заказа](/docs/merchant/order/metadata/) —
они вернутся во всех уведомлениях и в закрывающих документах.
- В зависимости от тайм-лимита (TL) бронирования, система автоматически формирует набор доступных способов оплаты.
Тайм-лимит у бронирования может быть любой.
- Если тайм-лимит короткий, подойдёт обещанный платёж: покупатель подтверждает заказ картой, сумма
счёта блокируется, билет оформляется сразу, а счёт уходит организации со сроком оплаты пять суток —
[платёжные инструменты для B2B](/docs/merchant/payment-instruments/). Отдельная механика —
[подтверждение оплаты кодом](/docs/merchant/guarantee/) из гарантийного фонда: она не блокирует
средства на карте, а списывает их с фонда постоянного покупателя.
- Если тайм-лимит свыше 24х часов, то ко всем возможностям, описанным выше, добавляется простой выпуск счёта с ожиданием
оплаты в течение суток.
- После оплаты счёта в срок бронирования Инвойсбокс отправляет системе перевозчика
[уведомление об оплате](/docs/merchant/notification/status/); по нему оформляется билет и сопутствующие услуги.
Тайм-лимит истёк, а деньги не пришли — заказ можно
[отменить](/docs/merchant/order/delete/) и освободить бронь.
- Отчётные документы оформляет и отправляет клиенту система Инвойсбокс — по регулярным перевозкам это
отчёт о переводе средств и маршрут-квитанция с выделенным НДС. Дополнительной нагрузки на бухгалтерию
авиакомпании запуск нового способа оплаты не создаёт.
- Возврат по вынужденному или добровольному отказу оформляется
[методом возврата](/docs/merchant/refund/create/). Если авиакомпания удерживает сбор, возврат проводится
[с корректировкой](/docs/merchant/refund/correction/): клиент получает разницу, а в закрывающих документах
остаётся удержанная сумма. Деньги уходят клиенту до двух рабочих дней после уведомления от перевозчика, в зависимости от способа оплаты.
### Проработанные интеграции
Интеграция Инвойсбокс отработана с решениями таких лидеров отрасли как [Сирена-Тревел (МПС)](/docs/merchant/pss/mps/), [ТАИС TravelShop](/docs/merchant/pss/tais/), SITA, Amadeus, Sabre.
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# 🛍️ B2B продажи товаров
# Автоматизация продаж товаров юридическим лицам и ИП (b2b)
Оптовый заказ редко уезжает целиком: часть товара отгружается сегодня, часть через неделю, а чего-то
не оказывается на складе вовсе. Покупатель должен заплатить за то, что доехало, и получить документы на
эту же сумму.
Инвойсбокс держит и то и другое: счёт организации с отсрочкой, отгрузки частями и корректировка, когда
привезли меньше, чем в счёте.
Что это даёт продавцу:
- покупатель-организация оплачивает заказ по счёту, с отсрочкой до 30 дней или картой;
- деньги приходят на счёт на следующий рабочий день после подтверждения оплаты ([сроки](/docs/terms/));
- счёт, акт и УПД формируются автоматически — ваша бухгалтерия к этому не подключается;
- отгрузку частями и возвраты закрывают [отгрузки](/docs/merchant/order/shipment_create/) и [корректировки](/docs/merchant/refund/correction/).
### Оплата заказов с любым сроком оплаты
Способы оплаты Инвойсбокс для организаций и ИП позволяют корпоративным клиентам оплачивать заказы
с любым сроком оплаты (от одной минуты). Магазину нет необходимости резервировать товар на складе
на длительное время.
Постоянные корпоративные клиенты могут получить отсрочку до 30 дней, при этом продавец гарантированно
получает денежные средства на следующий рабочий день после подтверждения оплаты заказа.
### Обработка возвратов
Сервис Инвойсбокс поддерживает как автоматизированное оформление возвратов, так и в ручном режиме через
личный кабинет. Денежные средства по возврату зачисляются клиенту до двух рабочих дней — срок зависит от способа оплаты.
### Автоматизированный документооборот
Отчётные документы для клиента формируются автоматически после подтверждения оплаты заказа, а оригиналы
могут быть отправлены в бумажном виде по почте или [каналам ЭДО](/docs/merchant/documentflow/). Дополнительно
см. [схему документооборота](/docs/merchant/schema/commission/).
### Схема взаимодействия с клиентом
- После того, как заказ сформирован, клиент переходит на страницу выбора способа оплаты. Как правило, мы
предлагаем разместить на сайте дополнительный способ: "Оплата по счёту для организаций и ИП".
- Если клиент выбирает способ оплаты "Оплата по счёту для организаций и ИП", ваша система передаёт в систему
Инвойсбокс состав заказа и данные для формирования счёта на оплату.
- В зависимости от срока оплаты заказа, система автоматически формирует набор доступных способов оплаты.
Срок оплаты у заказа может быть любой.
- После получения подтверждения оплаты по счёту в течение срока действия заказа, информация об оплате передаётся
в систему учёта Магазина, происходит отгрузка товара, оформление и обмен документами.
- Все закрывающие документы оформляет и отправляет клиенту система Инвойсбокс. Никакой дополнительной нагрузки на
вашу бухгалтерию, связанной с запуском нового способа оплаты, не возникает.
- Ваша учётная система может передавать информацию о возврате средств клиенту. Обычно после получения
уведомления деньги возвращаются до двух рабочих дней — срок зависит от способа оплаты.
## Отгрузка партиями: платит за то, что доехало
Корпоративный заказ редко уезжает одной машиной. Часть позиций на складе, часть под заказ, что-то
приедет через неделю — а счёт и закрывающие документы клиент ждёт по факту поставки.
1. Заказ создаётся целиком — [создание заказа](/docs/merchant/order/create/) со всей корзиной.
2. Каждая партия оформляется [отгрузкой](/docs/merchant/order/shipment_create/) с фактическим составом:
что уехало, в каком количестве, по какой цене.
3. Состав отгрузки уточняется [изменением отгрузки](/docs/merchant/order/shipment_update/) —
пересорт и недовоз фиксируются до закрытия документов.
4. Позиции, которых не оказалось, снимаются
[возвратом с корректировкой](/docs/merchant/refund/correction/): клиент получает разницу,
а в УПД остаётся фактически поставленное.
Если товара нет и отгрузка невозможна, продавец сообщает об этом
[уведомлением о невозможности отгрузки](/docs/merchant/notification/shipping-unavailable/) —
Инвойсбокс вернёт деньги клиенту, не дожидаясь обращения в поддержку.
## Регулярные поставки
Для постоянных клиентов со стабильным заказом подойдёт подписка — шаблон платежа: счёт уходит
покупателю по правилу (период, день или условие), менеджер не напоминает об оплате.
> [!NOTE]
> Организациям адресована именно подписка, а не привязка карты: владелец карты всегда физлицо, и
> сотруднику пришлось бы отчитываться за расход перед бухгалтерией —
> [почему так](/docs/merchant/order/recurring/#почему-для-организаций-регулярность-устроена-иначе).
> Счёт по подписке удобно доставлять [Запросом о платеже](/docs/scenarios/rtp/) — прямо в банковское
> приложение покупателя.
### Проработанные интеграции
Готовые модули: [CMS](/docs/merchant/cms) (1С-Битрикс, WooCommerce, OpenCart и другие),
[ERP и CRM](/docs/merchant/erp), [платёжный виджет](/docs/merchant/widget) без разработки.
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# 🍽️ Системы автоматизации ресторанов
# Системы автоматизации ресторанов (CRM, ERP, RAS)
Корпоративный гость в зале ресторана хочет уйти с закрывающими документами, а не с чеком на
физлицо. Мини-приложение Инвойсбокс выставляет счёт на организацию прямо со стола — по QR-коду,
номер стола уходит в метаданные заказа, оплата подтверждается на месте, а акт и счёт-фактура
отправляются в бухгалтерию клиента по электронному документообороту.
> [!IMPORTANT]
> Выступая в качестве партнёра Инвойсбокс, оператор системы автоматизации ресторанов получает вознаграждение от оборота — [как оно считается](/docs/partner/#вознаграждение-партнёра).
## Базовая схема взаимодействия
### Подключение ресторана к Инвойсбоксу
В ERP-системе может быть реализована возможность подключения приёма оплаты через систему Инвойсбокс.
При выборе такой опции ERP-система сможет направить по API [приглашение](/docs/partner/integration/invite/)
для прохождения процедур регистрации ресторана в системе Инвойсбокс. Приглашение будет отправлено
представителю по электронной почте.
По завершении регистрации система Инвойсбокс направит представителю ресторана специальный
код активации. С помощью кода активации ERP-система сможет получить [параметры авторизации](/docs/partner/integration/activation/), необходимые для дальнейшего использования API.
### Оформление заказа и счёта на оплату
После активации функции приёма платежей в кассах ресторана размещается способ оплаты **Оплата по счёту для организаций и ИП**.
**Сценарий с участием официанта**
Гость желает рассчитаться за обед как организация или ИП, сообщает об этом официанту.
При выборе способа расчёта на кассе (оплата по счёту) ERP-система [формирует заказ](/docs/merchant/order/create/)
от имени ресторана в системе Инвойсбокс, передавая состав заказа для оформления счёта и отчётных документов
(например, актов).
Официант выносит гостю пречек с QR-кодом. В QR-коде кодируется ссылка для перехода на платёжный шлюз. Ссылку возвращает [создание заказа](/docs/merchant/order/create/) — поле `paymentUrl`.
Гость сканирует QR-код и подтверждает оплату в приложении Инвойсбокс или мобильном браузере. После оплаты
заказ считается закрытым, а в ERP-систему поступает
[уведомление о смене статуса](/docs/merchant/notification/status/).
Если счёт открыт заранее — гость заказывает в течение вечера, а сумма растёт, — вместо оплаты по пречеку
подойдёт [холдирование](/docs/scenarios/guarantee/): при открытии стола резервируется предполагаемая сумма
[заказом с холдированием](/docs/merchant/order/hold/), а по закрытию списывается фактический счёт.
Блокировка средств — не оплата: деньги остаются у гостя до списания.
**Сценарий без участия официанта**
Ресторан формирует для каждого стола специальный статичный QR-код. QR-код может быть размещён в информационном
тейбл тенте. За таким QR-кодом стоит мини-приложение: гость открывает его, видит текущий счёт стола, а система
автоматизации [создаёт заказ](/docs/merchant/order/create/) с номером стола в
[метаданных](/docs/merchant/order/metadata/) — по нему счёт находится и закрывается без участия официанта.
Гость желающий рассчитаться за обед как организация или ИП, сканирует QR-код. Система Инвойсбокс запрашивает по
номеру стола актуальную корзину заказа для оплаты в кассовой системе. Пользователь подтверждает оплату заказа,
стол закрывается.
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт ресторана, а оператору ERP-системы - вознаграждение.
## Размещение информации в маркетплейсе Инвойсбокс
Информация о ресторане или множестве ресторанов может быть опубликована в [маркетплейсе Инвойсбокс](/docs/marketplace).
Маркетплейс Инвойсбокс позволит привлечь дополнительный поток клиентов за счёт продвижения информации на ресурсах сервиса
и его партнёров.
При наличии веб-витрины ресторана в ERP-системе (например, доставка еды или бизнес-ланчей) форма заказа может быть
размещена в маркетплейсе в виде [мини-приложения](/docs/marketplace/mini-apps/), реализованного на стороне ERP-системы.
Для дополнительной информации см. [схему взаимодействия](/docs/marketplace/mini-apps/schema/).
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
---
# 🚆 B2B продажи ж/д билетов
# Автоматизация продаж ж/д билетов юридическим лицам и ИП (b2b)
У железной дороги свои правила: тайм-лимит брони короче авиационного, а сервисный сбор агентства
покупателю не возвращается. Оплата по счёту должна успеть в этот срок.
Инвойсбокс выставляет счёт организации сразу и подтверждает оплату до истечения тайм-лимита; акт и
счёт-фактура уходят клиенту по ЭДО после оплаты.
Что это даёт перевозчику:
- корпоративный клиент оплачивает билет по счёту, с отсрочкой или картой, не покидая сайт;
- деньги приходят на счёт на следующий рабочий день после подтверждения оплаты ([сроки](/docs/terms/));
- закрывающие документы формируются после оплаты и уходят клиенту по ЭДО;
- срок оплаты равен тайм-лимиту брони и задаётся полем `expirationDate` при [создании заказа](/docs/merchant/order/create/).
### Оплата бронирований с любым тайм-лимитом
Способы оплаты Инвойсбокс для организаций и ИП позволяют корпоративным клиентам оплачивать электронные
билеты с любым тайм-лимитом (от одной минуты), открывая возможность покупки билетов по промо- и бюджетным тарифам
так же, как при покупках с помощью банковской карты.
Постоянные корпоративные клиенты могут получить отсрочку до 30 дней, при этом перевозчик гарантированно
получает денежные средства на следующий рабочий день после подтверждения оплаты бронирования.
### Подтверждение за минуты и отчёты в своём формате
Подтверждение оплаты приходит перевозчику за считанные минуты — так же быстро, как при оплате картой,
поэтому короткий тайм-лимит не мешает продавать корпоративному клиенту по счёту
([платёжные инструменты](/docs/merchant/payment-instruments/)).
Отчёты приходят в том формате, который принят у перевозчика: состав полей и разбивку можно расширить
или собрать по его требованиям при подключении.
### Обработка возвратов
Сервис Инвойсбокс поддерживает как автоматизированное оформление возвратов, так и в ручном режиме через
личный кабинет. Денежные средства по возврату зачисляются клиенту до двух рабочих дней — срок зависит от способа оплаты.
### Автоматизированный документооборот
Отчётные документы для клиента формируются автоматически после подтверждения оплаты бронирования, а оригиналы
могут быть отправлены в бумажном виде по почте или [каналам ЭДО](/docs/merchant/documentflow/).
### Работа с динамическим ценообразованием
Схема интеграции предполагает возможность изменения стоимости бронирования до момента его оплаты. На каждом этапе
оплаты от формирования счёта до его оплаты негативные сценарии отрабатываются как автоматически с использованием
информирования клиента, так и с привлечением специалистов службы клиентской поддержки.
Штатные ситуации отрабатываются автоматически: клиент получает уведомление, а система бронирования —
[сообщение о смене статуса заказа](/docs/merchant/notification/status/). Специалист поддержки подключается
там, где автоматика бессильна: нестандартное оформление, спорная оплата, ручной возврат.
### Схема взаимодействия с клиентом
- После того, как заказ/бронь сформирована, клиент переходит на страницу выбора способа оплаты. Как правило, мы
предлагаем перевозчику разместить на сайте дополнительный способ "Оплата по счёту для организаций и ИП".
- Если клиент выбирает способ оплаты "Оплата по счёту для организаций и ИП", система бронирования передаёт в систему
Инвойсбокс состав заказа и данные бронирования для формирования счёта на оплату.
- В зависимости от тайм-лимита (TL) бронирования система автоматически формирует набор доступных способов оплаты.
Тайм-лимит у бронирования может быть любой.
- Если тайм-лимит короткий, оплату подтверждают до прихода денег: обещанным платежом (сумма счёта
блокируется на карте, счёт уходит организации на пять суток) или из гарантийного фонда — см.
[платёжные инструменты для B2B](/docs/merchant/payment-instruments/). Билет оформляется сразу вместе
со счётом.
- Если тайм-лимит свыше 24х часов, то ко всем возможностям, описанным выше, добавляется простой выпуск счёта с ожиданием
оплаты в течение суток.
- После получения подтверждения оплаты по счёту в течение срока действия бронирования, информация об оплате передаётся
в систему бронирования, происходит оформление билета и иных документов (например, при оплате дополнительных услуг).
- Все закрывающие документы оформляет и отправляет клиенту система Инвойсбокс. Важно, чтобы в билете был
выделен НДС. Никакой дополнительной нагрузки на бухгалтерию перевозчика, связанной с запуском нового способа оплаты, не возникает.
- Система бронирования может передавать информацию о возврате средств клиенту от перевозчика. Обычно после получения
уведомления от перевозчика деньги возвращаются до двух рабочих дней — срок зависит от способа оплаты.
## Чем железная дорога отличается от авиа
- **Короткий тайм-лимит.** Места в поезде удерживаются минутами, а не часами: пока корпоративный
клиент согласует счёт, бронь сгорает. Поэтому основной режим — оплата с подтверждением до прихода
денег: [обещанный платёж](/docs/merchant/payment-instruments/),
[подтверждение кодом](/docs/merchant/guarantee/) из гарантийного фонда или
[холдирование](/docs/scenarios/guarantee/). Билет оформляется сразу, деньги списываются после.
- **Сервисный сбор возвращается не всегда.** Возврат билета почти всегда частичный, и удержание
зависит от тарифа. Оформляйте [возврат с корректировкой](/docs/merchant/refund/correction/):
клиент получает разницу, а в закрывающих документах остаётся удержанная сумма.
- **Поездка редко бывает одна.** Командировка — это билеты туда и обратно, иногда с пересадками
и постельным бельём отдельной позицией. Чтобы бухгалтерия клиента получила один счёт вместо
четырёх, объедините заказы [контейнером](/docs/merchant/order/create-order-container/).
- **Номер заказа перевозчика** удобно передавать в [метаданных](/docs/merchant/order/metadata/) —
он вернётся в уведомлениях и попадёт в документы, по которым клиент сверяет поездки.
### Проработанные интеграции
Решение Инвойсбокс отработано с такими системами, как "Экспресс".
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
## Читайте также
- [Оформление возврата](/docs/merchant/refund/create/)
---
# 🏨 Управление средствами размещения (PMS)
# Cистемы управления гостиницами, отелями и хостелами (PMS)
Гость бронирует номер, а платит за него компания: командировку оформляет работодатель, и ему нужен счёт
с реквизитами, акт и счёт-фактура. Пока документы едут по почте, номер уже занят и выезд состоялся.
Инвойсбокс встраивает в систему управления оплату картой, через СБП и по счёту для организаций и ИП.
Физлицу уходит [фискальный чек по 54-ФЗ](/docs/merchant/fz54/), организации — отчётные документы через
ЭДО, курьером или почтой.
> [!IMPORTANT]
> Выступая в качестве партнёра Инвойсбокс, оператор PMS получает вознаграждение от оборота — [как оно считается](/docs/partner/#вознаграждение-партнёра).
## Подключение средств размещения к Инвойсбоксу
В системе PMS может быть реализован автоматическое подключение средства размещения и запуск приёма оплаты
через систему Инвойсбокс. При выборе такой опции система PMS направляет по API [приглашение](/docs/partner/integration/invite/)
для прохождения регистрации средства размещения в системе Инвойсбокс. Приглашение будет отправлено
представителю средства размещения по электронной почте.
По завершении регистрации система Инвойсбокс направит представителю средства размещения специальный
код активации. С помощью кода активации система PMS получит [параметры авторизации](/docs/partner/integration/activation/),
необходимые для дальнейшего использования API от имени средства размещения.
## Оформление заказа и счёта на оплату
После активации функции приёма платежей на странице выбора способа оплаты бронирования размещаются
опции выбора - **Оплата онлайн** и **Оплата по счёту для организаций и ИП**. В системе PMS может быть
отрегулировано отображение той или иной опции. С точки зрения API, регулирование опции происходит за
счёт передачи параметра - [тип плательщика](/docs/merchant/order/create/#customer).
При выборе опции оплаты система PMS [формирует заказ](/docs/merchant/order/create/) от имени средства размещения
в системе Инвойсбокс, передавая параметры бронирования в [специальных метаданных](/docs/merchant/order/metadata/#данные-бронирования-места-проживания),
а также даты заселения и выезда для корректного оформления отчётных документов (например, акта, УПД и пр.) и тип плательщика.
После успешного формирования заказа система PMS переадресует гостя на платёжную страницу системы Инвойсбокс для подтверждения
оплаты заказа.
Так выглядит заказ на проживание: состав — ночи и допуслуги, в метаданных — бронь, номер и даты,
по которым бухгалтерия гостя поймёт, за что заплатила.
``` json
{
"merchantId": "01f1c3f8-0000-0000-0000-000000000001",
"merchantOrderId": "PMS-2026-04817",
"amount": "24800.00",
"currencyId": "643",
"description": "Проживание, Гранд Отель Европа, 12–14 августа",
"expirationDate": "2026-08-10T18:00:00+03:00",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"vatNumber": "7701234560",
"email": "buh@example.invbox.ru"
},
"basketItems": [
{
"sku": "ROOM-DBL",
"name": "Двухместный номер, 2 ночи",
"quantity": 2,
"amount": "22000.00",
"vatCode": "RUS_VAT22",
"measure": "сут."
},
{
"sku": "BREAKFAST",
"name": "Завтрак",
"quantity": 4,
"amount": "2800.00",
"vatCode": "RUS_VAT22",
"measure": "шт."
}
],
"metaData": {
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "LodgingReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"checkinTime": "2026-08-12T14:00:00+03:00",
"checkoutTime": "2026-08-14T12:00:00+03:00"
}
]
}
}
```
Полный список полей брони — в [метаданных заказа](/docs/merchant/order/metadata/#данные-бронирования-места-проживания),
структура запроса целиком — на странице [создания заказа](/docs/merchant/order/create/).
После подтверждения оплаты заказа гость возвращается на страницу системы PMS, а система Инвойсбокс
асинхронно направляет [уведомление об оплате](/docs/merchant/notification), оплата бронирования подтверждается.
Гость получает ваучер или иной подтверждающий бронирование документ.
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт средства размещения, а оператору системы PMS - вознаграждение.
При выезде гостя из отеля, система PMS может [передать информацию](/docs/merchant/order/update/) об актуальной
стоимости проживая и дополнительных услугах, которые были предоставлены гостю. Актуальные сведения необходимы для
корректного формирования отчётных документов (в зависимости от типа плательщика).
В системе PMS могут быть также реализованы функции [отмены заказа](/docs/merchant/order/delete/) или
[оформления возврата](/docs/merchant/refund). Если отель удерживает часть суммы за поздний отказ,
возврат оформляется [с корректировкой](/docs/merchant/refund/correction/) — удержание остаётся
в закрывающих документах.
Акт, счёт-фактуру и УПД Инвойсбокс формирует сам и отправляет корпоративному гостю
[по каналам ЭДО](/docs/merchant/documentflow/) — отелю подключать оператора отдельно не нужно.
## Размещение информации в маркетплейсе Инвойсбокс
Информация о средстве или множестве средств размещения может быть опубликована в [маркетплейсе Инвойсбокс](/docs/marketplace).
Маркетплейс Инвойсбокс позволит привлечь дополнительный поток клиентов за счёт продвижения информации на ресурсах сервиса и
его партнёров.
Отдельным взаимодействием системы PMS и маркетплейса может быть [мини-приложение](/docs/marketplace/mini-apps/), реализованное и работающее на стороне системы PMS.
Мини-приложение представляет из себя форму заказа товаров или услуг в сервисе поставщика, которая открывается в маркетплейсе Инвойсбокс (веб или мобильное приложение) и взаимодействует с системой Инвойсбокс.
Мини-приложение сможет предлагать пользователям Инвойсбокс забронировать комнату или номер в качестве дополнительной услуги к основному заказу, например, при покупке авиабилета.
Для дополнительной информации см. [схему взаимодействия](/docs/marketplace/mini-apps/schema/).
> Если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы будем рады вам помочь!
---
# ⛽ B2B продажи на АЗС
# Сценарий продажи топлива и дополнительных услуг на АЗС
Топливо отпускают до того, как известна сумма: заправка идёт по лимиту талона, а платит клиент за
фактический налив. Инвойсбокс выставляет счёт на лимит у колонки или на кассе, а после налива заказ
пересчитывается на фактическую сумму — организация получает один счёт и закрывающие документы, без
авансовых отчётов и бумажных талонов.
> [!IMPORTANT]
> Выступая в качестве партнёра Инвойсбокс, оператор приложения или системы автоматизации АЗС получает
> вознаграждение от оборота — [как оно считается](/docs/partner/#вознаграждение-партнёра).
Водитель не ждёт у колонки: подтверждение оплаты приходит на кассу за минуты, как при оплате картой
([платёжные инструменты](/docs/merchant/payment-instruments/)).
## Базовая схема взаимодействия
### Реализация мини-приложения
На стороне системы АЗС формируется [мини-приложение](/docs/marketplace/mini-apps). В мини-приложении
реализуются следующие функции (экраны):
- Экран поиска АЗС (список или карта, опционально)
- Экран детальной информации по АЗС и форма заказа - выбор типа топлива, номера колонки, объёма и перечень доп. услуг (или товаров)
- Опционально, другие экраны в соответствии с процессами покупки в рамках АЗС или сети АЗС
- Экран подтверждения заказа
- Функция создания заказа в системе Инвойсбокс
- Экран успешного подтверждения оплаты заказа
Информация об АЗС или множестве АЗС публикуется в [маркетплейсе Инвойсбокс](/docs/marketplace).
Для получения дополнительной информации см. также [описание работы мини-приложения](/docs/marketplace/mini-apps/description/) с
мини-приложением.
### Оформление заказа и счёта на оплату
**Сценарий без участия оператора (автомат)**
Клиент в приложении Инвойсбокс находит подходящую АЗС или приложение подсказывает пользователю ближайшую АЗС
на основе его геопозиции. Приложение Инвойсбокс инициализирует мини-приложение АЗС, покупатель оформляет заказ
в мини-приложении и подтверждает его оплату. По факту подтверждения оплаты заказа, покупатель производит заправку
автомобиля или получает товары/услуги.
**Сценарий с участием оператора**
Клиент желает рассчитаться за топливо, товары или услуги как организация или ИП, сообщает об этом оператору АЗС на
кассе.
При выборе способа расчёта на кассе (оплата по счёту) ERP-система [формирует заказ](/docs/merchant/order/create/)
от имени АЗС в системе Инвойсбокс, передавая состав заказа для оформления счёта и отчётных документов
(например, актов).
Оператор передаёт клиенту пречек с QR-кодом. В QR-коде кодируется ссылка для перехода на платёжный шлюз. Ссылку возвращает [создание заказа](/docs/merchant/order/create/) — поле `paymentUrl`.
Клиент сканирует QR-код и подтверждает оплату в приложении Инвойсбокс или мобильном браузере. После успешного подтверждения
оплаты, заказ считается оплаченным, а в ERP-систему поступает [уведомление об оплате](/docs/merchant/notification).
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт юридического лица АЗС, а оператору ERP-системы - вознаграждение.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
## Читайте также
- [Открывайте заказ с холдированием на предельную сумму](/docs/merchant/order/hold/)
---
# 🚕 B2B продажи такси и трансфера
# Сценарий продажи услуг такси и трансфера пассажиров
Корпоративные поездки неудобны обеим сторонам: сумма известна только после поездки, а счетов за
месяц набирается несколько десятков. Инвойсбокс закрывает и то, и другое: сумму можно зарезервировать
на карте и списать по факту, а месячные поездки собрать в один счёт заказом-контейнером — бухгалтерия
клиента получает один документ вместо тридцати.
## Базовая схема взаимодействия
### Реализация мини-приложения
На стороне системы бронирования услуг такси или трансфера формируется [мини-приложение](/docs/marketplace/mini-apps).
В мини-приложении реализуются следующие функции (экраны):
- Экран выбора пункта отправления/назначения (список или карта, опционально)
- Экран детальной информации о поездке (пункт назначения, тариф, расстояние и пр.) и форма заказа
- Опционально, другие экраны в соответствии с процессами покупки в рамках системы бронирования
- Экран подтверждения заказа
- Функция создания заказа в системе Инвойсбокс
- Экран успешного подтверждения оплаты заказа
Информация о службе такси или трансфера публикуется в [маркетплейсе Инвойсбокс](/docs/marketplace).
Для получения дополнительной информации см. также [описание работы мини-приложения](/docs/marketplace/mini-apps/description/) с
мини-приложением.
### Оформление заказа и счёта на оплату
Клиент, на платёжной странице, в процессе оформления авиа- или ж/д- перевозки или в приложении Инвойсбокс, изъявляет
желание добавить к заказу услугу такси или трансфера. Платёжная страница или приложение Инвойсбокс инициализирует мини-приложение
системы бронирования такси или трансфера. Мини-приложение системы бронирования может подсказать подходящие параметры исходя из
пункта отправления/назначения. Покупатель оформляет заказ в мини-приложении и подтверждает его оплату. По факту
подтверждения оплаты заказа, покупатель получает ваучер на услугу или саму услугу.
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт юридического лица оператора услуг такси или трансфера.
## Расчёт по факту поездки
Стоимость поездки известна только на финише: маршрут изменился, клиент попросил заехать по пути,
добавилось время ожидания. Выставлять счёт заранее — значит каждый раз доначислять или возвращать.
Для этого есть [холдирование](/docs/scenarios/guarantee/): при подаче машины резервируется
максимальная стоимость маршрута — [заказ с холдированием](/docs/merchant/order/hold/), — а по
завершении поездки списывается фактическая сумма. Разница освобождается на карте клиента сама,
отдельный возврат не нужен.
Для корпоративных клиентов с регулярными поездками удобнее не резервировать каждый раз, а собирать
поездки за период в один счёт: заказы группируются
[заказом-контейнером](/docs/merchant/order/create-order-container/), и бухгалтерия клиента получает
один документ вместо тридцати.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
---
# ⭐ B2B продажи бизнес-залов
# Сценарий продажи услуг бизнес-залов
Доступ в бизнес-зал покупают и заранее, вместе с билетом, и на стойке за минуту до вылета — а
компания-плательщик в обоих случаях ждёт счёт и закрывающие документы. Инвойсбокс закрывает оба
пути: оплату можно подтвердить онлайн в момент оформления билета или на месте через
мини-приложение, документы уходят в бухгалтерию клиента по электронному документообороту.
Скорость здесь решает: пассажир стоит у стойки, и подтверждение оплаты приходит оператору за минуты —
столько же, сколько занимает оплата картой ([платёжные инструменты](/docs/merchant/payment-instruments/)).
Комиссию можно оставить оператору, разделить с пассажиром или переложить на его компанию —
[кто платит комиссию](/docs/terms/#кто-платит-комиссию).
## Базовая схема взаимодействия
### Реализация мини-приложения
На стороне системы бронирования бизнес-зала формируется [мини-приложение](/docs/marketplace/mini-apps).
В мини-приложении реализуются следующие функции (экраны):
- Экран выбора пункта отправления/назначения (список или карта, опционально)
- Экран детальной информации о бизнес-зале и форма заказа
- Опционально, другие экраны в соответствии с процессами покупки в рамках системы бронирования
- Экран подтверждения заказа
- Функция создания заказа в системе Инвойсбокс
- Экран успешного подтверждения оплаты заказа
Информация о бизнес-зале или множестве залов публикуется в [маркетплейсе Инвойсбокс](/docs/marketplace).
Для получения дополнительной информации см. также [описание работы мини-приложения](/docs/marketplace/mini-apps/description/) с
мини-приложением.
### Оформление заказа и счёта на оплату
**Сценарий онлайн оплаты услуги**
Клиент, на платёжной странице, в процессе оформления авиа- или ж/д- перевозки или в приложении Инвойсбокс, изъявляет
желание добавить к заказу услугу бизнес-зала. Платёжная страница или приложение Инвойсбокс инициализирует мини-приложение
системы бронирования бизнес-зала. Мини-приложение системы бронирования может подсказать подходящий бизнес-зал исходя из
пункта отправления/назначения. Покупатель оформляет заказ в мини-приложении и подтверждает его оплату. По факту
подтверждения оплаты заказа, покупатель получает ваучер на услугу или саму услугу.
**Сценарий с участием представителя (на месте)**
Клиент желает рассчитаться за услуги бизнес-зала как организация или ИП, сообщает об этом представителю на месте.
При выборе способа расчёта на кассе (оплата по счёту) ERP-система (или система бронирования) [формирует заказ](/docs/merchant/order/create/)
от имени оператора бизнес-зала в системе Инвойсбокс, передавая состав заказа для оформления счёта и отчётных документов
(например, актов).
Представитель передаёт клиенту пречек с QR-кодом. В QR-коде кодируется ссылка для перехода на платёжный шлюз. Ссылку возвращает [создание заказа](/docs/merchant/order/create/) — поле `paymentUrl`.
Клиент сканирует QR-код и подтверждает оплату в приложении Инвойсбокс или мобильном браузере. После успешного подтверждения
оплаты, заказ считается оплаченным, а в ERP-систему поступает [уведомление об оплате](/docs/merchant/notification).
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт юридического лица оператора бизнес-зала.
## Что происходит после оплаты
- Оператор бизнес-зала получает [уведомление об оплате](/docs/merchant/notification/status/) —
по нему ваучер активируется, а гостя пускают в зал без ожидания подтверждения от бухгалтерии.
- Если гость воспользовался не всеми услугами или не пришёл вовсе, состав уточняется
[изменением заказа](/docs/merchant/order/update/) до закрытия документов.
- Неиспользованный визит возвращается [возвратом](/docs/merchant/refund/create/);
при удержании по тарифу — [возвратом с корректировкой](/docs/merchant/refund/correction/).
- Закрывающие документы уходят корпоративному клиенту
[по ЭДО](/docs/merchant/documentflow/) — акт и счёт-фактуру оператору формировать не нужно.
Гостям, которые пользуются залами регулярно, подойдёт
[холдирование](/docs/scenarios/guarantee/): сумма резервируется при бронировании, а списывается
фактическое обслуживание — с допуслугами, если они были.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
---
# ☂️ B2B продажи услуг страхования пассажиров
# Сценарий продажи услуг страхования пассажиров
Полис продаётся вместе с билетом и возвращается вместе с ним же — с удержанием части премии по
правилам страховщика. Инвойсбокс позволяет продать страховку тем же заказом, что и билет, а при
отказе оформить частичный возврат: клиент-организация видит одну операцию и получает документы по
электронному документообороту.
## Базовая схема взаимодействия
### Реализация мини-приложения
На стороне учётной системы страховых услуг формируется [мини-приложение](/docs/marketplace/mini-apps).
В мини-приложении реализуются следующие функции (экраны):
- Экран детальной информации о страховании поездки и форма заказа
- Опционально, другие экраны в соответствии с процессами покупки в рамках системы страхования
- Экран подтверждения заказа
- Функция создания заказа в системе Инвойсбокс
- Экран успешного подтверждения оплаты заказа
Информация об услуге страхования публикуется в [маркетплейсе Инвойсбокс](/docs/marketplace).
Для получения дополнительной информации см. также [описание работы мини-приложения](/docs/marketplace/mini-apps/description/) с
мини-приложением.
### Оформление заказа и счёта на оплату
Клиент, на платёжной странице, в процессе оформления авиа- или ж/д- перевозки или в приложении Инвойсбокс, изъявляет
желание добавить к заказу услугу страхования. Платёжная страница или приложение Инвойсбокс инициализирует мини-приложение
системы страхования. Мини-приложение может подсказать подходящие параметры исходя из данных основного заказа.
Покупатель оформляет заказ в мини-приложении и подтверждает его оплату. По факту подтверждения оплаты заказа, покупатель
получает ваучер на услугу.
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт юридического лица оператора услуг страхования.
## Возврат страховки
Полис возвращают чаще, чем билет: пассажир отказался от перелёта, страховка оказалась дублем
корпоративной, изменились даты. Возврат оформляется
[методом возврата](/docs/merchant/refund/create/) — полностью или частично, если страховая
удерживает часть премии за прошедший период.
Когда удержание есть, используйте
[возврат с корректировкой](/docs/merchant/refund/correction/): клиенту уходит разница, а в
закрывающих документах остаётся фактически оказанная услуга. Состав возврата, доступный к оформлению,
можно получить [запросом позиций заказа](/docs/merchant/refund/get/) — так не придётся считать
остаток на своей стороне.
О каждом шаге система страховщика узнаёт из
[уведомления о смене статуса](/docs/merchant/notification/status/).
## Страховка вместе с билетом
Страховка почти никогда не продаётся отдельно. Чтобы у корпоративного клиента не появлялось
несколько счетов на одну поездку, объедините билет, страховку и допуслуги
[заказом-контейнером](/docs/merchant/order/create-order-container/): оплата одна, документы —
по каждой услуге.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
## Читайте также
- [Основной заказ описан в кейсе продажи авиабилетов](/docs/scenarios/air-carriers/)
---
# 📦 Аренда складов, офисов и коворкингов
# Автоматизация оплат за аренду складов, офисов и коворкингов организациям и ИП (b2b)
Арендатор платит одну и ту же сумму каждый месяц, и каждый месяц кто-то вручную выставляет ему счёт, а
потом сверяет оплату с выпиской. К этому добавляются доначисления: уборка, парковка, переработка по
времени.
Инвойсбокс убирает ручные шаги: счёт уходит арендатору по правилу, оплата возвращается уведомлением, а
акт за период формируется сам.
Что это даёт арендодателю:
- арендатор платит по счёту, с отсрочкой до 30 дней или по [подписке](/docs/merchant/order/recurring/);
- деньги приходят на счёт на следующий рабочий день после подтверждения оплаты ([сроки](/docs/terms/));
- акт и счёт-фактура за период формируются автоматически и уходят по ЭДО;
- срок оплаты счёта задаётся полем `expirationDate` при [создании заказа](/docs/merchant/order/create/).
### Оплата аренды с любым сроком
Способы оплаты Инвойсбокс для организаций и ИП позволяют корпоративным клиентам оплачивать услуги аренды
с любым сроком оплаты (от одной минуты), открывая возможность экстренного оформления или продления услуги.
Срок задаётся полем `expirationDate` при [создании заказа](/docs/merchant/order/create/): по его истечении
неоплаченный счёт можно [отменить](/docs/merchant/order/delete/) и освободить помещение под следующего клиента.
Постоянные корпоративные клиенты могут получить отсрочку до 30 дней, при этом арендодатель гарантированно
получает денежные средства на следующий рабочий день после подтверждения оплаты.
### Регулярные платежи за аренду
Аренда — это оплата каждый месяц в одну и ту же дату, и напоминать о ней менеджеру не нужно.
Подписка закрывает ежемесячную арендную плату и коммунальные услуги: счёт уходит арендатору по
правилу — в нужный день или по условию, — а документы формируются по ЭДО.
> [!NOTE]
> Арендатору-организации адресована подписка, а не привязка карты: карта всегда оформлена на человека,
> и сотруднику пришлось бы объяснять расход бухгалтерии —
> [чем подписка отличается от рекуррентов](/docs/merchant/order/recurring/#почему-для-организаций-регулярность-устроена-иначе).
> Доставить счёт удобно [Запросом о платеже](/docs/scenarios/rtp/): он приходит в банковское приложение,
> оплата в один шаг.
Разовые доначисления — уборка, парковочное место, переработка по времени — оформляются отдельным заказом
или [изменением текущего](/docs/merchant/order/update/) до его оплаты.
Тем, кто платит не картой, а по счёту, удобнее [Запрос о платеже](/docs/scenarios/rtp): уведомление
приходит прямо в банковское приложение арендатора.
### Обработка возвратов
Сервис Инвойсбокс поддерживает как автоматизированное оформление возвратов, так и в ручном режиме через
личный кабинет. Денежные средства по возврату зачисляются арендатору до двух рабочих дней — срок зависит от способа оплаты.
### Автоматизированный документооборот
Отчётные документы для арендатора формируются автоматически после подтверждения оплаты, а оригиналы
могут быть отправлены в бумажном виде по почте или [через ЭДО](/docs/merchant/documentflow/).
### Схема взаимодействия с арендатором
- После того, как услуга оформлена, клиент переходит на страницу выбора способа оплаты. Как правило, мы
предлагаем арендодателю разместить на сайте дополнительный способ: "Оплата по счёту для организаций и ИП".
- Если клиент выбирает способ оплаты "Оплата по счёту для организаций и ИП", система управления складом передаёт в систему
Инвойсбокс состав заказа и данные для формирования счёта на оплату.
- Инвойсбокс позволяет формировать шаблоны счетов, которые могут автоматически направляться в виде ссылки для оплаты
арендатору по электронной почте, SMS или в мессенджер.
- В зависимости от срока оплаты счёта, система автоматически формирует набор доступных способов оплаты.
Срок оплаты может быть любой.
- Если срок оплаты короткий, подойдут инструменты с подтверждением до прихода денег — обещанный
платёж и гарантийный фонд ([платёжные инструменты для B2B](/docs/merchant/payment-instruments/)) —
или способы с мгновенным подтверждением: СБП, Запрос о платеже, оплата через банк-клиент (Альфа-Бизнес
Онлайн, СберБизнес, Т-Бизнес и другие).
- Если срок оплаты свыше 24х часов, то ко всем возможностям, описанным выше, добавляется простой выпуск счёта с ожиданием
оплаты в течение суток банковским переводом.
- После получения подтверждения оплаты по счёту, информация об оплате передаётся в систему арендодателя, происходит оформление услуги
и иных документов (например, при оплате дополнительных услуг).
- Все закрывающие документы оформляет и отправляет клиенту система Инвойсбокс. Никакой дополнительной нагрузки на бухгалтерию арендодателя,
связанной с запуском нового способа оплаты, не возникает.
### Свяжитесь с нами
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# ☁️ Подписки на сервисы для юрлиц (SaaS, хостинг, телеком)
# Подписки на сервисы для организаций и ИП (SaaS, хостинг, телеком)
Продавать подписку физлицу просто: карта привязана, списание идёт само. С организацией так не выходит.
Бухгалтерия платит по счёту, деньги идут через банк, и каждый месяц повторяется одна и та же работа:
выставить счёт, дождаться перевода, свести оплату с лицевым счётом, отправить акт. Пока перевод идёт,
сервис или отключается раньше времени, или работает в долг.
Инвойсбокс закрывает этот цикл: счёт уходит покупателю сам, оплата подтверждается за минуты или
секунды — в зависимости от [платёжного инструмента](/docs/merchant/payment-instruments/), — а акт и
счёт-фактура за период формируются без участия менеджера.
## Подписка для юрлица — это счёт по правилу, а не привязка карты
> [!IMPORTANT]
> Списание по сохранённой карте работает, но владелец карты — всегда физлицо: даже корпоративная карта
> оформлена на сотрудника, и расход придётся объяснять бухгалтерии — чек, обоснование, авансовый отчёт.
> Поэтому организациям адресована подписка: счёт уходит компании по правилу —
> [чем это отличается от рекуррентов](/docs/merchant/order/recurring/#почему-для-организаций-регулярность-устроена-иначе).
Правило задаёт период, конкретный день или условие — например, снижение баланса до порога. Собрать
подписку можно двумя способами:
- **расписание держит ваша система.** На каждый оплачиваемый период она
[создаёт заказ](/docs/merchant/order/create/) со сроком оплаты и составом по тарифу — биллинг и так
знает, когда у клиента заканчивается период. Инвойсбокс берёт на себя счёт, приём оплаты и документы.
- **расписание держит подписка.** Заказ-подписка создаётся один раз с параметрами периода и условий,
клиент подписывается на неё, и счета уходят ему сами. Параметры настраиваются при подключении —
публичного описания полей пока нет, состав правил уточняйте в
[поддержке](https://www.invoicebox.ru/ru/contacts).
Дальше в кейсе разобран первый способ: он не требует ничего, кроме обычного создания заказа.
Так выглядит счёт за месяц по тарифу. Номер договора и период попадают в `merchantOrderId` и
`description` — по ним бухгалтерия клиента поймёт, за что платит, а вы найдёте оплату в своей системе.
``` json
{
"merchantId": "01f1c3f8-0000-0000-0000-000000000001",
"merchantOrderId": "SUB-4417-2026-08",
"amount": "48000.00",
"currencyId": "643",
"description": "Тариф «Команда», август 2026, договор 4417",
"expirationDate": "2026-08-05T23:59:00+03:00",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"vatNumber": "7701234560",
"email": "buh@example.invbox.ru"
},
"basketItems": [
{
"sku": "TEAM-30",
"name": "Тариф «Команда», 30 рабочих мест, август 2026",
"quantity": 1,
"amount": "48000.00",
"vatCode": "RUS_VAT22",
"measure": "мес."
}
]
}
```
В позиции корзины можно передать [данные подписки](/docs/merchant/order/metadata/#данные-подписки) —
объект `PaymentPlan` с периодом биллинга, датами начала и окончания договора и ценой. Тогда счёт несёт
не только сумму, но и условия: бухгалтерия клиента видит, за какой период и по какому договору платит.
Что происходит дальше:
1. Клиент получает счёт и оплачивает его — из своего банка, по
[Запросу о платеже](/docs/scenarios/rtp/) в приложении банка или подтверждением из гарантийного
фонда за секунды. Способ определяется договором и настройками в кабинете, запрос при этом одинаковый.
2. Инвойсбокс сообщает об оплате [уведомлением о смене статуса](/docs/merchant/notification/status/) —
ваш сервис продлевает период по этому сигналу, а не по факту прихода денег на счёт.
3. Акт и счёт-фактура за период уходят клиенту [через ЭДО](/docs/merchant/documentflow/) или на бумаге.
4. Деньги приходят на расчётный счёт на следующий рабочий день после подтверждения оплаты —
[сроки и условия](/docs/terms/).
## Срок оплаты и мягкое отключение
Поле `expirationDate` задаёт, до какого момента счёт живёт. Для подписки это удобно: счёт на следующий
месяц выставляется, скажем, за пять дней до его начала, и до этой даты клиент платит по прежней ссылке.
Когда срок проходит, заказ получает состояние `expired` — оплатить старую ссылку нельзя, нужен новый
заказ.
Отсюда же берётся политика отключения. Пока счёт не оплачен, сервис работает или не работает по вашим
правилам; Инвойсбокс лишь сообщает, оплачен счёт или нет. Неоплаченный счёт, который потерял смысл
(клиент сменил тариф или ушёл), [отменяется](/docs/merchant/order/delete/) до оплаты — в списке
клиента он не останется висеть.
Если клиент готов платить, но не успевает провести перевод, помогает
[обещанный платёж](/docs/merchant/payment-instruments/): покупатель подтверждает заказ картой за
минуту, вы продлеваете период сразу, а счёт организация оплачивает в течение пяти суток.
## Смена тарифа и доначисления сверх пакета
Подписка редко стоит одинаково весь год: клиент добавляет рабочие места, выходит за лимит трафика,
берёт дополнительный номер или диск. Есть два пути, и выбор зависит от того, оплачен ли текущий счёт.
- **Счёт ещё не оплачен** — [измените заказ](/docs/merchant/order/update/): состав и сумма
пересчитываются, ссылка остаётся прежней. Так удобно поправить тариф, о котором договорились уже
после выставления счёта.
- **Счёт оплачен** — доначисление оформляется отдельным заказом за тот же период. Прежний счёт и
документы по нему остаются неизменными, а бухгалтерия клиента видит два понятных документа вместо
одного исправленного.
Если период уже закрыт документами, а сумму нужно уменьшить — например, клиент оплатил тридцать
рабочих мест, а пользовался двадцатью, — это [возврат с корректировкой](/docs/merchant/refund/correction/):
возвращается часть суммы, а корректировочный документ уходит клиенту вслед за возвратом.
## Много клиентов — много счетов: как не потеряться
Телеком и хостинг выставляют счета сотнями, и главный вопрос к системе — не «как создать заказ», а
«как свести реестр». Для этого достаточно двух вещей:
- **Свой номер в каждом заказе.** `merchantOrderId` вида `SUB-4417-2026-08` — договор и период. По нему
[заказ находится](/docs/merchant/order/get/) без сохранения идентификаторов Инвойсбокса.
- **Выборки по состоянию и датам.** Список неоплаченных счетов с истекающим сроком собирается
[фильтрами](/docs/api/filters/): `status=created` и условие по `expirationDate`. Ночная сверка по
такому запросу заменяет обзвон клиентов.
Обработчик уведомлений стоит сделать идемпотентным: одно и то же уведомление может прийти дважды, и
период не должен продлеваться два раза — [как проверить свой обработчик](/docs/merchant/notification/status/).
## Что это даёт
- Клиент-организация платит привычным способом, а сервис продлевается по сигналу об оплате, а не через
два-три банковских дня.
- Счёт, акт и счёт-фактура за период формируются сами и уходят по ЭДО — менеджеру остаются только
спорные случаи.
- Отсрочку и риск неплатежа можно отдать платформе: постоянный клиент подтверждает оплату сразу, а
рассчитывается в течение 30 дней — [платёжные инструменты](/docs/merchant/payment-instruments/).
- Физлица закрываются тем же вендором: для них работают и
[списание по сохранённой карте](/docs/merchant/order/recurring/), и
[чек по 54-ФЗ](/docs/merchant/fz54/).
## Чем подключиться
| Путь | Когда подходит |
|---|---|
| [API и PHP SDK](/docs/merchant/) | биллинг сервиса ведёт расписание сам — обычный случай для SaaS и телекома |
| [Готовый модуль](/docs/merchant/cms/) | тарифы продаются на сайте: 1С-Битрикс, Тильда, WooCommerce и другие |
| [Платёжный виджет](/widgets/) | нужно принять оплату за подписку сегодня, до доработки биллинга |
| [ИИ-агент](/for-agents/) | интеграцию делает Cursor или Claude Code по одному промпту |
## Смежные кейсы
- [Аренда складов, офисов и коворкингов](/docs/scenarios/warehouses/) — та же регулярность, но с
привязкой к сроку договора.
- [B2B продажи 24/7](/docs/scenarios/b2b-sales/) — четыре вызова базового сценария.
- [Запрос о платеже](/docs/scenarios/rtp/) — счёт приходит клиенту в приложение банка.
Посмотреть, как выглядит выставленный счёт и уведомление об оплате, можно в демо
[Счёт юрлицу из CRM](/demo/crm/) — вызовы уходят на демо-контур.
---
---
# 🧾 Автоматизация дебиторки: счёт, оплата, закрытие
# Автоматизация дебиторки: от счёта до закрывающих документов
Дебиторка отнимает время не там, где её считают, а там, где её ведут вручную. Менеджер выставляет счёт
в учётной системе, выгружает его в PDF, отправляет письмом, отмечает в таблице, через неделю звонит
напомнить, ищет платёж в выписке, сводит сумму, отправляет акт. Ошибка на любом шаге превращается в
неоплаченный счёт, о котором никто не помнит.
Инвойсбокс убирает из этой цепочки ручные шаги: счёт уходит покупателю автоматически, оплата
возвращается в учётную систему уведомлением, а закрывающие документы формируются по факту оплаты.
Реестр перестаёт быть таблицей, которую кто-то поддерживает, и становится состоянием заказов.
## Как выглядит цикл
1. **Счёт рождается в вашей системе.** Реализация в 1С, закрытая сделка в CRM, отгрузка в ERP —
в этот момент система [создаёт заказ](/docs/merchant/order/create/) с типом плательщика `legal`,
составом и сроком оплаты в `expirationDate`.
2. **Счёт уходит покупателю.** По ссылке `paymentUrl`, письмом от Инвойсбокса или прямо в приложение
банка — [Запросом о платеже](/docs/scenarios/rtp/). Отправлять вложением из почты менеджера больше
не нужно.
3. **Покупатель платит удобным ему способом.** Классический перевод, ускоренная оплата в один шаг из
интернет-банка, подтверждение из гарантийного фонда за секунды —
[пять инструментов](/docs/merchant/payment-instruments/) отличаются только тем, как быстро приходит
подтверждение.
4. **Оплата возвращается в учётную систему.** Инвойсбокс присылает
[уведомление о смене статуса](/docs/merchant/notification/status/); ваш обработчик закрывает
задолженность по `merchantOrderId`. Ждать выписку и сверять платёжки по назначению платежа не нужно.
5. **Документы уходят сами.** Акт, счёт-фактура и УПД формируются по факту оплаты и отправляются
[через ЭДО](/docs/merchant/documentflow/), почтой или курьером.
6. **Деньги приходят на расчётный счёт** на следующий рабочий день после подтверждения оплаты —
[сроки](/docs/terms/).
## Реестр вместо таблицы
Состояние каждого счёта живёт в Инвойсбоксе, и его можно получить запросом — отдельный учёт вести
не нужно.
| Что нужно бухгалтерии | Как получить |
|---|---|
| Что оплачено за период | [заказы](/docs/merchant/order/get/) с фильтром `status=completed` и условием по дате |
| Что ждёт оплаты | `status=created` — счёт выставлен, срок ещё не прошёл |
| Что просрочено | `status=expired`: срок из `expirationDate` прошёл, по прежней ссылке не оплатить |
| Что отменено | `status=canceled` — счёт [снят](/docs/merchant/order/delete/) до оплаты |
Условия по датам, сортировки и постраничный вывод — в разделе [фильтров](/docs/api/filters/). Ночная
выборка неоплаченных счетов с истекающим сроком заменяет обзвон: система сама напоминает тем, у кого
срок на исходе.
Два правила, без которых сверка ломается:
- **Свой номер в каждом заказе.** `merchantOrderId` — номер счёта или договора из вашей системы. По нему
вы находите заказ и закрываете задолженность, не храня идентификаторы Инвойсбокса.
- **Идемпотентный обработчик.** Одно и то же уведомление может прийти дважды; повторная обработка не
должна закрывать задолженность второй раз — [как проверить обработчик](/docs/merchant/notification/status/).
## Счета, которые оплачивают мимо Инвойсбокса
У большинства продавцов часть покупателей платит напрямую на расчётный счёт: так сложилось, так
записано в договоре. Держать из-за них вторую систему учёта не обязательно.
Заказ можно создать [не процессинговым](/docs/merchant/order/non-processable-order/) — с флагом
`processable = false`. Денег по нему Инвойсбокс не проводит, но счёт живёт в общем реестре, а отметку об
оплате вы ставите сами [сменой статуса](/docs/merchant/order/order-status-update/), когда увидели
платёж в выписке. Реестр остаётся один, и «дебиторка» в отчёте совпадает с реальностью.
> [!NOTE]
> Смена статуса работает только для не процессинговых заказов. У обычных заказов состояние меняет сам
> Инвойсбокс по факту движения денег — вручную его переставить нельзя, и это защищает отчётность.
## Обратная сторона: оплата счетов из фонда
Если вы автоматизируете не выставление счетов, а их оплату — например, делаете корпоративный кабинет
или сервис снабжения, — работает [Инвойсбокс.Бизнес](/docs/business/). Покупатель держит гарантийный
фонд и в его пределах подтверждает оплату сразу, не дожидаясь банковского перевода; сверх фонда даётся
отсрочка.
Два метода закрывают этот процесс: [получение счёта](/docs/business/get/) — список счетов и их
состояние, и [подтверждение оплаты](/docs/business/confirm_payment/) — оплата счёта из фонда с вашим
`partnerOperationId`, чтобы повторный вызов не создал второй платёж.
## Что это даёт
- Задолженность закрывается в момент подтверждения оплаты, а не после сверки выписки.
- Счёт доходит до покупателя по каналу, которым он пользуется: банковское приложение, письмо, ссылка.
- Просроченные счёта видны запросом, а не по памяти менеджера.
- Закрывающие документы уходят без участия людей — [документооборот](/docs/merchant/documentflow/).
- Риск неплатежа и отсрочку можно передать платформе: деньги приходят в обычный срок —
[инструменты](/docs/merchant/payment-instruments/).
## Чем подключиться
| Путь | Когда подходит |
|---|---|
| [Модуль CRM](/docs/merchant/crm/) | счета выставляют менеджеры: amoCRM, retailCRM, SportCRM |
| [Модуль ERP или PMS](/docs/merchant/erp/) | счёт рождается в учётной системе: iiko, Bnovo |
| [API и PHP SDK](/docs/merchant/) | своя учётная система или доработанная 1С |
| [Готовый модуль CMS](/docs/merchant/cms/) | заказы приходят с сайта |
## Смежные кейсы
- [B2B продажи товаров](/docs/scenarios/retail/) — отгрузка партиями и возврат с корректировкой.
- [Подписки для юрлиц](/docs/scenarios/saas/) — счёт на каждый период и доначисления.
- [Запрос о платеже](/docs/scenarios/rtp/) — счёт в приложении банка покупателя.
Как это выглядит со стороны менеджера, показывает демо [Счёт юрлицу из CRM](/demo/crm/): счёт
выставляется настоящим вызовом на демо-контур, статус меняется, уведомление приходит.
---
---
# 🛒 Маркетплейс и сплит-корзина
# Маркетплейс и сплит-корзина: одна оплата, несколько продавцов
Площадка, которая продаёт чужой товар, живёт в противоречии. Покупателю нужен один счёт: он собрал
корзину из товаров трёх поставщиков и не хочет платить трижды. Продавцам нужно обратное — своя выручка
на свой расчётный счёт и свои закрывающие документы от своего юрлица. Если площадка собирает деньги на
себя, она становится посредником со всеми последствиями: налоги, документы, ответственность за товар,
который никогда не видела.
Инвойсбокс разделяет одно от другого: покупатель платит один раз, а платёж расходится по продавцам,
каждый из которых остаётся продавцом в документах.
## Как выглядит цикл
1. **Поставщики подключаются к площадке.** Площадка отправляет
[приглашение](/docs/partner/integration/invite/) по API — поставщик проходит регистрацию сам, а по
её завершении площадка получает [параметры доступа](/docs/partner/integration/activation/), чтобы
создавать заказы от его имени. Собирать документы поставщиков вручную не нужно.
2. **Корзина превращается в группу заказов.** Один вызов
[создания группы заказов](/docs/merchant/order/create-order-container/) — и внутри столько заказов,
сколько в корзине продавцов. У каждого свой `merchantId`, свой состав и свои ставки НДС; покупатель
видит один номер счёта, который вы передаёте в `merchantOrderIdVisible`.
3. **Покупатель платит один раз** — по счёту, из интернет-банка в один шаг или подтверждением из
гарантийного фонда, [чем инструменты отличаются](/docs/merchant/payment-instruments/).
4. **Каждый заказ живёт своей жизнью.** Уведомления о смене статуса приходят по каждому заказу
отдельно — площадка узнаёт, что оплачено, и запускает сборку и доставку.
5. **Отгрузка и документы — от каждого продавца.** Товар доезжает партиями, отгрузки оформляются
[по каждому заказу](/docs/merchant/order/shipment_create/), а закрывающие документы уходят
покупателю [через ЭДО](/docs/merchant/documentflow/) от лица продавца.
6. **Возврат затрагивает только своего продавца.** Не привезли шкаф — [возврат](/docs/merchant/refund/create/)
идёт по заказу мебельного поставщика, а техника и доставка остаются оплаченными.
## Кто продавец в документах
Ответ определяется схемой работы, и от неё зависит, какие документы формируются.
- **Продавец — поставщик.** Заказ создаётся от его имени, счёт и УПД выставляет он. Площадка получает
вознаграждение за посредничество — так работает
[партнёрская схема](/docs/partner/#вознаграждение-партнёра).
- **Продавец — Инвойсбокс по договору комиссии.** Товар остаётся собственностью поставщика, а продажу
оформляет комиссионер: последовательность документов при полной и частичной отгрузке разобрана в
[комиссионной схеме](/docs/merchant/schema/commission/).
Выбор фиксируется в договоре и настройках магазинов, а не в каждом запросе — тело
[создания заказа](/docs/merchant/order/create/) в обоих случаях одинаковое.
## Франшиза: выплата уходит той точке, которая исполнила заказ
У сетей и франшиз заказ часто приходит на общий сайт, а исполняет его конкретная точка со своим юрлицом.
Заранее это неизвестно: точка определяется по адресу доставки или по наличию товара.
Для такого случая есть [перенос заказа на другой магазин](/docs/merchant/order/merchant-move/):
получателя выплаты можно сменить и до оплаты, и после неё. Условие одно — исходный магазин должен быть
создан с типом, который допускает перенос; это настраивается при подключении.
> [!NOTE]
> Заказы по реквизитам продавца (ИНН и КПП вместо идентификатора магазина) —
> [отдельный режим](/docs/merchant/order/agent-create/) для банков и крупных платёжных агрегаторов.
> Его схема не входит в публикуемый набор, поэтому консоли «Выполнить» на странице нет: контракт
> сверяется с технической поддержкой.
## Витрина: продажа рядом с чужой покупкой
Кроме собственной корзины у площадки есть второй источник продаж — [Витрина Инвойсбокса](/docs/marketplace/).
Точка продаж публикует себя в каталоге, а её [мини-приложение](/docs/marketplace/mini-apps/)
показывается покупателю прямо на [платёжной странице](/docs/merchant/payment-page/), пока он оплачивает
основную покупку: трансфер к авиабилету, страховка к поездке, доставка к заказу.
Точку продаж создаёт и обновляет [API маркетплейса](/docs/marketplace/create/), а скидки и акции
оформляются [спецпредложениями](/docs/marketplace/special-offer/).
## Что это даёт
- Покупатель-организация получает один счёт вместо трёх и один комплект документов на каждую покупку.
- Площадка не становится держателем чужих денег: выручка идёт продавцу, площадке — вознаграждение.
- Подключение поставщиков идёт по API, без обмена сканами документов.
- Возвраты и отгрузки не путаются между продавцами: каждый заказ внутри группы независим.
## Чем подключиться
| Путь | Когда подходит |
|---|---|
| [Партнёрское API](/docs/partner/) | площадка подключает продавцов и создаёт заказы от их имени |
| [Группа заказов](/docs/merchant/order/create-order-container/) | в корзине бывает больше одного продавца |
| [API маркетплейса](/docs/marketplace/) | нужна витрина и продажа на платёжной странице |
| [Мини-приложения](/docs/marketplace/mini-apps/) | покупатель оформляет заказ внутри чужого потока оплаты |
## Смежные кейсы
- [B2B продажи товаров](/docs/scenarios/retail/) — отгрузка партиями и возврат с корректировкой.
- [B2B продажи услуг страхования пассажиров](/docs/scenarios/insurance/) — продажа рядом с основной
покупкой через мини-приложение.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — сверка оплат, когда счетов много.
---
---
# 🧩 Приём платежей без разработчика
# Приём платежей без разработчика: юристы, аудит, агентства, студии
В небольшой профессиональной практике счёт выставляет тот же человек, который оказывает услугу.
Разработчика нет, сайт собран на конструкторе, и любая интеграция звучит как проект на месяц. Поэтому
всё остаётся как есть: счёт в Word, реквизиты в подписи письма, звонок бухгалтеру клиента с вопросом,
дошли ли деньги, и акт, который печатают и подписывают вручную.
Ни один шаг здесь не требует программирования. Оплату от организаций можно принять кодом, который
копируется в страницу, или готовым модулем к вашей платформе — счёт, чек и закрывающие документы
формируются на стороне Инвойсбокса.
## Четыре пути без программирования
| Путь | Что делаете вы | Сколько занимает |
|---|---|---|
| [Счёт из личного кабинета](https://www.invoicebox.ru/ru/free-invoice) | заполняете счёт в кабинете и отправляете покупателю | пара кликов |
| [Платёжный виджет](/widgets/) | собираете кнопку в конструкторе и вставляете код на страницу | минуты |
| [Готовый модуль](/docs/merchant/cms/) | устанавливаете модуль для своей платформы и вводите данные магазина | часы |
| [ИИ-агент](/for-agents/) | даёте агенту в Cursor или Claude Code один промпт — код он пишет сам | часы |
Сайт нужен не всегда. Если счетов немного и каждый обсуждается с клиентом, начните с кабинета: там
счёт выставляется вручную, к нему можно добавить QR-код для оплаты через СБП и оформить отчётные
документы — [бесплатно, без интеграции и без сайта](https://www.invoicebox.ru/ru/free-invoice).
Виджет подходит, когда сумма известна заранее или её называет клиент: консультация по прайсу, оплата
этапа договора, абонентское обслуживание. Модуль — когда заказы уже рождаются на сайте.
## Счёт руками, когда сайт не нужен
Юрист выставляет пять счетов в месяц, аудитор — десять, и каждый обсуждается с клиентом лично. Ставить
для этого кнопку на сайт незачем: [сервис бесплатного выставления счёта](https://www.invoicebox.ru/ru/free-invoice) закрывает задачу из
кабинета.
- Счёт заполняется вручную и уходит покупателю; ему достаточно ссылки.
- К счёту добавляется QR-код — покупатель оплачивает через СБП из приложения своего банка.
- Отчётные документы оформляются там же, руками, когда они понадобятся.
- Регистрация и работа бесплатны — платить за приём оплаты от юрлиц заранее не нужно.
Когда счетов станет много, те же реквизиты работают в виджете и в API — переносить ничего не придётся.
## Как это работает у вас на странице
1. **Соберите кнопку.** В [конструкторе](/widgets/constructor/) выбираются состав заказа или свободная
сумма, дополнительные поля, тип плательщика и адрес страницы завершения. Понадобятся идентификатор
магазина и региональный код — [где их взять](/docs/merchant/integrationdata/); для пробы конструктор
подставит демо-магазин.
2. **Поставьте тип плательщика «организация».** Тогда клиент указывает ИНН, а Инвойсбокс формирует счёт
и закрывающие документы — [схема для юрлиц](/docs/merchant/schema/legal/). Для физлиц тот же виджет
выдаёт [чек по 54-ФЗ](/docs/merchant/fz54/).
3. **Вставьте код на страницу.** Примеры для обычного сайта, Тильды, WordPress и 1С-Битрикс — в
[инструкции по вставке](/widgets/embed/).
4. **Получите оплату и документы.** Клиент платит по счёту или картой, акт и счёт-фактура уходят его
бухгалтерии [через ЭДО](/docs/merchant/documentflow/), деньги приходят на расчётный счёт на
следующий рабочий день — [сроки](/docs/terms/).
## Что важно знать про виджет
Сумма и состав заказа приходят из браузера покупателя и не подписаны — в браузере их можно изменить до
отправки. Это осознанное упрощение ради быстрого старта, и оно накладывает одну обязанность: сверять
сумму оплаты с той, которую вы ожидали. Подробно — [Безопасность виджета](/widgets/security/).
Для практики, где счёт выставляется по договорённости, это почти не риск: оплату вы всё равно
сопоставляете с договором. Если же цену определяет только ваша система, надёжнее создавать заказы
[через API](/docs/merchant/order/create/) — этот шаг можно сделать позже, ничего не переделывая: виджет
и API работают с одним и тем же магазином.
## Когда клиент просит счёт «как обычно»
Корпоративная бухгалтерия часто хочет счёт на бумаге или в почте, а не ссылку на оплату. Здесь ничего
менять не нужно: счёт формируется на стороне Инвойсбокса и доходит до клиента письмом, а оплатить его
он может из своего банка. Тем, кто пользуется банковским приложением, счёт можно доставить прямо туда —
[Запросом о платеже](/docs/scenarios/rtp/).
## Что это даёт
- Оплата от организаций принимается без разработки и без изменения сайта.
- Счёт, акт и счёт-фактура формируются сами — печатать и подписывать вручную не нужно.
- Клиент платит привычным способом, а вы видите оплату, не звоня его бухгалтеру.
- Переход на API не требует переделки: тот же магазин, те же документы.
## Смежные кейсы
- [Подписки для юрлиц](/docs/scenarios/saas/) — если услуга продаётся периодами.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — когда счетов станет много.
- [B2B продажи 24/7](/docs/scenarios/b2b-sales/) — что даёт переход на API.
---
---
# 🎓 Корпоративное обучение и ДПО
# Корпоративное обучение и ДПО: оплата обучения сотрудников организацией
Учебный центр продаёт курс не тому, кто учится. Заявку оставляет специалист по обучению, платит
бухгалтерия, а на занятия приходят двенадцать человек, из которых двое в последний момент меняются, а
один вообще не выходит на связь. Всё это должно сойтись в счёте, в акте и в удостоверениях — и обычно
сходится вручную, письмами и правками в счёте, потому что «список поменялся».
Инвойсбокс закрывает денежную часть: счёт организации, оплата привычным ей способом, акт и
счёт-фактура после курса. Список слушателей живёт в составе заказа, и его можно менять, пока счёт не
оплачен.
## Как выглядит цикл
1. **Заявка превращается в счёт.** [Создание заказа](/docs/merchant/order/create/) с типом плательщика
`legal`: в составе корзины — позиции по программе и слушателям, в `merchantOrderId` — номер заявки
или договора, в `expirationDate` — срок оплаты, обычно до начала потока.
2. **Организация платит.** Переводом, в один шаг из интернет-банка, по
[Запросу о платеже](/docs/scenarios/rtp/) или подтверждением из гарантийного фонда — способ зависит
от [платёжного инструмента](/docs/merchant/payment-instruments/), запрос при этом один и тот же.
3. **Вы узнаёте об оплате сигналом,** а не из выписки:
[уведомление о смене статуса](/docs/merchant/notification/status/) приходит сразу после
подтверждения, и слушателей можно зачислять.
4. **Курс проходит, документы уходят.** Акт и счёт-фактура формируются по факту оказания услуги и
отправляются [через ЭДО](/docs/merchant/documentflow/) или на бумаге.
5. **Кто не учился — тому возврат.** Двое не приступили к обучению: сумма за них возвращается, а
корректировочный документ уходит вслед за возвратом —
[возврат с корректировкой](/docs/merchant/refund/correction/).
## Список слушателей — это состав заказа
Позиции корзины — не только «курс за 145 000 ₽». Слушатель, программа и период обучения, вписанные в
позиции, попадают в счёт и в акт, и бухгалтерия покупателя видит, за кого именно заплатила. Так снимается
вопрос, с которым клиент возвращается чаще прочих: «а кто у вас в этом счёте?».
Из этого следуют два правила работы со списком:
- **До оплаты состав правится в самом заказе.** [Изменение заказа](/docs/merchant/order/update/)
пересчитывает состав и сумму, ссылка на оплату остаётся прежней. Так оформляется замена слушателя,
добавление ещё двоих или переход на другую программу.
- **После оплаты состав не меняют — деньги двигают.** Кто-то не приступил к обучению: это
[возврат с корректировкой](/docs/merchant/refund/correction/), а не правка оплаченного счёта. Прежние
документы остаются в силе, а корректировка объясняет разницу.
Неоплаченный счёт по отменённой заявке [отменяется](/docs/merchant/order/delete/) — у клиента в списке
не останется висеть счёт, который никто не собирается платить.
## Обучение частных слушателей на том же контуре
Учебные центры почти всегда продают и организациям, и людям. Разница только в типе плательщика: для
физлица тот же заказ выдаёт [чек по 54-ФЗ](/docs/merchant/fz54/), для организации —
[счёт и закрывающие документы](/docs/merchant/schema/legal/). Второго подрядчика и второй личный
кабинет для этого не нужно.
Если курс продаётся периодами — доступ к платформе на год с оплатой по месяцам, — работает механика
подписки: [счёт на каждый период](/docs/scenarios/saas/) вместо привязки карты.
## Что это даёт
- Заявка становится счётом за один вызов, а зачисление привязано к подтверждению оплаты.
- Список слушателей виден в счёте и акте — меньше переписки с бухгалтерией клиента.
- Замены и отказы оформляются штатно: изменением заказа до оплаты и возвратом с корректировкой после.
- Акт и счёт-фактура за курс уходят по ЭДО без участия менеджера.
## Чем подключиться
| Путь | Когда подходит |
|---|---|
| [API и PHP SDK](/docs/merchant/) | заявки приходят в вашу систему обучения или CRM |
| [Модуль CRM](/docs/merchant/crm/) | заявками занимаются менеджеры: amoCRM, retailCRM |
| [Готовый модуль CMS](/docs/merchant/cms/) | курсы продаются с сайта |
| [Платёжный виджет](/widgets/) | нужно принять оплату за курс сегодня |
## Смежные кейсы
- [Подписки для юрлиц](/docs/scenarios/saas/) — доступ к платформе периодами.
- [Приём платежей без разработчика](/docs/scenarios/no-code/) — если своего разработчика нет.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — когда счетов становится много.
---
---
# 🎪 Событийная индустрия: конференции и выставки
# Конференции и выставки: участие компании одним счётом
Компания едет на выставку не за билетом. Ей нужен стенд, электричество и мебель на нём, шесть
делегатов, парковка и место в каталоге — и всё это заканчивается одним разговором с бухгалтерией:
«пришлите счёт». Организатор в ответ шлёт три счёта от трёх юрлиц, а через неделю четвёртый, потому
что участник добавил ещё одного делегата. Дальше начинается сверка, которая занимает больше времени,
чем продажа.
Инвойсбокс собирает участие в один платёж: покупатель платит один раз, документы приходят одним
комплектом, а изменения в составе делегатов проходят штатно — до оплаты правкой заказа, после —
возвратом с корректировкой.
## Один счёт вместо стопки
Если участие продаёт одно юрлицо, всё умещается в один
[заказ](/docs/merchant/order/create/): стенд, делегаты, доп-услуги — позиции корзины со своими
ставками НДС и единицами измерения. В `expirationDate` ставится срок оплаты — обычно за несколько дней
до мероприятия, чтобы место не висело за неплательщиком.
Когда услуги оказывают разные юрлица — площадка сдаёт метры, подрядчик строит стенд, кейтеринг кормит
гостей, — работает [группа заказов](/docs/merchant/order/create-order-container/): внутри столько
заказов, сколько продавцов, а покупатель платит одной суммой и видит один номер счёта. Выручка и
документы при этом расходятся по продавцам — подробно это разобрано в кейсе
[маркетплейса и сплит-корзины](/docs/scenarios/marketplace-split/).
## Состав участия меняется до последнего дня
Это отраслевая норма, а не исключение: за неделю до выставки меняются фамилии делегатов, добавляется
второй стол на стенде, отваливается один из приехавших. Правило то же, что и в обучении, и оно
определяется одним признаком — оплачен ли счёт.
- **До оплаты** — [изменение заказа](/docs/merchant/order/update/): состав и сумма пересчитываются,
ссылка на оплату остаётся прежней. Замена делегата, лишний квадратный метр, отказ от парковки.
- **После оплаты** — деньги, а не состав. Делегат не приехал: сумма за него возвращается, а
корректировочный документ уходит вслед за возвратом —
[возврат с корректировкой](/docs/merchant/refund/correction/).
Заявка отменилась до оплаты — счёт [отменяется](/docs/merchant/order/delete/), место освобождается под
следующего участника.
## Срок оплаты и место, которое нельзя держать вечно
У мероприятия есть дата, и это меняет отношение к неоплаченным счетам. Стенд, забронированный и не
оплаченный, — это не дебиторка, а потерянное место в зале. Поэтому:
- `expirationDate` ставится по вашему регламенту бронирования, а не «на всякий случай» на месяц;
- список неоплаченных счетов с истекающим сроком собирается [фильтрами](/docs/api/filters/) по
`status=created` и дате — [как это устроено](/docs/scenarios/receivables/);
- если участник платит по счёту и тянет с оплатой, счёт можно доставить прямо в его банковское
приложение — [Запросом о платеже](/docs/scenarios/rtp/).
Тем, кому нужно место здесь и сейчас — регистрация в день мероприятия, доплата за апгрейд на стойке, —
подойдёт [обещанный платёж](/docs/merchant/payment-instruments/): участник подтверждает картой за
минуту, а его организация оплачивает счёт в течение пяти суток.
## Что это даёт
- Участие продаётся одним счётом, даже если услуги оказывают несколько юрлиц.
- Изменения в составе делегатов не превращаются в переписку: до оплаты — правка заказа, после — возврат
с корректировкой.
- Закрывающие документы уходят [по ЭДО](/docs/merchant/documentflow/) одним комплектом после
мероприятия.
- Частные участники платят там же и получают [чек по 54-ФЗ](/docs/merchant/fz54/).
## Смежные кейсы
- [Корпоративное обучение и ДПО](/docs/scenarios/education/) — та же механика списка участников.
- [Маркетплейс и сплит-корзина](/docs/scenarios/marketplace-split/) — когда продавцов несколько.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — сверка оплат перед мероприятием.
---
---
# 🏷️ Маркированные товары (Честный знак)
# Маркированные товары: продажа организациям с передачей кодов
Продавец маркированного товара платит за интеграцию дважды. Первый раз — чтобы принять оплату от
организации и выдать закрывающие документы. Второй — чтобы сведения о маркировке дошли до покупателя
и до Честного знака в нужный момент и в нужном документе. Обычно это два разных подрядчика, два
договора и два места, где что-то может разъехаться: товар отгружен, а коды ушли не с тем УПД.
Инвойсбокс закрывает оба контура. Заказ несёт товарную группу в составе корзины, а сведения о
маркировке уходят покупателю и в систему маркировки вместе с документами по отгрузке.
## Как выглядит цикл
1. **Заказ с товарной группой.** При [создании заказа](/docs/merchant/order/create/) в позиции корзины
передаётся `categoryType: honestSign` и код группы в `category` — `shoes`, `milk`, `water`, `beer` и
так далее; [полный справочник групп](/docs/merchant/honest-sign/). Если у вас свой справочник
категорий, в `categoryType` идёт `merchantHonestSignMap`. Без этих полей заказ создастся, но
сведения о маркировке в чек не попадут.
2. **Оплата по счёту или с отсрочкой.** Покупатель-организация платит переводом, в один шаг из своего
банка или подтверждением из гарантийного фонда —
[чем инструменты отличаются](/docs/merchant/payment-instruments/).
3. **Отгрузка партиями.** Оптовый заказ редко уезжает целиком: каждая партия оформляется
[отгрузкой](/docs/merchant/order/shipment_create/), и сведения о маркировке относятся к тому, что
действительно отгружено, а не к заказу в целом.
4. **Документы через ЭДО.** УПД уходит покупателю [по электронному документообороту](/docs/merchant/documentflow/),
события обмена — [в перечне событий ЭДО](/docs/merchant/documentflow/edo_events/).
5. **Недовоз — возврат с корректировкой.** Привезли меньше, чем в счёте: разница возвращается
покупателю, а корректировочный документ уходит вслед за возвратом —
[возврат с корректировкой](/docs/merchant/refund/correction/).
## Почему маркировка привязана к отгрузке, а не к заказу
Заказ — это договорённость: столько-то пар обуви такой-то модели. Коды маркировки относятся к
конкретным экземплярам, а какие именно уедут покупателю, известно только в момент сборки партии.
Поэтому сведения о маркировке идут с отгрузкой: сколько отгрузили — столько и сведений.
Отсюда два следствия для интеграции:
- **Отгрузку нельзя откладывать «на потом».** Пока её нет, у покупателя нет и УПД, а значит, товар
формально не принят. Отгрузка вызывается по факту передачи товара —
[как её оформить](/docs/merchant/order/shipment_create/), как [поправить](/docs/merchant/order/shipment_update/)
и как [посмотреть](/docs/merchant/order/shipment_get/).
- **Если отгрузить нечего** — товара не оказалось на складе, покупатель отказался — об этом сообщают
[уведомлением о невозможности отгрузки](/docs/merchant/notification/shipping-unavailable/), и заказ
не остаётся оплаченным без движения.
## Что смотреть в справочниках
| Что нужно | Где взять |
|---|---|
| Код товарной группы для `category` | [Честный знак](/docs/merchant/honest-sign/) — 20 групп с описаниями |
| Ставка НДС для позиции | [Справочник ставок](/docs/dictionary/tag1199/) |
| Единица измерения количества | [Признак предмета расчёта](/docs/dictionary/tag1212/) и [ОКЕИ](/docs/dictionary/okei/) |
| Что уходит в чек физлицу | [Фискализация по 54-ФЗ](/docs/merchant/fz54/) |
## Что это даёт
- Один вендор закрывает и приём оплаты от организаций, и передачу сведений о маркировке.
- Коды привязаны к отгруженным партиям, поэтому документы совпадают с фактом.
- Недовоз и отказ оформляются штатно: возврат с корректировкой или уведомление о невозможности
отгрузки, а не ручная переписка с бухгалтерией покупателя.
- Физлицам по тому же заказу выдаётся чек с реквизитами маркировки.
## Смежные кейсы
- [B2B продажи товаров](/docs/scenarios/retail/) — отгрузка партиями и возвраты в оптовой торговле.
- [Маркетплейс и сплит-корзина](/docs/scenarios/marketplace-split/) — если товар продают несколько
поставщиков.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — сверка оплат по большому числу счетов.
---
---
# 🚛 Логистика и грузоперевозки
# Логистика и грузоперевозки: расчёт по факту, а не по заявке
В перевозке цена заявки редко совпадает с ценой рейса. Вес уточняется на погрузке, объём — при
загрузке в машину, к тарифу добавляются простой, доупаковка, второй адрес выгрузки. Предоплата по
заявке означает возврат почти в каждом втором рейсе; постоплата — работу в долг и разговоры с
бухгалтерией клиента о том, почему сумма в счёте не та, о которой договаривались.
Инвойсбокс закрывает разрыв между заявкой и фактом двумя механиками: сумму по заявке можно
зарезервировать и списать по факту, а можно выставить счёт организации и подтвердить возможность
перевозки до того, как деньги ушли.
## Резерв по заявке, списание по факту
[Холдирование](/docs/merchant/order/hold/) подходит, когда заявку оплачивают картой — личной,
корпоративной или картой водителя.
1. Заказ создаётся с подтипом `subtype: hold`; все позиции корзины идут с типом оплаты
`full_prepayment`.
2. После подтверждения оплаты сумма блокируется на карте до даты из `holdTill` в
[ответе на создание заказа](/docs/merchant/order/create/#orderresponse).
3. Груз доехал — [создаётся отгрузка](/docs/merchant/order/shipment_create/) по позициям заказа.
Отгрузок может быть несколько: сборный груз доезжает частями, и на каждую оформляются документы.
4. Когда все позиции отгружены, заблокированные деньги списываются. Если рейс вышел дешевле —
отгрузка с флагом `final: true` списывает только фактическое, а остаток разблокируется.
Так закрывается частый случай: заявка на 60 000 ₽, по факту 54 000 ₽ — клиент платит за то, что
действительно перевезли, и никто не оформляет возврат.
> [!NOTE]
> Резерв работает на карте. Если перевозку оплачивает организация по счёту, до оплаты состав и сумму
> правит [изменение заказа](/docs/merchant/order/update/), а после — недоплату закрывает отдельный
> счёт, переплату [возврат с корректировкой](/docs/merchant/refund/correction/).
## Подтверждение рейса до того, как деньги ушли
У экспедитора машина находится не всегда: заявка принята, оплата подтверждена, а свободного борта на
дату нет. Для этого случая есть [контроль отгрузки на платёжной странице](/docs/merchant/notification/shipping-unavailable/):
Инвойсбокс дожидается ответа вашей системы, пока покупатель ещё стоит на платёжной странице.
- Машина нашлась, рейс поставлен в план — вы отвечаете `success`, покупатель видит подтверждение
оплаты и едет дальше по своему сценарию.
- Борта нет — вы сообщаете об этом, и покупатель узнаёт о невозможности перевозки сразу, а не через
день от диспетчера.
Настройка включается на стороне вашей платёжной страницы — попросите её у
[поддержки](https://www.invoicebox.ru/ru/contacts) до запуска.
## Рейсы за месяц одним счётом
Постоянный клиент делает по десять отправлений в неделю, и десять счетов в неделю его бухгалтерии не
нужны. [Группа заказов](/docs/merchant/order/create-order-container/) собирает несколько заказов под
одну оплату: каждый рейс остаётся отдельным заказом со своими документами, а покупатель платит один
раз. Так же удобно, когда в перевозке участвуют несколько исполнителей: у каждого свой заказ и своя
выручка.
## Что это даёт
- Клиент платит за фактически выполненный рейс, а не за заявку — меньше возвратов и меньше споров.
- Невозможность перевозки видна покупателю сразу на платёжной странице, а не после списания денег.
- Документы за рейс уходят [через ЭДО](/docs/merchant/documentflow/) по каждой отгрузке.
- Деньги приходят на расчётный счёт на следующий рабочий день после подтверждения оплаты —
[сроки](/docs/terms/).
## Смежные кейсы
- [B2B продажи такси и трансфера](/docs/scenarios/taxi/) — та же механика резерва в пассажирских
перевозках.
- [B2B продажи товаров](/docs/scenarios/retail/) — отгрузка партиями и корректировки.
- [Маркированные товары](/docs/scenarios/marked-goods/) — если возите маркировку.
---
---
# ⚡ Запрос о платеже (RtP)
# Запрос о платеже (RtP)
**Запрос о платеже (RtP или Request to Pay)** — это [удобный сервис от НСПК](https://www.invoicebox.ru/ru/products/rtp)
по передаче электронных платёжных счетов, способный доставить информацию о необходимости оплаты
товаров, работ и услуг от поставщика до плательщика.
Счёт не нужно везти на бумаге, пересылать письмом или в мессенджере: он доставляется прямо в личный
кабинет плательщика, а оплатить его можно в банковском или финансовом приложении.
Счёт через сервис RtP может быть направлен как плательщиками - физическими лицами (B2C), так и
организациям (B2B). Оплата может быть совершена с использованием QR-кода СБП или
[СБП B2B](https://www.invoicebox.ru/ru/products/sbp-b2b), а также множество альтернативных способов
оплаты на [платёжной странице](/docs/merchant/payment-page/) Инвойсбокс.
### Основные преимущества Запроса о платеже:
- Поставщик может полностью автоматизировать формирование и доставку счетов своим клиентам.
- Плательщик может контролировать процесс оплаты счёта, выбирая, когда и каким образом произвести платёж.
- Используются современные технологии для защиты данных и предотвращения мошенничества.
- Счета, а также информация об их оплате могут быть отправлены и получены в реальном времени, что упрощает
взаимодействие между сторонами, а также позволяет сократить дебиторскую задолженность.
> ❗ Почти 40% участников опроса [РСПП](https://rspp.ru/) назвали неплатежи со стороны контрагентов главным
препятствием для бизнеса, потеснив на второе место проблему снижения спроса. По данным мониторинга за второй квартал
2026 года доля таких ответов выросла на 5,6 процентного пункта. Запрос о платеже с моментальным подтверждением оплаты
снимает эту проблему: поставщик видит оплату сразу.
### Как это работает?
Поставщик товаров или услуг отправляет счёт (запрос на оплату) плательщику через свою учётную систему,
личный кабинет Инвойсбокс, [CRM](/docs/merchant/crm), [CMS](/docs/merchant/cms), [ERP](/docs/merchant/erp)
или мобильное приложение.
Плательщик получает уведомление с подробной информацией о счёте, включая сумму, описание и сроки оплаты. Плательщик
может получать такие уведомления на электронную почту, в мессенджерах или иных сервисах. Плательщик может
выбрать один из нескольких вариантов: оплатить счёт немедленно, назначить дату платежа или отклонить запрос.
Платёж может быть осуществлён мгновенно с использованием удобного способа оплаты, например, банковского перевода или СБП.
См. также [использование API для выставления счёта](/docs/merchant/schema/rtp) через Запрос о платеже.
### Применение Запрос о платеже
Набор сценариев использования RtP обширен и не ограничен приведёнными примерами:
- B2B и B2C расчёты: Компании могут оптимизировать свои финансовые потоки, используя этот метод для выставления счетов и мгновенного получения информации об оплате.
- Коммунальные платежи: Поставщики услуг могут отправлять запросы на оплату, которые клиенты могут оплачивать удобным способом.
- Онлайн-покупки и подписки: Магазины могут использовать RtP для упрощения процесса оплаты заказов, а также для автоматизации подписок.
- Школы, учебные заведения и курсы: Учреждения могут использовать Запрос о платеже для упрощения процесса оплаты курсов, а также для автоматизации приёма оплаты.
### Как подключить: последовательность вызовов
1. [Создайте заказ](/docs/merchant/order/create/) с составом и суммой — как для обычной оплаты по счёту.
Идентификатор заказа в вашей системе передайте в `merchantOrderId`, а внутренние поля —
в [метаданные](/docs/merchant/order/metadata/): они вернутся в уведомлениях.
2. Отправьте плательщику ссылку или QR-код на оплату. Запрос уходит в приложение его банка —
отдельная платёжная страница не нужна.
3. Дождитесь [уведомления о смене статуса](/docs/merchant/notification/status/): по нему запускайте
отгрузку или оказание услуги. Опрашивать [состояние заказа](/docs/merchant/order/get/) вручную
не требуется — но метод пригодится для сверки.
4. Если платить передумали или счёт устарел, [отмените заказ](/docs/merchant/order/delete/) —
запрос у плательщика погаснет.
5. Возврат оформляется обычным [методом возврата](/docs/merchant/refund/create/).
### Что это даёт бизнесу
- Снижение административных затрат, связанных с обработкой, отслеживанием платежей и ведением документооборота.
- Снижение дебиторской задолженности.
- Сокращение времени обработки транзакций, быстрое получение оплаты покупателя.
- Запрос о платеже активно развивается в финансовой отрасли и поддерживается банками и финансовыми институтами России.
### Универсальный QR
Универсальный QR-код Национальной системы платёжных карт (НСПК) — единый инструмент
для приёма различных видов платежей. Он позволяет торговым точкам использовать один QR-код для обработки платежей
через Систему быстрых платежей (СБП), банковские pay-сервисы, сервисы рассрочки, а в перспективе — и с использованием
цифрового рубля.
Решения Инвойсбокс API позволяют интегрировать [сервис RtP](https://www.invoicebox.ru/ru/products/rtp) и Универсальный
QR (включая оплату с использованием [СБП B2B](https://www.invoicebox.ru/ru/products/sbp-b2b)) в достаточно короткие
сроки и сопроводить оплату счёта необходимым документооборотом.
> Если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы будем рады вам помочь!
---
# 💳 Холдирование средств
# Холдирование средств: платите за факт, а не за план
Холдирование — это резерв суммы на карте покупателя до того, как известна окончательная цена.
Деньги остаются у клиента, но потратить их он не может; продавец списывает ровно столько,
сколько стоил фактический заказ, а остаток возвращается автоматически.
Сценарий закрывает боль отраслей с плавающей суммой. Заказ подтверждён, а окончательная сумма
станет известна через час, день или после отгрузки.
> Не путайте с [подтверждением оплаты заказа](/docs/merchant/guarantee/) — там речь о другом
> механизме: покупатель подтверждает уже сформированный платёж кодом.
## Как это работает
1. **Резерв.** Магазин [создаёт заказ с холдированием](/docs/merchant/order/hold/) на максимально
возможную сумму — например, максимальный чек поездки или полную стоимость брони.
Клиент подтверждает резерв, деньги блокируются на его карте.
2. **Отгрузка.** По факту продавец [создаёт отгрузку](/docs/merchant/order/shipment_create/) с тем,
что действительно отгружено или оказано. Отгрузок может быть сколько угодно, на каждую
оформляется фискальный чек. Когда в отгрузках закрыты все позиции заказа, заблокированные
средства списываются.
3. **Частичное списание.** Если часть заказа не состоялась, отгрузка оформляется с флагом
`final` = `true`: заказ считается выполненным, а остаток резерва разблокируется — без
отдельного возврата. До какой даты держится резерв, видно в поле `holdTill`
[ответа на создание заказа](/docs/merchant/order/create/#orderresponse).
4. **Уведомление.** Вашу систему о каждом шаге извещает
[уведомление о смене статуса](/docs/merchant/notification/status/) — по нему запускается
отгрузка, оформление документов или закрытие смены.
Если заказ не состоялся, резерв снимается [отменой заказа](/docs/merchant/order/delete/):
деньги освобождаются на карте клиента, списания не происходит.
Как это выглядит в числах: резерв берётся с запасом, списывается факт, разница освобождается сама.
```mermaid
sequenceDiagram
participant K as Покупатель
participant M as Магазин
participant I as Инвойсбокс
M->>I: заказ с холдированием на 3 000 ₽
I-->>M: paymentUrl, holdTill — 5 суток
K->>I: подтверждение, 3 000 ₽ заблокированы на карте
M->>I: отгрузка по факту на 2 400 ₽, final = true
I-->>K: списано 2 400 ₽, 600 ₽ разблокированы
I->>M: уведомление о смене статуса
```
## Где это нужно
| Отрасль | Что резервируем | Что списываем |
|---|---|---|
| [Такси и трансфер](/docs/scenarios/taxi) | максимальную стоимость маршрута | фактическую поездку по счётчику |
| [Рестораны](/docs/scenarios/ras) | сумму заказа при подтверждении | фактически поданные блюда |
| [Гостиницы](/docs/scenarios/pms) | стоимость проживания | проживание плюс допуслуги при выезде |
| Прокат и аренда оборудования | залог и максимальный срок | фактическое время использования |
| Розница с частичной отгрузкой | полную корзину | каждую отгруженную партию |
| Предзаказы с плавающей ценой | верхнюю границу цены | цену на момент отгрузки |
## Что учесть до внедрения
- **Срок жизни резерва** ограничен правилами платёжной системы. Если заказ выполняется дольше,
резерв нужно обновлять — уточните допустимый срок у вашего менеджера.
- **Списать больше зарезервированного нельзя.** Резервируйте с запасом: увеличить сумму
постфактум не выйдет, придётся выставлять отдельный счёт.
- **Клиент видит блокировку** как уменьшение доступного остатка. В интерфейсе честно называйте
это резервом, а не оплатой, — иначе неизбежны обращения в поддержку.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
## Читайте также
- [Демо «Касса АЗС](/demo/fuel/)
---
# 📱 Оплата внутри приложения без платёжной страницы
# Оплата внутри приложения: подтверждение кодом вместо перехода на платёжную страницу
В мобильном приложении переход на внешнюю страницу оплаты стоит дорого. Открывается браузер, теряется
контекст экрана, покупатель возвращается не туда, откуда ушёл, — и часть заказов остаётся
неоплаченной просто потому, что дорога назад оказалась длиннее, чем сам заказ. Для повторяющихся
покупок — обед на офис, расходники, поездка — это особенно заметно: сам заказ занимает пятнадцать
секунд, а оплата уводит на минуту в чужой интерфейс.
Постоянный покупатель с гарантийным фондом может подтвердить оплату прямо в вашем приложении: код
приходит ему от Инвойсбокса, вводится на вашем экране, заказ становится оплаченным.
## Три вызова вместо перехода
1. **Заказ.** [Создание заказа](/docs/merchant/order/create/) с типом плательщика `legal` — как обычно.
2. **Проверка возможности оплаты.** [Метод проверки](/docs/merchant/guarantee/validate/) отвечает,
хватает ли средств фонда. Спрашивать стоит до того, как покажете покупателю кнопку: так он не
упрётся в отказ на последнем шаге.
3. **Код подтверждения.** [Запрос кода](/docs/merchant/guarantee/code/) — Инвойсбокс отправляет код
покупателю.
4. **Подтверждение оплаты.** Покупатель вводит код на вашем экране, вы передаёте его
[методом подтверждения](/docs/merchant/guarantee/pay/), и заказ переходит в оплаченный.
Полная последовательность с участниками — в [схеме взаимодействия](/docs/merchant/guarantee/schema/),
а весь набор методов — в разделе [Гарантийный фонд](/docs/merchant/guarantee/).
> [!IMPORTANT]
> Раз оплата подтверждается в вашем интерфейсе, защита от перебора кода — тоже ваша.
> В вашем сервисе должна стоять капча: Google reCAPTCHA, Yandex SmartCaptcha, Huawei Safety Detect
> или аналог. Об этом прямо сказано в [описании методов](/docs/merchant/guarantee/).
## Кому это доступно и что делать с остальными
Подтверждение кодом работает для покупателей, у которых есть договор и гарантийный фонд —
[что это за инструмент](/docs/merchant/payment-instruments/). Остальным нужен обычный путь, и приложение
не обязано ради этого выбрасывать человека в браузер:
- **Мини-приложение в потоке Инвойсбокса.** Метод
[onCheckout](/docs/marketplace/mini-apps/miniapp-sdk/#метод-oncheckout) открывает платёжную страницу
поверх мини-приложения, а после оплаты вызывается
[обработчик onPaymentResult](/docs/marketplace/mini-apps/miniapp-sdk/#обработчик-onpaymentresult) со
статусом — покупатель возвращается ровно туда, откуда ушёл.
- **Ссылка на оплату внутри приложения.** `paymentUrl` из ответа на создание заказа открывается во
встроенном браузере; на устройстве с приложением Инвойсбокса откроется оно.
- **Оплата физлицом.** Тот же заказ выдаёт [чек по 54-ФЗ](/docs/merchant/fz54/), последовательность —
в [схеме для физических лиц](/docs/merchant/schema/private/).
## Не путайте с холдированием
Здесь деньги списываются с фонда организации, и происходит это в момент подтверждения кода.
[Холдирование](/docs/scenarios/guarantee/) — другое: сумма блокируется на банковской карте и
списывается по факту отгрузки. Механизмы решают разные задачи и настраиваются по-разному.
## Что это даёт
- Покупатель не выходит из приложения: оплата занимает столько же экранов, сколько сам заказ.
- Отказ по нехватке средств виден до кнопки оплаты, а не после неё.
- Закрывающие документы формируются как при любой другой оплате —
[документооборот](/docs/merchant/documentflow/).
- Для покупателей без фонда сценарий не ломается: платёжная страница открывается поверх и возвращает
человека обратно.
## Смежные кейсы
- [Холдирование средств](/docs/scenarios/guarantee/) — резерв суммы на карте и списание по факту.
- [B2B продажи такси и трансфера](/docs/scenarios/taxi/) — оплата в приложении с расчётом по факту.
- [Системы автоматизации ресторанов](/docs/scenarios/ras/) — оплата по QR-коду со стола.
---
---
# Коды ОКЕИ
# Коды ОКЕИ
Код единицы измерения передаётся в поле `measureCode` позиции корзины при
[создании заказа](/docs/merchant/order/create/#basketitem), а рядом в `measure` — обозначение для
человека: «шт.», «кг». Не путайте этот справочник с
[мерой количества в чеке](/docs/dictionary/tag2108/): там перечень ФНС и другие значения.
Ниже представлены наиболее популярные коды общероссийского классификатора единиц измерения (ОКЕИ).
Полный справочник кодов доступен на сайте [Федеральной службы государственной статистики](https://rosstat.gov.ru/opendata/7708234640-okei).
## Экономические единицы
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 796 | Штука | шт | pc
## Единицы длины
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 003 | Миллиметр | мм | mm
| 004 | Сантиметр | см | cm
| 005 | Дециметр | дм | dm
| 006 | Метр | м | m
| 008 | Километр | км | km
| 009 | Мегаметр | Мм | Mm
| 018 | Погонный метр | пог. м |
| 020 | Условный метр | усл. м |
| 039 | Дюйм | дюйм | in
| 041 | Фут | фут | ft
| 043 | Ярд | ярд | yd
| 047 | Морская миля | миля | mile
## Единицы площади
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 050 | Квадратный миллиметр | мм2 | mm2
| 051 | Квадратный сантиметр | см2 | cm2
| 053 | Квадратный дециметр | дм2 | dm2
| 055 | Квадратный метр | м2 | m2
| 059 | Гектар | га | ha
| 061 | Квадратный километр | км2 | km2
| 071 | Квадратный дюйм | дюйм2 | in2
| 073 | Квадратный фут | фут2 | ft2
| 075 | Квадратный ярд | ярд2 | yd2
| 109 | Ар | а | a
## Единицы объёма
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 110 | Кубический миллиметр | мм3 | mm3
| 111 | Кубический сантиметр | см3 | cm3
| 112 | Литр | л | L
| 113 | Кубический метр | м3 | m3
| 118 | Децилитр | дл | dl
| 122 | Гектолитр | гл | hl
| 126 | Мегалитр | Мл | Ml
| 131 | Кубический дюйм | дюйм3 | in3
| 132 | Кубический фут | фут3 | ft3
| 133 | Кубический ярд | ярд3 | yd3
| 159 | Миллион кубических метров | м3 | m3
## Единицы массы
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 160 | Гектограмм | гг | hg
| 161 | Миллиграмм | мг | mg
| 162 | Метрический карат | кар | МС
| 163 | Грамм | г | g
| 166 | Килограмм | кг | kg
| 168 | Тонна | т | t
| 170 | Килотонна | кт | kt
| 173 | Сантиграмм | сг | cg
| 181 | Брутто-регистровая тонна | БРТ |
| 185 | Грузоподъемность в метрических тоннах | т |
| 206 | Центнер (метрический) | ц |q
---
---
# Поиск по ИНН
# Поиск и получение данных об организации по ИНН
Реквизиты организации возвращает запрос по ИНН:
- метод: `GET`
- ресурс: `/v3/filter/api/counterparty-detail`
- тело ответа — коллекция объектов [Counterparty](#counterparty) в свойстве `data`
В запросе есть обязательный параметр `vatNumber` — ИНН.
Метод нужен, чтобы подставить реквизиты плательщика в заказ, не заставляя покупателя вводить их
руками: по ИНН возвращаются наименование, КПП и адреса, которые затем уходят в
[создание заказа](/docs/merchant/order/create/#customer).
> [!IMPORTANT]
> Если организация не найдена или справочный сервис недоступен, метод отвечает `200` с пустым `data`.
> Обрабатывайте это как «данных нет», а не как ошибку: пустой ответ не означает, что запрос не удался.
Пример запроса:
#### 🌐 HTTP
```http
GET /v3/filter/api/counterparty-detail?vatNumber=2323232323
Accept: application/json
User-Agent: MyApp 1.0
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
```
#### 🧊 CURL
```bash
curl -L -X GET '{baseUrl}/v3/filter/api/counterparty-detail?vatNumber=2323232323' \
-H 'Accept: application/json' \
-H 'User-Agent: MyApp 1.0' \
-H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e'
```
#### Пример запроса и ответа
``` json
GET /v3/filter/api/counterparty-detail
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
```
Ответ:
``` json
{
"data": [
{
"id": "01771534-196a-1105-839a-82422289d6d9",
"vatNumber": "7736207543",
"taxRegistrationReasonCode": "773601001",
"name": "ООО «Ромашка»",
"nameFull": "Общество с ограниченной ответственностью «Ромашка»",
"registrationNumber": "1027700123456",
"registrationDate": "2015-04-12T00:00:00+03:00",
"registrationAddress": "119021, г. Москва, ул. Тимура Фрунзе, д. 11",
"postAddress": "119021, г. Москва, ул. Тимура Фрунзе, д. 11",
"postAddressZip": "119021"
}
],
"metaData": {
"totalCount": 1,
"pageSize": 20,
"page": 1
}
}
```
## Counterparty
| Свойство | Обязательное | Тип | Описание |
|---------------------------|--------------|-----------------|--------------------------------------------------|
| id | да | string(36) | Идентификатор оригнизации в системе Инвойсбокс |
| vatNumber | да | string(20) | ИНН |
| taxRegistrationReasonCode | нет | string(9) | КПП |
| name | нет | string(100) | Наименование организации |
| nameFull | нет | string(300) | Полное наименование организации |
| nameI18n | нет | string(300) | Полное наименование организации на языке региона |
| registrationNumber | нет | string(20) | Регистрационный код организации |
| registrationDate | нет | datetime | Дата регистрации организации |
| registrationAddress | нет | string(200) | Адрес регистрации организации |
| postAddress | нет | string(200) | Почтовый адрес организации |
| postAddressZip | нет | string(6) | Почтовый индекс организации |
---
---
# Коды валют
# Коды валют (ISO 4217)
Ниже представлены коды валют, используемые в системе.
Полный классификатор валют доступен на сайте [Центрального банка России](https://www.cbr.ru/development/mcirabis/kv/).
## Экономические единицы
| Код | Наименование | Знак |
|------|------------------|------|
| RUB | Российский рубль | ₽ |
| CNY | Юань | ¥ |
| UZS | Узбекский сум | сум |
| EUR | Евро | € |
| GBP | Фунт стерлингов | £ |
| USD | Доллар США | $ |
---
---
# Признак предмета расчёта (тег 1212)
# Признак предмета расчёта (тег 1212)
Тег 1212 говорит, что именно продаётся: товар, работа, услуга, аванс. Значение передаётся
идентификатором в поле `type` позиции корзины при [создании заказа](/docs/merchant/order/create/#basketitem)
и попадает в фискальный чек.
## Что передавать в API
| Идентификатор | Что означает |
|---|---|
| `commodity` | товар, кроме подакцизного |
| `excise` | подакцизный товар |
| `job` | работа |
| `service` | услуга |
| `payment` | аванс, задаток, предоплата, кредит |
| `property_right` | передача имущественных прав |
| `another` | иной предмет расчёта |
У остальных признаков таблицы ФНС идентификатора нет: они относятся к деятельности, которую
Инвойсбокс не обслуживает (ставки, лотереи, вознаграждение платёжного агента), и в поле `type` не
передаются.
## Таблица ФНС
Таблица 101. Значения реквизита «признак предмета расчёта» (тег 1212), содержащихся в реквизите
«наименование предмета расчёта» (тег 1030) реквизита ФД в печатной форме.
| Код | Идентификатор | Реквизит «наименование предмета расчёта» (тег 1030) содержит сведения | Формат ПФ
| --- | --- | --- | --- |
| 1 | commodity | О реализуемом товаре, за исключением подакцизного товара и товара, подлежащего маркировке средствами идентификации (наименование и иные сведения, описывающие товар) | «ТОВАР» или «Т» или может не печататься
| 2 | excise | О реализуемом подакцизном товаре, за исключением товара, подлежащего маркировке средствами идентификации (наименование и иные сведения, описывающие товар) | «ПОДАКЦИЗНЫЙ ТОВАР» или «АТ» или может не печататься
| 3 | job | О выполняемой работе (наименование и иные сведения, описывающие работу) | «РАБОТА» или «Р» или может не печататься
| 4 | service | Об оказываемой услуге (наименование и иные сведения, описывающие услугу) | «УСЛУГА» или «У» или может не печататься
| 5 | --- | О приёме ставок при осуществлении деятельности по проведению азартных игр | «СТАВКА АЗАРТНОЙ ИГРЫ» или «СТАВКА ИГРЫ» или «СА» или может не печататься
| 6 | --- | О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр | «ВЫИГРЫШ АЗАРТНОЙ ИГРЫ» или «ВЫИГРЫШ АИ» или «ВА» или может не печататься
| 7 | --- | О приёме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приеме лотерейных ставок при осуществлении деятельности по проведению лотерей | «ЛОТЕРЕЙНЫЙ БИЛЕТ» или «СТАВКА ЛОТЕРЕИ» или «СЛ» или может не печататься
| 8 | --- | О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей | «ВЫИГРЫШ ЛОТЕРЕИ» или «ВЛ» или может не печататься
| 9 | --- | О предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации | «ПРЕДОСТАВЛЕНИЕ РИД» или «РИД» или может не печататься
| 10 | payment | Об авансе, задатке, предоплате, кредите | «ПЛАТЁЖ» или «П»или может не печататься
| 11 | --- | О вознаграждении пользователя, являющегося платёжным агентом (субагентом), банковским платёжным агентом (субагентом), комиссионером, поверенным или иным агентом | «АГЕНТСКОЕ ВОЗНАГРАЖДЕНИЕ» или «АВ»
| 12 | --- | О взносе в счёт оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчёта | «ВЫПЛАТА» или «В» или может не печататься
| 13 | another | О предмете расчёта, не относящемуся к предметам расчёта, которым может быть присвоено значение от «1» до «11» и от «14» до «26» | «ИНОЙ ПРЕДМЕТ РАСЧЁТА» или «ИПР» или может не печататься
| 14 | property_right | О передаче имущественных прав | «ИМУЩЕСТВЕННОЕ ПРАВО» или может не печататься
| 15 | --- | О внереализационном доходе | «ВНЕРЕАЛИЗАЦИОННЫЙ ДОХОД» или может не печататься
| 16 | --- | О суммах расходов, платежей и взносов, указанных в подпунктах 2 и 3 пункта Налогового кодекса Российской Федерации, уменьшающих сумму налога | «ИНЫЕ ПЛАТЕЖИ И ВЗНОСЫ» или может не печататься
| 17 | --- | О суммах уплаченного торгового сбора | «ТОРГОВЫЙ СБОР» или может не печататься
| 18 | --- | О курортном сборе | «КУРОРТНЫЙ СБОР» или может не печататься
| 19 | --- | О залоге | «ЗАЛОГ» или может не печататься
| 20 | --- | О суммах произведенных расходов в соответствии со статьей 346.16 Налогового кодекса Российской Федерации, уменьшающих доход | «РАСХОД» или может не печататься
| 21 | --- | О страховых взносах на обязательное пенсионное страхование, уплачиваемых ИП, не производящими выплаты и иные вознаграждения физическим лицам | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ ПЕНСИОННОЕ СТРАХОВАНИЕ ИП» или «ВЗНОСЫ НА ОПС ИП» или может не печататься
| 22 | --- | О страховых взносах на обязательное пенсионное страхование, уплачиваемых организациями и ИП, производящими выплаты и иные вознаграждения физическим лицам | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ ПЕНСИОННОЕ СТРАХОВАНИЕ» или «ВЗНОСЫ НА ОПС» или может не печататься
| 23 | --- | О страховых взносах на обязательное медицинское страхование, уплачиваемых ИП, не производящими выплаты и иные вознаграждения физическим лицам | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ МЕДИЦИНСКОЕ СТРАХОВАНИЕ ИП» или «ВЗНОСЫ НА ОМС ИП» или может не печататься
| 24 | --- | О страховых взносах на обязательное медицинское страхование, уплачиваемые организациями и ИП, производящими выплаты и иные вознаграждения физическим лицам | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ МЕДИЦИНСКОЕ СТРАХОВАНИЕ» или «ВЗНОСЫ НА ОМС» или может не печататься
| 25 | --- | О страховых взносах на обязательное социальное страхование на случай временной нетрудоспособности и в связи с материнством, на обязательное социальное страхование от несчастных случаев на производстве и профессиональных заболеваний | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ СОЦИАЛЬНОЕ СТРАХОВАНИЕ» или «ВЗНОСЫ НА ОСС» или может не печататься
| 26 | --- | О приёме и выплате денежных средств при осуществлении казино и залами игровых автоматов расчётов с использованием обменных знаков игорного заведения | «ПЛАТЕЖ КАЗИНО» или «ПК» или может не печататься
| 27 | --- | О выдаче денежных средств банковским платёжным агентом | «ВЫДАЧА ДЕНЕЖНЫХ СРЕДСТВ» или «ВЫДАЧА ДС» или может не печататься
| 30 | --- | О реализуемом подакцизном товаре, подлежащем маркировке средством идентификации, не имеющем кода маркировки | «АТНМ» или может не печататься
| 31 | --- | О реализуемом подакцизном товаре, подлежащем маркировке средством идентификации, имеющем код маркировки | «АТМ» или может не печататься
| 32 | --- | О реализуемом товаре, подлежащем маркировке средством идентификации, не имеющем кода маркировки, за исключением подакцизного товара | «ТНМ» или может не печататься
| 33 | --- | О реализуемом товаре, подлежащем маркировке средством идентификации, имеющем код маркировки, за исключением подакцизного товара | «ТМ» или может не печататься
Идентификатор используется в позиции корзины заказа в [методе создания заказа](/docs/merchant/order/create/#basketitem)
---
---
# Мера количества предмета расчёта (тег 2108)
# Мера количества предмета расчёта (тег 2108)
Таблица 114. Значения реквизита «мера количества предмета расчёта» (тег 2108)
Тег 2108 задаёт единицу измерения предмета расчёта в фискальном чеке. Перечень задан ФНС и **не
совпадает** со [справочником ОКЕИ](/docs/dictionary/okei) — тот используется в поле `measureCode`
позиции корзины, а сюда передают значение из первой колонки таблицы ниже.
Единица измерения позиции указывается при [создании заказа](/docs/merchant/order/create/#basketitem).
| Значение тега 2108 | Обозначение | Пояснение | № строки таблицы ФНС |
| --- | --- | --- | --- |
| 0 | шт. или ед. | Применяется для предметов расчёта, которые могут быть реализованы поштучно или единицами | 1 |
| 10 | г | Грамм | 2 |
| 11 | кг | Килограмм | 3 |
| 12 | т | Тонна | 4 |
| 20 | см | Сантиметр | 5 |
| 21 | дм | Дециметр | 6 |
| 22 | м | Метр | 7 |
| 30 | кв. см | Квадратный сантиметр | 8 |
| 31 | кв. дм | Квадратный дециметр | 9 |
| 32 | кв. м | Квадратный метр | 10 |
| 40 | мл | Миллилитр | 11 |
| 41 | л | Литр | 12 |
| 42 | куб. м | Кубический метр | 13 |
| 50 | кВт∙ч | Киловатт час | 14 |
| 51 | Гкал | Гигакалория | 15 |
| 70 | сутки | Сутки (день) | 16 |
| 71 | час | Час | 17 |
| 72 | мин | Минута | 18 |
| 73 | с | Секунда | 19 |
| 80 | Кбайт | Килобайт | 20 |
| 81 | Мбайт | Мегабайт | 21 |
| 82 | Гбайт | Гигабайт | 22 |
| 83 | Тбайт | Терабайт | 23 |
| -- | - | 255 | Применяется при использовании иных единиц измерения, не поименованных в п.п. 1-23
Для значений этого реквизита никаких логических проверок не предусмотрено и в составе чека ОФД будут
переданы те значения, которые поступили в карточках товаров. Если в карточке товара значение для
этого тега отсутствует, то для всех товаров автоматически будет передано в ОФД значение 0 (в печатной форме - шт./ед.).
---
---
# Ставка НДС (тег 1199)
# Ставка НДС (тег 1199)
> [!IMPORTANT]
> С 2026 года основная ставка НДС — **22 %**. В примерах документации стоят коды `RUS_VAT22`
> (налог в цене, расчётная 22/122) и `RUS_VAT22_ADDED` (налог сверх цены) — это не опечатка вместо 20 %.
> Ставки прошлых лет остались в таблице: они нужны для возвратов и корректировок по старым заказам.
Ставка передаётся кодом Инвойсбокса в поле `vatCode` позиции корзины при
[создании заказа](/docs/merchant/order/create/#basketitem).
Таблица 8. Значения реквизита «Ставка НДС» (тег 1199)
| Наименование ставки НДС | Значение реквизита | Формат ПФ | Код Инвойсбокс | Комментарий |
|-------------------------| ------------------ |------------|-----------------| --------------------------------------------------------- |
| ставка НДС 20% | 1 | НДС 20% | RUS_VAT20_ADDED | |
| ставка НДС 10% | 2 | НДС 10% | RUS_VAT10_ADDED | |
| ставка НДС расч. 20/120 | 3 | НДС 20/120 | RUS_VAT20 | |
| ставка НДС расч. 10/110 | 4 | НДС 10/110 | RUS_VAT10 | |
| ставка НДС 0% | 5 | НДС 0% | RUS_VAT0 | |
| НДС не облагается | 6 | - | VATNONE | |
| ставка НДС 5% | 7 | НДС 5% | RUS_VAT5_ADDED | введена приказом ФНС России № ЕД-7-20/1038 от 15.11.2024 |
| ставка НДС 7% | 8 | НДС 7% | RUS_VAT7_ADDED | введена приказом ФНС России № ЕД-7-20/1038 от 15.11.2024 |
| ставка НДС расч. 5/105 | 9 | НДС 5/105 | RUS_VAT5 | введена приказом ФНС России № ЕД-7-20/1038 от 15.11.2024 |
| ставка НДС расч. 7/107 | 10 | НДС 7/107 | RUS_VAT7 | введена приказом ФНС России № ЕД-7-20/1038 от 15.11.2024 |
| ставка НДС 22% | 11 | НДС 22% | RUS_VAT22_ADDED | введена законопроектом № 1026190-8 от 28.11.2025 |
| ставка НДС расч. 22/122 | 12 | НДС 22/122 | RUS_VAT22 | введена законопроектом № 1026190-8 от 28.11.2025 |
## В чём разница между ставками НДС 22% и 22/122, 10% и 10/110, 7% и 7/107, 5% и 5/105?
### Обычные ставки (22%, 10%, 0% и т.д.)
Когда использовать: Когда вы знаете цену товара БЕЗ НДС и вам нужно начислить (добавить) налог сверху.
Как считать: Цена без НДС × Ставка
Пример: Стулья стоят 1000 рублей без НДС. Ставка — 22%.
- НДС = 1000 × 22% = 220 рублей.
- Цена для покупателя = 1000 + 220 = 1220 рублей.
### Расчётные ставки (22/122, 10/110 и т.д.)
Когда использовать: Когда у вас на руках итоговая сумма, в которую НДС УЖЕ ВКЛЮЧЁН, и вам нужно "вытащить" (выделить) из неё сумму налога.
Как считать: Сумма с НДС × (Расчётная ставка)
Пример: Вы получили аванс от клиента 1200 рублей за будущую поставку стульев. В этой сумме уже сидит НДС. Нужно понять, сколько из этих 1200 рублей - это сам налог.
- НДС = 1200 × (22/122) = 216.39 рублей.
- Значит, аванс без НДС = 1200 - 216.39 = 983.61 рублей.
### Простая аналогия
Представьте торт 🥧.
- Обычная ставка - это когда у вас есть корж (цена без налога), и вы сверху намазываете крем (НДС).
- Расчётная ставка - это когда перед вами целый торт (цена с налогом), и вам нужно аккуратно снять с него крем, чтобы понять, сколько крема было.
22% - чтобы добавить налог к чистой цене. 22/122 - чтобы найти налог внутри итоговой суммы. То же самое для ставок 10% и 10/110.
## В чём разница между ставками НДС 0% и «НДС не облагается?
Ставка НДС 0% и статус «НДС не облагается» - это не одно и то же. Ставка 0% - это льгота для плательщиков налога (например, при экспорте),
которая позволяет не только не начислять НДС клиенту, но и вернуть себе весь «входной» НДС, уплаченный поставщикам, при выполнении условий.
А операции, которые «не облагаются» НДС (например, медицинские услуги), полностью выведены из-под этого налога: налог с клиента не берётся,
но и вернуть «входной» НДС по таким операциям уже нельзя - он включается в расходы.
См. также: [создание заказа](/docs/merchant/order/create/)
---
---
# Справочники
# Справочники
В текущем разделе описаны базовые справочники.
---
# Коды ошибок
# Коды ошибок
Ошибка приходит в свойстве `error` объекта ответа — см.
[структуру ответа](/docs/api/#структура-ответа). Перечень пополняется: незнакомый `code` обрабатывайте
по HTTP-коду, а не игнорируйте.
## Авторизация и доступ
| Код ошибки | HTTP | Что произошло | Что делать |
|---|---|---|---|
| `unauthorized` | 401 | Токен не передан или не распознан | Проверить заголовок `Authorization: Bearer <токен>` — [авторизация](/docs/api/auth/) |
| `forbidden` | 403 | Доступ к ресурсу или объекту запрещён | Проверить, принадлежит ли объект вашему магазину и есть ли у токена нужные права |
## Проверка заказа (422)
Все эти ошибки означают, что запрос дошёл и разобран, но данные не сходятся. Правило подсчёта сумм —
в разделе [как считаются суммы](/docs/merchant/order/create/#как-считаются-суммы).
| Код ошибки | Что произошло | Что делать |
|---|---|---|
| `wrong_expiration_date` | Неверный срок действия заказа | Проверить `expirationDate`: время в будущем, формат с часовым поясом |
| `wrong_currency` | Неверная валюта | Проверить `currencyId` |
| `language_not_found` | Неверный язык заказа | Проверить `languageId`: `ru` или `en` |
| `wrong_basket_item_total_amount` | Итог позиции не сходится | `totalAmount` позиции = `quantity × amount` |
| `wrong_basket_item_total_vat_amount` | НДС позиции не сходится | Пересчитать `totalVatAmount` по ставке из `vatCode` |
| `wrong_basket_item_amount_wo_vat` | Стоимость позиции без НДС не сходится | Проверить `amountWoVat` для одной единицы |
| `wrong_total_amount` | Сумма заказа не равна сумме позиций | `amount` заказа = сумма `totalAmount` позиций |
| `wrong_total_vat_amount` | Сумма НДС заказа не равна сумме НДС позиций | `vatAmount` заказа = сумма `totalVatAmount` позиций |
| `wrong_order_status` | Операция недопустима в текущем статусе | Посмотреть статус заказа и разрешённые переходы — [работа с заказом](/docs/merchant/order/) |
| `merchant_order_id_duplicate` | Такой `merchantOrderId` уже использовался. Приходит, только если у магазина включена проверка уникальности (настройка меняется через поддержку) | Заказ с этим номером уже создан — найдите его выборкой и работайте с ним. Новый номер генерировать не нужно: так появится второй заказ на ту же покупку. См. [повтор после сбоя](/docs/merchant/order/create/#повтор-после-сбоя-и-таймаута) |
## Технические
| HTTP | Что произошло | Что делать |
|---|---|---|
| 429 | Слишком много запросов | Снизить частоту и повторить с задержкой — [ограничения](/docs/api/limits/). Тело может не содержать `code` |
| 500 | Необработанная ошибка на стороне сервиса | Результат операции неизвестен: запрос мог дойти. Чтение можно повторить сразу; после создания заказа, возврата или отмены сначала проверьте выборкой, прошла ли операция, — [повтор после сбоя](/docs/merchant/order/create/#повтор-после-сбоя-и-таймаута). Сообщите нам `x-request-id` из заголовков ответа. Тело может не содержать `code` |
---
---
# Дизайн-система
# Дизайн-система Инвойсбокс
Дизайн-система Инвойсбокс — это набор готовых элементов, компонентов и стандартизированные правила
использования. Дизайнер и фронтендер получают инструмент, который упрощает работу и экономит время.
Продакт-менеджеру проще проверять гипотезы, а команде быстрее реализовывать MVP.
### Библиотека компонентов
Библиотека `invoicebox-ui` содержит ready-to-use компоненты для создания мини-приложений.
- NPM: [invoicebox-ui](https://www.npmjs.com/package/@invoicebox/ui)
- GitHub: [invoicebox-ui](https://github.com/InvoiceBox/invoicebox-ui)
- Документация с примерами: [invoicebox-ui](https://ui.invoicebox.ru)
## Читайте также
- [Где применяется: мини-приложения маркетплейса](/docs/marketplace/mini-apps/)
---
# Термины и определения
# Термины и определения
Термины ниже связаны между собой, и связи важнее самих определений: заказ создаёт магазин, счёт
объединяет заказы, транзакция зачисляется в пользу счёта. Схема показывает эти связи целиком.
Магазин создаёт заказ, состав заказа — корзина, заказ входит в счёт, счёт оплачивает плательщик,
поступление денег фиксируется транзакцией, а отгрузка закрывает заказ и служит основанием для
документов.
Один счёт может объединять несколько заказов — так работает
[группа заказов](/docs/merchant/order/create-order-container/) у маркетплейсов. Покупатель и плательщик
совпадают не всегда: заказ оформляет сотрудник, а платит его организация.
## Система и API
- **Система** — сервис «Инвойсбокс»: принимает оплату от юрлиц и ИП и готовит закрывающие документы
- **API** — программный интерфейс для взаимодействия с Системой
## Магазин и его люди
- **Магазин (Merchant)** — веб-сайт, торгово-сервисное предприятие или иная точка продажи товаров или услуг, поставщики товаров и услуг, принимающее оплату через систему Инвойсбокс
- **Контрагент Магазина (Merchant counterparty)** — частное лицо или организация, которому принадлежит Магазин
- **Личный кабинет (Merchant office)** — личный кабинет Магазина, в котором возможно формировать Заказы, просматривать Транзакции и оформлять Возвраты по переводам, совершенным в системе Инвойсбокс
- **Сотрудник Магазина (Merchant employee)** — представитель Контрагента Магазина, имеющий доступ в Личном кабинете к одному или нескольким Магазинам
## Договор
- **Договор (Contract)** — соглашение, заключенное с определенной даты и на определенный период, определяющее финансовые и иные взаимоотношения между Контрагентами в системе Инвойсбокс
## Заказ и корзина
- **Заказ (Order)** — заказ, сформированный Магазином и переданный в систему Инвойсбокс через API или личный кабинет
- **Корзина (Basket)** — набор сведений о товарах и услугах, их количестве, стоимости, облагаемом налоге, входящие в Заказ
- **Заказчик/Покупатель (Customer)** — частное лицо или организация указанные в Заказе
## Счёт и плательщик
- **Счёт (Invoice)** - счёт, сформированный для оплаты в системе Инвойсбокс, в который входят один или несколько Заказов
- **Плательщик (Payer)** - частное лицо или организация, которому был выставлен Счёт
## Деньги и платёжные инструменты
- **Транзакция (Transaction)** — информация о поступлении оплаты (перевода)/движении денежных средств от Фактического Плательщика в пользу Счёта
- **Обещанный платёж** - сервис для юридических лиц и ИП (платёжный инструмент Инвойсбокс) позволяющий подтверждать оплату заказа с отсрочкой оплаты по счёту
- **Гарантийный фонд** - сервис (платёжный инструмент Инвойсбокс), позволяющий юридическим лицам и ИП моментально подтверждать оплату заказа, используя заранее перечисленные деньги на специальный счёт
- **Овердрафт** - сервис в рамках платёжного инструмента Инвойсбокс **Гарантийный фонд**, позволяющий юридическим лицам и ИП моментально подтверждать оплату заказа на сумму, сверх суммы гарантийного фонда
## Отгрузка
- **Отгрузка (Shipment)** - факт оказания услуги или отгрузки товара Мерчантом (или грузоотправителем) по Заказу
## Платёжная страница
- **Платёжная страница (Payment page)** - пользовательский интерфейс системы Инвойсбокс в котором Плательщик формирует Счёт, выбирает способы оплаты
---
---
# Сроки и условия расчётов
# Сроки и условия расчётов
Сроки выплат, отсрочки и возвратов встречаются в кейсах и справочнике по частям — рядом с той механикой,
о которой идёт речь. Эта страница собирает их в одном месте, чтобы не искать по разделам.
> [!IMPORTANT]
> Цифры ниже описывают типовую схему. Конкретные сроки, тарифы и лимиты фиксируются в договоре
> с вашей организацией и могут отличаться. Уточняйте у менеджера — документация не заменяет договор.
## Деньги продавцу
| Что | Типовой срок | Где описано |
|---|---|---|
| Перечисление оплаченных заказов | на следующий рабочий день после подтверждения оплаты | [гостиницы](/docs/scenarios/pms), [рестораны](/docs/scenarios/ras), [АЗС](/docs/scenarios/gas) |
| Вознаграждение партнёра или площадки | вместе с расчётом по заказам | [схема с комиссией](/docs/merchant/schema/commission/) |
Выплаты идут консолидированным платежом: за день собираются все оплаченные заказы, и на счёт приходит
одна сумма. Разбивка по заказам доступна в личном кабинете и через
[получение заказов](/docs/merchant/order/get/).
## Кто платит комиссию
Комиссию за приём оплаты можно оставить продавцу, разделить между продавцом и покупателем в нужной
пропорции или полностью переложить на покупателя — тогда в счёте она идёт отдельной строкой. Условие
фиксируется в договоре и настраивается при подключении, в запросах на создание заказа ничего менять не
нужно.
## Срок оплаты счёта покупателем
| Что | Типовой срок | Где описано |
|---|---|---|
| Срок жизни счёта | задаёт магазин полем `expirationDate` при [создании заказа](/docs/merchant/order/create/) | от минуты до недель |
| Отсрочка для постоянных корпоративных клиентов | до 30 дней | [авиаперевозчики](/docs/scenarios/air-carriers), [склады и аренда](/docs/scenarios/warehouses) |
| Тайм-лимит бронирования | равен сроку удержания места у перевозчика | [авиа](/docs/scenarios/air-carriers), [ж/д](/docs/scenarios/railway-carriers) |
Неоплаченный счёт с истёкшим сроком можно [отменить](/docs/merchant/order/delete/) — бронь или товар
освободятся под следующего покупателя.
## Возвраты
| Что | Типовой срок | Где описано |
|---|---|---|
| Возврат покупателю после уведомления от магазина | до двух рабочих дней, зависит от способа оплаты | [возвраты](/docs/merchant/refund/) |
| Возврат с удержанием части суммы | тот же срок, удержание остаётся в документах | [возврат с корректировкой](/docs/merchant/refund/correction/) |
## Документы
Закрывающие документы — акт, счёт-фактура, УПД — формируются автоматически после оплаты и уходят
корпоративному покупателю [по каналам ЭДО](/docs/merchant/documentflow/). Фискальный чек регистрируется
в [онлайн-кассе](/docs/merchant/fz54/) в момент оплаты.
> [!TIP]
> Если сроки в вашем договоре отличаются от типовых, ориентируйтесь на договор, а в интеграции
> используйте `expirationDate`: он задаёт срок оплаты для конкретного заказа и не зависит от общих условий.
---
# Политики безопасности
# Соблюдение безопасности при работе с API
Используя описанный протокол взаимодействия, Магазин должен следовать правилам защиты информации.
### Уведомления о переводах
Мы настоятельно рекомендуем в ссылках для получения любых уведомлений использовать защищённое соединение
SSL/TLS безопасных версий.
### Целостность и аутентичность запросов
Для проверки целостности и аутентичности запросов, в ходе взаимодействия с системой «Инвойсбокс»
могут быть использованы различные механизмы. [Базовый вариант](/docs/merchant/notification/status/#%D0%BF%D0%BE%D0%B4%D0%BF%D0%B8%D1%81%D1%8C-%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D0%B0)
с использованием sha1-хеширования используется по умолчанию.
Для поддержания более высоких требований к безопасности, взаимодействие может идти
с использованием клиентских и серверных 🔒 сертификатов (включая ГОСТ-2012), в том числе самоподписных,
сформированных центрами сертификации магазина или системы «Инвойсбокс». В случае взаимодействия с использованием
сертификатов, необходимо проверять подлинность веб-сервисов системы «Инвойсбокс», сохранять конфиденциальность
приватных ключей, следить за сроком действия сертификатов. В случае компрометации приватного ключа необходимо незамедлительно
уведомить службу поддержки системы «Инвойсбокс».
## Читайте также
- [Токен хранится в секретах и меняется в личном кабинете](/docs/api/auth/)
## Что подготовить на сайте
| Страница | Зачем нужна |
|---|---|
| Страница с виджетом | здесь стоит код и покупатель вводит свои данные; подойдёт любая, даже главная |
| Страница завершения | сюда виджет вернёт покупателя и после успешной оплаты, и после неудачной. Её адрес указывается в настройках виджета — полезно описать на ней, что делать дальше |
## Настройки виджета
Все параметры задаются в [конструкторе](/widgets/constructor/); ниже — что каждый из них меняет. Если код виджета придётся править руками — например, подставлять номер заказа из своей системы, — смотрите [справочник параметров](/widgets/reference/): там перечислены поля кода, состав заказа и значения, которые они принимают.
| Настройка | Что задаёт | Когда нужна |
|---|---|---|
| Что оплачивают | заранее заданный состав заказа либо свободная сумма | состав — для товаров и услуг с известной ценой; свободная сумма — для пополнения баланса и абонентской платы |
| Текст на кнопке | подпись кнопки виджета | набор текстов расширяется по запросу в [поддержку](https://www.invoicebox.ru/ru/contacts) |
| Дополнительные поля | что покупатель заполнит сам: номер заказа, фамилия и имя, телефон, почта, количество | хотя бы одно из двух — почта или телефон — обязательно: по ним уходят счёт и документы |
| Тип плательщика | физическое лицо, организация или ИП, выбор покупателем | для оплаты от организаций и ИП выбирайте второй вариант: тогда формируется счёт и закрывающие документы |
| Код товара или услуги | ваш идентификатор заказа, договора или артикула | обязателен: по нему вы узнаёте платёж в своей системе |
| Ссылка возврата | адрес страницы завершения оплаты | заполняется всегда, иначе покупателю некуда вернуться |
| Оплачиваемые позиции | название, количество, цена и ставка НДС каждой позиции | минимум одна позиция; ставки — в [справочнике](/docs/dictionary/tag1199/) |
| Выбор одной позиции | покупатель выбирает один вариант из списка | удобно для тарифов: перечислите варианты, покупатель отметит нужный |
| Открывать в новом окне | форма открывается в новой вкладке или в текущей | снимите отметку, если хотите оставить покупателя на странице |
## Что важно знать до вставки
Сумма и состав заказа приходят из браузера покупателя и не подписаны — их можно изменить в браузере
до отправки. Это осознанное упрощение ради быстрого старта, но оно накладывает обязанность: получив
[уведомление об оплате](/docs/merchant/notification/status/), сверяйте сумму с той, которую ожидали.
Если цену определяет только ваш сервер, надёжнее создавать заказы
[через API](/docs/merchant/order/create/). Подробно — [Безопасность виджета](/widgets/security/).
Прежний конструктор на [widget.invoicebox.ru](https://widget.invoicebox.ru/?utm_source=docs)
продолжает работать: код, собранный там и в конструкторе портала, одинаковый.
### Примеры виджетов
Ниже — живые виджеты в песочнице портала: та же форма, что увидит покупатель на вашем сайте.
Собраны они на демо-магазине документации, поэтому оплата ничего не спишет. Свой виджет
собирается в [конструкторе](/widgets/constructor/) — настройки слева, код справа.
**Счёт организации или ИП.** Состав задан заранее, покупатель вводит только реквизиты. Так выставляют счёт за услуги по договору.
**Оплата товара с количеством.** Покупатель меняет количество, сумма пересчитывается на месте.
**Выбор из нескольких позиций.** Покупатель выбирает тариф или товар из списка.
**Пополнение баланса.** Сумму вводит покупатель — подходит для депозитов и абонентской платы.
---
---
# Модули для CMS
# Готовые модули для CMS
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей для платформ с открытым исходным кодом.
| Система управления сайтом (CMS) | Версия | Лицензия CMS/Модуля | Детали
|------------------------------------------------------------------|---------------|-------------------------------| ---------------------------------
| | > 16.x | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/1c-bitrix/)
| | > 1.2.x | Платная | [Смотреть »](/docs/merchant/cms/aspro/)
| | > 6.1.x | Бесплатный | [Смотреть »](/docs/merchant/cms/woocommerce/)
| | Все | Условно-бесплатный/Бесплатный | [Смотреть »](/docs/merchant/cms/tilda/)
| | InSales | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/insales/)
| | VirtualityCMS | Платная/Бесплатный | [Смотреть »](/docs/merchant/cms/vicms/)
| | --- | --- |
| | --- | --- |
| | --- | --- |
| | --- | --- |
| | --- | --- |
| | --- | --- |
| | > 5.* | Бесплатный |[Смотреть »](/docs/merchant/cms/joomshopping/)
| | Virtuema rt | Бесплатный |[Смотреть »](/docs/merchant/cms/virtuemart/)
| | --- | --- |
| | --- | --- |
| | 2.X | Бесплатный |[Смотреть »](/docs/merchant/cms/opencartv2/)
| | 3.X | Бесплатный |[Смотреть »](/docs/merchant/cms/opencartv3/)
| | --- | --- |
| | 8.X | Бесплатный |[Смотреть »](/docs/merchant/cms/prestashop/)
| | --- | --- |
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
## Читайте также
- [Требования к разработке расширений](/docs/merchant/cms/requirements/)
---
# Получение отгрузки
# Получение отгрузки
Отгрузки читаются одним запросом:
- метод: `GET`
- ресурс: `/v3/billing/api/order/shipment`
- тело ответа - коллекция объектов [ShipmentResponse](/docs/merchant/order/shipment_create/#shipmentresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
В запросе можно применять фильтры и сортировку.
#### Пример запроса и ответа
```http
GET /v3/billing/api/order/shipment?id=371723
```
Пример запроса с фильтром по id заказа
```http
GET /v3/billing/api/order/shipment?orderId=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по id магазина
```http
GET /v3/billing/api/order/shipment?merchantId=21827364-196a-1178-839a-82469489d6d7
```
---
Ответ:
``` json
{
"data": [
{
"id": 616095,
"orderId": "019e51e2-3970-9852-e8c8-803c16ac9c74",
"merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"basketItems": [
{
"sku": "baaa27aee304c4",
"name": "Мягкая игрушка Винни Пух",
"measure": "шт",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 1,
"amount": 14162,
"amountWoVat": 11608.2,
"totalAmount": 14162,
"totalVatAmount": 2553.8,
"vatCode": "RUS_VAT22",
"type": "commodity",
"paymentType": "full_payment"
}
],
"createdAt": "2026-05-22T23:10:55+00:00",
"type": "shipment",
"status": "completed",
"amount": 14162,
"vatAmount": 2553.8,
"final": true
}
]
}
```
---
# Модули для CRM
# Готовые модули для CRM
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей для платформ с открытым исходным кодом.
| Система управления клиентами (CRM) | Версия | Лицензия CRM/Модуля | Детали
|-----------------------------------------------|------------|---------------------| ---------------------------------
|  | любая | Платная/Бесплатный | [Смотреть »](/docs/merchant/crm/amocrm/)
|  | любая | Платная | [Смотреть »](/docs/merchant/crm/sportcrm/)
|  | любая | Платная/Бесплатный | [Смотреть »](/docs/merchant/crm/retailcrm/)
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
---
# Изменение отгрузки
# Изменение отгрузки
Отгрузка меняется по своему идентификатору:
- метод: `PUT`
- ресурс: `/v3/billing/api/order/shipment/:uuid` - где `:uuid` это идентификатор отгрузки
> [!NOTE]
> Идентификатор заказа при изменении не передаётся — отгрузка уже связана с заказом. Признак завершающей отгрузки задаётся при создании.
- тело запроса - объект [UpdateShipmentRequest](#updateshipmentrequest)
- тело ответа - объект [ShipmentResponse](#shipmentresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/shipment/{id}
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"amount": 100.5,
"vatAmount": 100.5,
"documentNumber": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": 1,
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"createdAt": "2026-08-03T12:00:00+03:00",
"type": "string",
"status": "draft",
"amount": 100.5,
"vatAmount": 100.5,
"final": false,
"documentNumber": "string",
"description": "string",
"documentDate": "2026-08-03T12:00:00+03:00"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## UpdateShipmentRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------------------------------|---------------------------------------------------------|----------------------------------------|
| documentNumber | нет | string(36) | Номер документа (накладная, счёт-фактура и пр.) | `123` |
| documentDate | нет | date | Дата документа | `2023-12-12` |
| basketItems | да | array of [BasketItem](#basketitem) | Корзина заказа | |
| type | нет | string, enum | Тип отгрузки, по умолчанию `shipment` | `shipment`, `cancel` |
## ShipmentResponse
Повторяет свойства объекта [CreateShipmentRequest](#updateshipmentrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|------------|-------------------------------------------------|-----------------------------------------|
| id | да | int | Идентификатор отгрузки в системе Инвойсбокс | `2` |
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76 ` |
## BasketItem
Корзина заказа. Пожалуйста, внимательно ознакомьтесь с требованиями по [заполнению наименования номенклатуры](/docs/merchant/fz54).
| Свойство | Обязательное | Тип | Описание |
|-------------------|--------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sku | да | string(500) | Артикул, например: `5fe0adcfa7fb4` |
| name | да | string(500) | Наименование, например `Бронирование номера` |
| groupName | нет | string(500) | Наименование группы позиций заказа, используется для формирования отчетных документов |
| measure | да | string(10) | Единица измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `шт.` |
| measureCode | да | string(4) | Код единицы измерения (для России - по [ОКЕИ](/docs/dictionary/okei/)), например `796` |
| originCountry | нет | string(20) | Страна происхождения товара, например, `Россия` |
| originCountryCode | нет | string(4) | Код страны происхождения, например, Россия `643` |
| grossWeight | нет | float | Вес брутто, например `125.45` |
| netWeight | нет | float | Вес нетто, например `125.45` |
| quantity | да | float | Количество, например `3` |
| amount | да | float | Стоимость единицы, например `100.55` |
| amountWoVat | да | float | Стоимость единицы без учёта НДС |
| totalAmount | да | float | Стоимость всех единиц с НДС, например`123.55` |
| totalVatAmount | да | float | Итого сумма НДС, например `23` |
| excise | нет | float | Сумма акциза, например, `10.00` |
| vatCode | да | string(20) enum | Код процента НДС, допустимые значения: `VATNONE` - не облагается,`VATNONE` - не облагается, `RUS_VAT0` - 0%, `RUS_VAT10` - 10/110, `RUS_VAT10_ADDED` - 10%, `RUS_VAT20` - 20/120, `RUS_VAT20_ADDED` - 20% `RUS_VAT22` - 22/122, `RUS_VAT22_ADDED` - 22% |
| type | да | string(10) или int | Тип позиции, [в соответствии со справочником](/docs/dictionary/tag1212) или service - сервис, commodity - товар |
| paymentType | да | string(20) enum | Тип оплаты, допустимые значения: `full_prepayment`, `prepayment`, `advance`, `full_payment` |
| metaData | нет | object | [Дополнительные данные элемента корзины](/docs/merchant/order/metadata/) |
---
---
# Virtuemart
# Virtuemart (joomla)
Расширение Virtuemart для Joomla предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает 1 режим работы, API «Инвойсбокс» версии 2
> [!NOTE]
> Модуль работает по API версии 2. Вторая версия поддерживается, но для новых магазинов
> рекомендуется третья — см. [Приём платежей](/docs/merchant/). Версию своего подключения уточните
> у персонального менеджера.
Для модуля необходима версия joomla 3+, но рекомендуется использовать 4ую и выше.
Скачать модуль можно по этой [ссылке](https://github.com/InvoiceBox/Virtuemart-3)
Также полезно будет установить [русификатор для расширения](https://virtuemart.net/community/translations/virtuemart/ru-RU)
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Устанавливается расширение через админ панель, в пункте "загрузить и установить"
1. Перейдите в компонент "Virtuemart" —> "Способы оплаты";
2. Добавьте новый метод оплаты "Invoicebox" и заполните поля. Нажмите «Сохранить»;
3. Зайти в раздел Администрирование -> Способы оплаты, добавить новый метод оплаты с процессором invoicebox;
4. Заполнить настройки на вкладке "Общее";
5. Перейдите во вкладку "Конфигурация" и заполните следующие поля:
- "Идентификатор магазина"
- "Региональный код магазина"
- "Ключ безопасности магазина"
6. Выберите необходимые статусы заказа;
7. Нажмите на кнопку "Сохранить".
### Настройка в личном кабинете Инвойсбокс
Без этого шага магазин не узнает об оплате: заказ так и останется неоплаченным в панели управления,
даже если деньги пришли.
1. Войдите в личный кабинет и откройте «Мои продажи» → «Мои магазины» → «Интеграция (API)».
2. Выберите тип уведомления — уведомление о смене статуса заказа.
3. В поле «URL уведомления» укажите адрес обработчика модуля на вашем сайте. Адрес показывает сам
модуль в своих настройках; он должен быть доступен снаружи и работать по HTTPS.
4. Сохраните изменения.
Как устроено уведомление и как проверить подпись — [Уведомление о смене статуса
заказа](/docs/merchant/notification/status/).
## Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Принятая валюта - выберите валюту рубли.
Страны - если этот параметр не важен, не изменяйте его, если вы продаете на несколько стран, то возможно вам стоит ограничить показать платежного плагина, и выбрать только для "России".
Минимальная сумма - минимальная сумма заказа, при которой возможен платеж данным платежным плагином.
Максимальная сумма - максимальная сумма заказа, при которой возможен платеж данным платежным плагином.
Плата за транзакцию - дополнительный фиксированный сбор при выборе данного платежного метода.
Плата или возврат процента от общей суммы - дополнительный сбор в процентах при выборе данного платежного метода.
Налог - налоговые правила для данного платежного метода.
---
# Модули для ERP
# Готовые модули для ERP-систем
Обращаем ваше внимание, что представленный перечень неполный и содержит только наиболее
актуальные варианты модулей.
| ERP-система | Версия | Лицензия ERP/Модуля | Детали
| ---------------------------------------| ---------| ------------------------------------------------------- | ---------------------------------
|  | >= 7.9.7 | Платная/Платный/Наличие лицензии api payment (21016318) | [Смотреть »](/docs/merchant/erp/iiko/)
|  | --- | Платная/Платный | [Смотреть »](/docs/merchant/erp/bnovo/)
Если вы не нашли подходящий, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы поможем подобрать необходимый модуль.
---
# Смена магазина
Для управления выплатами и реквизитами, по которым их следует осуществить,
вы можете воспользоваться методом смены магазина. Изменить магазин можно как
у оплаченного заказа, так и у не оплаченного. При этом, изначальный магазин
должен иметь специальный тип, позволяющий в дальнейшем вносить такие изменения
в заказ.
- метод: `PUT`
- ресурс: `/v3/billing/api/order/order/order-merchant-move`
- тело запроса - объект [UpdateOrderMerchantRequest](#updateordermerchantrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/order/order-merchant-move
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"orderId": "01771534-1a57-f184-dee3-ebeb91dded75"
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75",
"description": "string",
"currencyId": "RUB",
"amount": 100.5,
"vatAmount": 100.5,
"basketItems": [
{
"sku": "string",
"name": "string",
"groupName": "string",
"measure": "string",
"measureCode": "string",
"originCountry": "string",
"originCountryCode": "string",
"grossWeight": 100.5,
"netWeight": 100.5,
"quantity": 100.5,
"amount": 100.5,
"amountWoVat": 100.5,
"totalAmount": 100.5,
"totalVatAmount": 100.5,
"vatCode": "RUS_VAT22",
"type": "string",
"gtdNumber": "string",
"paymentType": "string",
"excise": 100.5,
"metaData": {},
"tnved": "string",
"rnpt": "string",
"gtin": "string",
"category": "string",
"categoryType": "string",
"serviceDate": "2026-08-03T12:00:00+03:00"
}
],
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"status": "string",
"shipmentStatus": "string",
"subtype": "string",
"processingStatus": "string",
"createdAt": "2026-08-03T12:00:00+03:00",
"merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"merchantOrderIdVisible": "string",
"expirationDate": "2026-08-03T12:00:00+03:00",
"metaData": {},
"customerData": {},
"notificationUrl": "string",
"orderSetting": {
"roundPolicy": "string",
"disableValidate": false
},
"internalProperty": {
"guarantee": false,
"hold": false,
"rtp": false,
"agent": false,
"rtpExternal": false
},
"tags": {},
"shopId": 1,
"sourceId": "l3",
"paidAt": "2026-08-03T12:00:00+03:00",
"parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
"returnUrl": "string",
"successUrl": "string",
"failUrl": "string",
"paymentUrl": "string",
"paymentUrlType": "redirect",
"paymentPageUrl": "string",
"customer": {
"type": "string",
"name": "string",
"phone": "string",
"email": "string",
"vatNumber": "string",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"registrationAddress": "string",
"taxRegistrationReasonCode": "string"
},
"languageId": "01771534-1a57-f184-dee3-ebeb91dded75",
"contactId": 1,
"contactCounterpartyId": 1,
"processable": false,
"userAccountId": "01771534-1a57-f184-dee3-ebeb91dded75",
"invoiceSetting": {
"customerLocked": false,
"customerLockedFields": {},
"customerHiddenFields": {},
"paymentMethodIdLocked": false,
"paymentMethodId": 1,
"savePaymentData": false,
"clientId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentToken": "string",
"paymentMethodCode": "string",
"paymentMethodAutosubmit": false,
"bankDetailId": 1
},
"orderContainerId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentInfo": {},
"holdTill": "2026-08-03T12:00:00+03:00",
"additionalOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
"shipmentTotalAmount": "string",
"shipmentTotalVatAmount": "string"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## UpdateOrderMerchantRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|-----------------|-------------------------------------------|----------------------------------------|
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76` |
| orderId | да | string(36) | Идентификатор заказа в системе Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded75` |
---
---
# Joomshopping
# JoomShopping
Расширение JoomShopping для Joomla предоставляет простую возможность подключить ваш интернет-магазин к системе оплаты «Инвойсбокс».
Модуль поддерживает 1 режим работы, API «Инвойсбокс» версии 2
> [!NOTE]
> Модуль работает по API версии 2. Вторая версия поддерживается, но для новых магазинов
> рекомендуется третья — см. [Приём платежей](/docs/merchant/). Версию своего подключения уточните
> у персонального менеджера.
Для модуля необходима версия Joomla 3+, но рекомендуется использовать 4ую и выше.
Скачать модуль можно по этой [ссылке](https://github.com/InvoiceBox/JoomShopping-4)
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка плагина
В админ-панели пройдите в "Компоненты" —> "JoomShoppping" —> "Установка и Обновление". Выберите файл "invoicebox_joomshoppping_5.zip" и нажмите на кнопку "Загрузить".
## Настройка модуля
1. Перейдите в компонент "JoomShoppping" —> "Опции" —> "Способ оплаты";
2. Выберите способ оплаты "InvoiceBox" (Инвойсбокс) и перейдите во вкладку "Конфигурация" и заполните следующие поля:
- "Идентификатор магазина"
- "Региональный код магазина"
- "Ключ безопасности магазина"
3. Выберите необходимые статусы заказа в опции "Статус заказа для успешных транзакций";
4. Нажмите на кнопку "Сохранить".
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
Изображения URL - ссылка на картинку, которая выводится вместе с платежной системой.
Цена - дополнительный сбор (в процентах или фиксированная сумма) при выборе данного платежного метода.
Выберите налог - налоговые правила для данного платежного метода.
### Настройка панели Инвойсбокс:
1. Для настройки панели управления Инвойсбокс, перейдите по [ссылке](https://login.invoicebox.ru/)
2. Авторизуйтесь и пройдите в раздел "Мои магазины". "Начало работы" -> "Настройки" -> "Мои магазины";
3. Пройдите по вкладку "Уведомления по протоколу" -> выберите "Тип уведомления" "Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных)"
4. В поле "URL уведомления" укажите:
`<домен_сайта>/index.php?option=com_jshopping&controller=checkout&task=step7&act=notify&js_paymentclass=pm_invoicebox&no_lang=1&tmpl=component`
5. Сохраните изменения.
---
# Смена статуса заказа
Изменение статуса возможно только у [не процессинговых заказов](/docs/merchant/order/non-processable-order/),
а именно у заказов со свойством `processable = false`. Для изменения статуса, вы можете воспользоваться соответствующим
методом.
- метод: `PUT`
- ресурс: `/v3/billing/api/order/:uuid/status` - где `:uuid` это идентификатор заказа
- тело запроса - объект [UpdateOrderStatusRequest](#updateorderstatusrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
#### Пример запроса и ответа
``` json
PUT /v3/billing/api/order/c5041a79-24a6-42d1-b0ce-4abb94982cd9/status
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"status": "completed"
}
```
Ответ:
``` json
{
"data": {
"id": "c5041a79-24a6-42d1-b0ce-4abb94982cd9",
"merchantOrderId": "O-12345",
"status": "completed",
"amount": 19658.45,
"currencyId": "RUB",
"paidAt": "2026-08-01T12:31:00+03:00"
}
}
```
## UpdateOrderStatusRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------|--------------|------------|-------------------------------------------|---------------------------------------------------|
| status | да | enum(4) | Статус заказа | `created`, `completed`, `expired`, `canceled` |
---
---
# Интеграции с PSS/GDS
# Готовые интеграции с PSS/GDS
Обращаем ваше внимание, что представленный перечень отлаженных интеграций неполный и содержит только наиболее актуальные варианты.
| PSS/GDS | Наименование | Детали
| ------------------------------------| ---------------------------| --------------------------------------------
|  | Сирена-Тревел/МПС (EgoPay) | [Смотреть »](/docs/merchant/pss/mps/)
|  | ТАИС TravelShop | [Смотреть »](/docs/merchant/pss/tais/)
Если вы не нашли подходящую интеграцию, [напишите нам](https://www.invoicebox.ru/ru/contacts) и мы
поможем вам соориентироваться.
---
# InSales
# Расширение Инвойсбокс для InSales
**Расширение доступно на тарифах Омни и Премиум.**
1. Чтобы подключить расширение Инвойсбокс, напишите на [почту](mailto:c-support@invbox.ru) и указать в письме номер личного кабинета InSales
2. После добавления, расширение будет доступно в личном кабинете в разделе "Расширения"
3. Нужно ввести данные для интеграции, которые будут находиться в [личном кабинете](https://business.invoicebox.ru) после регистрации и заключения договора.
Потребуется: Идентификатор магазина, Авторизационный токен (API токен в ЛК) и Ключ для проверки подписи запроса (API ключ в ЛК)
Данные для тестирования
- Идентификатор магазина
- Авторизационный токен
- Ключ для проверки подписи запроса
Тестовые значения и место, где взять рабочие, — [Данные для интеграции](/docs/merchant/integrationdata/).
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
Ставка НДС должна совпадать с вашим режимом налогообложения и ставкой указанной в настройках магазина.
Остальные настройки заполняются по умолчанию, если они не заполнены в магазине.
4. В пункте “настройка” - “оформление заказа” - “оплата” появится новый вид оплаты “Инвойсбокс”
5. В настройках нужно привязать способ оплаты к способам доставки, а также выставить тип плательщиков: физ.лицо и/или юр.лицо. Если ни один способ доставки не будет привязан, то вид оплаты не появится на странице оформления заказа. По желанию сменить название и установить наценку
6. Для включения возможности оплаты юр.лицам передите в "настройки" -> "оформление заказа" -> "перейти к редактированию полей клиента" и включить пункт "Организация". ИНН — обязательное поле
Остальные настройки будут заполнены автоматически и не требуют изменений.
7. В случае успешной оплаты, покупатель будет переадресован на страницу нового заказа со статусом “оплачен”.
В случае возникновения ошибки при оплате, покупатель будет перенаправлен в магазин на страницу оформления заказа , где у него будет возможность заново перейти к оплате
---
# Prestashop
# Описание платёжного модуля для Prestashop
Платёжный модуль для интеграции платёжной системы «Инвойсбокс» и PrestaShop v8.1.2.
Реализована поддержка платёжного API. Протестировано на CMS PrestaShop v8.1.2.
Скачать модуль можно по [ссылке](https://github.com/InvoiceBox/PrestaShop-1.7)
Модуль поддерживает работы с 2 версией АПИ
Версию вашего подключения уточняйте у вашего персонального менеджера или в [службе поддержки](https://www.invoicebox.ru/ru/contacts) системы.
> [!IMPORTANT]
> В случае, если у вас возникнут сложности при самостоятельной установке модуля и его корректной настройке,
пожалуйста, обратитесь к специалистам [службы поддержки](https://www.invoicebox.ru/ru/contacts).
## Установка модуля
1. В админ панели сайта выбираем пункт "Модули"->"Module manager"->"Загрузить модуль"
2. Далее необходимо настроить модуль
3. Здесь необходимо указать 3 обязательных параметра: id магазина для версии API v2, региональный код и ключ подписи запроса для обработки уведомлений об оплате.
4. Все необходимые параметры находится в [личном кабинете](business.invoicebox.ru/login) Инвойсбокс
### Специфические настройки
Тестовый режим - включите его для проведения тестовых платежей, при включении этого режима, вы пройдете все шаги в платежном терминале Инвойсбокс, но деньги с вашей карты списаны не будут.
### Настройка панели Инвойсбокс:
1. Авторизуйтесь в [личном кабинете](business.invoicebox.ru/login) Инвойсбокс
2. Пройдите в раздел "Мои магазины". "Начало работы" -> "Настройки" -> "Мои магазины";
3. Пройдите по вкладку "Уведомления по протоколу" -> выберите "Тип уведомления" "Оплата/HTTP/Post (HTTP POST запрос с данными оплаты в переменных)"
4. В поле "URL уведомления" укажите:
`<домен_сайта>/modules/invoicebox/callback.php`
5. Сохраните изменения.
---
---
# Рекуррентные платежи
# Рекуррентные платежи
При оплате заказа физическим лицом есть возможность применить рекуррентные платежи. Это позволит
сохранить токен банковской карты пользователя, для последующего списания с неё средств без участия
клиента, например, для списания средств по подписке.
## Почему для организаций регулярность устроена иначе
Списание по сохранённой карте работает, и дело не в поддержке. Владелец карты — всегда физическое
лицо: даже корпоративная карта оформлена на сотрудника. Значит расход ложится на человека, и потом
ему отчитываться перед бухгалтерией — сохранить чек, обосновать трату, приложить её к отчёту. Для
регулярных корпоративных расходов это неудобно, и чем больше сотрудников, тем неудобнее.
Поэтому организациям и ИП адресована подписка — шаблон платежа: правила, по которым покупателю
уходит счёт. Правило задаёт период, конкретный день или условие — например, снижение баланса до
порога. Дальше есть два пути:
- **заказы создаёт ваша система** — по своему расписанию вызывает
[создание заказа](/docs/merchant/order/create/), и счёт уходит покупателю как обычно;
- **заказ-подписка** — создаётся один раз с параметрами периода и условий, клиент подписывается на
неё, и счета приходят ему в нужное время без новых вызовов с вашей стороны.
Счёт по подписке доходит покупателю привычным каналом: письмом, ссылкой или
[Запросом о платеже](/docs/scenarios/rtp/) в приложение банка.
> [!NOTE]
> Параметры заказа-подписки настраиваются при подключении: публичного описания полей в контракте пока
> нет, поэтому состав правил уточняйте у [технической поддержки](https://www.invoicebox.ru/ru/contacts).
> Как только описание появится, оно встанет на эту страницу.
## Привязка карты
### Схема получения токена карты
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Магазин->>Инвойсбокс: Вызов метода создания заказа
Инвойсбокс->>Магазин: Идентификатор заказа и ссылка на оплату
Магазин->>Покупатель: Перенаправление на платёжную страницу
Покупатель->>Инвойсбокс: Подтверждение оплаты счёта
Инвойсбокс->>Покупатель: Перенаправление покупателя на сайт магазина
Инвойсбокс->>Магазин: Уведомление об успешной оплате и токен карты
Магазин-->>Инвойсбокс: Вызов метода отгрузки для разблокировки средств
end
1. Магазин создает в системе «Инвойсбокс» заказ [через метод API](/docs/merchant/order/create/) с указанием параметров `savePaymentData` и `clientId`.
1. Система возвращает ссылку на платёжную страницу для оплаты заказа.
1. Магазин перенаправляет покупателя по полученной ссылке.
1. Покупатель заполняет необходимые для оплаты сведения подтверждает оплату.
1. Система «Инвойсбокс» перенаправляет покупателя обратно на сайт Магазина.
1. Система «Инвойсбокс» оповещает Магазин об успешной оплате заказа с указанием токена.
1. Магазин сохраняет и привязывает полученный токен к пользователю.
1. Магазин передаёт в систему «Инвойсбокс» информацию об отгрузке [через метод API](/docs/merchant/order/shipment_create/) для разблокировки средств.
### Создание заказа
Карта привязывается к покупателю в момент оплаты: [создайте заказ](/docs/merchant/order/create/) с такими
параметрами —
- `savePaymentData`, `clientId`, `paymentMethodCode` `paymentMethodAutosubmit` в [invoiceSetting](/docs/merchant/order/create/#invoicesetting)
Если заказ нужен только для привязки карты, включите режим холдирования средств — подтип заказа
`subtype` = `hold`, — чтобы затем разблокировать их.
Для оплаты товаров и услуг, эту опцию так же можно использовать, если этого требуют бизнес-процессы.
Пример:
```json
{
....
"subtype": "hold",
"invoiceSetting": {
"savePaymentData": true,
"clientId": "client-12345",
"paymentMethodCode":"acquiring",
"paymentMethodAutosubmit": true
}
}
```
Далее, клиента следует перенаправить на страницу оплаты по ссылке, полученной в параметре `paymentUrl` в
[ответе](/docs/merchant/order/create/#orderresponse) на запрос создания заказа.
После успешного холдирования (блокировки) средств, магазину будет направлено [уведомление об оплате](/docs/merchant/notification),
в котром будет находится информация о платеже в объекте [PaymentInfo](/docs/merchant/order/create/#paymentinfo), в том числе параметр
`paymentToken`, который необходимо сохранить и привязать к плательщику (пользователю) для последующего проведения платежей.
Пример:
```json
{
....
"paymentInfo": {
"paymentToken": "token-abc123",
"cardholderName": "CARDHOLDER NAME",
"expiration": "13/26",
"maskedPan": "220071**6742",
"paymentSystem": "MIR"
}
}
```
Если заказ был инициирован только для привязки карты, то необходимо разблокировать средства, путём
[создания отгрузки](/docs/merchant/order/shipment_create) с пустым набором `basketItems` и флагом `final` = `true`.
> [!IMPORTANT]
> Для заказов, используемых только для привязки карты, рекомендуется использовать небольшие суммы заказа, например,
до 1 рубля.
## Подтверждение оплаты заказов с использованием токена
Теперь можно использовать сохранённый токен для подтверждения оплаты в последующих заказах.
Для этого [создаем заказ](/docs/merchant/order/create/) и получаем его идентификатор, а затем вызываем метод подтверждения
платежа с указанием платёжного токена:
- метод: `POST`
- ресурс: `/v3/billing/api/payment/confirm`
- тело запроса - объект [ConfirmRequest](#confirmrequest)
- тело ответа - объект [OrderResponse](/docs/merchant/order/create/#orderresponse)
## ConfirmRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|--------------|--------------|--------------|-------------------------------|----------------------------------------|
| orderId | да | string | Идентификатор заказа | `0193690f-a122-d2cd-ac46-9da9e848723c` |
| type | да | string, enum | Тип подтверждения оплаты | `paymentToken` |
| paymentToken | да | string | Платёжный токен карты клиента | `cc11a4881764e0e02573f83c99811ed9` |
В случае успешной оплаты `status` заказа станет `completed`, а для подтипа `hold` — `hold`. Статуса `paid` в контракте нет: оплаченным считается только `completed` (полный перечень — на странице [работы с заказом](/docs/merchant/order/)).
## Ошибки
При использовании метода могут возникнуть следующие ошибки:
#### Пример ошибки при попытке списания средств ошибочным токеном
```json
{
"error": {
"message": "Ошибка списания средств",
"code": "invalid_argument",
"fields": []
}
}
```
#### Пример ошибки при попытке списания средств по уже оплаченному заказу
```json
{
"error": {
"message": "Заказ уже оплачен",
"code": "already_paid",
"fields": []
}
}
```
### Удаление привязанной карты
- метод: `POST`
- ресурс: `/v3/processing/api/payment-token/delete`
- тело запроса - объект [DeletePaymentTokenRequest](#deletepaymenttokenrequest)
## DeletePaymentTokenRequest
| Свойство | Обязательное | Тип | Описание | Пример |
|--------------|--------------|--------------|-------------------------------|------------------------------------|
| clientId | да | string | Идентификатор клиента | `client-12345` |
| paymentToken | да | string | Платёжный токен карты клиента | `cc11a4881764e0e02573f83c99811ed9` |
Пример ответа в случае успешного удаления
```json
{
"data": {},
"extendedData": []
}
```
#### Пример ошибки удаления токена
```json
{
"error": {
"message": "Неверное состояние связки",
"code": "invalid_argument",
"fields": []
}
}
```
#### Пример ошибки, когда токен не найден
```json
{
"error": {
"message": "Error",
"code": "not_found",
"fields": []
}
}
```
---
# VirtualityCMS
# Расширение Инвойсбокс для VirtualityCMS
Для получения и настройки модуля, ознакомьтесь с [инструкцией на сайте VirtualityCMS](https://vicms.ru/article/invoicebox).
## Читайте также
- [Данные для интеграции](/docs/merchant/integrationdata/)
---
# Метаданные
# Метаданные заказа/элемента корзины
Передача расширенного набора данных по заказу или элементу корзины выполняется заполнением свойства заказа или элемента
корзины `metaData` в запросе [создания заказа](/docs/merchant/order/create/) и [оформления возврата](/docs/merchant/refund/create/).
По умолчанию, свойство заполняется в формате [json-ld](https://json-ld.org/). Система поддерживат типы объектов, описанные на
сайте [https://schema.org/](https://schema.org/).
## Данные бронирования авиабилетов
Для передачи данных бронирования авиаперелётов, в поле заказа `metaData`
необходимо передать объект [ReservationPackage](https://schema.org/ReservationPackage) с перечнем
дочерних объектов [FlightReservation](https://schema.org/FlightReservation). Для каждого из сегментов полёта,
а также для каждого из пассажиров передаётся отдельный объект [FlightReservation](https://schema.org/FlightReservation).
#### Пример объекта ReservationPackage
``` json
{
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "FlightReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "Андрей Макаров"
},
"reservationFor": {
"@type": "Flight",
"flightNumber": "NDJ37S",
"provider": {
"@type": "Airline",
"name": "Aeroflot",
"iataCode": "SU"
},
"seller": {
"@type": "Airline",
"name": "Aeroflot",
"iataCode": "SU"
},
"departureAirport": {
"@type": "Airport",
"name": "Москва (Шерементьево)",
"iataCode": "SVO"
},
"departureTime": "2022-03-04T20:15:00+03:00",
"departureGate": "11",
"departureTerminal": "C",
"arrivalAirport": {
"@type": "Airport",
"name": "Санкт-Петербург (Пулково)",
"iataCode": "LED"
},
"arrivalTime": "2022-03-05T21:30:00+03:00",
"arrivalGate": "11",
"arrivalTerminal": "1"
},
"airplaneSeat": "1A",
"airplaneSeatClass": {
"@type": "AirplaneSeatClass",
"name": "Business"
},
"ticketNumber": "111-1231231239",
"ticketToken": "qrCode:AB34",
"checkinUrl": "https://checkmytrip.ru/onlinecheckin.html",
"reservedTicket": {
"@type": "flightTicket",
"underName": {
"@type": "Person",
"name": "MAKAROV ANDREY"
},
"fareBase": 57.00,
"fareReservation": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}]
}
```
## Данные бронирования железнодорожных билетов
Для передачи данных бронирования железнодорожных билетов, в полях элементов корзины `metaData`
необходимо передать объект [TrainReservation](https://schema.org/TrainReservation) с перечнем
дочерних объектов.
#### Пример объекта элемента корзины (билета) TrainReservation
``` json
{
"@type": "TrainReservation",
"bookingTime": "2021-05-15T12:22:01",
"reservationId": "74345932763286",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"reservationFor": {
"@type": "TrainTrip",
"departureStation": {
"@type": "TrainStation",
"name": "Moscow Kievskyi"
},
"departureTime": "2021-06-04T10:30:00+01:00",
"arrivalStation": {
"@type": "TrainStation",
"name": "St. Petersburg Central"
},
"arrivalTime": "2021-06-04T03:10:00+01:00",
"trainName" : "ГСЭ",
"trainNumber": "425*СА"
},
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"provider": {
"@type": "Organization",
"name": "Sapsan",
"taxID": "2323232323"
},
"reservedTicket": {
"@type": "trainTicket",
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"gender": "male",
"nationality": "RUS",
"idDocumentNumber": "***** 3456",
"idDocumentDate": "2015-01-01",
"coachNumber": "04",
"coachType": "Плацкартный",
"serviceClass": "3Э",
"ticketedSeat": {
"@type": "Seat",
"seatNumber": "038"
},
"ticketNumber": "74363372056286",
"ticketStatus": "Оформлен",
"ticketIssueTime": "2021-05-15T12:30:21+01:00",
"fareBase": 57.00,
"fareReservation": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}
```
#### Пример объекта элемента корзины (услуги) TrainReservation
``` json
{
"@type": "TrainReservation",
"bookingTime": "2021-05-15T12:22:01",
"reservationId": "74345932763286",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"reservationFor": {
"@type": "TrainTrip",
"departureStation": {
"@type": "TrainStation",
"name": "Moscow Kievskyi"
},
"departureTime": "2021-06-04T10:30:00+01:00",
"arrivalStation": {
"@type": "TrainStation",
"name": "St. Petersburg Central"
},
"arrivalTime": "2021-06-04T03:10:00+01:00",
"trainName" : "ГСЭ",
"trainNumber": "425*СА"
},
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"provider": {
"@type": "Organization",
"name": "Sapsan",
"taxID": "2323232323"
},
"reservedTicket": {
"@type": "baggageCheck",
"underName": {
"@type": "Person",
"name": "Иванов Сергей Иванович"
},
"idDocumentNumber": "***** 3456",
"idDocumentDate": "2015-01-01",
"ticketNumber": "44363452345662",
"declaredName": "Велосипед",
"declaredValue": 100.00,
"note": "Малогабаритный багаж в специализированном купе",
"fare": 57.00,
"valueFee": 66.40,
"vatValue": [{
"vatCode": "RUS_VAT0",
"totalVatAmount": 0.00
},
{
"vatCode": "RUS_VAT22",
"totalVatAmount": 10.00
}],
"paymentType": "Безналичный расчёт"
}
}
```
## Данные бронирования места проживания
Для передачи данных бронирования места проживания (отель, хостел, апартаменты и пр.), в поле заказа `metaData`
необходимо передать объект [ReservationPackage](https://schema.org/ReservationPackage) с перечнем
дочерних объектов [LodgingReservation](https://schema.org/LodgingReservation).
#### Пример объекта ReservationPackage
``` json
{
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "LodgingReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "Андрей Макаров"
},
"reservationFor": {
"@type": "LodgingBusiness",
"name": "Гранд Отель Европа",
"address": {
"@type": "PostalAddress",
"streetAddress": "ул. Михайловская, д. 1/7",
"addressLocality": "Санкт-Петербург",
"addressRegion": "Санкт-Петербург",
"postalCode": "191186",
"addressCountry": "ru"
},
"telephone": "+7 (812) 329-6000"
},
"checkinTime": "2021-02-21T16:00:00-08:00",
"checkoutTime": "2021-02-23T11:00:00-08:00"
}]
}
```
## Данные подписки
Для передачи данных о подписке, в полях элементов корзины `metaData`
необходимо передать объект [PaymentPlan](https://schema.org/) с перечнем
дочерних объектов.
#### Пример объекта элемента корзины (подписки) PaymentPlan
``` json
{
"@context": "https://schema.org",
"@type": "PaymentPlan",
"name": "Pro-подписка на сервис Экспресс Клиент",
"description": "Доступ к премиум-функциям в течение 1 года с ежемесячными платежами",
"billingPeriod": "P1M",
"billingIncrement": "1",
"contractStartDate": "2025-01-01",
"contractEndDate": "2026-01-01",
"price": "2990.00",
"priceCurrency": "RUB",
"provider": {
"@type": "Organization",
"name": "Экспресс Клиент",
"url": "https://expressclient.ru"
}
}
```
---
---
# Требования
# Требования к разработке расширений «Инвойсбокс» для систем управления сайтами
## Используемый протокол обмена данными (API)
Расширение (далее, модуль «Инвойсбокс») системы управления сайтом (далее, CMS) Интернет-магазина (далее, магазина)
для передачи информации о заказе и составе корзины должен опираться на описание протокола, расположенное по адресу:
[Инвойсбокс API v3](https://docs.invoicebox.ru).
Перед отправкой данных заказа в API, модуль должен проверять корректность данных, в частности, формат данных должен
соответствовать описанному в API. В случае наличия ошибок в расчёте, отсутствия необходимых сведений и других ошибок,
модуль должен отобразить соответствующее сообщение пользователю, данные не должны отправляться в платёжный шлюз.
В модуле должны быть предусмотрены следующие функции:
1. Оформление заказа/переход на платёжную страницу системы «Инвойсбокс»;
2. Callback-скрипт для получения информации об оплате заказа;
3. Функции оформления возврата по заказу.
## Множество способов оплаты
В тех CMS, где это технически возможно, модуль должен поддерживать оформление двух способов оплаты, а именно -
оплата для физических лица (банковские карты, интернет банки и т.д.), а также оплата для юридических лиц
(оплата по счёту для организаций и ИП). В настройках модуля должна быть предусмотрена возможность выбора
используемых способов оплаты.
При выборе способа оплаты для организаций и ИП, по API должны передаваться данные организации - ИНН, КПП,
наименование, юридический адрес (при наличие данных в заказе).
Т.е. в результате установки модуля, в CMS должно появится два способа оплаты. Там где это невозможно,
способ оплаты выбирается на странице платёжного шлюза системы «Инвойсбокс».
## Идентификация модуля
Важно обратить внимание на формирование идентификатора приложения и модуля при работе с API.
В API v3 идентификатор приложения передаётся в HTTP-заголовке User-Agent.
В API v2, в параметрах платёжной формы, в обязательном порядке должно присутствовать поле с идентификатором
приложения - itransfer_cms_name.
## Параметры заказа (счёта)
Модуль обязательно должен передавать тип позиции в заказе - товар или услуга, для API V3 - более детальное
значение [см. справочник](/docs/dictionary/tag2108/);
## Callback для получения информации об оплате
Смена статуса заказа в CMS магазина происходит по факту получения информации об оплате в формате,
описанном по адресу:
Для API v3: [Уведомление по умолчанию](/docs/merchant/notification/status/);
Для API v2: [HTTP-уведомления о переводах](https://www.invoicebox.ru/ru/integration/webapi/notify/defaulthttp/).
При получении информации об оплате, модуль должен сверить подпись запроса, идентификатор магазина, валюту заказа,
сумму оплаты с суммой заказа. В случае расхождения, статус заказа менять не нужно, модуль должен
вернуть детальное описание ошибки в соответствии с форматом ответа API.
В модуле должно быть реализовано получение тестового запроса с информацией об оплате, при котором модуль
должен выдать успешный ответ в случае корректной передачи подписи запроса и идентификатора магазина.
Тестовый запрос используется для проверки корректность установки модуля и не должен приводить к смене статуса
какого-либо из заказов.
Для API v3, описание тестового запроса расположено на странице [уведомление по умолчанию](/docs/merchant/notification/status/) (раздел Система мониторинга и автоматическое тестирование интеграции);
Для API v2, в тестовом запросе передаётся номер счёта (ucode) равный: 00000-00000-00000-00000.
## Настройки модуля
Обязательным набором настроек модуля, которые пользователь может менять, являются:
- Идентификатор магазина (для API v2, v3);
- Региональный код магазина (для API v2);
- API ключ магазина (для API v2, v3);
- Включить/выключить тестовый режим (для API v2);
- Описание способа оплаты (текст, который отображается в описании способа оплаты в процессе выбора способа оплаты при оформлении заказа в магазине, для API v2, v3).
Опционально, в настройках модуля может быть предусмотрен статус, на который следует изменить статус заказа, при получении информации
об оплате, а также адрес эл. почты администратора магазина, на который следует отправлять отчёты, в случае возникновения ошибок в работе модуля.
При наличие технической возможности CMS, модуль должен поддерживать несколько настроек таким образом, чтобы для каждой группы товара
или отдельного товара можно было бы задать параметр - какие настройки использовать для оплаты. Это требования необходимо там, где
разные товары и услуги могут быть оплачены от разных организаций.
Модуль должен поддерживать 2 языка – русский и английский.
## Прочие сведения
Логотип системы для использования в модуле: [Логотипы системы «Инвойсбокс»](https://www.invoicebox.ru/ru/press.html)
Комплект модуля
В состав модуля должны входить следующие элементы:
- Файлы модуля (архив ZIP), включая файл version.txt, в котором должна быть отражена версия модуля;
- Информация о модуле – версия(ии) CMS для которой модуль предназначен, версия(ии) CMS, на которой модуль был протестирован;
- Логотип CMS (SVG);
- Пошаговая инструкция по установке модуля включая шаги, необходимые для установки модуля, изображения, сопровождающие описательную часть;
- Пошаговая инструкция по настройке модуля, необходимые для настройки модуля, изображения, сопровождающие описательную часть;
- URL, которую следует указать в личном кабинете системы «Инвойсбокс» для передачи информации об оплате.
Исходные коды модуля должны быть загружены на github:
- [github.com/InvoiceBox](https://github.com/InvoiceBox).
Информация о модуле и инструкции должны быть размещены на ресурсах:
- [Документаиця. Готовые модули для CMS](https://docs.invoicebox.ru/docs/merchant/cms).
## phpSDK
Для упрощенной разработки и поддержания модулей в актуальном состоянии, рекомендуется использование [phpSDK](/docs/merchant/sdk/php/).
## Общие требования к обновлению старых версий модулей
1. Обновление модулей в соответствии с актуальными версиями CMS;
2. Обновление логотип и наименование платёжной системы - Инвойсбокс, Инвойсбокс (б, b - маленькие);
3. Обновление инструкций по установке и настройке модулей;
4. Реализация функций возврата платежа, если такие функции поддерживает CMS;
---
[Проект на github](https://github.com/InvoiceBox/)
---
# Схема взаимодействия
# Схема взаимодействия с платёжным инструментом
sequenceDiagram
autonumber
participant Покупатель
participant Платёжный инструмент
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Покупатель->>Платёжный инструмент: Выбор способа оплаты и переход на страницу платёжного инструмента
Платёжный инструмент->>Инвойсбокс: Вызов метода получения информации по счёту
Покупатель->>Платёжный инструмент: Подтверждение оплаты счёта
Платёжный инструмент->>Инвойсбокс: Вызов метода подтверждения оплаты счёта
Платёжный инструмент->>Покупатель: Перенаправление на платёжную страницу
end
1. Покупатель оформляет заказ и выбирает способ оплаты через платёжный инструмент. Покупатель перенаправляется на страницу авторизации платёжного инструмента с идентификатором счёта. Ссылка на страницу авторизации предоставляется платёжным инструментом. Также могут быть переданы ссылки возврата на случай обработки негативных сценариев при работе с API.
1. Система платёжного инструмента получает информацию по счёту из системы «Инвойсбокс» по API [через метод API](/docs/payment/get/).
1. Покупатель подтверждает оплату счёта.
1. Система платёжного инструмента подтверждает оплату счёта в системе «Инвойсбокс» по API [через метод API](/docs/payment/confirm_payment/).
1. Платёжный инструмент перенаправляет покупателя по полученной ссылке (в запросе информации по счёту) на платёжную страницу системы «Инвойсбокс».
---
---
# Получение счёта
# Получение счёта
Счета читаются одним запросом — списком или по идентификатору:
- метод: `GET`
- ресурс: `/v3/payment/api/invoice` или `/v3/payment/api/invoice/{invoiceId}`
- тело ответа - коллекция объектов [InvoiceResponse](/docs/payment/get/#invoiceresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
#### Пример запроса и ответа
```http
GET /v3/payment/api/invoice/01771534-196a-1105-839a-82422289d6d9
```
В запросе возможно применения фильтров и сортировок.
Пример запроса с фильтром по идентификатору счёта
```http
GET /v3/payment/api/invoice?id=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по статусу
```http
GET /v3/payment/api/invoice?status=paid
```
Пример запроса с фильтром по ИНН
```http
GET /v3/payment/api/invoice?customer[type][eq]=legal&customer[vatNumber][eq]=2323232323
```
Пример запроса с фильтром по номеру телефона
```http
GET /v3/payment/api/invoice?customer[type][eq]=private&customer[phone][eq]=79001231212
```
Ответ:
``` json
{
"data": [
{
"id": "01771534-1a57-f184-dee3-ebeb91dded76",
"number": "123-123212",
"createdAt": "2026-08-01T10:00:00+03:00",
"expirationDate": "2026-08-04T10:00:00+03:00",
"description": "Оплата номера в отеле",
"amount": 19658.45,
"currencyId": "RUB",
"status": "created"
}
]
}
```
## InvoiceResponse
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------------|--------------|-------------------------------|-------------------------------------------------------------------------|----------------------------------------|
| id | да | string(36) | Идентификатор счёта | `01771534-1a57-f184-dee3-ebeb91dded76` |
| number | да | string(50) | Номер счёта | `123-123212` |
| createdAt | да | datetime | Дата создания счёта | `2023-12-22T00:00:00+00:00` |
| expirationDate | да | datetime | Срок оплаты счёта | `2023-12-25T00:00:00+00:00` |
| description | да | string(1000) | Описание счёта | `Оплата номера в отеле` |
| amount | да | float | Сумма счёта (к оплате) | `19658.45` |
| vatAmount | да | float | Сумма НДС в счёте | `156.56` |
| currencyId | да | string(3) enum | Код валюты счёта в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` |
| customer | нет | [Customer](#customer) | Информация о плательщике | |
| paymentOrderTemplate | нет | [PaymentOrderTemplate](#paymentordertemplate) | Шаблон платёжного поручения (детали платежа) | |
| status | нет | string(50) enum | Статус оплаты счёта (paid, pending, canceled, partial) | `paid` |
| paymentUrl | да | string(1000) | Ссылка для перехода на платёжный шлюз на страницу счёта | |
## Customer
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------|--------------|-----------------|-------------------|------------------------------------------------------|
| type | да | string(10) enum | Тип заказчика | `legal` - юр. лицо, `private` - физ лицо |
| name | нет | string(500) | Наименование или имя | `ООО «Ромашка»` |
| phone | нет | string(100) | Номер телефона | `79001112233` |
| email | нет | string(100) | Электронная почта | `buh@example.invbox.ru` |
| vatNumber | нет | string(20) | ИНН | `7701234560` |
| registrationAddress | нет | string(1000) | Юр. адрес | `190000, Санкт-Петербург, Невский пр. 147, офис 321` |
## PaymentOrderTemplate
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------------|--------------|-----------------|--------------------|----------------------------------------------------------------|
| type | да | string(10) enum | Тип получателя | `legal` - юр. лицо, `private` - физ лицо |
| amount | да | float | Сумма счёта (к оплате) | `19658.45` |
| currencyId | да | string(3) enum | Код валюты счёта в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` |
| name | да | string(500) | Наименование | `ООО Ромашка` |
| vatNumber | да | string(20) | ИНН | `7710044140` |
| taxRegistrationReasonCode | да | string(9) | КПП | `770001001` |
| settlementAccount | да | string(20) | Номер расчт. счёта | `40702810800190000253` |
| correspondentAccount | да | string(20) | Номер корр. счёта | `30101810700000000187` |
| bankName | да | string(100) | Наименование банка | `ПАО ВТБ` |
| bic | да | string(9) | БИК | `044039142` |
| kbk | да | string(20) | Код бюджетной классификации (КБК) | `18210501011011000110` |
| oktmo | да | string(7) | ОКТМО | `40000000` |
| uin | да | string(25) | УИН | `34934876203474` |
| paymentPurpose | да | string(210) | Назначение платежа | `Оплата по счёту №10-2946153 за авиабилеты, НДС не выделяется` |
---
---
# Подтверждение оплаты счёта
# Подтверждение оплаты заказа
Оплата счёта подтверждается одним вызовом:
- метод: `POST`
- ресурс: `/v3/payment/api/invoice/confirm`
- тело запроса - объект [CreateInvoicePaymentRequest](#createinvoicepaymentrequest)
- тело ответа - объект [InvoicePaymentResponse](#invoicepaymentresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса
``` json
POST /v3/payment/api/invoice/confirm
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"paymentOperationId" : "117a58b0-7dc9-424c-8f07-b8a865e8bcc7",
"paymentOrderNumber" : "1342",
"paymentOrderDate" : "2023-04-01",
"amount" : 19658.45,
"currencyId" : "RUB",
"customer" : {
"type" : "legal",
"name" : "ООО Ромашка",
"vatNumber" : "7710044140",
"taxRegistrationReasonCode" : "770001001",
"settlementAccount" : "40702810800190000253",
"correspondentAccount" : "30101810700000000187",
"bankName" : "ПАО ВТБ",
"bic" : "044039142"
}
}
```
Ответ:
``` json
{
"data": {
"id": "8c0e116d-31a5-4210-b62e-6b6917851f69",
"invoiceId": "01771534-1a57-f184-dee3-ebeb91dded75",
"paymentOperationId": "117a58b0-7dc9-424c-8f07-b8a865e8bcc7",
"amount": 19658.45,
"currencyId": "RUB",
"status": "paid"
}
}
```
## CreateInvoicePaymentRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|--------------------|--------------|-----------------|----------------------------|----------------------------------------|
| invoiceId | да | string(36) | Id счёта | `01771534-1a57-f184-dee3-ebeb91dded75` |
| paymentOperationId | да | string(36) | Id операции | `117a58b0-7dc9-424c-8f07-b8a865e8bcc7` |
| amount | да | float | Сумма платежа | `19658.45` |
| currencyId | да | string(3) enum | Код валюты счёта в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` |
| paymentOrder | нет | [PaymentOrder](#paymentorder) | Детали платежа) | |
| status | нет | string(50) enum | Статус платежа (paid, pending) | `paid` |
## PaymentOrder
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------------|--------------|-----------------|----------------------------|----------------------------------------------------------------|
| type | да | string(10) enum | Тип плательщика | `legal` - юр. лицо, `private` - физ лицо |
| number | нет | string(36) | Номер платёжного поручения | `1342` |
| date | нет | string(36) | Дата платёжного поручения | `2023-04-01` |
| amount | да | float | Сумма платежа | `19658.45` |
| currencyId | да | string(3) enum | Код валюты счёта в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` |
| name | нет | string(500) | Наименование плательщика | `ООО Ромашка` |
| phone | нет | string(100) | Номер телефона | `79001112233` |
| vatNumber | нет | string(20) | ИНН | `7710044140` |
| taxRegistrationReasonCode | нет | string(9) | КПП | `770001001` |
| settlementAccount | нет | string(20) | Номер расчт. счёта | `40702810800190000253` |
| correspondentAccount | нет | string(20) | Номер корр. счёта | `30101810700000000187` |
| bankName | нет | string(100) | Наименование банка | `ПАО ВТБ` |
| bic | нет | string(9) | БИК | `044039142` |
| kbk | нет | string(20) | Код бюджетной классификации (КБК) | `18210501011011000110` |
| paymentPurpose | нет | string(210) | Назначение платежа | `Оплата по счёту №10-2946153 за авиабилеты, НДС не выделяется` |
## InvoicePaymentResponse
Повторяет свойства объекта [CreateInvoicePaymentRequest](#createinvoicepaymentrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|------------|--------------|------------|-----------------------------------------------|-----------------------------------------|
| id | да | string(36) | Идентификатор транзакции в системе Инвойсбокс | `8c0e116d-31a5-4210-b62e-6b6917851f69` |
## NotificationErrorCode
| Код ошибки | Описание |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `out_of_service` | Техническая ошибка обработки запроса, при получении этого кода ошибки необходимо пытаться повторить запрос еще несколько раз в течение последующих суток. |
| `invoice_already_paid` | Счёт уже оплачен другим инструментом оплаты |
| `invoice_not_found` | Счёт не найден в учётной системе |
| `signature_error` | Ошибка проверки подписи запроса |
> [!WARNING]
> Обратите внимание, в случае, если аналогичный запрос на оплату уже был обработан ранее успешно и заказ был отмечен как оплаченный, то в этом случае будет возвращён статус успешной обработки `success`. В случае, если заказ был оплачен ранее под другим идентификатором или иным платёжным инструментом, вернётся ошибка `invoice_already_paid`.
## Подпись запроса
При отправке запросе необходимо сформировать и передать подпись тела запроса в заголовке `X-Signature`. При ошибке проверки подписи будет сформирован ответ [NotificationError](/docs/merchant/notification/status/#notificationerror) с [NotificationErrorCode](#notificationerrorcode) `signature_error`.
Электронная подпись формируется путем криптографического преобразования содержимого тела запроса с использованием ключа и согласованного алгоритма.
По умолчанию используется алгоритм sha1 и метод hmac.
---
---
# Вход через ID вашего банка
# Вход через ID вашего банка
На платёжной странице и в приложении Инвойсбокс может быть реализован механизм
авторизации через систему ID вашего банка.
Клиенты вашего банка получат улучшений опыт взаимодействия с сервисом и смогут
подтверждать оплату заказов в пару кликов.
Поддерживаются различные стандарты авторизации, в том числе oAuth.
Свяжитесь с нами сейчас и мы произведём интеграцию в кратчайшие сроки.
---
---
# Платёжные инструменты и банки
# Платёжные инструменты и банки
Инвойсбокс API для платёжных инструментов, банков и НКО позволяет получать информацию по заказам,
а также подтверждать их оплату. Пожалуйста, ознакомьтесь со [схемой взаимодействия](/docs/payment/schema/).
### Использование системы авторизации банка (банковский ID)
Если открытое API банка позволяет интегрировать систему авторизации, она может быть добавлена
в сервисы Инвойсбокс. См. [дополнительную информацию](/docs/payment/auth-id/).
## Читайте также
- [API Инвойсбокс.Бизнес](/docs/business/)
---
---
# Схема взаимодействия
# Автоматизация оплаты счетов с использованием гарантийного фонда
Предложенная схема описывает взаимодействие, позволяющее системе организации получать
информацию по счёту и подтверждать его оплату с использованием гарантийного фонда.
sequenceDiagram
autonumber
participant Организация
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Организация->>Инвойсбокс: Вызов метода получения информации по счёту
Организация->>Инвойсбокс: Вызов метода подтверждения оплаты счёта
Инвойсбокс->>Организация: Изменение размера гарантийного фонда
end
1. Система организации получает информацию по счёту из системы «Инвойсбокс.Бизнес» [через метод API](/docs/business/get/).
1. Система организации подтверждает оплату счёта в системе «Инвойсбокс.Бизнес» [через метод API](/docs/business/confirm_payment/).
1. Система «Инвойсбокс» изменяет размер гарантийного фонда партнёра.
# Схема взаимодействия для систем программ лояльности
Предложенная схема описывает взаимодействие, позволяющие интегрировать систему программы лояльности
в качестве платёжного инструмента Инвойсбокс.
Например, у покупателя есть счёт (баланс) внутри программы лояльности, кафетерия льгот или иной системы,
с помощью которой, он хочет приобрести товары или услуги используя систему Инвойсбокс. Оператор
системы программы лояльности регистрируется в системе Инвойсбокс и размещает гарантийный фонд.
sequenceDiagram
autonumber
participant Покупатель
participant Партнёр
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Покупатель->>Партнёр: Выбор способа оплаты и переход на страницу партнёра
Партнёр->>Инвойсбокс: Вызов метода получения информации по счёту
Покупатель->>Партнёр: Подтверждение оплаты счёта
Партнёр->>Инвойсбокс: Вызов метода подтверждения оплаты счёта
Инвойсбокс->>Партнёр: Изменение размера гарантийного фонда
Партнёр->>Покупатель: Перенаправление на платёжную страницу
end
1. Покупатель оформляет заказ и выбирает способ оплаты через систему партнёра. Покупатель перенаправляется на страницу авторизации партнёра с идентификатором счёта. Ссылка на страницу авторизации предоставляется платёжным инструментом. Также могут быть переданы ссылки возврата на случай обработки негативных сценариев при работе с API.
1. Система партнёра получает информацию по счёту из системы «Инвойсбокс.Бизнес» [через метод API](/docs/business/get/).
1. Покупатель подтверждает оплату счёта.
1. Система партнёра подтверждает оплату счёта в системе «Инвойсбокс.Бизнес» [через метод API](/docs/business/confirm_payment/).
1. Система «Инвойсбокс» изменяет размер гарантийного фонда партнёра.
1. Партнёр перенаправляет покупателя по полученной ссылке (в запросе информации по счёту) на платёжную страницу системы «Инвойсбокс».
---
---
# Получение счёта
# Получение счёта
Счета читаются одним запросом — списком или по идентификатору:
- метод: `GET`
- ресурс: `/v3/business/api/invoice` или `/v3/business/api/invoice/{invoiceId}`
- тело ответа - коллекция объектов [InvoiceResponse](/docs/business/get/#invoiceresponse) в свойстве `data`, постраничность — в `metaData` (см. [формат ответа выборки](/docs/api/filters/#формат-ответа-выборки))
#### Пример запроса и ответа
```http
GET /v3/business/api/invoice/01771534-196a-1105-839a-82422289d6d9
```
В запросе возможно применения фильтров и сортировок.
Пример запроса с фильтром по идентификатору счёта
```http
GET /v3/business/api/invoice?id=01771534-196a-1105-839a-82422289d6d9
```
Пример запроса с фильтром по идентификатору заказа Магазина
```http
GET /v3/business/api/invoice?merchantOrderId=ABCDE
```
или по номеру заказа, который видит плательщик
```http
GET /v3/business/api/invoice?merchantOrderIdVisible=ABCDE
```
Пример запроса с фильтром по статусу
```http
GET /v3/business/api/invoice?status=paid
```
Ответ:
``` json
{
"data": [
{
"id": "01771534-1a57-f184-dee3-ebeb91dded76",
"number": "123-123212",
"createdAt": "2026-08-01T10:00:00+03:00",
"expirationDate": "2026-08-04T10:00:00+03:00",
"description": "Оплата номера в отеле",
"amount": 19658.45,
"currencyId": "RUB",
"status": "created"
}
]
}
```
## InvoiceResponse
| Свойство | Обязательное | Тип | Описание | Пример значения |
|----------------|--------------|---------------------------|-------------------------------------------------------------------------|----------------------------------------|
| id | да | string(36) | Идентификатор счёта | `01771534-1a57-f184-dee3-ebeb91dded76` |
| number | да | string(50) | Номер счёта | `123-123212` |
| createdAt | да | datetime | Дата создания счёта | `2023-12-22T00:00:00+00:00` |
| expirationDate | да | datetime | Срок оплаты счёта | `2023-12-25T00:00:00+00:00` |
| description | да | string(1000) | Описание счёта | `Оплата номера в отеле` |
| amount | да | float | Сумма счёта (к оплате) | `19658.45` |
| vatAmount | да | float | Сумма НДС в счёте | `156.56` |
| currencyId | да | string(3) enum | Код валюты счёта в соответствии с [ISO 4217](/docs/dictionary/iso4217/) | `RUB`, `USD`,`EUR`, `GBP` |
| customer | да | [Customer](#customer) | Информация о плательщике | |
| status | нет | string(50) enum | Статус оплаты счёта (paid, pending, canceled, partial) | `paid` |
| paymentUrl | да | string(1000) | Ссылка для перехода на платёжный шлюз на страницу счёта | |
## Customer
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------|--------------|-----------------|-------------------|------------------------------------------------------|
| type | нет | string(10) enum | Тип заказчика | `legal` - юр. лицо, `private` - физ лицо |
| name | нет | string(500) | Наименование или имя | `ООО «Ромашка»` |
| phone | нет | string(100) | Номер телефона | `79001112233` |
| email | нет | string(100) | Электронная почта | `buh@example.invbox.ru` |
| vatNumber | нет | string(20) | ИНН | `7701234560` |
| registrationAddress | нет | string(1000) | Юр. адрес | `190000, Санкт-Петербург, Невский пр. 147, офис 321` |
## Читайте также
- [Полный синтаксис операторов, сортировки и постраничного вывода](/docs/api/filters/)
---
---
# Подтверждение оплаты счёта
# Подтверждение оплаты заказа
Оплата счёта из гарантийного фонда подтверждается одним вызовом:
- метод: `POST`
- ресурс: `/v3/business/api/invoice/{invoiceId}/confirm`
- тело запроса - объект [CreateInvoicePaymentRequest](#createinvoicepaymentrequest)
- тело ответа - объект [InvoicePaymentResponse](#invoicepaymentresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса
``` json
POST /v3/business/api/invoice/{invoiceId}/confirm
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"partnerOperationId" : "117a58b0-7dc9-424c-8f07-b8a865e8bcc7"
}
```
Ответ:
``` json
{
"data": {
"id": "8c0e116d-31a5-4210-b62e-6b6917851f69",
"invoiceId": "01771534-1a57-f184-dee3-ebeb91dded75",
"partnerOperationId": "117a58b0-7dc9-424c-8f07-b8a865e8bcc7",
"amount": 19658.45,
"currencyId": "RUB",
"status": "paid"
}
}
```
## Параметры запроса
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-----------------|--------------|------------|----------------|----------------------------------------|
| invoiceId | да | string(36) | Id счёта | `01771534-1a57-f184-dee3-ebeb91dded75` |
## CreateInvoicePaymentRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|--------------------|--------------|------------|----------------------|----------------------------------------|
| partnerOperationId | да | string(36) | Id операции партнёра | `117a58b0-7dc9-424c-8f07-b8a865e8bcc7` |
## InvoicePaymentResponse
Повторяет свойства объекта [CreateInvoicePaymentRequest](#createinvoicepaymentrequest) с дополнительными свойствами:
| Свойство | Обязательное | Тип | Описание | Пример значения |
|------------|--------------|------------|-----------------------------------------------|-----------------------------------------|
| id | да | string(36) | Идентификатор транзакции в системе Инвойсбокс | `8c0e116d-31a5-4210-b62e-6b6917851f69` |
---
---
# Инвойсбокс.Бизнес
# Инвойсбокс.Бизнес
Инвойсбокс.Бизнес — сервис для постоянных покупателей, заключивших договор. Покупатель перечисляет
сумму гарантийного фонда и в её пределах мгновенно подтверждает оплату покупок, не дожидаясь
банковского перевода.
Отсрочка даётся сверх фонда: если на балансе 10 000 ₽, а покупка стоит 15 000 ₽, система подтвердит
оплату и даст отсрочку на недостающие 5 000 ₽. Лимит рассчитывается индивидуально, условия — в
договоре. Подробнее об инструментах — на странице [платёжных инструментов](/docs/merchant/payment-instruments/).
API для работы с «Инвойсбокс.Бизнес» позволяет получать информацию по заказам, а также
подтверждать оплату счёта с использованием гарантийного фонда.
---
# Добавление точки продаж
# Добавление точки продаж в маркетплейс
Магазин и точка продаж добавляются в маркетплейс одним запросом:
- метод: `POST`
- ресурс: `/v3/marketplace/api/shop`
- тело запроса - объект [CreateShopRequest](#createshoprequest)
- тело ответа - объект [ShopResponse](#shopresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса
``` json
POST /v3/marketplace/api/shop
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"title": "Тестовый магазин",
"description": "Это наш тестовый магазин",
"brandId": 123,
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded76",
"externalUpdate": true
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": 1,
"title": "string",
"description": "string",
"shortDescription": "string",
"seoTitle": "string",
"seoKeywords": "string",
"seoDescription": "string",
"categoryId": 1,
"shopDeliveryId": 1,
"alias": "string",
"shopUrl": "string",
"minOrderSum": 100.5,
"stockMode": "string",
"priceMode": "string",
"notificationEmail": "string",
"defaultPriceId": 1,
"imagePath": "string",
"imageId": 1,
"ogImagePath": "string",
"ogImageId": 1,
"mode": "string",
"jivositeId": "01771534-1a57-f184-dee3-ebeb91dded75",
"orderFlow": "string",
"yandexMetrikaId": 1,
"deliveryInfo": "string",
"shopIds": {},
"accountProgramIds": {},
"type": "string",
"orderLifetime": 1,
"modelId": 1,
"manualProperties": {},
"compiledProperties": {},
"properties": {},
"imageIds": {},
"modelIds": {},
"hours": {
"mon": {},
"tue": {},
"wed": {},
"thu": {},
"fri": {},
"sat": {},
"sun": {}
},
"address": "string",
"lat": 100.5,
"lon": 100.5,
"distance": 100.5,
"externalId": "01771534-1a57-f184-dee3-ebeb91dded75",
"brandId": 1,
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
"cityId": 1,
"active": false,
"priority": 1,
"merchantCategoryId": 1,
"status": "string",
"contactEmail": "string",
"contactPhone": "string",
"contactVkLink": "string",
"contactTgLink": "string",
"contactOkLink": "string"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## CreateShopRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-------------------|--------------|---------------|----------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| title | да | string(50) | Название магазина | `Тестовый магазин` |
| description | нет | string(2000) | Описание магазина | `Это наш первый тестовый магазин` |
| brandId | нет | int | Идентификатор магазина с типом brand | 123 |
| merchantId | нет | string(36) | Идентификатор магазина Инвойсбокс, для подгрузки чсти данных из Инвойсбокс | `01771534-1a57-f184-dee3-ebeb91dded76` |
| accountProgramIds | нет | array
sequenceDiagram
autonumber
participant Покупатель
participant Витрина
participant Мини-приложение
participant Инвойсбокс
participant Магазин
rect rgba(43, 170, 93, 0.13)
Покупатель->>Витрина: Выбор товара или услуги
Витрина->>Мини-приложение: Инициализация
Покупатель->>Мини-приложение: Оформление заказа
Мини-приложение->>Инвойсбокс: Создание заказа
Инвойсбокс->>Мини-приложение: Ссылка на оплату
Мини-приложение->>Покупатель: Переход на платёжную страницу
Покупатель->>Инвойсбокс: Оплата счёта
Инвойсбокс->>Магазин: Уведомление об оплате
Инвойсбокс->>Мини-приложение: Возврат покупателя
Мини-приложение->>Покупатель: Что оплачено и что дальше
end
1. Покупатель ищет товар, услугу или точку продаж в [Витрине Инвойсбокса](/docs/marketplace/).
1. Витрина открывает [мини-приложение](/docs/marketplace/mini-apps/) магазина.
1. Покупатель оформляет заказ в мини-приложении.
1. Мини-приложение вызывает [создание заказа](/docs/merchant/order/create/) от имени магазина.
1. В ответе приходит `paymentUrl` — ссылка на платёжную страницу.
1. Мини-приложение открывает платёжную страницу: методом
[onDone](/docs/marketplace/mini-apps/miniapp-sdk/#метод-ondone), если работу можно завершить, или
[onCheckout](/docs/marketplace/mini-apps/miniapp-sdk/#метод-oncheckout), если после оплаты нужно
вернуться в мини-приложение. На мобильном устройстве с установленным приложением Инвойсбокс
открывается приложение.
1. Покупатель подтверждает оплату счёта.
1. Инвойсбокс сообщает магазину [об оплате](/docs/merchant/notification/status/).
1. Покупатель возвращается в мини-приложение; при `onCheckout` вызывается
[обработчик onPaymentResult](/docs/marketplace/mini-apps/miniapp-sdk/#обработчик-onpaymentresult)
со статусом заказа.
1. Мини-приложение показывает, что оплачено, и передаёт управление родительскому окну.
## Мини-приложение как форма дополнительного заказа
Покупатель уже оплачивает основную покупку на платёжной странице, а мини-приложение продаёт ему
дополнительную услугу — трансфер к билету, страховку к поездке, доставку к заказу.
sequenceDiagram
autonumber
participant Покупатель
participant Платёжная страница
participant Мини-приложение
participant Инвойсбокс
participant Магазин
rect rgba(31, 111, 235, 0.12)
Покупатель->>Платёжная страница: Оплата основной покупки
Платёжная страница->>Мини-приложение: Инициализация с идентификатором заказа
Покупатель->>Мини-приложение: Выбор дополнительной услуги
Мини-приложение->>Инвойсбокс: Обновление переданного заказа
Мини-приложение->>Платёжная страница: onDone — управление возвращено
Покупатель->>Инвойсбокс: Оплата счёта целиком
Инвойсбокс->>Магазин: Уведомление об оплате
end
1. Покупатель открывает платёжную страницу основной покупки — например, авиабилета.
1. Платёжная страница открывает мини-приложение и передаёт ему идентификатор текущего заказа.
1. Покупатель выбирает дополнительную услугу.
1. Мини-приложение [обновляет переданный заказ](/docs/merchant/order/update/) — своего счёта здесь не
появляется, услуга добавляется в тот, который покупатель уже оплачивает.
1. Мини-приложение сообщает родительскому окну об успехе методом
[onDone](/docs/marketplace/mini-apps/miniapp-sdk/#метод-ondone) и закрывается.
1. Покупатель оплачивает счёт целиком — вместе с дополнительной услугой.
1. Инвойсбокс сообщает магазину [об оплате](/docs/merchant/notification/status/).
> [!NOTE]
> В обоих режимах мини-приложение сообщает родительскому окну и о неудачах: об ошибке —
> [onError](/docs/marketplace/mini-apps/miniapp-sdk/#метод-onerror), о собственной недоступности —
> [onUnavailable](/docs/marketplace/mini-apps/miniapp-sdk/#метод-onunavailable). Молчание мини-приложения
> родительское окно трактовать не умеет.
---
---
# Настройка заголовков
# Настройка отображения мини-приложения
Для корректной работы мини-приложения в экосистеме Инвойсбокс, сервер мини-приложения должен позволять
отображать его и связанное содержимое в iframe.
Если в своём мини-приложении при отправке ответов с сервера вы используете заголовок `Content-Security-Policy`,
то рекомендуем внести правки, чтобы поддержать его корректную работу. [Подробнее о Content Security Policy](https://developer.mozilla.org/ru/docs/Web/HTTP/CSP).
**Пример настройки Nginx**
```nginx
add_header Content-Security-Policy "frame-ancestors 'self' *.invoicebox.ru";
```
**Пример настройки Apache**
```apacheconf
Header always set Content-Security-Policy "frame-ancestors 'self' *.invoicebox.ru";
```
## Заголовок X-Frame-Options придётся убрать
Если сервер мини-приложения отдаёт `X-Frame-Options` со значением `DENY` или `SAMEORIGIN`,
приложение не откроется: браузер заблокирует кадр, и покупатель увидит пустой прямоугольник.
Значение `ALLOW-FROM` современные браузеры не поддерживают, поэтому «разрешить только
Инвойсбоксу» этим заголовком нельзя.
Уберите заголовок и оставьте только `Content-Security-Policy: frame-ancestors` — пример настройки
выше. Если оба заголовка присутствуют, браузер видит противоречие и запрещает встраивание.
**Как проверить.** Откройте страницу мини-приложения в кадре на любой своей странице. Если она не
показывается, в консоли браузера будет сообщение о `frame-ancestors` или `X-Frame-Options` — по нему
видно, какой из заголовков блокирует.
> [!WARNING]
> Обратите внимание, если в своём мини-приложении при отправке ответов с сервера вы используете заголовок
`X-Frame-Options`, то рекомендуем внести правки, чтобы поддержать корректную работу в современных браузерах.
Использование заголовка `X-Frame-Options` устарел и может не поддерживаться.
---
---
# Мини-приложения
# Мини-приложения
Мини-приложения — это открытая платформа встраиваемых кросс-платформенных приложений с помощью
которых магазины могут предоставить витрину своих товаров и услуг на площадках системы Инвойсбокс -
на платёжной странице, маркетплейсе и приложениях Инвойсбокс (далее - маркетплейс Инвойсбокс).
Мини-приложение представляет из себя сервис оформления заказа (форму оформления заказа) магазина,
реализованную в соответствии с требованиями [дизайн-системы Инвойсбокс](/docs/design) и работающую
на стороне магазина.
---
---
# Структура приложения
# Структура приложения
Для того, чтобы мини-приложение нативно отображалось в экосистеме Инвойсбокс, оно должно поддерживать обязательный
набор экранов:
- **Скелетон.** Скелетон должен отображаться сразу при навигации по ссылке мини-приложения и до тех пор, пока оно
не будет полностью инициализировано (загружены необходимые данные, изображения, стили и прочие ресурсы)
См. также: | [Storybook](https://ui.invoicebox.ru/?path=/docs/common-skeleton--docs) | [GutHub](https://github.com/InvoiceBox/invoicebox-ui/tree/main/src/components/common/Skeleton)
- **Экран(ы) выбора и оформления услуги.** Мы рекомендуем реализовать процесс с использванием не более 3х-4х экранов
для выбора и оформления покупки. В противном случае возврастает вероятность того, что покупатель запутается и
завершит процесс без покупки из-за избытка информации.
- **Экран успешной оплаты заказа.** Ссылка на такой экран должна быть передана серверной частью мини-приложения в систему
Инвойсбокс при [создании заказа](/docs/merchant/order/create/). Пользователь будет возвращён на такой экран только в том
случае, когда через мини-приложение оформляется основной заказ (тип мини-приложения `order`). В связи с тем, что информация
от системы Инвойсбокс об оплате заказа поступает асинхронно, мы рекомендуем на таком экране покупателю отображать загрузчик
до момента получения статуса оплаты или отобразить дополнительную информацию по истечению срока ожидания.
- **Экран неуспешной оплаты заказа.** Ссылка на такой экран должна быть передана серверной частью мини-приложения в систему
Инвойсбокс при [создании заказа](/docs/merchant/order/create/). Пользователь будет возвращён на такой экран только в том
случае, когда через мини-приложение оформляется основной заказ (тип мини-приложения `order`).
См. также: | [Storybook](https://ui.invoicebox.ru/?path=/docs/common-invoiceboxloader--docs) | [GutHub](https://github.com/InvoiceBox/invoicebox-ui/tree/main/src/components/common/InvoiceboxLoader)
---
---
# MiniApp SDK
# Инвойсбокс MiniApp SDK
Библиотека `minapp-sdk` позволяет мини-приложениям использовать API Инвойсбокс и API операционной системы, установленной
на устройстве пользователя.
Библиотека — мост между мини-приложениями, работающими на стороне пользователя, и клиентской частью Инвойсбокс
(десктопной версией платёжного сервиса, мобильной версией платёжного сервиса или мобильным приложением). Именно они
обмениваются данными с серверами Инвойсбокс, а библиотека работает как посредник на стороне пользователя.
- NPM: [minapp-sdk](https://www.npmjs.com/package/@invoicebox/minapp-sdk)
- GitHub: [minapp-sdk](https://github.com/InvoiceBox/invoicebox-minapp-sdk)
## Как использовать библиотеку MiniApp SDK
Чтобы использовать библиотеку:
1. Создайте проект мини-приложения
2. [Подключите MiniApp SDK](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BF%D0%BE%D0%B4%D0%BA%D0%BB%D1%8E%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-miniapp-sdk)
3. Используйте методы:
- Метод [invoiceboxMinapp.connect](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-connect). Установить соединение с родительским окном.
- Метод [invoiceboxMinapp.disconnect](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-disconnect). Разорвать соединение с родительским окном.
- Метод [invoiceboxMinapp.isConnected](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-isconnected). Узнать, установлено ли соединение с родительским окном.
- Метод [invoiceboxMinapp.getInitialData](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-getinitialdata). Получить данные покупателя от родительского окна.
- Метод [invoiceboxMinapp.matchMetaDataValues](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-matchmetadatavalues). Узнать, есть ли в метаданных нужная информация.
- Метод [invoiceboxMinapp.getMetaDataValues](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-getmetadatavalues). Получить, из метаданных нужную информацию.
4. Обработайте события:
- Метод [invoiceboxMinapp.onHeightChange](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-onheightchange). Сообщить родительскому окну параметры высоты мини-приложения.
- Метод [invoiceboxMinapp.onDone](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-ondone). Сообщить родительскому окну о готовности заказа к оплате.
- Метод [invoiceboxMinapp.onCheckout](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-oncheckout). Открыть платежную страницу поверх мини-приложения с возможностью вернуться.
- Обработчик [invoiceboxMinapp.onPaymentResult](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BE%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D1%87%D0%B8%D0%BA-onpaymentresult). Обработать результат оплаты после возврата в мини-приложение.
- Метод [invoiceboxMinapp.onError](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-onerror). Сообщить родительскому окну об ошибке в мини-приложении.
- Метод [invoiceboxMinapp.onLink](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-onlink). Сообщить родительскому окну о необходимости открыть страницу.
- Метод [invoiceboxMinapp.onUnavailable](/docs/marketplace/mini-apps/miniapp-sdk/#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-onunavailable). Сообщить родительскому окну, что мини-приложение недоступно.
Инструкция ниже актуальна для любой операционной системы. Для первых шагов потребуется знание языка JavaScript и умение работать с командной строкой.
## Подключение MiniApp SDK
Родительским окном мини-приложения может быть `iframe` или `WebView`.
### Через пакет NPM
Перейдите в созданный проект мини-приложения:
```bash
cd <ПУТЬ_К_МИНИ_ПРИЛОЖЕНИЮ>
```
Установите библиотеку:
```bash
npm install @invoicebox/minapp-sdk || yarn add @invoicebox/minapp-sdk
```
Инициализируйте MiniApp SDK в файле index.js:
```javascript
import { invoiceboxMinapp } from '@invoicebox/minapp-sdk';
invoiceboxMinapp.connect();
```
### Включение скрипта в HTML-код страницы
Этот способ подходит, если вы не используете менеджеры пакетов, такие как npm или yarn, для создания своего HTML-приложения.
**В код каждой HTML-страницы, где вы будете вызывать библиотеку, добавьте ссылку на файл index.min.js**
В репозитории MiniApp SDK этот файл находится в папке cjs (commonjs modules). Мы рекомендуем ссылаться на копию файла, расположенную
на сервисе unpkg.com. В этом случае вы автоматически будете получать последнюю версию библиотеки и вам не нужно будет самостоятельно
следить за выходом её обновлений.
```html
```
**В коде каждой HTML-страницы, где вы будете вызывать библиотеку, инициализируйте MiniApp SDK**
```html
```
## Методы, которые вызывает мини-приложение
Все перечисленные ниже вызовы делает само мини-приложение: сообщает высоту, завершает работу,
открывает ссылку, переходит к оплате. Единственный обработчик, который оно устанавливает, —
[onPaymentResult](#обработчик-onpaymentresult).
### Метод connect
Для того, чтобы установить соединение с родительским окном, воспользуйтесь методом `connect`.
```ts
connect(): void;
```
### Метод disconnect
Чтобы разорвать соединение с родительским окном, воспользуйтесь методом `disconnect`.
```ts
disconnect(): void;
```
### Метод isConnected
Чтобы узнать установлено ли соединение с родительским окном, воспользуйтесь методом `isConnected`.
```ts
isConnected(): boolean;
```
### Метод getInitialData
Для того, чтобы получить данные покупателя для оформления заказа, воспользуйтесь методом `getInitialData`.
```ts
getInitialData(): Promise<{
shopId?: number;
userEmail: string;
userName: string;
userPhone: string;
fullHeight: boolean;
locale: string;
} & (
| {
orderContainerId?: never;
minappType: 'order';
}
| {
orderContainerId: string;
minappType: 'suborder';
}
)>
```
- minappType - значение `order` указывает, что мини-приложение работает в режиме основного заказа, значение `suborder` - в режиме дополнительной услуги
- orderContainerId - обязательно, если `minappType: 'suborder'`, отсутствует, если `minappType: 'order'`, идентификатор родительского заказа, если этот заказ — дополнительная услуга
- shopId - опционально, идентификатор точки продаж, если мини-приложение работает с множеством точек продаж
- userEmail - адрес электронной почты покупателя
- userName - имя покупателя
- userPhone - номер мобильного телефона покупателя
- fullHeight - флаг сообщающий, что мини-приложение должно занять всю высоту контейнера, в котором располагается
- locale - локаль
Пример использования
```ts
invoiceboxMinapp.getInitialData().then(console.log);
/*
{
minappType: 'suborder',
orderContainerId: '3c15a3d1-3da8-4ba8-87e5-2dba828299fa',
shopId: 123,
userEmail: 'email@example.com',
userName: 'Иван Иванов',
userPhone: '+71231234567',
fullHeight: false,
locale: 'ru';
}
*/
```
### Метод matchMetaDataValues
Общая информация по наличию метаданных в заказах описана в [документации](/docs/merchant/order/metadata/).
Для того, чтобы узнать есть ли нужная информация в метаданных, воспользуйтесь методом `matchMetaDataValues`.
```ts
matchMetaDataValues(targetKey: string, targetValues: unknown[]): Promise{children}
;
};
```
### Метод onDone
Когда мини-приложение добавило новый заказ в существующий `orderContainer` или создало новый, оно вызывает
метод `onDone`. `paymentUrl` приходит от сервера в момент создания заказа.
Если заказ создан, но будет оплачен не через Инвойсбокс, метод можно вызвать без платёжной ссылки: `onDone(null)`. Пользователь увидит, что мини-приложение завершило работу, но переадресации на оплату не будет.
```ts
onDone(paymentUrl: string | null): void
```
Пример использования
```ts
createOrderRequest(someData).then((response) => {
invoiceboxMinapp.onDone(response.data.url);
});
```
### Метод onError
При ошибке в мини-приложении — например, при оформлении заказа или при обращении к API Инвойсбокс —
мини-приложение вызывает метод `onError`. Родительская страница уведомит пользователя об ошибке. Функция принимает один опциональный
строковый аргумент - пользовательское сообщение. Если сообщение есть, то оно отобразится. Если нет, то отобразится сообщение
по умолчанию `Что-то пошло не так`.
```ts
onError(message?: string): void
```
Пример использования
```ts
// Пользователь увидит "Ошибка создания заказа"
invoiceboxMinapp.onError("Ошибка создания заказа");
// Пользователь увидит "Что-то пошло не так"
invoiceboxMinapp.onError();
```
### Метод onLink
Метод `onLink` позволяет произвести переадресацию пользователя по ссылке в родительском окне, как будто переадресация была
вызвана не в контексте `iframe`/`webview`, а в контексте родительской страницы.
```ts
onLink(href: string): void
```
Пример использования
```ts
// На платёжной странице будет открыта новая вкладка с Google страницей
// это никак не повлияет на работу мини-приложения
invoiceboxMinapp.onLink("https://www.google.ru");
```
### Метод onUnavailable
Метод `onUnavailable` позволяет сообщить родительскому окну, что мини-приложение недоступно. Мини-приложение будет закрыто. Пользователь увидит соответствующее сообщение.
```ts
onUnavailable(): void
```
Пример использования
```ts
invoiceboxMinapp.onUnavailable();
```
### Метод onCheckout
sequenceDiagram
autonumber
participant Мини-приложение
participant Родительское окно
participant Покупатель
rect rgba(43, 170, 93, 0.13)
Note over Мини-приложение,Покупатель: onDone — работа закончена
Мини-приложение->>Родительское окно: onDone(paymentUrl)
Родительское окно->>Покупатель: Платёжная страница вместо мини-приложения
end
rect rgba(31, 111, 235, 0.12)
Note over Мини-приложение,Покупатель: onCheckout — работа продолжится
Мини-приложение->>Родительское окно: onCheckout(paymentUrl)
Родительское окно->>Покупатель: Платёжная страница поверх мини-приложения
Покупатель->>Родительское окно: Оплата или отказ
Родительское окно->>Мини-приложение: onPaymentResult(status)
Мини-приложение->>Покупатель: Что дальше после оплаты
end
Обе ветки открывают одну и ту же платёжную страницу, но по-разному заканчиваются: после `onDone`
мини-приложение закрыто и о результате оплаты не узнает, после `onCheckout` — остаётся на фоне и
получает статус в [onPaymentResult](#обработчик-onpaymentresult). Выбирайте `onCheckout`, если после
оплаты покупателю есть что показать: билет, код брони, следующий шаг.
Метод `onCheckout` позволяет открыть платежную страницу поверх мини-приложения с возможностью продолжить работу с мини-приложением после оплаты. В отличие от метода `onDone`, мини-приложение не закрывается, а остается открытым на фоне.
```ts
onCheckout(paymentUrl: string): void
```
- paymentUrl - URL платежной страницы, полученный от сервера в момент создания заказа
Пример использования
```ts
createOrderRequest(someData).then((response) => {
invoiceboxMinapp.onCheckout(response.data.url);
});
```
## Обработчики, которые устанавливает мини-приложение
Здесь мини-приложение передаёт библиотеке свою функцию и ждёт вызова — в отличие от методов выше,
которые оно вызывает само.
### Обработчик onPaymentResult
Метод `onPaymentResult` позволяет установить обработчик, который будет вызван при возврате пользователя в мини‑приложение со страницы оплаты.
```ts
'onPaymentResult'(handler: (status: 'pending' | 'completed' | 'canceled' | 'expired' | 'hold') => void): void
```
### Параметры
| Параметр | Тип | Описание |
|----------|-----|----------|
| `handler` | `(status: string) => void` | Функция‑обработчик, которая получает статус оплаты. |
### Статусы
| Статус | Описание |
|--------|-----------------------------------------------------------------------|
| `pending` | Оплата находится в процессе обработки. |
| `completed` | Платёж успешно завершён (оплачен). |
| `canceled` | Платёж отменён. |
| `expired` | Срок действия счёта истёк, счёт больше не может быть оплачен. |
| `hold` | По счёту средства удерживаются (блокируются). |
### Пример использования
```ts
invoiceboxMinapp.onPaymentResult((status) => {
navigateTo('PaymentResultScreen', { status });
});
```
## Схема взаимодействия при оплате через onCheckout
1. Создание заказа:
- Мини-приложение вызывает `onCheckout(paymentUrl)`, передавая URL платежной страницы
- Основное приложение открывает WebView с платежной страницей поверх мини-приложения
2. Завершение оплаты:
- После завершения оплаты платежная страница закрывается
- Основное приложение возвращается к мини-приложению и передает статус оплаты
- Вызывается обработчик, установленный через `onPaymentResult`
3. Продолжение работы:
- Мини-приложение продолжает работу, отображая актуальный статус оплаты
- Пользователь может продолжить взаимодействие с мини-приложением
---
---
# Библиотека компонентов
# Инвойсбокс библиотека компонентов
Библиотека `invoicebox-ui` содержит ready-to-use компоненты для создания мини-приложений.
- NPM: [invoicebox-ui](https://www.npmjs.com/package/@invoicebox/ui)
- GitHub: [invoicebox-ui](https://github.com/InvoiceBox/invoicebox-ui)
- Документация с примерами: [invoicebox-ui](https://ui.invoicebox.ru)
## Читайте также
- [Компоненты соответствуют дизайн-системе Инвойсбокс](/docs/design/)
---
---
# Банки, PSP и агрегаторы
## Банки, PSP и агрегаторы приёма платежей
Банки, PSP и агрегаторы, предоставляющие своим клиентам возможность принимать оплату от физических лиц, могут интегрировать
систему Инвойсбокс для приёма платежей от юридических лиц.
Схема интеграции схожа с подключением типового торгово-сервисного предприятия в эквайринге, она делится на два этапа:
1. Создание и получение доступа к магазину клиента в системе Инвойсбокс
2. Создание заказа и подтверждение оплаты
### Получение доступа к магазину клиента в системе Инвойсбокс
sequenceDiagram
autonumber
participant Магазин
participant Партнёр
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Магазин->>Партнёр: Желание принимать платежи от юр. лиц
Партнёр-->>Инвойсбокс: Заявка на подключение к Инвойсбокс
Партнёр->>Инвойсбокс: Запрос на предоставление доступа к магазину
Инвойсбокс->>Магазин: Запрос на предоставление доступа к магазину
Магазин->>Инвойсбокс: Подтверждение запроса, разрешение доступа
Инвойсбокс->>Партнёр: Предоставление доступа Партнёру к Магазину
end
1. Магазин в системе партнёра выбирает услугу приёма платежей от юридических лиц через систему Инвойсбокс
1. Если магазин не зарегистрирован, Партнёр отправляет заявку на подключение в систему Инвойсбокс
1. Если магазин зарегистрирован, Партнёр отправляет запрос в систему Инвойсбокс на предоставление доступа к магазину
1. Система Инвойсбокс направляет магазину запрос на предоставление доступа
1. Магазин либо разрешает доступ (принимает запрос), либо отклоняет его
1. В случае, если магазин принял запрос, система Инвойсбокс предоставляет Партнёру доступ к магазину для создания в нём заказов и оформления счетов
### Создания заказа и подтверждение оплаты
sequenceDiagram
autonumber
participant Покупатель
participant Магазин
participant Партнёр
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Покупатель->>Магазин: Оформление заказа
Магазин->>Партнёр: Заказ с корзиной
Партнёр->>Покупатель: Выбор способа оплаты
Покупатель->>Партнёр: Оплата от юрлица
Партнёр->>Инвойсбокс: Создание заказа
Инвойсбокс-->>Покупатель: Счёт в приложении
Инвойсбокс->>Партнёр: Ссылка на оплату
Партнёр->>Покупатель: Ссылка или QR-код
Покупатель->>Инвойсбокс: Подтверждение оплаты
Инвойсбокс->>Партнёр: Уведомление об оплате
Инвойсбокс->>Магазин: Выплата
Партнёр->>Магазин: Уведомление об оплате
Партнёр->>Покупатель: Уведомление об оплате
end
1. Покупатель оформляет заказ у магазина — на сайте, в приложении или на кассе.
1. Магазин передаёт заказ в систему партнёра вместе с корзиной: без состава корзины счёт юрлицу не
выставить, потому что в закрывающих документах нужны позиции, количество и ставки НДС.
1. Партнёр показывает покупателю способы оплаты — привычные ему (карта, QR, POS-терминал) и оплату
от организации через Инвойсбокс.
1. Покупатель выбирает оплату от юрлица.
1. Партнёр [создаёт заказ](/docs/merchant/order/create/) в Инвойсбоксе от имени магазина, доступ к
которому получен на первом этапе.
1. Если покупатель зарегистрирован в Инвойсбоксе, счёт приходит ему в приложение — платить по ссылке
не обязательно.
1. В ответе на создание заказа Инвойсбокс возвращает `paymentUrl`.
1. Партнёр передаёт ссылку покупателю: сообщением, письмом или
[QR-кодом](/docs/merchant/payment-page/) на экране кассы.
1. Покупатель подтверждает оплату — способ и скорость зависят от
[платёжного инструмента](/docs/merchant/payment-instruments/): от секунд при гарантийном фонде до
банковского перевода.
1. Инвойсбокс сообщает партнёру [об оплате](/docs/merchant/notification/status/).
1. Принятые оплаты перечисляются магазину — [сроки и условия](/docs/terms/).
1. Партнёр сообщает магазину, что заказ оплачен, и магазин отдаёт товар или оказывает услугу.
1. Партнёр сообщает об оплате покупателю в своём интерфейсе.
> [!NOTE]
> Заказы можно создавать и по реквизитам продавца — ИНН и КПП вместо идентификатора магазина
> ([агентский режим](/docs/merchant/order/agent-create/)). Схема этого метода не входит в публикуемый
> набор, поэтому консоли «Выполнить» на его странице нет: контракт сверяется с технической поддержкой.
---
# Партнёрское API
# Партнёрское API
## Вознаграждение партнёра
Вознаграждение считается от оборота привлечённых магазинов — без порога, с любого оборота.
Статистика по привлечённым магазинам доступна партнёру в личном кабинете: сколько подключено,
какой оборот и что начислено.
Размер вознаграждения и порядок выплаты определяет договор.
## Что в разделе
- [Интеграция магазина](/docs/partner/integration/) — как партнёр подключает магазин к Инвойсбоксу
своими методами.
- [Приглашение магазина](/docs/partner/integration/invite/) — отправка приглашения будущему магазину.
- [Активация интеграции](/docs/partner/integration/activation/) — включение подключённого магазина.
- [Банки и платёжные провайдеры](/docs/partner/payment-service-provider/) — сценарий для тех, кто
предоставляет платёжные сервисы своим клиентам.
## Как получить доступ
Партнёрский идентификатор и токен выдаются при заключении партнёрского договора; они видны в личном
кабинете партнёра. Токен передаётся так же, как в остальных методах — см.
[авторизацию](/docs/api/auth/).
---
# Интеграция магазина
# Интеграция магазина
Партнёр может реализвовать в своей системе механизм автоматической регистрации
и настройки интеграции магазина. Схема взаимодействия выглядит следующим образом:
sequenceDiagram
autonumber
participant Магазин
participant Партнёр
participant Инвойсбокс
rect rgba(43, 170, 93, 0.13)
Магазин->>Партнёр: Выбор услуги приёма платежей через Инвойсбокс
Партнёр->>Инвойсбокс: Вызов [метода отправки приглашения](/docs/partner/integration/) в систему Инвойсбокс
Инвойсбокс->>Магазин: Отправка инструкций и документов для подключения
Магазин->>Инвойсбокс: Предоставление необходимых документов, подтверждение подключения
Инвойсбокс->>Магазин: Отправка кода активации
Магазин->>Партнёр: Завершение подключения услуги приёма платежей через Инвойсбокс, ввод кода активации
Партнёр->>Инвойсбокс: Вызов [метода активации магазина](/docs/partner/integration/activation/)
Инвойсбокс->>Партнёр: Предоставление параметров интеграции магазина
end
1. Магазин в системе партнёра выбирает услугу приёма платежей через систему «Инвойсбокс»
1. Партнёр отправляет приглашение [через метод API](/docs/partner/integration/) в систему «Инвойсбокс»
1. Система «Инвойсбокс» направляет магазину необходимые данные для регистрации в системе
1. Магазин предоставляет необходимые сведения системе «Инвойсбокс», подтверждает подключение
1. Система «Инвойсбокс» направляет магазину код активации
1. Магазин в системе партнёра завершает подключение услуги приёма платежей через систему «Инвойсбокс» указывая полученный код активации
1. Партнёр отправляет запрос на активацию магазина [через метод API](/docs/partner/integration/activation/)
1. Партнёр получает от системы «Инвойсбокс» необходимые для работы с API параметры интеграции - идентификатор магазина и токен
## Читайте также
- [Партнёр отправляет приглашение через метод API (сейчас ссылка ведёт на саму страницу)](/docs/partner/integration/invite/)
---
---
# Отправка приглашения
# Отправка приглашения
Партнёр может инициировать отправку приглашения для регистрации в системе Инвойсбокс.
При успешном выполнении запроса на указанный адрес электронной почты будет отправлена ссылка для
регистрации в системе Инвойсбокс. После успешной регистрации и оформления договора, пользователь
получит код для активации для настройки своего магазина.
Для отправки приглашения, отправьте следующий запрос:
- метод: `POST`
- ресурс: `/v3/notification/api/invite`
- тело запроса - объект [InviteRequest](#inviterequest)
- тело ответа - объект [InviteResponse](#inviteresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
POST /v3/notification/api/invite
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"identifier": "shop@shop.com",
"type": "email",
"partnerId": "ffffffff-ffff-ffff-ffff-ffffffffffff"
}
```
``` json
{
"data":{
"id":"d5490c3d-e2f8-4f90-aa8b-87b1cd2956af"
}
}
```
Ответ (по схеме):
``` json
{
"data": {
"id": "01771534-1a57-f184-dee3-ebeb91dded75"
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## InviteRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-----------------|--------------|-----------------|---------------------------------------------------------------------|----------------------------------------|
| partnerId | да | string(36) | Идентификатор партнёра (интегратора) | `01771534-1a57-f184-dee3-ebeb91dded76` |
| type | да | enum | Тип приглашения | `email` |
| identifier | да | string(100) | Значение приглашения | `shop@shop.com` |
## InviteResponse
| Свойство | Обязательное | Тип | Описание | Пример значения |
|---------------------------|--------------|-------|------------------------------|-----------------|
| id | да | int | Идентификатор приглашения | `123` |
---
---
# Активация магазина по коду
# Активация магазина по коду
Партнёр может активировать магазин и его интеграцию по специальному коду.
Для активации магазина и получения параметров интеграции, отправьте следующий запрос:
- метод: `POST`
- ресурс: `/v3/security/api/api-user-group/activation`
- тело запроса - объект [ActivationRequest](#activationrequest)
- тело ответа - объект [ActivationResponse](#activationresponse)
- Возможные [ошибки](/docs/dictionary/error/)
#### Пример запроса и ответа
``` json
POST /v3/billing/api/merchant/merchant-integration-setting/activation
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
{
"activationCode":"111222333",
"partnerId":"dda90c3d-e2f8-4f90-aa8b-87b1cd2956a1"
}
```
``` json
{
"data":{
"merchantId":"ffffffff-ffff-ffff-ffff-ffffffffffff",
"token":"T1RBMFpXKOAY8W45072Wa09XRTBPR1EwTW1V"
}
}
```
Ответ (по схеме):
``` json
{
"data": {
"merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
"token": "string",
"notificationSetting": {}
},
"metaData": {
"totalCount": 1,
"pageSize": 1,
"page": 1
},
"extendedData": [
{
"type": "string",
"data": {}
}
]
}
```
## ActivationRequest
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-----------------|--------------|-----------------|--------------------------------------|----------------------------------------|
| partnerId | да | string(36) | Идентификатор партнёра (интегратора) | `01771534-1a57-f184-dee3-ebeb91dded76` |
| activationCode | да | string(36) | Код активации магазина | `143232423434` |
## ActivationResponse
| Свойство | Обязательное | Тип | Описание | Пример значения |
|-----------------|--------------|--------------|-----------------------------------|----------------------------------------|
| merchantId | да | string(36) | Идентификатор магазина | `01771534-1a57-f184-dee3-ebeb91dded76` |
| token | да | string(512) | [Токен магазина](/docs/api/auth/) | `T1RBMFpXKOAY8W45072Wa09XRTBPR1EwTW1V` |
## Читайте также
- [С полученными merchantId и token можно создавать заказы](/docs/merchant/order/create/)
---
---
# Сценарии и бизнес-кейсы
# Оплата от юрлиц и ИП: сценарии по отраслям
Инвойсбокс принимает оплату от организаций и ИП и сразу готовит закрывающие документы. Покупатель платит
привычным способом — картой, через СБП, по счёту или с отсрочкой, — а акт, счёт-фактура и УПД уходят его
бухгалтерии сами. Договариваться с каждым банком отдельно не нужно.
## Что это даёт бизнесу
- **Корпоративный покупатель платит так, как ему удобно.** Классическая и ускоренная оплата по счёту,
обещанный платёж, гарантийный фонд, фонд с овердрафтом. [Чем они отличаются](/docs/merchant/payment-instruments/).
- **Документы формируются без участия людей.** Счёт, акт, счёт-фактура и УПД уходят по итогу оплаты в
электронном виде — [как устроен документооборот](/docs/merchant/documentflow/).
- **Отсрочку и риск неплатежа можно отдать платформе.** Покупатель подтверждает оплату сразу, а платит в
течение 30 дней. [Сроки и условия](/docs/terms/).
- **Физлица закрываются тем же вендором.** Чек и онлайн-касса уже внутри:
[схема для физлиц](/docs/merchant/schema/private/), [фискализация по 54-ФЗ](/docs/merchant/fz54/).
## Посмотреть, как это работает
Три интерактивных демо делают настоящие вызовы к демо-контуру. Счёт выставляется, приходит
уведомление, статус в карточке меняется сам. Читать документацию для этого не нужно.
- [Оплата бронирования](/demo/booking/) — гостиница выставляет счёт гостю-юрлицу и видит оплату.
- [Счёт юрлицу из CRM](/demo/crm/) — менеджер закрывает сделку счётом, не выходя из карточки.
- [Касса АЗС](/demo/fuel/) — счёт на лимит по талону и пересчёт по факту налива.
## Отрасли и кейсы
В каждом кейсе разобран путь денег и документов в конкретной отрасли: что происходит с заказом, какие
методы API за этим стоят, что видит покупатель. В подписи сказано, какую механику показывает кейс.
Отрасли, у которых пока нет своего кейса, закрываются теми же методами:
- **НКО, банки и платёжные агрегаторы** — [платёжный инструмент](/docs/payment/): подтверждение оплаты
на своей стороне и банковский вход. Схема подключения продавца через банк или PSP —
[в партнёрском разделе](/docs/partner/payment-service-provider/).
- **Медицина, ДМС и медосмотры** — механика та же, что в
[корпоративном обучении](/docs/scenarios/education/): счёт организации за группу сотрудников,
правка состава до оплаты и возврат с корректировкой после.
## Как подключиться
Четыре пути, от простого к гибкому. Механика везде одна: счёт для юрлица, оплата, документы
автоматически. Меняется только то, кто создаёт заказ.
| Путь | Кому подходит | Что нужно сделать |
|---|---|---|
| [Платёжный виджет](/widgets/) | нужен приём оплаты сегодня, разработчика нет | скопировать код и вставить на страницу |
| [Готовый модуль](/docs/merchant/cms/) | сайт или учётная система на популярной платформе | установить модуль для 1С-Битрикс, Тильды, WooCommerce, amoCRM, iiko |
| [ИИ-агент](/for-agents/) | есть Cursor, Claude Code или другой агент | дать агенту один промпт — интеграцию по API он сделает сам |
| [API и PHP SDK](/docs/merchant/) | заказы создаёт ваша система, нужен полный контроль | четыре вызова базового сценария — [быстрый старт](/quickstart/) |
Счёт может прийти покупателю прямо в приложение банка — это
[Запрос о платеже](/docs/scenarios/rtp/), он работает с любым из путей выше.
Проверить вызовы можно не выходя из документации: на странице каждого метода есть кнопка «Выполнить»,
она работает на демо-магазине. Машиночитаемый контракт — [в разделе схем](/schemas/).
## Перед боевым запуском
- [Уведомление об оплате](/docs/merchant/notification/status/) — как узнать о платеже: запросом к
Инвойсбоксу или уведомлением от него.
- [Чеклист запуска в прод](/go-live/) — идемпотентность, проверка подписи, документы, лимиты.
---
Не нашли свою отрасль или нужный модуль? [Напишите нам](https://www.invoicebox.ru/ru/contacts) —
подскажем ближайший сценарий или разработаем интеграцию под вашу инфраструктуру.
---
# 🕓 B2B продажи 24/7
# B2B-платежи, которые работают на ваш бизнес, а не против него
Покупатель-физлицо платит картой за минуту. Организация в это же время согласовывает счёт, ждёт
платёжного поручения и требует закрывающие документы — и каждый шаг делает человек. Добавьте отсрочку,
расчёты с нерезидентами ([как это работает](https://www.invoicebox.ru/ru/products/belarus)) и
регламенты, по которым нельзя платить иначе.
Инвойсбокс закрывает этот путь целиком: счёт, приём оплаты, поступление денег на расчётный счёт и
передача документов бухгалтерии покупателя. Менеджеру остаются только спорные случаи.
## Сначала - боль. Потом - решение.
Вот что обычно мешает продавать организациям.
- Один счёт занимает у менеджера полдня: договор, акт, накладная, согласование с бухгалтерией,
отправка почтой.
- Клиент просит отсрочку, а продавец не может её дать: работать в долг не на что, отказать — значит
потерять заказ.
- Оплата по счёту нужна всем корпоративным покупателям, но обрабатывать её вручную некому.
- Документы уходят с опозданием, и бухгалтерия клиента возвращается с вопросами.
Дальше — что с каждым из этих пунктов делает Инвойсбокс.
## Как это работает
### Отсрочку можно дать, не работая в долг
Постоплата, отсрочка, обещанный платёж — риск неплатежа берёт на себя Инвойсбокс. Деньги приходят
продавцу в обычный срок, а покупатель рассчитывается по условиям договора: до 30 дней —
[платёжные инструменты](/docs/merchant/payment-instruments/), [сроки расчётов](/docs/terms/).
### Документы формируются из данных заказа
Их не переписывают руками, поэтому расхождений с суммой заказа не бывает. Инвойсбокс оформляет счёт или
счёт-договор, акт выполненных работ, счёт-фактуру и УПД, а отправляет их через ЭДО или Почтой России —
[как устроен документооборот](/docs/merchant/documentflow/).
### Покупатель обслуживает себя сам
Корпоративный покупатель получает ссылку на оплату, выбирает способ — банковский счёт, карта,
[СБП B2B](https://www.invoicebox.ru/ru/products/sbp-b2b),
[Запрос о платеже](/docs/scenarios/rtp/) — и забирает документы без участия менеджера. От счёта до
закрывающих документов заказ проходит сам.
### С чего начинается интеграция
Механика одинакова для любой отрасли и укладывается в четыре вызова:
1. [Создание заказа](/docs/merchant/order/create/) — состав, сумма, данные плательщика-юрлица.
2. Оплата: платёжная страница, [Запрос о платеже](/docs/scenarios/rtp/) или
[холдирование](/docs/scenarios/guarantee/), если сумма уточняется по факту.
3. [Уведомление о смене статуса](/docs/merchant/notification/status/) — сигнал вашей системе
отгружать товар или оказывать услугу.
4. [Возврат](/docs/merchant/refund/create/), когда это нужно; закрывающие документы Инвойсбокс
формирует и отправляет [по ЭДО](/docs/merchant/documentflow/) сам.
Без разработки те же шаги закрывают [платёжный виджет](/docs/merchant/widget) и
[готовые модули CMS](/docs/merchant/cms).
## Что меняется в процессе
- Деньги поступают на расчётный счёт на следующий рабочий день после подтверждения оплаты —
[сроки расчётов](/docs/terms/).
- Постоянному покупателю можно дать отсрочку до 30 дней, а риск неплатежа взять на систему —
[платёжные инструменты](/docs/merchant/payment-instruments/).
- Счёт, акт, счёт-фактуру и УПД система формирует и отправляет сама —
[документооборот](/docs/merchant/documentflow/).
- Оплату принимает не менеджер по почте, а сайт или учётная система: счёт выставляется вызовом API
или [виджетом](/widgets/).
## Что закрывает какую задачу
Ниже — та же четвёрка препятствий из начала страницы и то, чем каждое снимается.
| Ваша боль | Наше решение |
|-----------------------------------------------------|---------------------------------------------------------------------------------------------|
| Хочу давать отсрочку, но боюсь не получить деньги | **[Обещанный платёж и Гарантийный фонд](/docs/merchant/payment-instruments/)** - мы платим вам сразу, клиент платит нам позже |
| Ручной документооборот тормозит сделки | **Полная автоматизация документов** - счёт, акт, счёт-фактура, УПД, ЭДО - всё в один клик |
| Клиенты хотят оплату по счёту, а у меня нет времени | **[Ускоренная оплата по счёту, СБП B2B и Запрос о платеже](/docs/merchant/payment-instruments/)** - клиент получает ссылку и оплачивает удобно по счёту, через [СБП B2B](https://www.invoicebox.ru/ru/products/sbp-b2b), [Запрос о платеже](/docs/scenarios/rtp/), банк-клиент |
| Нет интеграции с сайтом | **[Платёжный виджет и Инвойсбокс Кассир](/widgets/)** - выставляйте счета вручную или через приложение «[Инвойсбокс Кассир](https://www.invoicebox.ru/ru/products/kassir)» |
| Хочу привлечь СМБ, но у них сложные процессы | **Мы - доверенный платёжный агент** - упрощаем взаимодействие с юрлицами и ИП |
## С чего начать
[Заполните форму](https://www.invoicebox.ru/ru/contacts) - и мы покажем, как Инвойсбокс сэкономит вам время, деньги и нервы.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
## Читайте также
- [Быстрый старт](/quickstart/)
---
# ✈️ B2B продажи авиабилетов
# Автоматизация продаж авиабилетов юридическим лицам и ИП (b2b)
Командировка начинается с брони, а бронь живёт по тайм-лимиту: часы, иногда меньше. Корпоративный
клиент в это время ждёт счёт, потому что карту компания сотруднику не выдаёт.
Инвойсбокс закрывает этот разрыв: счёт выставляется сразу после бронирования, оплата подтверждается за
минуты, а закрывающие документы уходят бухгалтерии клиента без участия ваших менеджеров.
Что это даёт перевозчику:
- корпоративный клиент оплачивает билет привычным способом — по счёту, с отсрочкой или картой;
- деньги приходят на счёт на следующий рабочий день после подтверждения оплаты ([сроки](/docs/terms/));
- отчётные документы формируются после оплаты и уходят бухгалтерии клиента; какие именно — зависит от
вида перевозки, [подробнее ниже](#автоматизированный-документооборот);
- срок оплаты счёта задаёт сама система бронирования — через поле `expirationDate` при [создании заказа](/docs/merchant/order/create/).
### Оплата бронирований с любым тайм-лимитом
Способы оплаты Инвойсбокс для организаций и ИП позволяют корпоративным клиентам оплачивать электронные
билеты с любым тайм-лимитом (от одной минуты), открывая возможность покупки билетов по промо- и бюджетным тарифам
так же, как при покупке с помощью банковской карты.
Подтверждение оплаты приходит авиакомпании за считанные минуты — с той же скоростью, что при оплате
картой. Короткий тайм-лимит перестаёт быть причиной отказывать корпоративному клиенту в оплате по счёту.
Постоянные корпоративные клиенты могут получить отсрочку до 30 дней, при этом авиаперевозчик гарантированно
получает денежные средства на следующий рабочий день после подтверждения оплаты бронирования.
### Отчётность по правилам авиакомпании
Отчёты приходят перевозчику в том формате, который принят у него: состав полей и разбивку можно
расширить или собрать по требованиям авиакомпании при подключении. Бухгалтерии и отделу
взаиморасчётов не приходится переделывать выгрузки под новый способ оплаты.
### Обработка возвратов
Сервис Инвойсбокс поддерживает как автоматизированное оформление возвратов, так и в ручном режиме через
личный кабинет. Денежные средства по возврату зачисляются клиенту до двух рабочих дней — срок зависит от способа оплаты.
### Автоматизированный документооборот
Отчётные документы формируются автоматически после подтверждения оплаты, а оригиналы уходят
[каналами ЭДО](/docs/merchant/documentflow/) или в бумажном виде почтой. Состав документов зависит от
вида перевозки.
| Что продано | Отчётные документы |
|---|---|
| Регулярная перевозка | отчёт о переводе средств и маршрут-квитанция электронного билета |
| Чартер, грузоперевозка | акт, счёт-фактура или УПД |
Для регулярных перевозок акт и счёт-фактура не выпускаются: расходы клиент подтверждает
маршрут-квитанцией, а расчёты — отчётом о переводе средств. Поэтому в квитанции важно, чтобы был
выделен НДС.
### Работа с динамическим ценообразованием
Схема интеграции предполагает возможность изменения стоимости бронирования до момента его оплаты. На каждом этапе
оплаты от формирования счёта до его оплаты негативные сценарии отрабатываются как автоматически с использованием
информирования клиента, так и с привлечением специалистов службы клиентской поддержки.
Штатные ситуации — недоплата, просрочка тайм-лимита, отмена брони — отрабатываются автоматически: клиент получает
уведомление, а система бронирования — [сообщение о смене статуса заказа](/docs/merchant/notification/status/).
Комиссию за приём оплаты можно разделить между перевозчиком и покупателем в нужной пропорции или целиком
переложить на покупателя — тогда в счёте она идёт отдельной строкой.
Специалист поддержки Инвойсбокс подключается там, где автоматика бессильна: нестандартное билетооформление,
спорная оплата, ручной возврат.
### Схема взаимодействия с клиентом
- После того, как заказ/бронь сформирована, клиент переходит на страницу выбора способа оплаты. Как правило, мы
предлагаем перевозчику разместить на сайте дополнительный способ: "Оплата по счёту для организаций и ИП".
- Если клиент выбирает способ оплаты "Оплата по счёту для организаций и ИП", система бронирования
[создаёт заказ](/docs/merchant/order/create/) в Инвойсбокс, передавая состав перелёта и данные бронирования.
Номер брони (PNR) и тайм-лимит удобно положить в [метаданные заказа](/docs/merchant/order/metadata/) —
они вернутся во всех уведомлениях и в закрывающих документах.
- В зависимости от тайм-лимита (TL) бронирования, система автоматически формирует набор доступных способов оплаты.
Тайм-лимит у бронирования может быть любой.
- Если тайм-лимит короткий, подойдёт обещанный платёж: покупатель подтверждает заказ картой, сумма
счёта блокируется, билет оформляется сразу, а счёт уходит организации со сроком оплаты пять суток —
[платёжные инструменты для B2B](/docs/merchant/payment-instruments/). Отдельная механика —
[подтверждение оплаты кодом](/docs/merchant/guarantee/) из гарантийного фонда: она не блокирует
средства на карте, а списывает их с фонда постоянного покупателя.
- Если тайм-лимит свыше 24х часов, то ко всем возможностям, описанным выше, добавляется простой выпуск счёта с ожиданием
оплаты в течение суток.
- После оплаты счёта в срок бронирования Инвойсбокс отправляет системе перевозчика
[уведомление об оплате](/docs/merchant/notification/status/); по нему оформляется билет и сопутствующие услуги.
Тайм-лимит истёк, а деньги не пришли — заказ можно
[отменить](/docs/merchant/order/delete/) и освободить бронь.
- Отчётные документы оформляет и отправляет клиенту система Инвойсбокс — по регулярным перевозкам это
отчёт о переводе средств и маршрут-квитанция с выделенным НДС. Дополнительной нагрузки на бухгалтерию
авиакомпании запуск нового способа оплаты не создаёт.
- Возврат по вынужденному или добровольному отказу оформляется
[методом возврата](/docs/merchant/refund/create/). Если авиакомпания удерживает сбор, возврат проводится
[с корректировкой](/docs/merchant/refund/correction/): клиент получает разницу, а в закрывающих документах
остаётся удержанная сумма. Деньги уходят клиенту до двух рабочих дней после уведомления от перевозчика, в зависимости от способа оплаты.
### Проработанные интеграции
Интеграция Инвойсбокс отработана с решениями таких лидеров отрасли как [Сирена-Тревел (МПС)](/docs/merchant/pss/mps/), [ТАИС TravelShop](/docs/merchant/pss/tais/), SITA, Amadeus, Sabre.
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# 🛍️ B2B продажи товаров
# Автоматизация продаж товаров юридическим лицам и ИП (b2b)
Оптовый заказ редко уезжает целиком: часть товара отгружается сегодня, часть через неделю, а чего-то
не оказывается на складе вовсе. Покупатель должен заплатить за то, что доехало, и получить документы на
эту же сумму.
Инвойсбокс держит и то и другое: счёт организации с отсрочкой, отгрузки частями и корректировка, когда
привезли меньше, чем в счёте.
Что это даёт продавцу:
- покупатель-организация оплачивает заказ по счёту, с отсрочкой до 30 дней или картой;
- деньги приходят на счёт на следующий рабочий день после подтверждения оплаты ([сроки](/docs/terms/));
- счёт, акт и УПД формируются автоматически — ваша бухгалтерия к этому не подключается;
- отгрузку частями и возвраты закрывают [отгрузки](/docs/merchant/order/shipment_create/) и [корректировки](/docs/merchant/refund/correction/).
### Оплата заказов с любым сроком оплаты
Способы оплаты Инвойсбокс для организаций и ИП позволяют корпоративным клиентам оплачивать заказы
с любым сроком оплаты (от одной минуты). Магазину нет необходимости резервировать товар на складе
на длительное время.
Постоянные корпоративные клиенты могут получить отсрочку до 30 дней, при этом продавец гарантированно
получает денежные средства на следующий рабочий день после подтверждения оплаты заказа.
### Обработка возвратов
Сервис Инвойсбокс поддерживает как автоматизированное оформление возвратов, так и в ручном режиме через
личный кабинет. Денежные средства по возврату зачисляются клиенту до двух рабочих дней — срок зависит от способа оплаты.
### Автоматизированный документооборот
Отчётные документы для клиента формируются автоматически после подтверждения оплаты заказа, а оригиналы
могут быть отправлены в бумажном виде по почте или [каналам ЭДО](/docs/merchant/documentflow/). Дополнительно
см. [схему документооборота](/docs/merchant/schema/commission/).
### Схема взаимодействия с клиентом
- После того, как заказ сформирован, клиент переходит на страницу выбора способа оплаты. Как правило, мы
предлагаем разместить на сайте дополнительный способ: "Оплата по счёту для организаций и ИП".
- Если клиент выбирает способ оплаты "Оплата по счёту для организаций и ИП", ваша система передаёт в систему
Инвойсбокс состав заказа и данные для формирования счёта на оплату.
- В зависимости от срока оплаты заказа, система автоматически формирует набор доступных способов оплаты.
Срок оплаты у заказа может быть любой.
- После получения подтверждения оплаты по счёту в течение срока действия заказа, информация об оплате передаётся
в систему учёта Магазина, происходит отгрузка товара, оформление и обмен документами.
- Все закрывающие документы оформляет и отправляет клиенту система Инвойсбокс. Никакой дополнительной нагрузки на
вашу бухгалтерию, связанной с запуском нового способа оплаты, не возникает.
- Ваша учётная система может передавать информацию о возврате средств клиенту. Обычно после получения
уведомления деньги возвращаются до двух рабочих дней — срок зависит от способа оплаты.
## Отгрузка партиями: платит за то, что доехало
Корпоративный заказ редко уезжает одной машиной. Часть позиций на складе, часть под заказ, что-то
приедет через неделю — а счёт и закрывающие документы клиент ждёт по факту поставки.
1. Заказ создаётся целиком — [создание заказа](/docs/merchant/order/create/) со всей корзиной.
2. Каждая партия оформляется [отгрузкой](/docs/merchant/order/shipment_create/) с фактическим составом:
что уехало, в каком количестве, по какой цене.
3. Состав отгрузки уточняется [изменением отгрузки](/docs/merchant/order/shipment_update/) —
пересорт и недовоз фиксируются до закрытия документов.
4. Позиции, которых не оказалось, снимаются
[возвратом с корректировкой](/docs/merchant/refund/correction/): клиент получает разницу,
а в УПД остаётся фактически поставленное.
Если товара нет и отгрузка невозможна, продавец сообщает об этом
[уведомлением о невозможности отгрузки](/docs/merchant/notification/shipping-unavailable/) —
Инвойсбокс вернёт деньги клиенту, не дожидаясь обращения в поддержку.
## Регулярные поставки
Для постоянных клиентов со стабильным заказом подойдёт подписка — шаблон платежа: счёт уходит
покупателю по правилу (период, день или условие), менеджер не напоминает об оплате.
> [!NOTE]
> Организациям адресована именно подписка, а не привязка карты: владелец карты всегда физлицо, и
> сотруднику пришлось бы отчитываться за расход перед бухгалтерией —
> [почему так](/docs/merchant/order/recurring/#почему-для-организаций-регулярность-устроена-иначе).
> Счёт по подписке удобно доставлять [Запросом о платеже](/docs/scenarios/rtp/) — прямо в банковское
> приложение покупателя.
### Проработанные интеграции
Готовые модули: [CMS](/docs/merchant/cms) (1С-Битрикс, WooCommerce, OpenCart и другие),
[ERP и CRM](/docs/merchant/erp), [платёжный виджет](/docs/merchant/widget) без разработки.
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# 🍽️ Системы автоматизации ресторанов
# Системы автоматизации ресторанов (CRM, ERP, RAS)
Корпоративный гость в зале ресторана хочет уйти с закрывающими документами, а не с чеком на
физлицо. Мини-приложение Инвойсбокс выставляет счёт на организацию прямо со стола — по QR-коду,
номер стола уходит в метаданные заказа, оплата подтверждается на месте, а акт и счёт-фактура
отправляются в бухгалтерию клиента по электронному документообороту.
> [!IMPORTANT]
> Выступая в качестве партнёра Инвойсбокс, оператор системы автоматизации ресторанов получает вознаграждение от оборота — [как оно считается](/docs/partner/#вознаграждение-партнёра).
## Базовая схема взаимодействия
### Подключение ресторана к Инвойсбоксу
В ERP-системе может быть реализована возможность подключения приёма оплаты через систему Инвойсбокс.
При выборе такой опции ERP-система сможет направить по API [приглашение](/docs/partner/integration/invite/)
для прохождения процедур регистрации ресторана в системе Инвойсбокс. Приглашение будет отправлено
представителю по электронной почте.
По завершении регистрации система Инвойсбокс направит представителю ресторана специальный
код активации. С помощью кода активации ERP-система сможет получить [параметры авторизации](/docs/partner/integration/activation/), необходимые для дальнейшего использования API.
### Оформление заказа и счёта на оплату
После активации функции приёма платежей в кассах ресторана размещается способ оплаты **Оплата по счёту для организаций и ИП**.
**Сценарий с участием официанта**
Гость желает рассчитаться за обед как организация или ИП, сообщает об этом официанту.
При выборе способа расчёта на кассе (оплата по счёту) ERP-система [формирует заказ](/docs/merchant/order/create/)
от имени ресторана в системе Инвойсбокс, передавая состав заказа для оформления счёта и отчётных документов
(например, актов).
Официант выносит гостю пречек с QR-кодом. В QR-коде кодируется ссылка для перехода на платёжный шлюз. Ссылку возвращает [создание заказа](/docs/merchant/order/create/) — поле `paymentUrl`.
Гость сканирует QR-код и подтверждает оплату в приложении Инвойсбокс или мобильном браузере. После оплаты
заказ считается закрытым, а в ERP-систему поступает
[уведомление о смене статуса](/docs/merchant/notification/status/).
Если счёт открыт заранее — гость заказывает в течение вечера, а сумма растёт, — вместо оплаты по пречеку
подойдёт [холдирование](/docs/scenarios/guarantee/): при открытии стола резервируется предполагаемая сумма
[заказом с холдированием](/docs/merchant/order/hold/), а по закрытию списывается фактический счёт.
Блокировка средств — не оплата: деньги остаются у гостя до списания.
**Сценарий без участия официанта**
Ресторан формирует для каждого стола специальный статичный QR-код. QR-код может быть размещён в информационном
тейбл тенте. За таким QR-кодом стоит мини-приложение: гость открывает его, видит текущий счёт стола, а система
автоматизации [создаёт заказ](/docs/merchant/order/create/) с номером стола в
[метаданных](/docs/merchant/order/metadata/) — по нему счёт находится и закрывается без участия официанта.
Гость желающий рассчитаться за обед как организация или ИП, сканирует QR-код. Система Инвойсбокс запрашивает по
номеру стола актуальную корзину заказа для оплаты в кассовой системе. Пользователь подтверждает оплату заказа,
стол закрывается.
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт ресторана, а оператору ERP-системы - вознаграждение.
## Размещение информации в маркетплейсе Инвойсбокс
Информация о ресторане или множестве ресторанов может быть опубликована в [маркетплейсе Инвойсбокс](/docs/marketplace).
Маркетплейс Инвойсбокс позволит привлечь дополнительный поток клиентов за счёт продвижения информации на ресурсах сервиса
и его партнёров.
При наличии веб-витрины ресторана в ERP-системе (например, доставка еды или бизнес-ланчей) форма заказа может быть
размещена в маркетплейсе в виде [мини-приложения](/docs/marketplace/mini-apps/), реализованного на стороне ERP-системы.
Для дополнительной информации см. [схему взаимодействия](/docs/marketplace/mini-apps/schema/).
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
---
# 🚆 B2B продажи ж/д билетов
# Автоматизация продаж ж/д билетов юридическим лицам и ИП (b2b)
У железной дороги свои правила: тайм-лимит брони короче авиационного, а сервисный сбор агентства
покупателю не возвращается. Оплата по счёту должна успеть в этот срок.
Инвойсбокс выставляет счёт организации сразу и подтверждает оплату до истечения тайм-лимита; акт и
счёт-фактура уходят клиенту по ЭДО после оплаты.
Что это даёт перевозчику:
- корпоративный клиент оплачивает билет по счёту, с отсрочкой или картой, не покидая сайт;
- деньги приходят на счёт на следующий рабочий день после подтверждения оплаты ([сроки](/docs/terms/));
- закрывающие документы формируются после оплаты и уходят клиенту по ЭДО;
- срок оплаты равен тайм-лимиту брони и задаётся полем `expirationDate` при [создании заказа](/docs/merchant/order/create/).
### Оплата бронирований с любым тайм-лимитом
Способы оплаты Инвойсбокс для организаций и ИП позволяют корпоративным клиентам оплачивать электронные
билеты с любым тайм-лимитом (от одной минуты), открывая возможность покупки билетов по промо- и бюджетным тарифам
так же, как при покупках с помощью банковской карты.
Постоянные корпоративные клиенты могут получить отсрочку до 30 дней, при этом перевозчик гарантированно
получает денежные средства на следующий рабочий день после подтверждения оплаты бронирования.
### Подтверждение за минуты и отчёты в своём формате
Подтверждение оплаты приходит перевозчику за считанные минуты — так же быстро, как при оплате картой,
поэтому короткий тайм-лимит не мешает продавать корпоративному клиенту по счёту
([платёжные инструменты](/docs/merchant/payment-instruments/)).
Отчёты приходят в том формате, который принят у перевозчика: состав полей и разбивку можно расширить
или собрать по его требованиям при подключении.
### Обработка возвратов
Сервис Инвойсбокс поддерживает как автоматизированное оформление возвратов, так и в ручном режиме через
личный кабинет. Денежные средства по возврату зачисляются клиенту до двух рабочих дней — срок зависит от способа оплаты.
### Автоматизированный документооборот
Отчётные документы для клиента формируются автоматически после подтверждения оплаты бронирования, а оригиналы
могут быть отправлены в бумажном виде по почте или [каналам ЭДО](/docs/merchant/documentflow/).
### Работа с динамическим ценообразованием
Схема интеграции предполагает возможность изменения стоимости бронирования до момента его оплаты. На каждом этапе
оплаты от формирования счёта до его оплаты негативные сценарии отрабатываются как автоматически с использованием
информирования клиента, так и с привлечением специалистов службы клиентской поддержки.
Штатные ситуации отрабатываются автоматически: клиент получает уведомление, а система бронирования —
[сообщение о смене статуса заказа](/docs/merchant/notification/status/). Специалист поддержки подключается
там, где автоматика бессильна: нестандартное оформление, спорная оплата, ручной возврат.
### Схема взаимодействия с клиентом
- После того, как заказ/бронь сформирована, клиент переходит на страницу выбора способа оплаты. Как правило, мы
предлагаем перевозчику разместить на сайте дополнительный способ "Оплата по счёту для организаций и ИП".
- Если клиент выбирает способ оплаты "Оплата по счёту для организаций и ИП", система бронирования передаёт в систему
Инвойсбокс состав заказа и данные бронирования для формирования счёта на оплату.
- В зависимости от тайм-лимита (TL) бронирования система автоматически формирует набор доступных способов оплаты.
Тайм-лимит у бронирования может быть любой.
- Если тайм-лимит короткий, оплату подтверждают до прихода денег: обещанным платежом (сумма счёта
блокируется на карте, счёт уходит организации на пять суток) или из гарантийного фонда — см.
[платёжные инструменты для B2B](/docs/merchant/payment-instruments/). Билет оформляется сразу вместе
со счётом.
- Если тайм-лимит свыше 24х часов, то ко всем возможностям, описанным выше, добавляется простой выпуск счёта с ожиданием
оплаты в течение суток.
- После получения подтверждения оплаты по счёту в течение срока действия бронирования, информация об оплате передаётся
в систему бронирования, происходит оформление билета и иных документов (например, при оплате дополнительных услуг).
- Все закрывающие документы оформляет и отправляет клиенту система Инвойсбокс. Важно, чтобы в билете был
выделен НДС. Никакой дополнительной нагрузки на бухгалтерию перевозчика, связанной с запуском нового способа оплаты, не возникает.
- Система бронирования может передавать информацию о возврате средств клиенту от перевозчика. Обычно после получения
уведомления от перевозчика деньги возвращаются до двух рабочих дней — срок зависит от способа оплаты.
## Чем железная дорога отличается от авиа
- **Короткий тайм-лимит.** Места в поезде удерживаются минутами, а не часами: пока корпоративный
клиент согласует счёт, бронь сгорает. Поэтому основной режим — оплата с подтверждением до прихода
денег: [обещанный платёж](/docs/merchant/payment-instruments/),
[подтверждение кодом](/docs/merchant/guarantee/) из гарантийного фонда или
[холдирование](/docs/scenarios/guarantee/). Билет оформляется сразу, деньги списываются после.
- **Сервисный сбор возвращается не всегда.** Возврат билета почти всегда частичный, и удержание
зависит от тарифа. Оформляйте [возврат с корректировкой](/docs/merchant/refund/correction/):
клиент получает разницу, а в закрывающих документах остаётся удержанная сумма.
- **Поездка редко бывает одна.** Командировка — это билеты туда и обратно, иногда с пересадками
и постельным бельём отдельной позицией. Чтобы бухгалтерия клиента получила один счёт вместо
четырёх, объедините заказы [контейнером](/docs/merchant/order/create-order-container/).
- **Номер заказа перевозчика** удобно передавать в [метаданных](/docs/merchant/order/metadata/) —
он вернётся в уведомлениях и попадёт в документы, по которым клиент сверяет поездки.
### Проработанные интеграции
Решение Инвойсбокс отработано с такими системами, как "Экспресс".
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
## Читайте также
- [Оформление возврата](/docs/merchant/refund/create/)
---
# 🏨 Управление средствами размещения (PMS)
# Cистемы управления гостиницами, отелями и хостелами (PMS)
Гость бронирует номер, а платит за него компания: командировку оформляет работодатель, и ему нужен счёт
с реквизитами, акт и счёт-фактура. Пока документы едут по почте, номер уже занят и выезд состоялся.
Инвойсбокс встраивает в систему управления оплату картой, через СБП и по счёту для организаций и ИП.
Физлицу уходит [фискальный чек по 54-ФЗ](/docs/merchant/fz54/), организации — отчётные документы через
ЭДО, курьером или почтой.
> [!IMPORTANT]
> Выступая в качестве партнёра Инвойсбокс, оператор PMS получает вознаграждение от оборота — [как оно считается](/docs/partner/#вознаграждение-партнёра).
## Подключение средств размещения к Инвойсбоксу
В системе PMS может быть реализован автоматическое подключение средства размещения и запуск приёма оплаты
через систему Инвойсбокс. При выборе такой опции система PMS направляет по API [приглашение](/docs/partner/integration/invite/)
для прохождения регистрации средства размещения в системе Инвойсбокс. Приглашение будет отправлено
представителю средства размещения по электронной почте.
По завершении регистрации система Инвойсбокс направит представителю средства размещения специальный
код активации. С помощью кода активации система PMS получит [параметры авторизации](/docs/partner/integration/activation/),
необходимые для дальнейшего использования API от имени средства размещения.
## Оформление заказа и счёта на оплату
После активации функции приёма платежей на странице выбора способа оплаты бронирования размещаются
опции выбора - **Оплата онлайн** и **Оплата по счёту для организаций и ИП**. В системе PMS может быть
отрегулировано отображение той или иной опции. С точки зрения API, регулирование опции происходит за
счёт передачи параметра - [тип плательщика](/docs/merchant/order/create/#customer).
При выборе опции оплаты система PMS [формирует заказ](/docs/merchant/order/create/) от имени средства размещения
в системе Инвойсбокс, передавая параметры бронирования в [специальных метаданных](/docs/merchant/order/metadata/#данные-бронирования-места-проживания),
а также даты заселения и выезда для корректного оформления отчётных документов (например, акта, УПД и пр.) и тип плательщика.
После успешного формирования заказа система PMS переадресует гостя на платёжную страницу системы Инвойсбокс для подтверждения
оплаты заказа.
Так выглядит заказ на проживание: состав — ночи и допуслуги, в метаданных — бронь, номер и даты,
по которым бухгалтерия гостя поймёт, за что заплатила.
``` json
{
"merchantId": "01f1c3f8-0000-0000-0000-000000000001",
"merchantOrderId": "PMS-2026-04817",
"amount": "24800.00",
"currencyId": "643",
"description": "Проживание, Гранд Отель Европа, 12–14 августа",
"expirationDate": "2026-08-10T18:00:00+03:00",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"vatNumber": "7701234560",
"email": "buh@example.invbox.ru"
},
"basketItems": [
{
"sku": "ROOM-DBL",
"name": "Двухместный номер, 2 ночи",
"quantity": 2,
"amount": "22000.00",
"vatCode": "RUS_VAT22",
"measure": "сут."
},
{
"sku": "BREAKFAST",
"name": "Завтрак",
"quantity": 4,
"amount": "2800.00",
"vatCode": "RUS_VAT22",
"measure": "шт."
}
],
"metaData": {
"@type": "ReservationPackage",
"subReservation": [
{
"@type": "LodgingReservation",
"reservationId": "YQVM18",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"checkinTime": "2026-08-12T14:00:00+03:00",
"checkoutTime": "2026-08-14T12:00:00+03:00"
}
]
}
}
```
Полный список полей брони — в [метаданных заказа](/docs/merchant/order/metadata/#данные-бронирования-места-проживания),
структура запроса целиком — на странице [создания заказа](/docs/merchant/order/create/).
После подтверждения оплаты заказа гость возвращается на страницу системы PMS, а система Инвойсбокс
асинхронно направляет [уведомление об оплате](/docs/merchant/notification), оплата бронирования подтверждается.
Гость получает ваучер или иной подтверждающий бронирование документ.
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт средства размещения, а оператору системы PMS - вознаграждение.
При выезде гостя из отеля, система PMS может [передать информацию](/docs/merchant/order/update/) об актуальной
стоимости проживая и дополнительных услугах, которые были предоставлены гостю. Актуальные сведения необходимы для
корректного формирования отчётных документов (в зависимости от типа плательщика).
В системе PMS могут быть также реализованы функции [отмены заказа](/docs/merchant/order/delete/) или
[оформления возврата](/docs/merchant/refund). Если отель удерживает часть суммы за поздний отказ,
возврат оформляется [с корректировкой](/docs/merchant/refund/correction/) — удержание остаётся
в закрывающих документах.
Акт, счёт-фактуру и УПД Инвойсбокс формирует сам и отправляет корпоративному гостю
[по каналам ЭДО](/docs/merchant/documentflow/) — отелю подключать оператора отдельно не нужно.
## Размещение информации в маркетплейсе Инвойсбокс
Информация о средстве или множестве средств размещения может быть опубликована в [маркетплейсе Инвойсбокс](/docs/marketplace).
Маркетплейс Инвойсбокс позволит привлечь дополнительный поток клиентов за счёт продвижения информации на ресурсах сервиса и
его партнёров.
Отдельным взаимодействием системы PMS и маркетплейса может быть [мини-приложение](/docs/marketplace/mini-apps/), реализованное и работающее на стороне системы PMS.
Мини-приложение представляет из себя форму заказа товаров или услуг в сервисе поставщика, которая открывается в маркетплейсе Инвойсбокс (веб или мобильное приложение) и взаимодействует с системой Инвойсбокс.
Мини-приложение сможет предлагать пользователям Инвойсбокс забронировать комнату или номер в качестве дополнительной услуги к основному заказу, например, при покупке авиабилета.
Для дополнительной информации см. [схему взаимодействия](/docs/marketplace/mini-apps/schema/).
> Если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы будем рады вам помочь!
---
# ⛽ B2B продажи на АЗС
# Сценарий продажи топлива и дополнительных услуг на АЗС
Топливо отпускают до того, как известна сумма: заправка идёт по лимиту талона, а платит клиент за
фактический налив. Инвойсбокс выставляет счёт на лимит у колонки или на кассе, а после налива заказ
пересчитывается на фактическую сумму — организация получает один счёт и закрывающие документы, без
авансовых отчётов и бумажных талонов.
> [!IMPORTANT]
> Выступая в качестве партнёра Инвойсбокс, оператор приложения или системы автоматизации АЗС получает
> вознаграждение от оборота — [как оно считается](/docs/partner/#вознаграждение-партнёра).
Водитель не ждёт у колонки: подтверждение оплаты приходит на кассу за минуты, как при оплате картой
([платёжные инструменты](/docs/merchant/payment-instruments/)).
## Базовая схема взаимодействия
### Реализация мини-приложения
На стороне системы АЗС формируется [мини-приложение](/docs/marketplace/mini-apps). В мини-приложении
реализуются следующие функции (экраны):
- Экран поиска АЗС (список или карта, опционально)
- Экран детальной информации по АЗС и форма заказа - выбор типа топлива, номера колонки, объёма и перечень доп. услуг (или товаров)
- Опционально, другие экраны в соответствии с процессами покупки в рамках АЗС или сети АЗС
- Экран подтверждения заказа
- Функция создания заказа в системе Инвойсбокс
- Экран успешного подтверждения оплаты заказа
Информация об АЗС или множестве АЗС публикуется в [маркетплейсе Инвойсбокс](/docs/marketplace).
Для получения дополнительной информации см. также [описание работы мини-приложения](/docs/marketplace/mini-apps/description/) с
мини-приложением.
### Оформление заказа и счёта на оплату
**Сценарий без участия оператора (автомат)**
Клиент в приложении Инвойсбокс находит подходящую АЗС или приложение подсказывает пользователю ближайшую АЗС
на основе его геопозиции. Приложение Инвойсбокс инициализирует мини-приложение АЗС, покупатель оформляет заказ
в мини-приложении и подтверждает его оплату. По факту подтверждения оплаты заказа, покупатель производит заправку
автомобиля или получает товары/услуги.
**Сценарий с участием оператора**
Клиент желает рассчитаться за топливо, товары или услуги как организация или ИП, сообщает об этом оператору АЗС на
кассе.
При выборе способа расчёта на кассе (оплата по счёту) ERP-система [формирует заказ](/docs/merchant/order/create/)
от имени АЗС в системе Инвойсбокс, передавая состав заказа для оформления счёта и отчётных документов
(например, актов).
Оператор передаёт клиенту пречек с QR-кодом. В QR-коде кодируется ссылка для перехода на платёжный шлюз. Ссылку возвращает [создание заказа](/docs/merchant/order/create/) — поле `paymentUrl`.
Клиент сканирует QR-код и подтверждает оплату в приложении Инвойсбокс или мобильном браузере. После успешного подтверждения
оплаты, заказ считается оплаченным, а в ERP-систему поступает [уведомление об оплате](/docs/merchant/notification).
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт юридического лица АЗС, а оператору ERP-системы - вознаграждение.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
## Читайте также
- [Открывайте заказ с холдированием на предельную сумму](/docs/merchant/order/hold/)
---
# 🚕 B2B продажи такси и трансфера
# Сценарий продажи услуг такси и трансфера пассажиров
Корпоративные поездки неудобны обеим сторонам: сумма известна только после поездки, а счетов за
месяц набирается несколько десятков. Инвойсбокс закрывает и то, и другое: сумму можно зарезервировать
на карте и списать по факту, а месячные поездки собрать в один счёт заказом-контейнером — бухгалтерия
клиента получает один документ вместо тридцати.
## Базовая схема взаимодействия
### Реализация мини-приложения
На стороне системы бронирования услуг такси или трансфера формируется [мини-приложение](/docs/marketplace/mini-apps).
В мини-приложении реализуются следующие функции (экраны):
- Экран выбора пункта отправления/назначения (список или карта, опционально)
- Экран детальной информации о поездке (пункт назначения, тариф, расстояние и пр.) и форма заказа
- Опционально, другие экраны в соответствии с процессами покупки в рамках системы бронирования
- Экран подтверждения заказа
- Функция создания заказа в системе Инвойсбокс
- Экран успешного подтверждения оплаты заказа
Информация о службе такси или трансфера публикуется в [маркетплейсе Инвойсбокс](/docs/marketplace).
Для получения дополнительной информации см. также [описание работы мини-приложения](/docs/marketplace/mini-apps/description/) с
мини-приложением.
### Оформление заказа и счёта на оплату
Клиент, на платёжной странице, в процессе оформления авиа- или ж/д- перевозки или в приложении Инвойсбокс, изъявляет
желание добавить к заказу услугу такси или трансфера. Платёжная страница или приложение Инвойсбокс инициализирует мини-приложение
системы бронирования такси или трансфера. Мини-приложение системы бронирования может подсказать подходящие параметры исходя из
пункта отправления/назначения. Покупатель оформляет заказ в мини-приложении и подтверждает его оплату. По факту
подтверждения оплаты заказа, покупатель получает ваучер на услугу или саму услугу.
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт юридического лица оператора услуг такси или трансфера.
## Расчёт по факту поездки
Стоимость поездки известна только на финише: маршрут изменился, клиент попросил заехать по пути,
добавилось время ожидания. Выставлять счёт заранее — значит каждый раз доначислять или возвращать.
Для этого есть [холдирование](/docs/scenarios/guarantee/): при подаче машины резервируется
максимальная стоимость маршрута — [заказ с холдированием](/docs/merchant/order/hold/), — а по
завершении поездки списывается фактическая сумма. Разница освобождается на карте клиента сама,
отдельный возврат не нужен.
Для корпоративных клиентов с регулярными поездками удобнее не резервировать каждый раз, а собирать
поездки за период в один счёт: заказы группируются
[заказом-контейнером](/docs/merchant/order/create-order-container/), и бухгалтерия клиента получает
один документ вместо тридцати.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
---
# ⭐ B2B продажи бизнес-залов
# Сценарий продажи услуг бизнес-залов
Доступ в бизнес-зал покупают и заранее, вместе с билетом, и на стойке за минуту до вылета — а
компания-плательщик в обоих случаях ждёт счёт и закрывающие документы. Инвойсбокс закрывает оба
пути: оплату можно подтвердить онлайн в момент оформления билета или на месте через
мини-приложение, документы уходят в бухгалтерию клиента по электронному документообороту.
Скорость здесь решает: пассажир стоит у стойки, и подтверждение оплаты приходит оператору за минуты —
столько же, сколько занимает оплата картой ([платёжные инструменты](/docs/merchant/payment-instruments/)).
Комиссию можно оставить оператору, разделить с пассажиром или переложить на его компанию —
[кто платит комиссию](/docs/terms/#кто-платит-комиссию).
## Базовая схема взаимодействия
### Реализация мини-приложения
На стороне системы бронирования бизнес-зала формируется [мини-приложение](/docs/marketplace/mini-apps).
В мини-приложении реализуются следующие функции (экраны):
- Экран выбора пункта отправления/назначения (список или карта, опционально)
- Экран детальной информации о бизнес-зале и форма заказа
- Опционально, другие экраны в соответствии с процессами покупки в рамках системы бронирования
- Экран подтверждения заказа
- Функция создания заказа в системе Инвойсбокс
- Экран успешного подтверждения оплаты заказа
Информация о бизнес-зале или множестве залов публикуется в [маркетплейсе Инвойсбокс](/docs/marketplace).
Для получения дополнительной информации см. также [описание работы мини-приложения](/docs/marketplace/mini-apps/description/) с
мини-приложением.
### Оформление заказа и счёта на оплату
**Сценарий онлайн оплаты услуги**
Клиент, на платёжной странице, в процессе оформления авиа- или ж/д- перевозки или в приложении Инвойсбокс, изъявляет
желание добавить к заказу услугу бизнес-зала. Платёжная страница или приложение Инвойсбокс инициализирует мини-приложение
системы бронирования бизнес-зала. Мини-приложение системы бронирования может подсказать подходящий бизнес-зал исходя из
пункта отправления/назначения. Покупатель оформляет заказ в мини-приложении и подтверждает его оплату. По факту
подтверждения оплаты заказа, покупатель получает ваучер на услугу или саму услугу.
**Сценарий с участием представителя (на месте)**
Клиент желает рассчитаться за услуги бизнес-зала как организация или ИП, сообщает об этом представителю на месте.
При выборе способа расчёта на кассе (оплата по счёту) ERP-система (или система бронирования) [формирует заказ](/docs/merchant/order/create/)
от имени оператора бизнес-зала в системе Инвойсбокс, передавая состав заказа для оформления счёта и отчётных документов
(например, актов).
Представитель передаёт клиенту пречек с QR-кодом. В QR-коде кодируется ссылка для перехода на платёжный шлюз. Ссылку возвращает [создание заказа](/docs/merchant/order/create/) — поле `paymentUrl`.
Клиент сканирует QR-код и подтверждает оплату в приложении Инвойсбокс или мобильном браузере. После успешного подтверждения
оплаты, заказ считается оплаченным, а в ERP-систему поступает [уведомление об оплате](/docs/merchant/notification).
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт юридического лица оператора бизнес-зала.
## Что происходит после оплаты
- Оператор бизнес-зала получает [уведомление об оплате](/docs/merchant/notification/status/) —
по нему ваучер активируется, а гостя пускают в зал без ожидания подтверждения от бухгалтерии.
- Если гость воспользовался не всеми услугами или не пришёл вовсе, состав уточняется
[изменением заказа](/docs/merchant/order/update/) до закрытия документов.
- Неиспользованный визит возвращается [возвратом](/docs/merchant/refund/create/);
при удержании по тарифу — [возвратом с корректировкой](/docs/merchant/refund/correction/).
- Закрывающие документы уходят корпоративному клиенту
[по ЭДО](/docs/merchant/documentflow/) — акт и счёт-фактуру оператору формировать не нужно.
Гостям, которые пользуются залами регулярно, подойдёт
[холдирование](/docs/scenarios/guarantee/): сумма резервируется при бронировании, а списывается
фактическое обслуживание — с допуслугами, если они были.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
---
# ☂️ B2B продажи услуг страхования пассажиров
# Сценарий продажи услуг страхования пассажиров
Полис продаётся вместе с билетом и возвращается вместе с ним же — с удержанием части премии по
правилам страховщика. Инвойсбокс позволяет продать страховку тем же заказом, что и билет, а при
отказе оформить частичный возврат: клиент-организация видит одну операцию и получает документы по
электронному документообороту.
## Базовая схема взаимодействия
### Реализация мини-приложения
На стороне учётной системы страховых услуг формируется [мини-приложение](/docs/marketplace/mini-apps).
В мини-приложении реализуются следующие функции (экраны):
- Экран детальной информации о страховании поездки и форма заказа
- Опционально, другие экраны в соответствии с процессами покупки в рамках системы страхования
- Экран подтверждения заказа
- Функция создания заказа в системе Инвойсбокс
- Экран успешного подтверждения оплаты заказа
Информация об услуге страхования публикуется в [маркетплейсе Инвойсбокс](/docs/marketplace).
Для получения дополнительной информации см. также [описание работы мини-приложения](/docs/marketplace/mini-apps/description/) с
мини-приложением.
### Оформление заказа и счёта на оплату
Клиент, на платёжной странице, в процессе оформления авиа- или ж/д- перевозки или в приложении Инвойсбокс, изъявляет
желание добавить к заказу услугу страхования. Платёжная страница или приложение Инвойсбокс инициализирует мини-приложение
системы страхования. Мини-приложение может подсказать подходящие параметры исходя из данных основного заказа.
Покупатель оформляет заказ в мини-приложении и подтверждает его оплату. По факту подтверждения оплаты заказа, покупатель
получает ваучер на услугу.
Система Инвойсбокс перечисляет денежные средства консолидированным платежом на следующий рабочий день на
расчётный счёт юридического лица оператора услуг страхования.
## Возврат страховки
Полис возвращают чаще, чем билет: пассажир отказался от перелёта, страховка оказалась дублем
корпоративной, изменились даты. Возврат оформляется
[методом возврата](/docs/merchant/refund/create/) — полностью или частично, если страховая
удерживает часть премии за прошедший период.
Когда удержание есть, используйте
[возврат с корректировкой](/docs/merchant/refund/correction/): клиенту уходит разница, а в
закрывающих документах остаётся фактически оказанная услуга. Состав возврата, доступный к оформлению,
можно получить [запросом позиций заказа](/docs/merchant/refund/get/) — так не придётся считать
остаток на своей стороне.
О каждом шаге система страховщика узнаёт из
[уведомления о смене статуса](/docs/merchant/notification/status/).
## Страховка вместе с билетом
Страховка почти никогда не продаётся отдельно. Чтобы у корпоративного клиента не появлялось
несколько счетов на одну поездку, объедините билет, страховку и допуслуги
[заказом-контейнером](/docs/merchant/order/create-order-container/): оплата одна, документы —
по каждой услуге.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
## Читайте также
- [Основной заказ описан в кейсе продажи авиабилетов](/docs/scenarios/air-carriers/)
---
# 📦 Аренда складов, офисов и коворкингов
# Автоматизация оплат за аренду складов, офисов и коворкингов организациям и ИП (b2b)
Арендатор платит одну и ту же сумму каждый месяц, и каждый месяц кто-то вручную выставляет ему счёт, а
потом сверяет оплату с выпиской. К этому добавляются доначисления: уборка, парковка, переработка по
времени.
Инвойсбокс убирает ручные шаги: счёт уходит арендатору по правилу, оплата возвращается уведомлением, а
акт за период формируется сам.
Что это даёт арендодателю:
- арендатор платит по счёту, с отсрочкой до 30 дней или по [подписке](/docs/merchant/order/recurring/);
- деньги приходят на счёт на следующий рабочий день после подтверждения оплаты ([сроки](/docs/terms/));
- акт и счёт-фактура за период формируются автоматически и уходят по ЭДО;
- срок оплаты счёта задаётся полем `expirationDate` при [создании заказа](/docs/merchant/order/create/).
### Оплата аренды с любым сроком
Способы оплаты Инвойсбокс для организаций и ИП позволяют корпоративным клиентам оплачивать услуги аренды
с любым сроком оплаты (от одной минуты), открывая возможность экстренного оформления или продления услуги.
Срок задаётся полем `expirationDate` при [создании заказа](/docs/merchant/order/create/): по его истечении
неоплаченный счёт можно [отменить](/docs/merchant/order/delete/) и освободить помещение под следующего клиента.
Постоянные корпоративные клиенты могут получить отсрочку до 30 дней, при этом арендодатель гарантированно
получает денежные средства на следующий рабочий день после подтверждения оплаты.
### Регулярные платежи за аренду
Аренда — это оплата каждый месяц в одну и ту же дату, и напоминать о ней менеджеру не нужно.
Подписка закрывает ежемесячную арендную плату и коммунальные услуги: счёт уходит арендатору по
правилу — в нужный день или по условию, — а документы формируются по ЭДО.
> [!NOTE]
> Арендатору-организации адресована подписка, а не привязка карты: карта всегда оформлена на человека,
> и сотруднику пришлось бы объяснять расход бухгалтерии —
> [чем подписка отличается от рекуррентов](/docs/merchant/order/recurring/#почему-для-организаций-регулярность-устроена-иначе).
> Доставить счёт удобно [Запросом о платеже](/docs/scenarios/rtp/): он приходит в банковское приложение,
> оплата в один шаг.
Разовые доначисления — уборка, парковочное место, переработка по времени — оформляются отдельным заказом
или [изменением текущего](/docs/merchant/order/update/) до его оплаты.
Тем, кто платит не картой, а по счёту, удобнее [Запрос о платеже](/docs/scenarios/rtp): уведомление
приходит прямо в банковское приложение арендатора.
### Обработка возвратов
Сервис Инвойсбокс поддерживает как автоматизированное оформление возвратов, так и в ручном режиме через
личный кабинет. Денежные средства по возврату зачисляются арендатору до двух рабочих дней — срок зависит от способа оплаты.
### Автоматизированный документооборот
Отчётные документы для арендатора формируются автоматически после подтверждения оплаты, а оригиналы
могут быть отправлены в бумажном виде по почте или [через ЭДО](/docs/merchant/documentflow/).
### Схема взаимодействия с арендатором
- После того, как услуга оформлена, клиент переходит на страницу выбора способа оплаты. Как правило, мы
предлагаем арендодателю разместить на сайте дополнительный способ: "Оплата по счёту для организаций и ИП".
- Если клиент выбирает способ оплаты "Оплата по счёту для организаций и ИП", система управления складом передаёт в систему
Инвойсбокс состав заказа и данные для формирования счёта на оплату.
- Инвойсбокс позволяет формировать шаблоны счетов, которые могут автоматически направляться в виде ссылки для оплаты
арендатору по электронной почте, SMS или в мессенджер.
- В зависимости от срока оплаты счёта, система автоматически формирует набор доступных способов оплаты.
Срок оплаты может быть любой.
- Если срок оплаты короткий, подойдут инструменты с подтверждением до прихода денег — обещанный
платёж и гарантийный фонд ([платёжные инструменты для B2B](/docs/merchant/payment-instruments/)) —
или способы с мгновенным подтверждением: СБП, Запрос о платеже, оплата через банк-клиент (Альфа-Бизнес
Онлайн, СберБизнес, Т-Бизнес и другие).
- Если срок оплаты свыше 24х часов, то ко всем возможностям, описанным выше, добавляется простой выпуск счёта с ожиданием
оплаты в течение суток банковским переводом.
- После получения подтверждения оплаты по счёту, информация об оплате передаётся в систему арендодателя, происходит оформление услуги
и иных документов (например, при оплате дополнительных услуг).
- Все закрывающие документы оформляет и отправляет клиенту система Инвойсбокс. Никакой дополнительной нагрузки на бухгалтерию арендодателя,
связанной с запуском нового способа оплаты, не возникает.
### Свяжитесь с нами
Для настройки интеграции, пожалуйста, [напишите нам](https://www.invoicebox.ru/ru/contacts).
---
# ☁️ Подписки на сервисы для юрлиц (SaaS, хостинг, телеком)
# Подписки на сервисы для организаций и ИП (SaaS, хостинг, телеком)
Продавать подписку физлицу просто: карта привязана, списание идёт само. С организацией так не выходит.
Бухгалтерия платит по счёту, деньги идут через банк, и каждый месяц повторяется одна и та же работа:
выставить счёт, дождаться перевода, свести оплату с лицевым счётом, отправить акт. Пока перевод идёт,
сервис или отключается раньше времени, или работает в долг.
Инвойсбокс закрывает этот цикл: счёт уходит покупателю сам, оплата подтверждается за минуты или
секунды — в зависимости от [платёжного инструмента](/docs/merchant/payment-instruments/), — а акт и
счёт-фактура за период формируются без участия менеджера.
## Подписка для юрлица — это счёт по правилу, а не привязка карты
> [!IMPORTANT]
> Списание по сохранённой карте работает, но владелец карты — всегда физлицо: даже корпоративная карта
> оформлена на сотрудника, и расход придётся объяснять бухгалтерии — чек, обоснование, авансовый отчёт.
> Поэтому организациям адресована подписка: счёт уходит компании по правилу —
> [чем это отличается от рекуррентов](/docs/merchant/order/recurring/#почему-для-организаций-регулярность-устроена-иначе).
Правило задаёт период, конкретный день или условие — например, снижение баланса до порога. Собрать
подписку можно двумя способами:
- **расписание держит ваша система.** На каждый оплачиваемый период она
[создаёт заказ](/docs/merchant/order/create/) со сроком оплаты и составом по тарифу — биллинг и так
знает, когда у клиента заканчивается период. Инвойсбокс берёт на себя счёт, приём оплаты и документы.
- **расписание держит подписка.** Заказ-подписка создаётся один раз с параметрами периода и условий,
клиент подписывается на неё, и счета уходят ему сами. Параметры настраиваются при подключении —
публичного описания полей пока нет, состав правил уточняйте в
[поддержке](https://www.invoicebox.ru/ru/contacts).
Дальше в кейсе разобран первый способ: он не требует ничего, кроме обычного создания заказа.
Так выглядит счёт за месяц по тарифу. Номер договора и период попадают в `merchantOrderId` и
`description` — по ним бухгалтерия клиента поймёт, за что платит, а вы найдёте оплату в своей системе.
``` json
{
"merchantId": "01f1c3f8-0000-0000-0000-000000000001",
"merchantOrderId": "SUB-4417-2026-08",
"amount": "48000.00",
"currencyId": "643",
"description": "Тариф «Команда», август 2026, договор 4417",
"expirationDate": "2026-08-05T23:59:00+03:00",
"customer": {
"type": "legal",
"name": "ООО «Ромашка»",
"vatNumber": "7701234560",
"email": "buh@example.invbox.ru"
},
"basketItems": [
{
"sku": "TEAM-30",
"name": "Тариф «Команда», 30 рабочих мест, август 2026",
"quantity": 1,
"amount": "48000.00",
"vatCode": "RUS_VAT22",
"measure": "мес."
}
]
}
```
В позиции корзины можно передать [данные подписки](/docs/merchant/order/metadata/#данные-подписки) —
объект `PaymentPlan` с периодом биллинга, датами начала и окончания договора и ценой. Тогда счёт несёт
не только сумму, но и условия: бухгалтерия клиента видит, за какой период и по какому договору платит.
Что происходит дальше:
1. Клиент получает счёт и оплачивает его — из своего банка, по
[Запросу о платеже](/docs/scenarios/rtp/) в приложении банка или подтверждением из гарантийного
фонда за секунды. Способ определяется договором и настройками в кабинете, запрос при этом одинаковый.
2. Инвойсбокс сообщает об оплате [уведомлением о смене статуса](/docs/merchant/notification/status/) —
ваш сервис продлевает период по этому сигналу, а не по факту прихода денег на счёт.
3. Акт и счёт-фактура за период уходят клиенту [через ЭДО](/docs/merchant/documentflow/) или на бумаге.
4. Деньги приходят на расчётный счёт на следующий рабочий день после подтверждения оплаты —
[сроки и условия](/docs/terms/).
## Срок оплаты и мягкое отключение
Поле `expirationDate` задаёт, до какого момента счёт живёт. Для подписки это удобно: счёт на следующий
месяц выставляется, скажем, за пять дней до его начала, и до этой даты клиент платит по прежней ссылке.
Когда срок проходит, заказ получает состояние `expired` — оплатить старую ссылку нельзя, нужен новый
заказ.
Отсюда же берётся политика отключения. Пока счёт не оплачен, сервис работает или не работает по вашим
правилам; Инвойсбокс лишь сообщает, оплачен счёт или нет. Неоплаченный счёт, который потерял смысл
(клиент сменил тариф или ушёл), [отменяется](/docs/merchant/order/delete/) до оплаты — в списке
клиента он не останется висеть.
Если клиент готов платить, но не успевает провести перевод, помогает
[обещанный платёж](/docs/merchant/payment-instruments/): покупатель подтверждает заказ картой за
минуту, вы продлеваете период сразу, а счёт организация оплачивает в течение пяти суток.
## Смена тарифа и доначисления сверх пакета
Подписка редко стоит одинаково весь год: клиент добавляет рабочие места, выходит за лимит трафика,
берёт дополнительный номер или диск. Есть два пути, и выбор зависит от того, оплачен ли текущий счёт.
- **Счёт ещё не оплачен** — [измените заказ](/docs/merchant/order/update/): состав и сумма
пересчитываются, ссылка остаётся прежней. Так удобно поправить тариф, о котором договорились уже
после выставления счёта.
- **Счёт оплачен** — доначисление оформляется отдельным заказом за тот же период. Прежний счёт и
документы по нему остаются неизменными, а бухгалтерия клиента видит два понятных документа вместо
одного исправленного.
Если период уже закрыт документами, а сумму нужно уменьшить — например, клиент оплатил тридцать
рабочих мест, а пользовался двадцатью, — это [возврат с корректировкой](/docs/merchant/refund/correction/):
возвращается часть суммы, а корректировочный документ уходит клиенту вслед за возвратом.
## Много клиентов — много счетов: как не потеряться
Телеком и хостинг выставляют счета сотнями, и главный вопрос к системе — не «как создать заказ», а
«как свести реестр». Для этого достаточно двух вещей:
- **Свой номер в каждом заказе.** `merchantOrderId` вида `SUB-4417-2026-08` — договор и период. По нему
[заказ находится](/docs/merchant/order/get/) без сохранения идентификаторов Инвойсбокса.
- **Выборки по состоянию и датам.** Список неоплаченных счетов с истекающим сроком собирается
[фильтрами](/docs/api/filters/): `status=created` и условие по `expirationDate`. Ночная сверка по
такому запросу заменяет обзвон клиентов.
Обработчик уведомлений стоит сделать идемпотентным: одно и то же уведомление может прийти дважды, и
период не должен продлеваться два раза — [как проверить свой обработчик](/docs/merchant/notification/status/).
## Что это даёт
- Клиент-организация платит привычным способом, а сервис продлевается по сигналу об оплате, а не через
два-три банковских дня.
- Счёт, акт и счёт-фактура за период формируются сами и уходят по ЭДО — менеджеру остаются только
спорные случаи.
- Отсрочку и риск неплатежа можно отдать платформе: постоянный клиент подтверждает оплату сразу, а
рассчитывается в течение 30 дней — [платёжные инструменты](/docs/merchant/payment-instruments/).
- Физлица закрываются тем же вендором: для них работают и
[списание по сохранённой карте](/docs/merchant/order/recurring/), и
[чек по 54-ФЗ](/docs/merchant/fz54/).
## Чем подключиться
| Путь | Когда подходит |
|---|---|
| [API и PHP SDK](/docs/merchant/) | биллинг сервиса ведёт расписание сам — обычный случай для SaaS и телекома |
| [Готовый модуль](/docs/merchant/cms/) | тарифы продаются на сайте: 1С-Битрикс, Тильда, WooCommerce и другие |
| [Платёжный виджет](/widgets/) | нужно принять оплату за подписку сегодня, до доработки биллинга |
| [ИИ-агент](/for-agents/) | интеграцию делает Cursor или Claude Code по одному промпту |
## Смежные кейсы
- [Аренда складов, офисов и коворкингов](/docs/scenarios/warehouses/) — та же регулярность, но с
привязкой к сроку договора.
- [B2B продажи 24/7](/docs/scenarios/b2b-sales/) — четыре вызова базового сценария.
- [Запрос о платеже](/docs/scenarios/rtp/) — счёт приходит клиенту в приложение банка.
Посмотреть, как выглядит выставленный счёт и уведомление об оплате, можно в демо
[Счёт юрлицу из CRM](/demo/crm/) — вызовы уходят на демо-контур.
---
---
# 🧾 Автоматизация дебиторки: счёт, оплата, закрытие
# Автоматизация дебиторки: от счёта до закрывающих документов
Дебиторка отнимает время не там, где её считают, а там, где её ведут вручную. Менеджер выставляет счёт
в учётной системе, выгружает его в PDF, отправляет письмом, отмечает в таблице, через неделю звонит
напомнить, ищет платёж в выписке, сводит сумму, отправляет акт. Ошибка на любом шаге превращается в
неоплаченный счёт, о котором никто не помнит.
Инвойсбокс убирает из этой цепочки ручные шаги: счёт уходит покупателю автоматически, оплата
возвращается в учётную систему уведомлением, а закрывающие документы формируются по факту оплаты.
Реестр перестаёт быть таблицей, которую кто-то поддерживает, и становится состоянием заказов.
## Как выглядит цикл
1. **Счёт рождается в вашей системе.** Реализация в 1С, закрытая сделка в CRM, отгрузка в ERP —
в этот момент система [создаёт заказ](/docs/merchant/order/create/) с типом плательщика `legal`,
составом и сроком оплаты в `expirationDate`.
2. **Счёт уходит покупателю.** По ссылке `paymentUrl`, письмом от Инвойсбокса или прямо в приложение
банка — [Запросом о платеже](/docs/scenarios/rtp/). Отправлять вложением из почты менеджера больше
не нужно.
3. **Покупатель платит удобным ему способом.** Классический перевод, ускоренная оплата в один шаг из
интернет-банка, подтверждение из гарантийного фонда за секунды —
[пять инструментов](/docs/merchant/payment-instruments/) отличаются только тем, как быстро приходит
подтверждение.
4. **Оплата возвращается в учётную систему.** Инвойсбокс присылает
[уведомление о смене статуса](/docs/merchant/notification/status/); ваш обработчик закрывает
задолженность по `merchantOrderId`. Ждать выписку и сверять платёжки по назначению платежа не нужно.
5. **Документы уходят сами.** Акт, счёт-фактура и УПД формируются по факту оплаты и отправляются
[через ЭДО](/docs/merchant/documentflow/), почтой или курьером.
6. **Деньги приходят на расчётный счёт** на следующий рабочий день после подтверждения оплаты —
[сроки](/docs/terms/).
## Реестр вместо таблицы
Состояние каждого счёта живёт в Инвойсбоксе, и его можно получить запросом — отдельный учёт вести
не нужно.
| Что нужно бухгалтерии | Как получить |
|---|---|
| Что оплачено за период | [заказы](/docs/merchant/order/get/) с фильтром `status=completed` и условием по дате |
| Что ждёт оплаты | `status=created` — счёт выставлен, срок ещё не прошёл |
| Что просрочено | `status=expired`: срок из `expirationDate` прошёл, по прежней ссылке не оплатить |
| Что отменено | `status=canceled` — счёт [снят](/docs/merchant/order/delete/) до оплаты |
Условия по датам, сортировки и постраничный вывод — в разделе [фильтров](/docs/api/filters/). Ночная
выборка неоплаченных счетов с истекающим сроком заменяет обзвон: система сама напоминает тем, у кого
срок на исходе.
Два правила, без которых сверка ломается:
- **Свой номер в каждом заказе.** `merchantOrderId` — номер счёта или договора из вашей системы. По нему
вы находите заказ и закрываете задолженность, не храня идентификаторы Инвойсбокса.
- **Идемпотентный обработчик.** Одно и то же уведомление может прийти дважды; повторная обработка не
должна закрывать задолженность второй раз — [как проверить обработчик](/docs/merchant/notification/status/).
## Счета, которые оплачивают мимо Инвойсбокса
У большинства продавцов часть покупателей платит напрямую на расчётный счёт: так сложилось, так
записано в договоре. Держать из-за них вторую систему учёта не обязательно.
Заказ можно создать [не процессинговым](/docs/merchant/order/non-processable-order/) — с флагом
`processable = false`. Денег по нему Инвойсбокс не проводит, но счёт живёт в общем реестре, а отметку об
оплате вы ставите сами [сменой статуса](/docs/merchant/order/order-status-update/), когда увидели
платёж в выписке. Реестр остаётся один, и «дебиторка» в отчёте совпадает с реальностью.
> [!NOTE]
> Смена статуса работает только для не процессинговых заказов. У обычных заказов состояние меняет сам
> Инвойсбокс по факту движения денег — вручную его переставить нельзя, и это защищает отчётность.
## Обратная сторона: оплата счетов из фонда
Если вы автоматизируете не выставление счетов, а их оплату — например, делаете корпоративный кабинет
или сервис снабжения, — работает [Инвойсбокс.Бизнес](/docs/business/). Покупатель держит гарантийный
фонд и в его пределах подтверждает оплату сразу, не дожидаясь банковского перевода; сверх фонда даётся
отсрочка.
Два метода закрывают этот процесс: [получение счёта](/docs/business/get/) — список счетов и их
состояние, и [подтверждение оплаты](/docs/business/confirm_payment/) — оплата счёта из фонда с вашим
`partnerOperationId`, чтобы повторный вызов не создал второй платёж.
## Что это даёт
- Задолженность закрывается в момент подтверждения оплаты, а не после сверки выписки.
- Счёт доходит до покупателя по каналу, которым он пользуется: банковское приложение, письмо, ссылка.
- Просроченные счёта видны запросом, а не по памяти менеджера.
- Закрывающие документы уходят без участия людей — [документооборот](/docs/merchant/documentflow/).
- Риск неплатежа и отсрочку можно передать платформе: деньги приходят в обычный срок —
[инструменты](/docs/merchant/payment-instruments/).
## Чем подключиться
| Путь | Когда подходит |
|---|---|
| [Модуль CRM](/docs/merchant/crm/) | счета выставляют менеджеры: amoCRM, retailCRM, SportCRM |
| [Модуль ERP или PMS](/docs/merchant/erp/) | счёт рождается в учётной системе: iiko, Bnovo |
| [API и PHP SDK](/docs/merchant/) | своя учётная система или доработанная 1С |
| [Готовый модуль CMS](/docs/merchant/cms/) | заказы приходят с сайта |
## Смежные кейсы
- [B2B продажи товаров](/docs/scenarios/retail/) — отгрузка партиями и возврат с корректировкой.
- [Подписки для юрлиц](/docs/scenarios/saas/) — счёт на каждый период и доначисления.
- [Запрос о платеже](/docs/scenarios/rtp/) — счёт в приложении банка покупателя.
Как это выглядит со стороны менеджера, показывает демо [Счёт юрлицу из CRM](/demo/crm/): счёт
выставляется настоящим вызовом на демо-контур, статус меняется, уведомление приходит.
---
---
# 🛒 Маркетплейс и сплит-корзина
# Маркетплейс и сплит-корзина: одна оплата, несколько продавцов
Площадка, которая продаёт чужой товар, живёт в противоречии. Покупателю нужен один счёт: он собрал
корзину из товаров трёх поставщиков и не хочет платить трижды. Продавцам нужно обратное — своя выручка
на свой расчётный счёт и свои закрывающие документы от своего юрлица. Если площадка собирает деньги на
себя, она становится посредником со всеми последствиями: налоги, документы, ответственность за товар,
который никогда не видела.
Инвойсбокс разделяет одно от другого: покупатель платит один раз, а платёж расходится по продавцам,
каждый из которых остаётся продавцом в документах.
## Как выглядит цикл
1. **Поставщики подключаются к площадке.** Площадка отправляет
[приглашение](/docs/partner/integration/invite/) по API — поставщик проходит регистрацию сам, а по
её завершении площадка получает [параметры доступа](/docs/partner/integration/activation/), чтобы
создавать заказы от его имени. Собирать документы поставщиков вручную не нужно.
2. **Корзина превращается в группу заказов.** Один вызов
[создания группы заказов](/docs/merchant/order/create-order-container/) — и внутри столько заказов,
сколько в корзине продавцов. У каждого свой `merchantId`, свой состав и свои ставки НДС; покупатель
видит один номер счёта, который вы передаёте в `merchantOrderIdVisible`.
3. **Покупатель платит один раз** — по счёту, из интернет-банка в один шаг или подтверждением из
гарантийного фонда, [чем инструменты отличаются](/docs/merchant/payment-instruments/).
4. **Каждый заказ живёт своей жизнью.** Уведомления о смене статуса приходят по каждому заказу
отдельно — площадка узнаёт, что оплачено, и запускает сборку и доставку.
5. **Отгрузка и документы — от каждого продавца.** Товар доезжает партиями, отгрузки оформляются
[по каждому заказу](/docs/merchant/order/shipment_create/), а закрывающие документы уходят
покупателю [через ЭДО](/docs/merchant/documentflow/) от лица продавца.
6. **Возврат затрагивает только своего продавца.** Не привезли шкаф — [возврат](/docs/merchant/refund/create/)
идёт по заказу мебельного поставщика, а техника и доставка остаются оплаченными.
## Кто продавец в документах
Ответ определяется схемой работы, и от неё зависит, какие документы формируются.
- **Продавец — поставщик.** Заказ создаётся от его имени, счёт и УПД выставляет он. Площадка получает
вознаграждение за посредничество — так работает
[партнёрская схема](/docs/partner/#вознаграждение-партнёра).
- **Продавец — Инвойсбокс по договору комиссии.** Товар остаётся собственностью поставщика, а продажу
оформляет комиссионер: последовательность документов при полной и частичной отгрузке разобрана в
[комиссионной схеме](/docs/merchant/schema/commission/).
Выбор фиксируется в договоре и настройках магазинов, а не в каждом запросе — тело
[создания заказа](/docs/merchant/order/create/) в обоих случаях одинаковое.
## Франшиза: выплата уходит той точке, которая исполнила заказ
У сетей и франшиз заказ часто приходит на общий сайт, а исполняет его конкретная точка со своим юрлицом.
Заранее это неизвестно: точка определяется по адресу доставки или по наличию товара.
Для такого случая есть [перенос заказа на другой магазин](/docs/merchant/order/merchant-move/):
получателя выплаты можно сменить и до оплаты, и после неё. Условие одно — исходный магазин должен быть
создан с типом, который допускает перенос; это настраивается при подключении.
> [!NOTE]
> Заказы по реквизитам продавца (ИНН и КПП вместо идентификатора магазина) —
> [отдельный режим](/docs/merchant/order/agent-create/) для банков и крупных платёжных агрегаторов.
> Его схема не входит в публикуемый набор, поэтому консоли «Выполнить» на странице нет: контракт
> сверяется с технической поддержкой.
## Витрина: продажа рядом с чужой покупкой
Кроме собственной корзины у площадки есть второй источник продаж — [Витрина Инвойсбокса](/docs/marketplace/).
Точка продаж публикует себя в каталоге, а её [мини-приложение](/docs/marketplace/mini-apps/)
показывается покупателю прямо на [платёжной странице](/docs/merchant/payment-page/), пока он оплачивает
основную покупку: трансфер к авиабилету, страховка к поездке, доставка к заказу.
Точку продаж создаёт и обновляет [API маркетплейса](/docs/marketplace/create/), а скидки и акции
оформляются [спецпредложениями](/docs/marketplace/special-offer/).
## Что это даёт
- Покупатель-организация получает один счёт вместо трёх и один комплект документов на каждую покупку.
- Площадка не становится держателем чужих денег: выручка идёт продавцу, площадке — вознаграждение.
- Подключение поставщиков идёт по API, без обмена сканами документов.
- Возвраты и отгрузки не путаются между продавцами: каждый заказ внутри группы независим.
## Чем подключиться
| Путь | Когда подходит |
|---|---|
| [Партнёрское API](/docs/partner/) | площадка подключает продавцов и создаёт заказы от их имени |
| [Группа заказов](/docs/merchant/order/create-order-container/) | в корзине бывает больше одного продавца |
| [API маркетплейса](/docs/marketplace/) | нужна витрина и продажа на платёжной странице |
| [Мини-приложения](/docs/marketplace/mini-apps/) | покупатель оформляет заказ внутри чужого потока оплаты |
## Смежные кейсы
- [B2B продажи товаров](/docs/scenarios/retail/) — отгрузка партиями и возврат с корректировкой.
- [B2B продажи услуг страхования пассажиров](/docs/scenarios/insurance/) — продажа рядом с основной
покупкой через мини-приложение.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — сверка оплат, когда счетов много.
---
---
# 🧩 Приём платежей без разработчика
# Приём платежей без разработчика: юристы, аудит, агентства, студии
В небольшой профессиональной практике счёт выставляет тот же человек, который оказывает услугу.
Разработчика нет, сайт собран на конструкторе, и любая интеграция звучит как проект на месяц. Поэтому
всё остаётся как есть: счёт в Word, реквизиты в подписи письма, звонок бухгалтеру клиента с вопросом,
дошли ли деньги, и акт, который печатают и подписывают вручную.
Ни один шаг здесь не требует программирования. Оплату от организаций можно принять кодом, который
копируется в страницу, или готовым модулем к вашей платформе — счёт, чек и закрывающие документы
формируются на стороне Инвойсбокса.
## Четыре пути без программирования
| Путь | Что делаете вы | Сколько занимает |
|---|---|---|
| [Счёт из личного кабинета](https://www.invoicebox.ru/ru/free-invoice) | заполняете счёт в кабинете и отправляете покупателю | пара кликов |
| [Платёжный виджет](/widgets/) | собираете кнопку в конструкторе и вставляете код на страницу | минуты |
| [Готовый модуль](/docs/merchant/cms/) | устанавливаете модуль для своей платформы и вводите данные магазина | часы |
| [ИИ-агент](/for-agents/) | даёте агенту в Cursor или Claude Code один промпт — код он пишет сам | часы |
Сайт нужен не всегда. Если счетов немного и каждый обсуждается с клиентом, начните с кабинета: там
счёт выставляется вручную, к нему можно добавить QR-код для оплаты через СБП и оформить отчётные
документы — [бесплатно, без интеграции и без сайта](https://www.invoicebox.ru/ru/free-invoice).
Виджет подходит, когда сумма известна заранее или её называет клиент: консультация по прайсу, оплата
этапа договора, абонентское обслуживание. Модуль — когда заказы уже рождаются на сайте.
## Счёт руками, когда сайт не нужен
Юрист выставляет пять счетов в месяц, аудитор — десять, и каждый обсуждается с клиентом лично. Ставить
для этого кнопку на сайт незачем: [сервис бесплатного выставления счёта](https://www.invoicebox.ru/ru/free-invoice) закрывает задачу из
кабинета.
- Счёт заполняется вручную и уходит покупателю; ему достаточно ссылки.
- К счёту добавляется QR-код — покупатель оплачивает через СБП из приложения своего банка.
- Отчётные документы оформляются там же, руками, когда они понадобятся.
- Регистрация и работа бесплатны — платить за приём оплаты от юрлиц заранее не нужно.
Когда счетов станет много, те же реквизиты работают в виджете и в API — переносить ничего не придётся.
## Как это работает у вас на странице
1. **Соберите кнопку.** В [конструкторе](/widgets/constructor/) выбираются состав заказа или свободная
сумма, дополнительные поля, тип плательщика и адрес страницы завершения. Понадобятся идентификатор
магазина и региональный код — [где их взять](/docs/merchant/integrationdata/); для пробы конструктор
подставит демо-магазин.
2. **Поставьте тип плательщика «организация».** Тогда клиент указывает ИНН, а Инвойсбокс формирует счёт
и закрывающие документы — [схема для юрлиц](/docs/merchant/schema/legal/). Для физлиц тот же виджет
выдаёт [чек по 54-ФЗ](/docs/merchant/fz54/).
3. **Вставьте код на страницу.** Примеры для обычного сайта, Тильды, WordPress и 1С-Битрикс — в
[инструкции по вставке](/widgets/embed/).
4. **Получите оплату и документы.** Клиент платит по счёту или картой, акт и счёт-фактура уходят его
бухгалтерии [через ЭДО](/docs/merchant/documentflow/), деньги приходят на расчётный счёт на
следующий рабочий день — [сроки](/docs/terms/).
## Что важно знать про виджет
Сумма и состав заказа приходят из браузера покупателя и не подписаны — в браузере их можно изменить до
отправки. Это осознанное упрощение ради быстрого старта, и оно накладывает одну обязанность: сверять
сумму оплаты с той, которую вы ожидали. Подробно — [Безопасность виджета](/widgets/security/).
Для практики, где счёт выставляется по договорённости, это почти не риск: оплату вы всё равно
сопоставляете с договором. Если же цену определяет только ваша система, надёжнее создавать заказы
[через API](/docs/merchant/order/create/) — этот шаг можно сделать позже, ничего не переделывая: виджет
и API работают с одним и тем же магазином.
## Когда клиент просит счёт «как обычно»
Корпоративная бухгалтерия часто хочет счёт на бумаге или в почте, а не ссылку на оплату. Здесь ничего
менять не нужно: счёт формируется на стороне Инвойсбокса и доходит до клиента письмом, а оплатить его
он может из своего банка. Тем, кто пользуется банковским приложением, счёт можно доставить прямо туда —
[Запросом о платеже](/docs/scenarios/rtp/).
## Что это даёт
- Оплата от организаций принимается без разработки и без изменения сайта.
- Счёт, акт и счёт-фактура формируются сами — печатать и подписывать вручную не нужно.
- Клиент платит привычным способом, а вы видите оплату, не звоня его бухгалтеру.
- Переход на API не требует переделки: тот же магазин, те же документы.
## Смежные кейсы
- [Подписки для юрлиц](/docs/scenarios/saas/) — если услуга продаётся периодами.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — когда счетов станет много.
- [B2B продажи 24/7](/docs/scenarios/b2b-sales/) — что даёт переход на API.
---
---
# 🎓 Корпоративное обучение и ДПО
# Корпоративное обучение и ДПО: оплата обучения сотрудников организацией
Учебный центр продаёт курс не тому, кто учится. Заявку оставляет специалист по обучению, платит
бухгалтерия, а на занятия приходят двенадцать человек, из которых двое в последний момент меняются, а
один вообще не выходит на связь. Всё это должно сойтись в счёте, в акте и в удостоверениях — и обычно
сходится вручную, письмами и правками в счёте, потому что «список поменялся».
Инвойсбокс закрывает денежную часть: счёт организации, оплата привычным ей способом, акт и
счёт-фактура после курса. Список слушателей живёт в составе заказа, и его можно менять, пока счёт не
оплачен.
## Как выглядит цикл
1. **Заявка превращается в счёт.** [Создание заказа](/docs/merchant/order/create/) с типом плательщика
`legal`: в составе корзины — позиции по программе и слушателям, в `merchantOrderId` — номер заявки
или договора, в `expirationDate` — срок оплаты, обычно до начала потока.
2. **Организация платит.** Переводом, в один шаг из интернет-банка, по
[Запросу о платеже](/docs/scenarios/rtp/) или подтверждением из гарантийного фонда — способ зависит
от [платёжного инструмента](/docs/merchant/payment-instruments/), запрос при этом один и тот же.
3. **Вы узнаёте об оплате сигналом,** а не из выписки:
[уведомление о смене статуса](/docs/merchant/notification/status/) приходит сразу после
подтверждения, и слушателей можно зачислять.
4. **Курс проходит, документы уходят.** Акт и счёт-фактура формируются по факту оказания услуги и
отправляются [через ЭДО](/docs/merchant/documentflow/) или на бумаге.
5. **Кто не учился — тому возврат.** Двое не приступили к обучению: сумма за них возвращается, а
корректировочный документ уходит вслед за возвратом —
[возврат с корректировкой](/docs/merchant/refund/correction/).
## Список слушателей — это состав заказа
Позиции корзины — не только «курс за 145 000 ₽». Слушатель, программа и период обучения, вписанные в
позиции, попадают в счёт и в акт, и бухгалтерия покупателя видит, за кого именно заплатила. Так снимается
вопрос, с которым клиент возвращается чаще прочих: «а кто у вас в этом счёте?».
Из этого следуют два правила работы со списком:
- **До оплаты состав правится в самом заказе.** [Изменение заказа](/docs/merchant/order/update/)
пересчитывает состав и сумму, ссылка на оплату остаётся прежней. Так оформляется замена слушателя,
добавление ещё двоих или переход на другую программу.
- **После оплаты состав не меняют — деньги двигают.** Кто-то не приступил к обучению: это
[возврат с корректировкой](/docs/merchant/refund/correction/), а не правка оплаченного счёта. Прежние
документы остаются в силе, а корректировка объясняет разницу.
Неоплаченный счёт по отменённой заявке [отменяется](/docs/merchant/order/delete/) — у клиента в списке
не останется висеть счёт, который никто не собирается платить.
## Обучение частных слушателей на том же контуре
Учебные центры почти всегда продают и организациям, и людям. Разница только в типе плательщика: для
физлица тот же заказ выдаёт [чек по 54-ФЗ](/docs/merchant/fz54/), для организации —
[счёт и закрывающие документы](/docs/merchant/schema/legal/). Второго подрядчика и второй личный
кабинет для этого не нужно.
Если курс продаётся периодами — доступ к платформе на год с оплатой по месяцам, — работает механика
подписки: [счёт на каждый период](/docs/scenarios/saas/) вместо привязки карты.
## Что это даёт
- Заявка становится счётом за один вызов, а зачисление привязано к подтверждению оплаты.
- Список слушателей виден в счёте и акте — меньше переписки с бухгалтерией клиента.
- Замены и отказы оформляются штатно: изменением заказа до оплаты и возвратом с корректировкой после.
- Акт и счёт-фактура за курс уходят по ЭДО без участия менеджера.
## Чем подключиться
| Путь | Когда подходит |
|---|---|
| [API и PHP SDK](/docs/merchant/) | заявки приходят в вашу систему обучения или CRM |
| [Модуль CRM](/docs/merchant/crm/) | заявками занимаются менеджеры: amoCRM, retailCRM |
| [Готовый модуль CMS](/docs/merchant/cms/) | курсы продаются с сайта |
| [Платёжный виджет](/widgets/) | нужно принять оплату за курс сегодня |
## Смежные кейсы
- [Подписки для юрлиц](/docs/scenarios/saas/) — доступ к платформе периодами.
- [Приём платежей без разработчика](/docs/scenarios/no-code/) — если своего разработчика нет.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — когда счетов становится много.
---
---
# 🎪 Событийная индустрия: конференции и выставки
# Конференции и выставки: участие компании одним счётом
Компания едет на выставку не за билетом. Ей нужен стенд, электричество и мебель на нём, шесть
делегатов, парковка и место в каталоге — и всё это заканчивается одним разговором с бухгалтерией:
«пришлите счёт». Организатор в ответ шлёт три счёта от трёх юрлиц, а через неделю четвёртый, потому
что участник добавил ещё одного делегата. Дальше начинается сверка, которая занимает больше времени,
чем продажа.
Инвойсбокс собирает участие в один платёж: покупатель платит один раз, документы приходят одним
комплектом, а изменения в составе делегатов проходят штатно — до оплаты правкой заказа, после —
возвратом с корректировкой.
## Один счёт вместо стопки
Если участие продаёт одно юрлицо, всё умещается в один
[заказ](/docs/merchant/order/create/): стенд, делегаты, доп-услуги — позиции корзины со своими
ставками НДС и единицами измерения. В `expirationDate` ставится срок оплаты — обычно за несколько дней
до мероприятия, чтобы место не висело за неплательщиком.
Когда услуги оказывают разные юрлица — площадка сдаёт метры, подрядчик строит стенд, кейтеринг кормит
гостей, — работает [группа заказов](/docs/merchant/order/create-order-container/): внутри столько
заказов, сколько продавцов, а покупатель платит одной суммой и видит один номер счёта. Выручка и
документы при этом расходятся по продавцам — подробно это разобрано в кейсе
[маркетплейса и сплит-корзины](/docs/scenarios/marketplace-split/).
## Состав участия меняется до последнего дня
Это отраслевая норма, а не исключение: за неделю до выставки меняются фамилии делегатов, добавляется
второй стол на стенде, отваливается один из приехавших. Правило то же, что и в обучении, и оно
определяется одним признаком — оплачен ли счёт.
- **До оплаты** — [изменение заказа](/docs/merchant/order/update/): состав и сумма пересчитываются,
ссылка на оплату остаётся прежней. Замена делегата, лишний квадратный метр, отказ от парковки.
- **После оплаты** — деньги, а не состав. Делегат не приехал: сумма за него возвращается, а
корректировочный документ уходит вслед за возвратом —
[возврат с корректировкой](/docs/merchant/refund/correction/).
Заявка отменилась до оплаты — счёт [отменяется](/docs/merchant/order/delete/), место освобождается под
следующего участника.
## Срок оплаты и место, которое нельзя держать вечно
У мероприятия есть дата, и это меняет отношение к неоплаченным счетам. Стенд, забронированный и не
оплаченный, — это не дебиторка, а потерянное место в зале. Поэтому:
- `expirationDate` ставится по вашему регламенту бронирования, а не «на всякий случай» на месяц;
- список неоплаченных счетов с истекающим сроком собирается [фильтрами](/docs/api/filters/) по
`status=created` и дате — [как это устроено](/docs/scenarios/receivables/);
- если участник платит по счёту и тянет с оплатой, счёт можно доставить прямо в его банковское
приложение — [Запросом о платеже](/docs/scenarios/rtp/).
Тем, кому нужно место здесь и сейчас — регистрация в день мероприятия, доплата за апгрейд на стойке, —
подойдёт [обещанный платёж](/docs/merchant/payment-instruments/): участник подтверждает картой за
минуту, а его организация оплачивает счёт в течение пяти суток.
## Что это даёт
- Участие продаётся одним счётом, даже если услуги оказывают несколько юрлиц.
- Изменения в составе делегатов не превращаются в переписку: до оплаты — правка заказа, после — возврат
с корректировкой.
- Закрывающие документы уходят [по ЭДО](/docs/merchant/documentflow/) одним комплектом после
мероприятия.
- Частные участники платят там же и получают [чек по 54-ФЗ](/docs/merchant/fz54/).
## Смежные кейсы
- [Корпоративное обучение и ДПО](/docs/scenarios/education/) — та же механика списка участников.
- [Маркетплейс и сплит-корзина](/docs/scenarios/marketplace-split/) — когда продавцов несколько.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — сверка оплат перед мероприятием.
---
---
# 🏷️ Маркированные товары (Честный знак)
# Маркированные товары: продажа организациям с передачей кодов
Продавец маркированного товара платит за интеграцию дважды. Первый раз — чтобы принять оплату от
организации и выдать закрывающие документы. Второй — чтобы сведения о маркировке дошли до покупателя
и до Честного знака в нужный момент и в нужном документе. Обычно это два разных подрядчика, два
договора и два места, где что-то может разъехаться: товар отгружен, а коды ушли не с тем УПД.
Инвойсбокс закрывает оба контура. Заказ несёт товарную группу в составе корзины, а сведения о
маркировке уходят покупателю и в систему маркировки вместе с документами по отгрузке.
## Как выглядит цикл
1. **Заказ с товарной группой.** При [создании заказа](/docs/merchant/order/create/) в позиции корзины
передаётся `categoryType: honestSign` и код группы в `category` — `shoes`, `milk`, `water`, `beer` и
так далее; [полный справочник групп](/docs/merchant/honest-sign/). Если у вас свой справочник
категорий, в `categoryType` идёт `merchantHonestSignMap`. Без этих полей заказ создастся, но
сведения о маркировке в чек не попадут.
2. **Оплата по счёту или с отсрочкой.** Покупатель-организация платит переводом, в один шаг из своего
банка или подтверждением из гарантийного фонда —
[чем инструменты отличаются](/docs/merchant/payment-instruments/).
3. **Отгрузка партиями.** Оптовый заказ редко уезжает целиком: каждая партия оформляется
[отгрузкой](/docs/merchant/order/shipment_create/), и сведения о маркировке относятся к тому, что
действительно отгружено, а не к заказу в целом.
4. **Документы через ЭДО.** УПД уходит покупателю [по электронному документообороту](/docs/merchant/documentflow/),
события обмена — [в перечне событий ЭДО](/docs/merchant/documentflow/edo_events/).
5. **Недовоз — возврат с корректировкой.** Привезли меньше, чем в счёте: разница возвращается
покупателю, а корректировочный документ уходит вслед за возвратом —
[возврат с корректировкой](/docs/merchant/refund/correction/).
## Почему маркировка привязана к отгрузке, а не к заказу
Заказ — это договорённость: столько-то пар обуви такой-то модели. Коды маркировки относятся к
конкретным экземплярам, а какие именно уедут покупателю, известно только в момент сборки партии.
Поэтому сведения о маркировке идут с отгрузкой: сколько отгрузили — столько и сведений.
Отсюда два следствия для интеграции:
- **Отгрузку нельзя откладывать «на потом».** Пока её нет, у покупателя нет и УПД, а значит, товар
формально не принят. Отгрузка вызывается по факту передачи товара —
[как её оформить](/docs/merchant/order/shipment_create/), как [поправить](/docs/merchant/order/shipment_update/)
и как [посмотреть](/docs/merchant/order/shipment_get/).
- **Если отгрузить нечего** — товара не оказалось на складе, покупатель отказался — об этом сообщают
[уведомлением о невозможности отгрузки](/docs/merchant/notification/shipping-unavailable/), и заказ
не остаётся оплаченным без движения.
## Что смотреть в справочниках
| Что нужно | Где взять |
|---|---|
| Код товарной группы для `category` | [Честный знак](/docs/merchant/honest-sign/) — 20 групп с описаниями |
| Ставка НДС для позиции | [Справочник ставок](/docs/dictionary/tag1199/) |
| Единица измерения количества | [Признак предмета расчёта](/docs/dictionary/tag1212/) и [ОКЕИ](/docs/dictionary/okei/) |
| Что уходит в чек физлицу | [Фискализация по 54-ФЗ](/docs/merchant/fz54/) |
## Что это даёт
- Один вендор закрывает и приём оплаты от организаций, и передачу сведений о маркировке.
- Коды привязаны к отгруженным партиям, поэтому документы совпадают с фактом.
- Недовоз и отказ оформляются штатно: возврат с корректировкой или уведомление о невозможности
отгрузки, а не ручная переписка с бухгалтерией покупателя.
- Физлицам по тому же заказу выдаётся чек с реквизитами маркировки.
## Смежные кейсы
- [B2B продажи товаров](/docs/scenarios/retail/) — отгрузка партиями и возвраты в оптовой торговле.
- [Маркетплейс и сплит-корзина](/docs/scenarios/marketplace-split/) — если товар продают несколько
поставщиков.
- [Автоматизация дебиторки](/docs/scenarios/receivables/) — сверка оплат по большому числу счетов.
---
---
# 🚛 Логистика и грузоперевозки
# Логистика и грузоперевозки: расчёт по факту, а не по заявке
В перевозке цена заявки редко совпадает с ценой рейса. Вес уточняется на погрузке, объём — при
загрузке в машину, к тарифу добавляются простой, доупаковка, второй адрес выгрузки. Предоплата по
заявке означает возврат почти в каждом втором рейсе; постоплата — работу в долг и разговоры с
бухгалтерией клиента о том, почему сумма в счёте не та, о которой договаривались.
Инвойсбокс закрывает разрыв между заявкой и фактом двумя механиками: сумму по заявке можно
зарезервировать и списать по факту, а можно выставить счёт организации и подтвердить возможность
перевозки до того, как деньги ушли.
## Резерв по заявке, списание по факту
[Холдирование](/docs/merchant/order/hold/) подходит, когда заявку оплачивают картой — личной,
корпоративной или картой водителя.
1. Заказ создаётся с подтипом `subtype: hold`; все позиции корзины идут с типом оплаты
`full_prepayment`.
2. После подтверждения оплаты сумма блокируется на карте до даты из `holdTill` в
[ответе на создание заказа](/docs/merchant/order/create/#orderresponse).
3. Груз доехал — [создаётся отгрузка](/docs/merchant/order/shipment_create/) по позициям заказа.
Отгрузок может быть несколько: сборный груз доезжает частями, и на каждую оформляются документы.
4. Когда все позиции отгружены, заблокированные деньги списываются. Если рейс вышел дешевле —
отгрузка с флагом `final: true` списывает только фактическое, а остаток разблокируется.
Так закрывается частый случай: заявка на 60 000 ₽, по факту 54 000 ₽ — клиент платит за то, что
действительно перевезли, и никто не оформляет возврат.
> [!NOTE]
> Резерв работает на карте. Если перевозку оплачивает организация по счёту, до оплаты состав и сумму
> правит [изменение заказа](/docs/merchant/order/update/), а после — недоплату закрывает отдельный
> счёт, переплату [возврат с корректировкой](/docs/merchant/refund/correction/).
## Подтверждение рейса до того, как деньги ушли
У экспедитора машина находится не всегда: заявка принята, оплата подтверждена, а свободного борта на
дату нет. Для этого случая есть [контроль отгрузки на платёжной странице](/docs/merchant/notification/shipping-unavailable/):
Инвойсбокс дожидается ответа вашей системы, пока покупатель ещё стоит на платёжной странице.
- Машина нашлась, рейс поставлен в план — вы отвечаете `success`, покупатель видит подтверждение
оплаты и едет дальше по своему сценарию.
- Борта нет — вы сообщаете об этом, и покупатель узнаёт о невозможности перевозки сразу, а не через
день от диспетчера.
Настройка включается на стороне вашей платёжной страницы — попросите её у
[поддержки](https://www.invoicebox.ru/ru/contacts) до запуска.
## Рейсы за месяц одним счётом
Постоянный клиент делает по десять отправлений в неделю, и десять счетов в неделю его бухгалтерии не
нужны. [Группа заказов](/docs/merchant/order/create-order-container/) собирает несколько заказов под
одну оплату: каждый рейс остаётся отдельным заказом со своими документами, а покупатель платит один
раз. Так же удобно, когда в перевозке участвуют несколько исполнителей: у каждого свой заказ и своя
выручка.
## Что это даёт
- Клиент платит за фактически выполненный рейс, а не за заявку — меньше возвратов и меньше споров.
- Невозможность перевозки видна покупателю сразу на платёжной странице, а не после списания денег.
- Документы за рейс уходят [через ЭДО](/docs/merchant/documentflow/) по каждой отгрузке.
- Деньги приходят на расчётный счёт на следующий рабочий день после подтверждения оплаты —
[сроки](/docs/terms/).
## Смежные кейсы
- [B2B продажи такси и трансфера](/docs/scenarios/taxi/) — та же механика резерва в пассажирских
перевозках.
- [B2B продажи товаров](/docs/scenarios/retail/) — отгрузка партиями и корректировки.
- [Маркированные товары](/docs/scenarios/marked-goods/) — если возите маркировку.
---
---
# ⚡ Запрос о платеже (RtP)
# Запрос о платеже (RtP)
**Запрос о платеже (RtP или Request to Pay)** — это [удобный сервис от НСПК](https://www.invoicebox.ru/ru/products/rtp)
по передаче электронных платёжных счетов, способный доставить информацию о необходимости оплаты
товаров, работ и услуг от поставщика до плательщика.
Счёт не нужно везти на бумаге, пересылать письмом или в мессенджере: он доставляется прямо в личный
кабинет плательщика, а оплатить его можно в банковском или финансовом приложении.
Счёт через сервис RtP может быть направлен как плательщиками - физическими лицами (B2C), так и
организациям (B2B). Оплата может быть совершена с использованием QR-кода СБП или
[СБП B2B](https://www.invoicebox.ru/ru/products/sbp-b2b), а также множество альтернативных способов
оплаты на [платёжной странице](/docs/merchant/payment-page/) Инвойсбокс.
### Основные преимущества Запроса о платеже:
- Поставщик может полностью автоматизировать формирование и доставку счетов своим клиентам.
- Плательщик может контролировать процесс оплаты счёта, выбирая, когда и каким образом произвести платёж.
- Используются современные технологии для защиты данных и предотвращения мошенничества.
- Счета, а также информация об их оплате могут быть отправлены и получены в реальном времени, что упрощает
взаимодействие между сторонами, а также позволяет сократить дебиторскую задолженность.
> ❗ Почти 40% участников опроса [РСПП](https://rspp.ru/) назвали неплатежи со стороны контрагентов главным
препятствием для бизнеса, потеснив на второе место проблему снижения спроса. По данным мониторинга за второй квартал
2026 года доля таких ответов выросла на 5,6 процентного пункта. Запрос о платеже с моментальным подтверждением оплаты
снимает эту проблему: поставщик видит оплату сразу.
### Как это работает?
Поставщик товаров или услуг отправляет счёт (запрос на оплату) плательщику через свою учётную систему,
личный кабинет Инвойсбокс, [CRM](/docs/merchant/crm), [CMS](/docs/merchant/cms), [ERP](/docs/merchant/erp)
или мобильное приложение.
Плательщик получает уведомление с подробной информацией о счёте, включая сумму, описание и сроки оплаты. Плательщик
может получать такие уведомления на электронную почту, в мессенджерах или иных сервисах. Плательщик может
выбрать один из нескольких вариантов: оплатить счёт немедленно, назначить дату платежа или отклонить запрос.
Платёж может быть осуществлён мгновенно с использованием удобного способа оплаты, например, банковского перевода или СБП.
См. также [использование API для выставления счёта](/docs/merchant/schema/rtp) через Запрос о платеже.
### Применение Запрос о платеже
Набор сценариев использования RtP обширен и не ограничен приведёнными примерами:
- B2B и B2C расчёты: Компании могут оптимизировать свои финансовые потоки, используя этот метод для выставления счетов и мгновенного получения информации об оплате.
- Коммунальные платежи: Поставщики услуг могут отправлять запросы на оплату, которые клиенты могут оплачивать удобным способом.
- Онлайн-покупки и подписки: Магазины могут использовать RtP для упрощения процесса оплаты заказов, а также для автоматизации подписок.
- Школы, учебные заведения и курсы: Учреждения могут использовать Запрос о платеже для упрощения процесса оплаты курсов, а также для автоматизации приёма оплаты.
### Как подключить: последовательность вызовов
1. [Создайте заказ](/docs/merchant/order/create/) с составом и суммой — как для обычной оплаты по счёту.
Идентификатор заказа в вашей системе передайте в `merchantOrderId`, а внутренние поля —
в [метаданные](/docs/merchant/order/metadata/): они вернутся в уведомлениях.
2. Отправьте плательщику ссылку или QR-код на оплату. Запрос уходит в приложение его банка —
отдельная платёжная страница не нужна.
3. Дождитесь [уведомления о смене статуса](/docs/merchant/notification/status/): по нему запускайте
отгрузку или оказание услуги. Опрашивать [состояние заказа](/docs/merchant/order/get/) вручную
не требуется — но метод пригодится для сверки.
4. Если платить передумали или счёт устарел, [отмените заказ](/docs/merchant/order/delete/) —
запрос у плательщика погаснет.
5. Возврат оформляется обычным [методом возврата](/docs/merchant/refund/create/).
### Что это даёт бизнесу
- Снижение административных затрат, связанных с обработкой, отслеживанием платежей и ведением документооборота.
- Снижение дебиторской задолженности.
- Сокращение времени обработки транзакций, быстрое получение оплаты покупателя.
- Запрос о платеже активно развивается в финансовой отрасли и поддерживается банками и финансовыми институтами России.
### Универсальный QR
Универсальный QR-код Национальной системы платёжных карт (НСПК) — единый инструмент
для приёма различных видов платежей. Он позволяет торговым точкам использовать один QR-код для обработки платежей
через Систему быстрых платежей (СБП), банковские pay-сервисы, сервисы рассрочки, а в перспективе — и с использованием
цифрового рубля.
Решения Инвойсбокс API позволяют интегрировать [сервис RtP](https://www.invoicebox.ru/ru/products/rtp) и Универсальный
QR (включая оплату с использованием [СБП B2B](https://www.invoicebox.ru/ru/products/sbp-b2b)) в достаточно короткие
сроки и сопроводить оплату счёта необходимым документооборотом.
> Если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы будем рады вам помочь!
---
# 💳 Холдирование средств
# Холдирование средств: платите за факт, а не за план
Холдирование — это резерв суммы на карте покупателя до того, как известна окончательная цена.
Деньги остаются у клиента, но потратить их он не может; продавец списывает ровно столько,
сколько стоил фактический заказ, а остаток возвращается автоматически.
Сценарий закрывает боль отраслей с плавающей суммой. Заказ подтверждён, а окончательная сумма
станет известна через час, день или после отгрузки.
> Не путайте с [подтверждением оплаты заказа](/docs/merchant/guarantee/) — там речь о другом
> механизме: покупатель подтверждает уже сформированный платёж кодом.
## Как это работает
1. **Резерв.** Магазин [создаёт заказ с холдированием](/docs/merchant/order/hold/) на максимально
возможную сумму — например, максимальный чек поездки или полную стоимость брони.
Клиент подтверждает резерв, деньги блокируются на его карте.
2. **Отгрузка.** По факту продавец [создаёт отгрузку](/docs/merchant/order/shipment_create/) с тем,
что действительно отгружено или оказано. Отгрузок может быть сколько угодно, на каждую
оформляется фискальный чек. Когда в отгрузках закрыты все позиции заказа, заблокированные
средства списываются.
3. **Частичное списание.** Если часть заказа не состоялась, отгрузка оформляется с флагом
`final` = `true`: заказ считается выполненным, а остаток резерва разблокируется — без
отдельного возврата. До какой даты держится резерв, видно в поле `holdTill`
[ответа на создание заказа](/docs/merchant/order/create/#orderresponse).
4. **Уведомление.** Вашу систему о каждом шаге извещает
[уведомление о смене статуса](/docs/merchant/notification/status/) — по нему запускается
отгрузка, оформление документов или закрытие смены.
Если заказ не состоялся, резерв снимается [отменой заказа](/docs/merchant/order/delete/):
деньги освобождаются на карте клиента, списания не происходит.
Как это выглядит в числах: резерв берётся с запасом, списывается факт, разница освобождается сама.
```mermaid
sequenceDiagram
participant K as Покупатель
participant M as Магазин
participant I as Инвойсбокс
M->>I: заказ с холдированием на 3 000 ₽
I-->>M: paymentUrl, holdTill — 5 суток
K->>I: подтверждение, 3 000 ₽ заблокированы на карте
M->>I: отгрузка по факту на 2 400 ₽, final = true
I-->>K: списано 2 400 ₽, 600 ₽ разблокированы
I->>M: уведомление о смене статуса
```
## Где это нужно
| Отрасль | Что резервируем | Что списываем |
|---|---|---|
| [Такси и трансфер](/docs/scenarios/taxi) | максимальную стоимость маршрута | фактическую поездку по счётчику |
| [Рестораны](/docs/scenarios/ras) | сумму заказа при подтверждении | фактически поданные блюда |
| [Гостиницы](/docs/scenarios/pms) | стоимость проживания | проживание плюс допуслуги при выезде |
| Прокат и аренда оборудования | залог и максимальный срок | фактическое время использования |
| Розница с частичной отгрузкой | полную корзину | каждую отгруженную партию |
| Предзаказы с плавающей ценой | верхнюю границу цены | цену на момент отгрузки |
## Что учесть до внедрения
- **Срок жизни резерва** ограничен правилами платёжной системы. Если заказ выполняется дольше,
резерв нужно обновлять — уточните допустимый срок у вашего менеджера.
- **Списать больше зарезервированного нельзя.** Резервируйте с запасом: увеличить сумму
постфактум не выйдет, придётся выставлять отдельный счёт.
- **Клиент видит блокировку** как уменьшение доступного остатка. В интерфейсе честно называйте
это резервом, а не оплатой, — иначе неизбежны обращения в поддержку.
> В случае, если у вас возникли вопросы, пожалуйста, [обратитесь к специалистам](https://www.invoicebox.ru/ru/contacts)
> системы Инвойсбокс. Мы ответим на любые ваши вопросы!
## Читайте также
- [Демо «Касса АЗС](/demo/fuel/)
---
# 📱 Оплата внутри приложения без платёжной страницы
# Оплата внутри приложения: подтверждение кодом вместо перехода на платёжную страницу
В мобильном приложении переход на внешнюю страницу оплаты стоит дорого. Открывается браузер, теряется
контекст экрана, покупатель возвращается не туда, откуда ушёл, — и часть заказов остаётся
неоплаченной просто потому, что дорога назад оказалась длиннее, чем сам заказ. Для повторяющихся
покупок — обед на офис, расходники, поездка — это особенно заметно: сам заказ занимает пятнадцать
секунд, а оплата уводит на минуту в чужой интерфейс.
Постоянный покупатель с гарантийным фондом может подтвердить оплату прямо в вашем приложении: код
приходит ему от Инвойсбокса, вводится на вашем экране, заказ становится оплаченным.
## Три вызова вместо перехода
1. **Заказ.** [Создание заказа](/docs/merchant/order/create/) с типом плательщика `legal` — как обычно.
2. **Проверка возможности оплаты.** [Метод проверки](/docs/merchant/guarantee/validate/) отвечает,
хватает ли средств фонда. Спрашивать стоит до того, как покажете покупателю кнопку: так он не
упрётся в отказ на последнем шаге.
3. **Код подтверждения.** [Запрос кода](/docs/merchant/guarantee/code/) — Инвойсбокс отправляет код
покупателю.
4. **Подтверждение оплаты.** Покупатель вводит код на вашем экране, вы передаёте его
[методом подтверждения](/docs/merchant/guarantee/pay/), и заказ переходит в оплаченный.
Полная последовательность с участниками — в [схеме взаимодействия](/docs/merchant/guarantee/schema/),
а весь набор методов — в разделе [Гарантийный фонд](/docs/merchant/guarantee/).
> [!IMPORTANT]
> Раз оплата подтверждается в вашем интерфейсе, защита от перебора кода — тоже ваша.
> В вашем сервисе должна стоять капча: Google reCAPTCHA, Yandex SmartCaptcha, Huawei Safety Detect
> или аналог. Об этом прямо сказано в [описании методов](/docs/merchant/guarantee/).
## Кому это доступно и что делать с остальными
Подтверждение кодом работает для покупателей, у которых есть договор и гарантийный фонд —
[что это за инструмент](/docs/merchant/payment-instruments/). Остальным нужен обычный путь, и приложение
не обязано ради этого выбрасывать человека в браузер:
- **Мини-приложение в потоке Инвойсбокса.** Метод
[onCheckout](/docs/marketplace/mini-apps/miniapp-sdk/#метод-oncheckout) открывает платёжную страницу
поверх мини-приложения, а после оплаты вызывается
[обработчик onPaymentResult](/docs/marketplace/mini-apps/miniapp-sdk/#обработчик-onpaymentresult) со
статусом — покупатель возвращается ровно туда, откуда ушёл.
- **Ссылка на оплату внутри приложения.** `paymentUrl` из ответа на создание заказа открывается во
встроенном браузере; на устройстве с приложением Инвойсбокса откроется оно.
- **Оплата физлицом.** Тот же заказ выдаёт [чек по 54-ФЗ](/docs/merchant/fz54/), последовательность —
в [схеме для физических лиц](/docs/merchant/schema/private/).
## Не путайте с холдированием
Здесь деньги списываются с фонда организации, и происходит это в момент подтверждения кода.
[Холдирование](/docs/scenarios/guarantee/) — другое: сумма блокируется на банковской карте и
списывается по факту отгрузки. Механизмы решают разные задачи и настраиваются по-разному.
## Что это даёт
- Покупатель не выходит из приложения: оплата занимает столько же экранов, сколько сам заказ.
- Отказ по нехватке средств виден до кнопки оплаты, а не после неё.
- Закрывающие документы формируются как при любой другой оплате —
[документооборот](/docs/merchant/documentflow/).
- Для покупателей без фонда сценарий не ломается: платёжная страница открывается поверх и возвращает
человека обратно.
## Смежные кейсы
- [Холдирование средств](/docs/scenarios/guarantee/) — резерв суммы на карте и списание по факту.
- [B2B продажи такси и трансфера](/docs/scenarios/taxi/) — оплата в приложении с расчётом по факту.
- [Системы автоматизации ресторанов](/docs/scenarios/ras/) — оплата по QR-коду со стола.
---
---
# Коды ОКЕИ
# Коды ОКЕИ
Код единицы измерения передаётся в поле `measureCode` позиции корзины при
[создании заказа](/docs/merchant/order/create/#basketitem), а рядом в `measure` — обозначение для
человека: «шт.», «кг». Не путайте этот справочник с
[мерой количества в чеке](/docs/dictionary/tag2108/): там перечень ФНС и другие значения.
Ниже представлены наиболее популярные коды общероссийского классификатора единиц измерения (ОКЕИ).
Полный справочник кодов доступен на сайте [Федеральной службы государственной статистики](https://rosstat.gov.ru/opendata/7708234640-okei).
## Экономические единицы
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 796 | Штука | шт | pc
## Единицы длины
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 003 | Миллиметр | мм | mm
| 004 | Сантиметр | см | cm
| 005 | Дециметр | дм | dm
| 006 | Метр | м | m
| 008 | Километр | км | km
| 009 | Мегаметр | Мм | Mm
| 018 | Погонный метр | пог. м |
| 020 | Условный метр | усл. м |
| 039 | Дюйм | дюйм | in
| 041 | Фут | фут | ft
| 043 | Ярд | ярд | yd
| 047 | Морская миля | миля | mile
## Единицы площади
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 050 | Квадратный миллиметр | мм2 | mm2
| 051 | Квадратный сантиметр | см2 | cm2
| 053 | Квадратный дециметр | дм2 | dm2
| 055 | Квадратный метр | м2 | m2
| 059 | Гектар | га | ha
| 061 | Квадратный километр | км2 | km2
| 071 | Квадратный дюйм | дюйм2 | in2
| 073 | Квадратный фут | фут2 | ft2
| 075 | Квадратный ярд | ярд2 | yd2
| 109 | Ар | а | a
## Единицы объёма
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 110 | Кубический миллиметр | мм3 | mm3
| 111 | Кубический сантиметр | см3 | cm3
| 112 | Литр | л | L
| 113 | Кубический метр | м3 | m3
| 118 | Децилитр | дл | dl
| 122 | Гектолитр | гл | hl
| 126 | Мегалитр | Мл | Ml
| 131 | Кубический дюйм | дюйм3 | in3
| 132 | Кубический фут | фут3 | ft3
| 133 | Кубический ярд | ярд3 | yd3
| 159 | Миллион кубических метров | м3 | m3
## Единицы массы
| Код | Наименование | Обозначение | Международное |
| --- | --- | --- | --- |
| 160 | Гектограмм | гг | hg
| 161 | Миллиграмм | мг | mg
| 162 | Метрический карат | кар | МС
| 163 | Грамм | г | g
| 166 | Килограмм | кг | kg
| 168 | Тонна | т | t
| 170 | Килотонна | кт | kt
| 173 | Сантиграмм | сг | cg
| 181 | Брутто-регистровая тонна | БРТ |
| 185 | Грузоподъемность в метрических тоннах | т |
| 206 | Центнер (метрический) | ц |q
---
---
# Поиск по ИНН
# Поиск и получение данных об организации по ИНН
Реквизиты организации возвращает запрос по ИНН:
- метод: `GET`
- ресурс: `/v3/filter/api/counterparty-detail`
- тело ответа — коллекция объектов [Counterparty](#counterparty) в свойстве `data`
В запросе есть обязательный параметр `vatNumber` — ИНН.
Метод нужен, чтобы подставить реквизиты плательщика в заказ, не заставляя покупателя вводить их
руками: по ИНН возвращаются наименование, КПП и адреса, которые затем уходят в
[создание заказа](/docs/merchant/order/create/#customer).
> [!IMPORTANT]
> Если организация не найдена или справочный сервис недоступен, метод отвечает `200` с пустым `data`.
> Обрабатывайте это как «данных нет», а не как ошибку: пустой ответ не означает, что запрос не удался.
Пример запроса:
#### 🌐 HTTP
```http
GET /v3/filter/api/counterparty-detail?vatNumber=2323232323
Accept: application/json
User-Agent: MyApp 1.0
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
```
#### 🧊 CURL
```bash
curl -L -X GET '{baseUrl}/v3/filter/api/counterparty-detail?vatNumber=2323232323' \
-H 'Accept: application/json' \
-H 'User-Agent: MyApp 1.0' \
-H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e'
```
#### Пример запроса и ответа
``` json
GET /v3/filter/api/counterparty-detail
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
```
Ответ:
``` json
{
"data": [
{
"id": "01771534-196a-1105-839a-82422289d6d9",
"vatNumber": "7736207543",
"taxRegistrationReasonCode": "773601001",
"name": "ООО «Ромашка»",
"nameFull": "Общество с ограниченной ответственностью «Ромашка»",
"registrationNumber": "1027700123456",
"registrationDate": "2015-04-12T00:00:00+03:00",
"registrationAddress": "119021, г. Москва, ул. Тимура Фрунзе, д. 11",
"postAddress": "119021, г. Москва, ул. Тимура Фрунзе, д. 11",
"postAddressZip": "119021"
}
],
"metaData": {
"totalCount": 1,
"pageSize": 20,
"page": 1
}
}
```
## Counterparty
| Свойство | Обязательное | Тип | Описание |
|---------------------------|--------------|-----------------|--------------------------------------------------|
| id | да | string(36) | Идентификатор оригнизации в системе Инвойсбокс |
| vatNumber | да | string(20) | ИНН |
| taxRegistrationReasonCode | нет | string(9) | КПП |
| name | нет | string(100) | Наименование организации |
| nameFull | нет | string(300) | Полное наименование организации |
| nameI18n | нет | string(300) | Полное наименование организации на языке региона |
| registrationNumber | нет | string(20) | Регистрационный код организации |
| registrationDate | нет | datetime | Дата регистрации организации |
| registrationAddress | нет | string(200) | Адрес регистрации организации |
| postAddress | нет | string(200) | Почтовый адрес организации |
| postAddressZip | нет | string(6) | Почтовый индекс организации |
---
---
# Коды валют
# Коды валют (ISO 4217)
Ниже представлены коды валют, используемые в системе.
Полный классификатор валют доступен на сайте [Центрального банка России](https://www.cbr.ru/development/mcirabis/kv/).
## Экономические единицы
| Код | Наименование | Знак |
|------|------------------|------|
| RUB | Российский рубль | ₽ |
| CNY | Юань | ¥ |
| UZS | Узбекский сум | сум |
| EUR | Евро | € |
| GBP | Фунт стерлингов | £ |
| USD | Доллар США | $ |
---
---
# Признак предмета расчёта (тег 1212)
# Признак предмета расчёта (тег 1212)
Тег 1212 говорит, что именно продаётся: товар, работа, услуга, аванс. Значение передаётся
идентификатором в поле `type` позиции корзины при [создании заказа](/docs/merchant/order/create/#basketitem)
и попадает в фискальный чек.
## Что передавать в API
| Идентификатор | Что означает |
|---|---|
| `commodity` | товар, кроме подакцизного |
| `excise` | подакцизный товар |
| `job` | работа |
| `service` | услуга |
| `payment` | аванс, задаток, предоплата, кредит |
| `property_right` | передача имущественных прав |
| `another` | иной предмет расчёта |
У остальных признаков таблицы ФНС идентификатора нет: они относятся к деятельности, которую
Инвойсбокс не обслуживает (ставки, лотереи, вознаграждение платёжного агента), и в поле `type` не
передаются.
## Таблица ФНС
Таблица 101. Значения реквизита «признак предмета расчёта» (тег 1212), содержащихся в реквизите
«наименование предмета расчёта» (тег 1030) реквизита ФД в печатной форме.
| Код | Идентификатор | Реквизит «наименование предмета расчёта» (тег 1030) содержит сведения | Формат ПФ
| --- | --- | --- | --- |
| 1 | commodity | О реализуемом товаре, за исключением подакцизного товара и товара, подлежащего маркировке средствами идентификации (наименование и иные сведения, описывающие товар) | «ТОВАР» или «Т» или может не печататься
| 2 | excise | О реализуемом подакцизном товаре, за исключением товара, подлежащего маркировке средствами идентификации (наименование и иные сведения, описывающие товар) | «ПОДАКЦИЗНЫЙ ТОВАР» или «АТ» или может не печататься
| 3 | job | О выполняемой работе (наименование и иные сведения, описывающие работу) | «РАБОТА» или «Р» или может не печататься
| 4 | service | Об оказываемой услуге (наименование и иные сведения, описывающие услугу) | «УСЛУГА» или «У» или может не печататься
| 5 | --- | О приёме ставок при осуществлении деятельности по проведению азартных игр | «СТАВКА АЗАРТНОЙ ИГРЫ» или «СТАВКА ИГРЫ» или «СА» или может не печататься
| 6 | --- | О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр | «ВЫИГРЫШ АЗАРТНОЙ ИГРЫ» или «ВЫИГРЫШ АИ» или «ВА» или может не печататься
| 7 | --- | О приёме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приеме лотерейных ставок при осуществлении деятельности по проведению лотерей | «ЛОТЕРЕЙНЫЙ БИЛЕТ» или «СТАВКА ЛОТЕРЕИ» или «СЛ» или может не печататься
| 8 | --- | О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей | «ВЫИГРЫШ ЛОТЕРЕИ» или «ВЛ» или может не печататься
| 9 | --- | О предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации | «ПРЕДОСТАВЛЕНИЕ РИД» или «РИД» или может не печататься
| 10 | payment | Об авансе, задатке, предоплате, кредите | «ПЛАТЁЖ» или «П»или может не печататься
| 11 | --- | О вознаграждении пользователя, являющегося платёжным агентом (субагентом), банковским платёжным агентом (субагентом), комиссионером, поверенным или иным агентом | «АГЕНТСКОЕ ВОЗНАГРАЖДЕНИЕ» или «АВ»
| 12 | --- | О взносе в счёт оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчёта | «ВЫПЛАТА» или «В» или может не печататься
| 13 | another | О предмете расчёта, не относящемуся к предметам расчёта, которым может быть присвоено значение от «1» до «11» и от «14» до «26» | «ИНОЙ ПРЕДМЕТ РАСЧЁТА» или «ИПР» или может не печататься
| 14 | property_right | О передаче имущественных прав | «ИМУЩЕСТВЕННОЕ ПРАВО» или может не печататься
| 15 | --- | О внереализационном доходе | «ВНЕРЕАЛИЗАЦИОННЫЙ ДОХОД» или может не печататься
| 16 | --- | О суммах расходов, платежей и взносов, указанных в подпунктах 2 и 3 пункта Налогового кодекса Российской Федерации, уменьшающих сумму налога | «ИНЫЕ ПЛАТЕЖИ И ВЗНОСЫ» или может не печататься
| 17 | --- | О суммах уплаченного торгового сбора | «ТОРГОВЫЙ СБОР» или может не печататься
| 18 | --- | О курортном сборе | «КУРОРТНЫЙ СБОР» или может не печататься
| 19 | --- | О залоге | «ЗАЛОГ» или может не печататься
| 20 | --- | О суммах произведенных расходов в соответствии со статьей 346.16 Налогового кодекса Российской Федерации, уменьшающих доход | «РАСХОД» или может не печататься
| 21 | --- | О страховых взносах на обязательное пенсионное страхование, уплачиваемых ИП, не производящими выплаты и иные вознаграждения физическим лицам | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ ПЕНСИОННОЕ СТРАХОВАНИЕ ИП» или «ВЗНОСЫ НА ОПС ИП» или может не печататься
| 22 | --- | О страховых взносах на обязательное пенсионное страхование, уплачиваемых организациями и ИП, производящими выплаты и иные вознаграждения физическим лицам | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ ПЕНСИОННОЕ СТРАХОВАНИЕ» или «ВЗНОСЫ НА ОПС» или может не печататься
| 23 | --- | О страховых взносах на обязательное медицинское страхование, уплачиваемых ИП, не производящими выплаты и иные вознаграждения физическим лицам | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ МЕДИЦИНСКОЕ СТРАХОВАНИЕ ИП» или «ВЗНОСЫ НА ОМС ИП» или может не печататься
| 24 | --- | О страховых взносах на обязательное медицинское страхование, уплачиваемые организациями и ИП, производящими выплаты и иные вознаграждения физическим лицам | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ МЕДИЦИНСКОЕ СТРАХОВАНИЕ» или «ВЗНОСЫ НА ОМС» или может не печататься
| 25 | --- | О страховых взносах на обязательное социальное страхование на случай временной нетрудоспособности и в связи с материнством, на обязательное социальное страхование от несчастных случаев на производстве и профессиональных заболеваний | «ВЗНОСЫ НА ОБЯЗАТЕЛЬНОЕ СОЦИАЛЬНОЕ СТРАХОВАНИЕ» или «ВЗНОСЫ НА ОСС» или может не печататься
| 26 | --- | О приёме и выплате денежных средств при осуществлении казино и залами игровых автоматов расчётов с использованием обменных знаков игорного заведения | «ПЛАТЕЖ КАЗИНО» или «ПК» или может не печататься
| 27 | --- | О выдаче денежных средств банковским платёжным агентом | «ВЫДАЧА ДЕНЕЖНЫХ СРЕДСТВ» или «ВЫДАЧА ДС» или может не печататься
| 30 | --- | О реализуемом подакцизном товаре, подлежащем маркировке средством идентификации, не имеющем кода маркировки | «АТНМ» или может не печататься
| 31 | --- | О реализуемом подакцизном товаре, подлежащем маркировке средством идентификации, имеющем код маркировки | «АТМ» или может не печататься
| 32 | --- | О реализуемом товаре, подлежащем маркировке средством идентификации, не имеющем кода маркировки, за исключением подакцизного товара | «ТНМ» или может не печататься
| 33 | --- | О реализуемом товаре, подлежащем маркировке средством идентификации, имеющем код маркировки, за исключением подакцизного товара | «ТМ» или может не печататься
Идентификатор используется в позиции корзины заказа в [методе создания заказа](/docs/merchant/order/create/#basketitem)
---
---
# Мера количества предмета расчёта (тег 2108)
# Мера количества предмета расчёта (тег 2108)
Таблица 114. Значения реквизита «мера количества предмета расчёта» (тег 2108)
Тег 2108 задаёт единицу измерения предмета расчёта в фискальном чеке. Перечень задан ФНС и **не
совпадает** со [справочником ОКЕИ](/docs/dictionary/okei) — тот используется в поле `measureCode`
позиции корзины, а сюда передают значение из первой колонки таблицы ниже.
Единица измерения позиции указывается при [создании заказа](/docs/merchant/order/create/#basketitem).
| Значение тега 2108 | Обозначение | Пояснение | № строки таблицы ФНС |
| --- | --- | --- | --- |
| 0 | шт. или ед. | Применяется для предметов расчёта, которые могут быть реализованы поштучно или единицами | 1 |
| 10 | г | Грамм | 2 |
| 11 | кг | Килограмм | 3 |
| 12 | т | Тонна | 4 |
| 20 | см | Сантиметр | 5 |
| 21 | дм | Дециметр | 6 |
| 22 | м | Метр | 7 |
| 30 | кв. см | Квадратный сантиметр | 8 |
| 31 | кв. дм | Квадратный дециметр | 9 |
| 32 | кв. м | Квадратный метр | 10 |
| 40 | мл | Миллилитр | 11 |
| 41 | л | Литр | 12 |
| 42 | куб. м | Кубический метр | 13 |
| 50 | кВт∙ч | Киловатт час | 14 |
| 51 | Гкал | Гигакалория | 15 |
| 70 | сутки | Сутки (день) | 16 |
| 71 | час | Час | 17 |
| 72 | мин | Минута | 18 |
| 73 | с | Секунда | 19 |
| 80 | Кбайт | Килобайт | 20 |
| 81 | Мбайт | Мегабайт | 21 |
| 82 | Гбайт | Гигабайт | 22 |
| 83 | Тбайт | Терабайт | 23 |
| -- | - | 255 | Применяется при использовании иных единиц измерения, не поименованных в п.п. 1-23
Для значений этого реквизита никаких логических проверок не предусмотрено и в составе чека ОФД будут
переданы те значения, которые поступили в карточках товаров. Если в карточке товара значение для
этого тега отсутствует, то для всех товаров автоматически будет передано в ОФД значение 0 (в печатной форме - шт./ед.).
---
---
# Ставка НДС (тег 1199)
# Ставка НДС (тег 1199)
> [!IMPORTANT]
> С 2026 года основная ставка НДС — **22 %**. В примерах документации стоят коды `RUS_VAT22`
> (налог в цене, расчётная 22/122) и `RUS_VAT22_ADDED` (налог сверх цены) — это не опечатка вместо 20 %.
> Ставки прошлых лет остались в таблице: они нужны для возвратов и корректировок по старым заказам.
Ставка передаётся кодом Инвойсбокса в поле `vatCode` позиции корзины при
[создании заказа](/docs/merchant/order/create/#basketitem).
Таблица 8. Значения реквизита «Ставка НДС» (тег 1199)
| Наименование ставки НДС | Значение реквизита | Формат ПФ | Код Инвойсбокс | Комментарий |
|-------------------------| ------------------ |------------|-----------------| --------------------------------------------------------- |
| ставка НДС 20% | 1 | НДС 20% | RUS_VAT20_ADDED | |
| ставка НДС 10% | 2 | НДС 10% | RUS_VAT10_ADDED | |
| ставка НДС расч. 20/120 | 3 | НДС 20/120 | RUS_VAT20 | |
| ставка НДС расч. 10/110 | 4 | НДС 10/110 | RUS_VAT10 | |
| ставка НДС 0% | 5 | НДС 0% | RUS_VAT0 | |
| НДС не облагается | 6 | - | VATNONE | |
| ставка НДС 5% | 7 | НДС 5% | RUS_VAT5_ADDED | введена приказом ФНС России № ЕД-7-20/1038 от 15.11.2024 |
| ставка НДС 7% | 8 | НДС 7% | RUS_VAT7_ADDED | введена приказом ФНС России № ЕД-7-20/1038 от 15.11.2024 |
| ставка НДС расч. 5/105 | 9 | НДС 5/105 | RUS_VAT5 | введена приказом ФНС России № ЕД-7-20/1038 от 15.11.2024 |
| ставка НДС расч. 7/107 | 10 | НДС 7/107 | RUS_VAT7 | введена приказом ФНС России № ЕД-7-20/1038 от 15.11.2024 |
| ставка НДС 22% | 11 | НДС 22% | RUS_VAT22_ADDED | введена законопроектом № 1026190-8 от 28.11.2025 |
| ставка НДС расч. 22/122 | 12 | НДС 22/122 | RUS_VAT22 | введена законопроектом № 1026190-8 от 28.11.2025 |
## В чём разница между ставками НДС 22% и 22/122, 10% и 10/110, 7% и 7/107, 5% и 5/105?
### Обычные ставки (22%, 10%, 0% и т.д.)
Когда использовать: Когда вы знаете цену товара БЕЗ НДС и вам нужно начислить (добавить) налог сверху.
Как считать: Цена без НДС × Ставка
Пример: Стулья стоят 1000 рублей без НДС. Ставка — 22%.
- НДС = 1000 × 22% = 220 рублей.
- Цена для покупателя = 1000 + 220 = 1220 рублей.
### Расчётные ставки (22/122, 10/110 и т.д.)
Когда использовать: Когда у вас на руках итоговая сумма, в которую НДС УЖЕ ВКЛЮЧЁН, и вам нужно "вытащить" (выделить) из неё сумму налога.
Как считать: Сумма с НДС × (Расчётная ставка)
Пример: Вы получили аванс от клиента 1200 рублей за будущую поставку стульев. В этой сумме уже сидит НДС. Нужно понять, сколько из этих 1200 рублей - это сам налог.
- НДС = 1200 × (22/122) = 216.39 рублей.
- Значит, аванс без НДС = 1200 - 216.39 = 983.61 рублей.
### Простая аналогия
Представьте торт 🥧.
- Обычная ставка - это когда у вас есть корж (цена без налога), и вы сверху намазываете крем (НДС).
- Расчётная ставка - это когда перед вами целый торт (цена с налогом), и вам нужно аккуратно снять с него крем, чтобы понять, сколько крема было.
22% - чтобы добавить налог к чистой цене. 22/122 - чтобы найти налог внутри итоговой суммы. То же самое для ставок 10% и 10/110.
## В чём разница между ставками НДС 0% и «НДС не облагается?
Ставка НДС 0% и статус «НДС не облагается» - это не одно и то же. Ставка 0% - это льгота для плательщиков налога (например, при экспорте),
которая позволяет не только не начислять НДС клиенту, но и вернуть себе весь «входной» НДС, уплаченный поставщикам, при выполнении условий.
А операции, которые «не облагаются» НДС (например, медицинские услуги), полностью выведены из-под этого налога: налог с клиента не берётся,
но и вернуть «входной» НДС по таким операциям уже нельзя - он включается в расходы.
См. также: [создание заказа](/docs/merchant/order/create/)
---
---
# Справочники
# Справочники
В текущем разделе описаны базовые справочники.
---
# Коды ошибок
# Коды ошибок
Ошибка приходит в свойстве `error` объекта ответа — см.
[структуру ответа](/docs/api/#структура-ответа). Перечень пополняется: незнакомый `code` обрабатывайте
по HTTP-коду, а не игнорируйте.
## Авторизация и доступ
| Код ошибки | HTTP | Что произошло | Что делать |
|---|---|---|---|
| `unauthorized` | 401 | Токен не передан или не распознан | Проверить заголовок `Authorization: Bearer <токен>` — [авторизация](/docs/api/auth/) |
| `forbidden` | 403 | Доступ к ресурсу или объекту запрещён | Проверить, принадлежит ли объект вашему магазину и есть ли у токена нужные права |
## Проверка заказа (422)
Все эти ошибки означают, что запрос дошёл и разобран, но данные не сходятся. Правило подсчёта сумм —
в разделе [как считаются суммы](/docs/merchant/order/create/#как-считаются-суммы).
| Код ошибки | Что произошло | Что делать |
|---|---|---|
| `wrong_expiration_date` | Неверный срок действия заказа | Проверить `expirationDate`: время в будущем, формат с часовым поясом |
| `wrong_currency` | Неверная валюта | Проверить `currencyId` |
| `language_not_found` | Неверный язык заказа | Проверить `languageId`: `ru` или `en` |
| `wrong_basket_item_total_amount` | Итог позиции не сходится | `totalAmount` позиции = `quantity × amount` |
| `wrong_basket_item_total_vat_amount` | НДС позиции не сходится | Пересчитать `totalVatAmount` по ставке из `vatCode` |
| `wrong_basket_item_amount_wo_vat` | Стоимость позиции без НДС не сходится | Проверить `amountWoVat` для одной единицы |
| `wrong_total_amount` | Сумма заказа не равна сумме позиций | `amount` заказа = сумма `totalAmount` позиций |
| `wrong_total_vat_amount` | Сумма НДС заказа не равна сумме НДС позиций | `vatAmount` заказа = сумма `totalVatAmount` позиций |
| `wrong_order_status` | Операция недопустима в текущем статусе | Посмотреть статус заказа и разрешённые переходы — [работа с заказом](/docs/merchant/order/) |
| `merchant_order_id_duplicate` | Такой `merchantOrderId` уже использовался. Приходит, только если у магазина включена проверка уникальности (настройка меняется через поддержку) | Заказ с этим номером уже создан — найдите его выборкой и работайте с ним. Новый номер генерировать не нужно: так появится второй заказ на ту же покупку. См. [повтор после сбоя](/docs/merchant/order/create/#повтор-после-сбоя-и-таймаута) |
## Технические
| HTTP | Что произошло | Что делать |
|---|---|---|
| 429 | Слишком много запросов | Снизить частоту и повторить с задержкой — [ограничения](/docs/api/limits/). Тело может не содержать `code` |
| 500 | Необработанная ошибка на стороне сервиса | Результат операции неизвестен: запрос мог дойти. Чтение можно повторить сразу; после создания заказа, возврата или отмены сначала проверьте выборкой, прошла ли операция, — [повтор после сбоя](/docs/merchant/order/create/#повтор-после-сбоя-и-таймаута). Сообщите нам `x-request-id` из заголовков ответа. Тело может не содержать `code` |
---
---
# Дизайн-система
# Дизайн-система Инвойсбокс
Дизайн-система Инвойсбокс — это набор готовых элементов, компонентов и стандартизированные правила
использования. Дизайнер и фронтендер получают инструмент, который упрощает работу и экономит время.
Продакт-менеджеру проще проверять гипотезы, а команде быстрее реализовывать MVP.
### Библиотека компонентов
Библиотека `invoicebox-ui` содержит ready-to-use компоненты для создания мини-приложений.
- NPM: [invoicebox-ui](https://www.npmjs.com/package/@invoicebox/ui)
- GitHub: [invoicebox-ui](https://github.com/InvoiceBox/invoicebox-ui)
- Документация с примерами: [invoicebox-ui](https://ui.invoicebox.ru)
## Читайте также
- [Где применяется: мини-приложения маркетплейса](/docs/marketplace/mini-apps/)
---
# Термины и определения
# Термины и определения
Термины ниже связаны между собой, и связи важнее самих определений: заказ создаёт магазин, счёт
объединяет заказы, транзакция зачисляется в пользу счёта. Схема показывает эти связи целиком.
Магазин создаёт заказ, состав заказа — корзина, заказ входит в счёт, счёт оплачивает плательщик,
поступление денег фиксируется транзакцией, а отгрузка закрывает заказ и служит основанием для
документов.
Один счёт может объединять несколько заказов — так работает
[группа заказов](/docs/merchant/order/create-order-container/) у маркетплейсов. Покупатель и плательщик
совпадают не всегда: заказ оформляет сотрудник, а платит его организация.
## Система и API
- **Система** — сервис «Инвойсбокс»: принимает оплату от юрлиц и ИП и готовит закрывающие документы
- **API** — программный интерфейс для взаимодействия с Системой
## Магазин и его люди
- **Магазин (Merchant)** — веб-сайт, торгово-сервисное предприятие или иная точка продажи товаров или услуг, поставщики товаров и услуг, принимающее оплату через систему Инвойсбокс
- **Контрагент Магазина (Merchant counterparty)** — частное лицо или организация, которому принадлежит Магазин
- **Личный кабинет (Merchant office)** — личный кабинет Магазина, в котором возможно формировать Заказы, просматривать Транзакции и оформлять Возвраты по переводам, совершенным в системе Инвойсбокс
- **Сотрудник Магазина (Merchant employee)** — представитель Контрагента Магазина, имеющий доступ в Личном кабинете к одному или нескольким Магазинам
## Договор
- **Договор (Contract)** — соглашение, заключенное с определенной даты и на определенный период, определяющее финансовые и иные взаимоотношения между Контрагентами в системе Инвойсбокс
## Заказ и корзина
- **Заказ (Order)** — заказ, сформированный Магазином и переданный в систему Инвойсбокс через API или личный кабинет
- **Корзина (Basket)** — набор сведений о товарах и услугах, их количестве, стоимости, облагаемом налоге, входящие в Заказ
- **Заказчик/Покупатель (Customer)** — частное лицо или организация указанные в Заказе
## Счёт и плательщик
- **Счёт (Invoice)** - счёт, сформированный для оплаты в системе Инвойсбокс, в который входят один или несколько Заказов
- **Плательщик (Payer)** - частное лицо или организация, которому был выставлен Счёт
## Деньги и платёжные инструменты
- **Транзакция (Transaction)** — информация о поступлении оплаты (перевода)/движении денежных средств от Фактического Плательщика в пользу Счёта
- **Обещанный платёж** - сервис для юридических лиц и ИП (платёжный инструмент Инвойсбокс) позволяющий подтверждать оплату заказа с отсрочкой оплаты по счёту
- **Гарантийный фонд** - сервис (платёжный инструмент Инвойсбокс), позволяющий юридическим лицам и ИП моментально подтверждать оплату заказа, используя заранее перечисленные деньги на специальный счёт
- **Овердрафт** - сервис в рамках платёжного инструмента Инвойсбокс **Гарантийный фонд**, позволяющий юридическим лицам и ИП моментально подтверждать оплату заказа на сумму, сверх суммы гарантийного фонда
## Отгрузка
- **Отгрузка (Shipment)** - факт оказания услуги или отгрузки товара Мерчантом (или грузоотправителем) по Заказу
## Платёжная страница
- **Платёжная страница (Payment page)** - пользовательский интерфейс системы Инвойсбокс в котором Плательщик формирует Счёт, выбирает способы оплаты
---
---
# Сроки и условия расчётов
# Сроки и условия расчётов
Сроки выплат, отсрочки и возвратов встречаются в кейсах и справочнике по частям — рядом с той механикой,
о которой идёт речь. Эта страница собирает их в одном месте, чтобы не искать по разделам.
> [!IMPORTANT]
> Цифры ниже описывают типовую схему. Конкретные сроки, тарифы и лимиты фиксируются в договоре
> с вашей организацией и могут отличаться. Уточняйте у менеджера — документация не заменяет договор.
## Деньги продавцу
| Что | Типовой срок | Где описано |
|---|---|---|
| Перечисление оплаченных заказов | на следующий рабочий день после подтверждения оплаты | [гостиницы](/docs/scenarios/pms), [рестораны](/docs/scenarios/ras), [АЗС](/docs/scenarios/gas) |
| Вознаграждение партнёра или площадки | вместе с расчётом по заказам | [схема с комиссией](/docs/merchant/schema/commission/) |
Выплаты идут консолидированным платежом: за день собираются все оплаченные заказы, и на счёт приходит
одна сумма. Разбивка по заказам доступна в личном кабинете и через
[получение заказов](/docs/merchant/order/get/).
## Кто платит комиссию
Комиссию за приём оплаты можно оставить продавцу, разделить между продавцом и покупателем в нужной
пропорции или полностью переложить на покупателя — тогда в счёте она идёт отдельной строкой. Условие
фиксируется в договоре и настраивается при подключении, в запросах на создание заказа ничего менять не
нужно.
## Срок оплаты счёта покупателем
| Что | Типовой срок | Где описано |
|---|---|---|
| Срок жизни счёта | задаёт магазин полем `expirationDate` при [создании заказа](/docs/merchant/order/create/) | от минуты до недель |
| Отсрочка для постоянных корпоративных клиентов | до 30 дней | [авиаперевозчики](/docs/scenarios/air-carriers), [склады и аренда](/docs/scenarios/warehouses) |
| Тайм-лимит бронирования | равен сроку удержания места у перевозчика | [авиа](/docs/scenarios/air-carriers), [ж/д](/docs/scenarios/railway-carriers) |
Неоплаченный счёт с истёкшим сроком можно [отменить](/docs/merchant/order/delete/) — бронь или товар
освободятся под следующего покупателя.
## Возвраты
| Что | Типовой срок | Где описано |
|---|---|---|
| Возврат покупателю после уведомления от магазина | до двух рабочих дней, зависит от способа оплаты | [возвраты](/docs/merchant/refund/) |
| Возврат с удержанием части суммы | тот же срок, удержание остаётся в документах | [возврат с корректировкой](/docs/merchant/refund/correction/) |
## Документы
Закрывающие документы — акт, счёт-фактура, УПД — формируются автоматически после оплаты и уходят
корпоративному покупателю [по каналам ЭДО](/docs/merchant/documentflow/). Фискальный чек регистрируется
в [онлайн-кассе](/docs/merchant/fz54/) в момент оплаты.
> [!TIP]
> Если сроки в вашем договоре отличаются от типовых, ориентируйтесь на договор, а в интеграции
> используйте `expirationDate`: он задаёт срок оплаты для конкретного заказа и не зависит от общих условий.
---
# Политики безопасности
# Соблюдение безопасности при работе с API
Используя описанный протокол взаимодействия, Магазин должен следовать правилам защиты информации.
### Уведомления о переводах
Мы настоятельно рекомендуем в ссылках для получения любых уведомлений использовать защищённое соединение
SSL/TLS безопасных версий.
### Целостность и аутентичность запросов
Для проверки целостности и аутентичности запросов, в ходе взаимодействия с системой «Инвойсбокс»
могут быть использованы различные механизмы. [Базовый вариант](/docs/merchant/notification/status/#%D0%BF%D0%BE%D0%B4%D0%BF%D0%B8%D1%81%D1%8C-%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D0%B0)
с использованием sha1-хеширования используется по умолчанию.
Для поддержания более высоких требований к безопасности, взаимодействие может идти
с использованием клиентских и серверных 🔒 сертификатов (включая ГОСТ-2012), в том числе самоподписных,
сформированных центрами сертификации магазина или системы «Инвойсбокс». В случае взаимодействия с использованием
сертификатов, необходимо проверять подлинность веб-сервисов системы «Инвойсбокс», сохранять конфиденциальность
приватных ключей, следить за сроком действия сертификатов. В случае компрометации приватного ключа необходимо незамедлительно
уведомить службу поддержки системы «Инвойсбокс».
## Читайте также
- [Токен хранится в секретах и меняется в личном кабинете](/docs/api/auth/)