Boxberry через API и MCP: документация переехала в Яндекс, а API остался жив

Обзор

Boxberry — служба доставки для интернет-магазинов: пункты выдачи, курьер, международные отправления. У неё есть открытый API — но в 2026 году он оказался в необычном положении: сама служба вошла в Яндекс Доставку, и прежняя документация (boxberry.ru, help.boxberry.ru) сегодня целиком переадресует на yandex.ru/support/delivery-boxberry. Первое движение — проверить, жив ли вообще эндпоинт api.boxberry.ru/json.php — оказалось не формальностью: curl с неверным токеном честно ответил 401 с телом {"err":"Ваша учетная запись заблокирована"}, за инфраструктурой Яндекса (заголовки X-YaTraceId), но по существу. API жив, просто его прежняя проза переехала.

Mira подключает этот API — 34 действия, собранные из трёх источников (живая переехавшая документация, её собственная «Таблица изменений» с версиями по 2025 год, и исходный перечень методов) — и отдаёт его в Claude через MCP.

Один адрес, а не набор путей

У Boxberry нет привычного REST: любое действие — города, расчёт стоимости, создание заказа, отмена — идёт на один и тот же адрес, https://api.boxberry.ru/json.php. Какое это действие, говорит поле method внутри запроса, а не путь. Для инструмента, который отдаёт список действий модели, это значит: закрытый список названий вместо проверки пути — модель может попросить ListCities или ParselCreate, но не может подставить произвольную строку вместо метода и «дотянуться» до чужого действия так, как это возможно у путевых API через ../.

Отказ, который прячется в успешном ответе

Самая неочевидная особенность API — старая, но документированная прямо: метод CancelOrder отвечает полем err, которое либо false (успех), либо текст причины отказа — и статус-код при этом может быть 200. Разбор ответа в Mira поэтому смотрит на две вещи одновременно, а не только на код ответа: HTTP-статус ≥ 400 ИЛИ истинный err в теле. Пропустить второе условие значило бы иногда докладывать «готово» там, где Boxberry на самом деле отказал.

Токен — не в адресе

Часть документации показывает примеры с GET-запросами, где токен едет в query-строке. Mira отправляет всё исключительно POST-запросами с JSON-телом: токен живёт только в теле запроса, а адрес всегда один и тот же — https://api.boxberry.ru/json.php, без единого параметра. Это не косметика: адрес запроса — то, что чаще всего попадает в логи транспорта и текст сетевых ошибок, и когда в нём никогда нет секрета, целый класс утечек закрывается один раз, а не проверяется на каждом отдельном месте кода.

Что стоит за созданием заказа

Барьер записи у Boxberry делит одиннадцать пишущих действий на «просто меняет» и «ещё и тратит»: создание посылки и заявка на курьерский забор считаются платными — магазин берёт на себя обязательство перед Boxberry в момент оформления, — а отмена заказа, наоборот, не тратит: отмена не начисляет платёж, а может его избежать. Формирование акта приёма-передачи и управление складами продавца — меняющие действия, но не денежные: это передача уже существующих посылок и административная настройка.

Честно о пределах покрытия

Документация Boxberry разложена неровно, и коннектор это не скрывает. Одиннадцать действий описаны на живых страницах поставщика полностью, с формой каждого параметра. Ещё четырнадцать названы в «Таблице изменений» по имени, но без разбора параметров — их коннектор передаёт как есть, не достраивая полей, которых в документации не видел. Оставшиеся девять взяты из первоначального перечня методов, устоявшегося в открытых SDK, и отдельной страницей 2026 года не подтверждены.

Практический вывод для владельца: первые работают предсказуемо, последние могут ответить отказом, если Boxberry с тех пор их поменял. Это лучше, чем обещание «покрыто целиком», за которым не стоит ничего.