ПЭК через API и MCP: 52 из 52 методов, от расчёта до заявки на перевозку

Обзор

ПЭК — одна из крупных российских транспортных компаний — даёт клиентам открытый API (Kabinet API) без заявок и одобрений: ключ доступа выпускается прямо в личном кабинете, на странице «Регистрационные данные» → «Ключи API». Авторизация — HTTP Basic на каждый запрос: логин личного кабинета и любой из активных ключей.

Mira подключает этот API — 52 из 52 методов официальной документации — и отдаёт его в Claude через MCP. Ниже — что там есть на самом деле и что расходится с интуицией.

Что доступно

Барьер записи без единого «тратящего» действия

У большинства коннекторов, которые Mira уже подключила — банки, платёжные шлюзы — барьер записи делится на два уровня: «меняет данные» и «ещё и тратит деньги» (у Модульбанка, например, подписание платёжного поручения — трата, а его создание черновиком — нет). У ПЭК этого деления нет вовсе, и причина не в недосмотре, а в устройстве самого бизнеса: ПЭК — грузоперевозчик, а не платёжный шлюз. Перевозка стоит денег, но счёт выставляется и оплачивается вне Kabinet API — документами и банковским переводом, а не вызовом метода.

Означает ли это, что барьер записи здесь не нужен? Нет — 11 из 52 методов всё равно требуют разрешения на запись у источника: заявка на забор груза, предварительное оформление, отмена и возврат, справочник получателей, подписка на уведомления. Правило барьера — не только «трогает деньги», но и «видно снаружи» или «необратимо». За заявкой на забор груза выезжает настоящая машина, отправителю звонит оператор, получателю приходит SMS — это видно снаружи ровно так же, как публикация объявления на Авито. А отменить заявку можно только в узком окне — 5–10 минут после подачи и до того, как она попала в маршрутный лист водителя.

HTTP 200 ещё не значит успех

Самая неочевидная особенность API ПЭК — обработка ошибок. Неверный адрес метода отвечает кодом 404, нарушение прав — 403, но логическая ошибка (не хватает параметра, неверный формат) возвращается с кодом 200 и конвертом {"error": {"title": "...", "message": "..."}} в теле. Обычный response.raise_for_status() здесь ничего не поймает — код состояния лжёт об успехе. Разбор ответа в коннекторе Mira проверяет этот конверт даже у ответов с кодом 200, а не полагается на HTTP-статус как на единственный сигнал.

Своего Swagger у ПЭК нет — и это тоже решаемо

В отличие от Модульбанка, который публикует полноценную Swagger-спецификацию прямо на боевом хосте, у ПЭК машиночитаемого контракта в привычном смысле нет — документация оформлена как HTML-страницы с примерами JSON и построчными комментариями «обязательно» / «необязательно» у каждого поля. Это тоже устойчивая, разбираемая программно структура: скрипт коннектора скачивает все 18 страниц документации и извлекает путь, метод и поля тела так же честно, как если бы это был Swagger — просто источником служит разметка страницы, а не отдельный JSON-файл. Число операций сошлось с независимой проверкой — сторонним PHP SDK, сгенерированным из реконструированного OpenAPI по тем же официальным страницам: 52 у обоих источников.

Заявка на забор — один и тот же метод для двух сценариев

Метод cargopickup/submit умеет и оформлять полную заявку (машина плюс перевозка), и подавать упрощённый заказ машины отдельно — по одному и тому же адресу, но с разным набором обязательных полей. Документация ПЭК описывает оба сценария на одной странице под двумя заголовками; коннектор Mira сводит их в одно действие с объединённым набором допустимых полей, а не заводит два действия на один физический вызов.