СДЭК через API и MCP: 46 методов, «принято» ≠ «выполнено» и две формы отказа

Обзор

СДЭК — одна из немногих служб доставки в России, где интеграция по API не требует одобрения заявки: продавец заключает договор, получает пару ключей в личном кабинете (lk.cdek.ru → Интеграция → API-ключи) — и готово. Тестовый контур api.edu.cdek.ru с публичной тестовой учётной записью доступен ещё до подписания договора: попробовать API можно сразу.

Mira подключает CDEK API v2 целиком — 46 методов в тринадцати разделах — и отдаёт его в Claude через MCP. Первый коннектор новой категории «Логистика»: следом делаются Boxberry, Яндекс Доставка и ПЭК.

Что доступно продавцу

Отдельного раздела «интернет-магазины» в API нет — это не набор методов, а значение поля type при создании заказа (1 — интернет-магазин, только для договора «Договор с ИМ»; 2 — доставка, для любого договора). Один и тот же метод POST /v2/orders обслуживает оба случая.

Устройство, которое стоит знать заранее

«Принято» — не значит «выполнено»

Это главная ловушка API. Создание заказа, вызов курьера и большинство других команд отвечают HTTP 202 Accepted мгновенно — но это значит только «запрос встал в очередь на обработку», а не «заказ создан». Итог обработки нужно смотреть отдельно, в поле state внутри того же ответа: ACCEPTED, WAITING, SUCCESSFUL или INVALID.

Проверено живым вызовом против тестового контура: попытка создать заказ с несуществующим тарифом отвечает тем же успешным HTTP-кодом, что и рабочий заказ — разница видна только в requests[0].state. Интеграция, которая читает только код ответа, решит, что заказ создан, хотя СДЭК его отклонил. MCP-инструмент Mira разбирает это поле сам: отказ, спрятанный под успешным кодом, доходит до агента как отказ, а не как «готово» с несуществующим заказом внутри.

Это касается только команд, которые ЧТО-ТО ДЕЛАЮТ — создают, меняют, вызывают курьера. Для обычного чтения то же поле в ответе означает историю ВСЕХ прошлых команд по этой сущности, а не итог текущего запроса: старая ошибка в истории заказа не должна гасить его свежее, вполне успешное чтение. Спутать эти два случая — значит либо пропустить настоящий отказ, либо ложно забраковать нормальное чтение.

Два разных конверта отказа

У калькулятора, локаций и большинства методов, отвечающих сразу, — плоский конверт: {"errors": [{"code", "message"}]}. У заказов и курьера при отказе ДО постановки в очередь — тот же список ошибок, но вложенный в requests[0].errors. Оба варианта подтверждены живыми вызовами против тестового контура: калькулятор с неполным телом отвечает первой формой, запрос несуществующего заказа — второй. Инструмент Mira разбирает обе — причина доходит до чата словами поставщика, а не «HTTP 400» без объяснения.

Печатные формы — тоже асинхронные

Квитанция и штрихкод места не формируются мгновенно: запрос создаёт задачу, статус проверяется отдельным вызовом, а готовый PDF скачивается третьим — по адресу с буквальным суффиксом .pdf, не параметром. Содержимое файла в чат не переносится: инструмент отдаёт тип и размер, как и для архива с фотодокументами.

Барьер: платно ровно три действия из четырнадцати меняющих

Из 46 методов 14 меняют данные — заказы, курьер, печатные формы, вебхуки, договорённость о доставке — и только 3 из них тратят деньги или запускают платную услугу: создание заказа, вызов курьера и регистрация клиентского возврата (она создаёт новую платную доставку по тому же принципу, что обычный заказ). Барьер выведен из одной таблицы, где описан каждый метод — разойтись им негде.

Изменение и удаление заказа, отмена вызова курьера — это тоже запись, но деньги они ОСТАНАВЛИВАЮТ, а не тратят, и поэтому не требуют отдельного подтверждения о списании.

Как это выглядит через MCP

Сколько будет стоить доставка коробки 2 кг из Москвы в Новосибирск тарифом «Экспресс»?

Claude обращается к калькулятору, называет сумму и срок — без захода в личный кабинет.

Вызови курьера завтра с 10 до 18 по заказу на Тверской, 5

Claude собирает заявку на вызов курьера — платное действие, и без разрешения на запись у источника оно остановится ещё до похода к СДЭК, а не после.

Что это даёт на практике

Интернет-магазину. Статус доставки, стоимость и вызов курьера одним вопросом, без переключения между личным кабинетом СДЭК и остальными инструментами.

Агентству и разработчику. Готовый клиент вместо разбора того, где именно в ответе спрятан настоящий итог асинхронной команды, и без риска принять «принято в очередь» за «выполнено».

Как подключить

1. Личный кабинет СДЭК (lk.cdek.ru) → Интеграция → API-ключи → «Создать ключ».
2. Скопировать Client ID и Client Secret.
3. В Mira: проект → источники → СДЭК → вставить оба ключа.

Дальше СДЭК доступен и в чате Mira, и через MCP-сервер в Claude, Cursor или другом клиенте с поддержкой протокола.