Инструменты MCP

Восемь инструментов на восемь операций — это сознательный выбор. В публичном контракте тридцать четыре метода, но чем больше инструментов видит модель, тем чаще она выбирает не тот. Здесь только то, что нужно для связного сценария: выставить счёт, узнать статус, подтвердить отгрузку и получить по ней закрывающие документы, вернуть деньги.

Имя	Что делает	Параметры	Метод API	Подтверждение
`lookup_company_by_inn`	Находит реквизиты организации или ИП по ИНН, чтобы заполнить счёт без ручного ввода. Возвращает наименование, КПП, адрес и статус в реестре. Не более десяти разных ИНН за сессию, повторные запросы отвечает кэш.	`inn`	`GET /v3/filter/api/counterparty-detail`	—
`get_order`	Статус, суммы, дата оплаты и ссылка на оплату по счёту. Статусы: created — ждёт оплаты, completed — оплачен, hold — средства захолдированы, canceled — отменён, expired — просрочен. Штатный канал узнать об оплате — уведомление магазину, а не опрос этим инструментом.	`order_id, merchant_order_id, response_format`	`GET /v3/billing/api/order/order/{id}; GET /v3/filter/api/order/order`	—
`find_orders`	Выборка счетов по номеру, статусу и датам создания. Этим же инструментом отвечают на вопрос «что оплачено»: отдельной выборки платежей в API нет, оплата видна статусом счёта. Ответ усечён, страница до 50 записей.	`merchant_order_id, status, created_from, created_to, page, page_size, response_format`	`GET /v3/filter/api/order/order`	—
`find_shipments`	Что по заказу уже отгружено и в каком статусе: draft — черновик, pending — в обработке, completed — завершена и по ней сформированы документы, canceled — отменена. Штатный шаг перед create_shipment: показывает остаток, чтобы человек видел, что подтверждает. detailed добавляет состав и стоит в разы дороже: состав усечён до пяти позиций на отгрузку.	`order_id, page, page_size, response_format`	`GET /v3/billing/api/order/shipment`	—
`create_order` меняет данные	Выставляет счёт покупателю и возвращает ссылку на оплату. Покупатель — организация или ИП (type = legal, у ИП ИНН из 12 цифр и без КПП) либо физлицо (type = private, тогда из документов только фискальный чек). Первый вызов ничего не отправляет: возвращает итоговое тело запроса и одноразовый токен подтверждения. Номер заказа генерирует сервер.	`description, customer, basket_items, amount, vat_amount, currency_id, language_id, expiration_date, success_url, fail_url, return_url, notification_url`	`POST /v3/billing/api/order/order`	да, в два шага
`cancel_order` меняет данные	Отменяет счёт в статусе created. Оплаченный счёт не отменяется — по нему оформляют возврат. У счёта, оплаченного гарантийным инструментом, отмена запускает настоящий возврат, поэтому подтверждение нужно всегда.	`order_id, reason`	`GET /v3/billing/api/order/order/{id}; DELETE /v3/billing/api/order/order/{id}`	да, в два шага
`create_shipment` меняет данные	Подтверждает отгрузку товара или оказание услуги. По отгрузке Инвойсбокс формирует акт или ТОРГ-12, счёт-фактуру и УПД, а у заказов с холдированием списывает заблокированные средства. Отгрузок по заказу может быть несколько; final = true закрывает заказ и разблокирует остаток резерва. Отдельного «сформировать УПД» в API нет: документы идут по отгрузке.	`order_id, basket_items, final, document_number, document_date`	`GET /v3/billing/api/order/order/{id}; GET /v3/billing/api/order/shipment; POST /v3/billing/api/order/shipment`	да, в два шага
`create_refund` меняет данные	Возврат по оплаченному счёту — полный или по составу. Перед сводкой сервер читает состав, доступный к возврату: остаток лежит в availableAmount, и сумма строки его не превышает. Первый вызов ничего не отправляет: сводка и одноразовый токен на 15 минут.	`parent_order_id, description, amount, vat_amount, basket_items`	`GET /v3/billing/api/order/order/{id}; GET /v3/billing/api/order/order/{id}/refund-basket-item; POST /v3/billing/api/order/refund-order`	да, в два шага

