ПланФакт через API и MCP: 187 действий, конверт isSuccess вместо HTTP-кодов и почему это не банк

Обзор

ПланФакт — не банк и не касса. Это сервис финансового УЧЁТА: он хранит то, что уже случилось (или запланировано) в вашем банке или кассе — счета, контрагентов, статьи, проекты, юрлица и сами операции (поступления, списания, перемещения, начисления), — и строит поверх этого отчёты ДДС и ОПиУ. Через его API нельзя провести настоящий платёж, только записать в учёте то, что провёл банк.

Mira подключает 187 действий из 189 в спецификации поставщика и отдаёт их в Claude через MCP — по ключу API, который выпускается в личном кабинете самим владельцем аккаунта, без похода за отдельным одобрением. Это весь API ПланФакта: не выборка «нужных» разделов, а покрытие целиком — не входят только два метода, у которых в спецификации в принципе нет объявленной JSON-схемы тела (см. «Единственное настоящее исключение» ниже).

Что доступно

Отказ приходит HTTP 200 — и это не опечатка

У большинства коннекторов бизнес-отказ («счёт не найден», «нельзя удалить контрагента с операциями») — это HTTP-код 4xx. У ПланФакта — нет. Сверено по официальной спецификации построчно: у любой из 189 операций объявлено ровно четыре кода — 200, 401, 403, 500. Всё остальное — а поставщик знает больше 150 разных бизнес-кодов ошибок — приходит HTTP 200 с телом:

{"data": null, "isSuccess": false,
 "errorMessage": "Счёт не найден", "errorCode": "AccountAccessDenied"}

Проверка только resp.status_code эту ошибку не поймает вовсе. Разбор ответа обязан читать isSuccess у КАЖДОГО ответа 200 — иначе отказ прошёл бы за успех, а данные из пустого data выдались бы за настоящие.

Единственное настоящее исключение — 2 операции из 189

Сначала коннектор покрывал не весь API, а выборку разделов «по смыслу задачи» — операции, счета, контрагенты, отчёты и так далее, 83 действия из 189. У этого подхода есть цена: сделки, счета на оплату, товары и бюджеты — не экзотика, а обычные данные учёта у части бизнесов, и «не входит в контракт» для них означало бы просто «спросите нас позже». Поэтому периметр расширен до полного API: 187 действий, все разделы спецификации, включая сделки (закупки и продажи), их привязку к операциям, счета на оплату, товарный каталог, бюджеты и даже платный уровень «Показатели ПРО» — он читается, если он есть у аккаунта, а если нет — откажет сам ПланФакт, не коннектор.

Не попали ровно два метода — POST и PUT создания/изменения вложения (EntityAttachments). У обоих в спецификации ПУСТАЯ схема тела: по тексту описания это multipart/form-data (файл плюс два поля), а не JSON, и все 187 вызовов этого коннектора, как и у остальных источников Mira, уходят JSON-ом. Действие, которое не может сработать НИ РАЗУ без переделки самого механизма вызова, хуже своего отсутствия — оно обещает то, чего дать не может. Чтение и удаление вложения работают: файла в их теле нет.

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

Барьер без «тратит»

У коннекторов реальных платёжных сервисов барьер записи различает «просто меняет» и «ещё и тратит деньги» — возврат или выплата у ЮKassa, например. У ПланФакта такого различия нет и быть не может: это учёт, а не касса. 80 действий (создание, изменение, удаление любой сущности — счёта, сделки, товара, бюджета, быстрого фильтра) стоят под барьером «меняет», а флага «тратит» просто нет — он был бы всегда False и не нёс бы смысла. Поисковые и сводные запросы, даже оформленные как POST (список сделок с фильтром, расчёт периода быстрого фильтра, «Показатели ПРО»), под барьер не попадают — HTTP-метод сам по себе барьер не определяет, определяет смысл действия.

PUT заменяет сущность целиком

Документация ПланФакта отдельно предупреждает: метод PUT не патчит поля, а заменяет сущность целиком — не переданное поле сбрасывается, а не остаётся прежним. Пример из самой документации: если при обновлении проекта не передать projectGroupId, проект молча уедет в «Проекты без группы». Это не наша особенность, а прямая цитата поставщика, и коннектор несёт её текстом в подсказке к каждому такому действию — до похода к API, а не после сюрприза.

Живая проверка

Живых ключей от боевого аккаунта нет — раздел появится, когда владелец аккаунта их даст. Разбор адреса и query-параметров, барьер записи, заголовок X-ApiKey и разбор конверта isSuccess проверены против собственного HTTP-сервера в тестах (перехват на транспорте — тот же приём, что у Авито, Ozon Performance и ЮKassa), а не против api.planfact.io.