Лимиты, ошибки и журнал
Что ограничено и почему, как читать отказы, что попадает в журнал операций и ответы на вопросы, которые задают до подключения. Состав инструментов — на странице инструментов, правила подтверждения — в безопасности.
Лимиты
| Что | Предел | Почему так |
|---|---|---|
| Частота запросов | 60 запросов за 30 секунд | Общий лимит учётной записи — 100 за 30 секунд. Сервер оставляет запас основной интеграции магазина, иначе ассистент остановил бы приём платежей |
| Одновременные запросы | не больше четырёх | Три чтения и одна запись: шквал чтений не должен съедать канал для создания счёта |
| Размер страницы выборки | до 50, по умолчанию 20 | Длинный ответ вытесняет из контекста то, ради чего его запрашивали |
| Повторное чтение одного счёта | не чаще раза в 5 секунд | Об оплате штатно сообщает уведомление магазину, а не опрос |
| Поиск по ИНН | до 10 разных ИНН за сессию, кэш на сутки | Предел останавливает перебор реестра в цикле |
| Возвраты за сутки | 10 штук и 50 000 ₽ | Настраивается; превышение — повод человеку разобраться, а не тихий отказ |
| Вызовы за сессию | до 200 | Модель, зациклившаяся на вызовах, не должна выесть лимит магазина |
Предел достигнут — сервер не молчит: он говорит, чего именно не хватило и что делать. Частоту и суточные потолки можно поднять переменными INVOICEBOX_RATE_LIMIT и INVOICEBOX_LIMITS, но выше лимита учётной записи частота не поднимется: сервер возьмёт максимум допустимого и скажет об этом.
Разбор отказов
Отказ приходит обычным ответом инструмента с полем reason и подсказкой, а не обрывом связи: ассистент должен прочитать причину и поправить запрос. Большинство проверок происходит до обращения к API — значит в Инвойсбокс ничего не ушло.
| Текст | Что случилось | Что делать |
|---|---|---|
суммы не сходятся | Сумма позиций не равна сумме заказа или НДС не сходится | Ответ называет позицию и оба числа — поправьте состав или сумму |
ИНН не проходит проверку контрольной суммы | Опечатка в номере | Проверьте цифры: контрольная сумма считается по самому номеру |
у физлица КПП не бывает | Тип покупателя private вместе с КПП | Уберите КПП или укажите type = legal |
счёт оплачен, отмена к нему не применяется | Попытка отменить оплаченный счёт | Деньги возвращают возвратом, а не отменой |
отгрузка выходит за остаток | Сумма отгрузок превысила сумму заказа | Посмотрите отгруженное инструментом find_shipments |
к возврату доступно… | Запрошено больше, чем осталось | Остаток считается по availableAmount, а не по цене за единицу |
подтверждение просрочено | Между сводкой и исполнением прошло больше 15 минут | Запросите сводку заново |
подтверждали другую операцию | Между шагами изменилась сумма, контрагент или состав | Так и должно быть: подтверждение привязано к параметрам |
суточный потолок исчерпан | Достигнут предел операций за сутки | Поднять потолок — решение человека, а не ассистента |
API Инвойсбокса не отвечает, вызовы приостановлены | Пять отказов подряд разомкнули цепь на 30 секунд | Подождите: пока цепь разомкнута, запросы не отправляются |
результат неизвестен | Связь оборвалась на записи | Сервер сам проверит выборкой, прошла ли операция, и не создаст дубль |
В каждом ответе есть request_id — идентификатор запроса в Инвойсбоксе. С ним поддержка находит вызов сразу, без переписки «а когда это было».
Журнал операций
Сервер пишет строку на каждый вызов: время, инструмент, приложение клиента, адрес вызывающего, контур, магазин, параметры, номер созданного заказа, способ подтверждения, код ответа API, request_id, длительность и итог. Итог различает четыре состояния: выполнено, отклонено сервером, ошибка API и «результат неизвестен» — последнее выделено отдельно, потому что это единственный случай, когда операция могла пройти.
- Где смотреть. Локальный сервер пишет журнал в поток диагностики (клиент собирает его в свои логи) и в файл, если задан
INVOICEBOX_STATE_DIR. - Как найти операцию. По номеру заказа (
merchant_order_id, сервер генерирует его с префиксомmcp-) или поrequest_idиз ответа. - Чего в журнале нет. Токена, ключей и полных персональных данных: они маскируются до записи. Наружу журнал не уходит, пока вы сами не укажете приёмник —
INVOICEBOX_GRAYLOG_URLилиINVOICEBOX_SENTRY_DSN.
Вопросы
Сколько это стоит
Отдельной цены у сервера нет: он работает с вашим магазином по действующему договору, а комиссия остаётся такой же, как при любой другой интеграции. Демо-контур бесплатен всегда.
Чем это отличается от личного кабинета
Кабинет — для человека, который сам заполняет поля. Сервер — для ассистента, который собирает запрос по просьбе человека и показывает готовый результат на подтверждение. Данные и документы одни и те же: и то и другое ходит в одно API.
Что будет при обрыве связи
Чтения повторяются автоматически. Записи — нет: сервер помечает результат как неизвестный и сам проверяет выборкой, прошла ли операция. Повторный вызов с тем же содержимым возвращает прежний результат, а не создаёт второй счёт, отгрузку или возврат.
Можно ли попробовать без своего магазина
Да. Параметры демонстрационного магазина опубликованы на странице авторизации, и на них проходят все инструменты. Демо и бой сервер не смешивает: он сверяет пару «контур и магазин» при запуске и не поднимается при расхождении.
Чего сервер не умеет
- Реестра поступлений и сведения платежей: отдельной выборки платежей в API нет, оплата видна статусом счёта.
- Рассылки счетов покупателю: счёт формируется сразу при создании заказа, Инвойсбокс отдаёт его сам.
- Подписок и холдирования: они ждут решений продукта.
- Выполнять денежную операцию без человека — ни при каких настройках.