Таблица сгенерирована из каталога пакета @invoicebox/mcp-server, отпечаток каталога bd36e3aa8964b467b3d5f6fe4f6514b9 — тот же, что зафиксирован тестом в самом сервере: описания на странице и в tools/list не могут разойтись молча.

Что нужно знать до первого вызова

Суммы — целые копейки строкой. "12200" это 122,00 ₽. Так модель не теряет копейку на числе с плавающей точкой, а сервер сам переводит значение в формат API.
Все записи идут в два шага. Первый вызов ничего не отправляет в Инвойсбокс: он возвращает сводку и одноразовый токен на 15 минут. Второй вызов с этим токеном исполняет операцию — подробнее в безопасности.
Покупатель — юрлицо, ИП или физлицо. В API типа два: legal (у ИП ИНН из двенадцати цифр и без КПП) и private — тогда из документов формируется только фискальный чек.
Закрывающие документы идут по отгрузке. Отдельного «сформировать УПД» в API нет: акт, ТОРГ-12, счёт-фактуру и УПД запускает create_shipment.
Сумма позиции — с НДС, а amount_wo_vat — цена одной единицы без него. Налог считается внутри суммы: сумма × ставка / (100 + ставка). Для 1 200 ₽ со ставкой 22 % это amount и total_amount — "120000", total_vat_amount — "21639", amount_wo_vat — "98361". Сервер сверяет состав с итогом и при расхождении отвечает отказом с арифметикой в тексте, поэтому ассистент может исправиться сам — но начислять налог сверху суммы он будет до тех пор, пока правило не названо в его подсказке.
Единица измерения обязательна. В позиции нужен measure словом либо measure_code по ОКЕИ — например 796 для штук. Придуманные единицы вроде «усл» справочник не принимает, и отказ приходит с указанием позиции.
Срок оплаты — метка времени, а не дата. expiration_date принимается строкой ISO 8601 со временем и зоной (2026-08-20T00:00:00+03:00); дата без времени отклоняется, прошедший срок — тоже. Ассистенту стоит назвать сегодняшнее число: своей даты он не знает и легко поставит вчерашний срок.
Имена параметров — в snake_case, поля API — в camelCase. Инструмент принимает basket_items и measure_code, а в Инвойсбокс уходят basketItems и measureCode: перевод делает сервер. Так устроены описания функций, на которых обучены модели, — и форма нашего API не диктует форму диалога. В сообщении об ошибке сервер иногда называет поле именем из API: передавать всё равно нужно параметр инструмента.
В ответе назван контур и контекст. Поля environment и scope_context показывают, где и от чьего имени выполнен вызов: демо и бой в одном диалоге не перепутаются.

Что сервер делает сам

Часть работы снята с модели намеренно: там, где ошибка стоит денег, полагаться на её внимательность нельзя.

Номер заказа. Уникальный merchantOrderId генерирует сервер и записывает в журнал — модель его не придумывает и не может повторить.
Сходимость сумм. Перед отправкой сумма счёта сверяется с составом, а НДС — с суммой налога по позициям. Расхождение возвращается моделью как ошибка ввода, а не уезжает в API.
Проверка статуса. Перед отменой и возвратом сервер сам читает текущее состояние счёта: отменить оплаченный или вернуть неоплаченный не выйдет.
Защита от дублей. Перед созданием возврата сервер ищет уже существующие по тому же счёту. Повтор после обрыва связи вернёт первый результат, а не спишет дважды.
Короткие ответы. Поиск возвращает несколько полей на запись, а не весь объект: длинный ответ вытесняет из контекста то, ради чего его запрашивали.

Чего в наборе нет

Списание по сохранённой карте, приглашения контрагентов, управление магазинами Витрины и спецпредложениями, поиск возвратов по исходному счёту. Часть из этого меняет деньги без очевидного для человека следа, часть требует контекста, которого у ассистента нет. Эти операции остаются в личном кабинете и в прямой интеграции.

Отгрузку сервер, наоборот, умеет — она в наборе write и подтверждается человеком отдельно: у неё налоговый след, и одним вызовом её не отменить. Подробно об этом решении — на странице о безопасности.

Соответствие API

Каждый инструмент — это один метод из публичного контракта, с теми же ограничениями и теми же кодами ошибок. Если метод недоступен вашему магазину по договору, инструмент вернёт ту же ошибку, что и прямой вызов.