Финтабло через API и MCP: 112 методов финучёта, семь путей без объявленных параметров и почему тут нет отчётов

Обзор

Финтабло — сервис финансового учёта: ДДС, статьи, счета, контрагенты, направления, сделки, обязательства, зарплата (в том числе сдельная), имущество с амортизацией, ОПиУ. У каждого аккаунта свой API-токен в настройках, и через него можно и читать данные, и вести учёт программно — то же самое, что человек делает руками в интерфейсе my.fintablo.ru.

Mira подключает этот API целиком — 112 действий — и отдаёт его в Claude через MCP. Число не с сайта и не из головы: официальная OpenAPI-спецификация (FinTablo-v1-swagger.yaml, её адрес отдаёт редок на my.fintablo.ru/api/docs) скачана и разобрана программно — 50 путей, но большинство несут по несколько HTTP-глаголов на одном адресе (список и создание на одном пути, чтение/правка/удаление — на другом). Ниже — что там есть на самом деле и что расходится с интуицией.

Что доступно

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

Отчётов в API нет

Интуитивно у сервиса финучёта должны быть отчёты — ДДС за период, ОПиУ, баланс. В спецификации их нет: список тегов проверен программно, тега «Отчёты» или похожего не существует. Есть только справочники и операции, которые эти отчёты формируют внутри интерфейса Финтабло. Кто хочет отчёт через API — считает его сам по операциям, статьям и направлениям, которые Mira отдаёт целиком: у агента есть все исходные данные, просто не готовая сводка от поставщика.

Спецификация сама не дописывает параметры

Семь операций несут параметр прямо в URL — /v1/deal/{id}/add-stage, три операции /v1/deal/{dealId}/plan-dds и три /v1/deal/{dealId}/plan-dr, — которого нет ни в объявлении параметров пути, ни операции. Это не наша недоработка: сверено построчно по parameters каждого из 112 путей спецификации. Поставщик просто не упомянул то, что использовал в шаблоне адреса. Сборка запроса в Mira достаёт имена подстановки из самого текста пути, а не из объявленных параметров — поэтому пробел поставщика инструменту не мешает, но именно поэтому автоматическая сверка таблицы вызовов со снимком спецификации не может проверить эти семь путей мимоходом и называет их отдельно.

id дублируется в теле — но только у четырёх PUT

Двадцать шесть из тридцати PUT-запросов на правку сущностей тело не требуют вовсе — параметр в адресе достаточен. Но у четырёх — правки сотрудника, ведомости, имущества и сдельной зарплаты — схема требует передать id ещё и в теле запроса, хотя он уже есть в URL. У правки сдельной зарплаты сверх того обязательны dealId и date — зачем такой правке эти поля, спецификация не поясняет. Это не общее правило API, а свойство четырёх конкретных схем, и найдено оно тем же построчным разбором required каждой схемы, а не догадкой «раз PUT — значит нужен id».

Обязательные поля проверяются до похода к поставщику

Каждое из 112 действий несёт список обязательных полей тела, извлечённый из той же спецификации. Прежде чем инструмент отправит что-либо в Финтабло, он сверяет присланные параметры с этим списком — и если чего-то не хватает, говорит об этом сразу, без сетевого запроса. Список не переписан руками: его сверяет автоматический тест против снимка официальной спецификации, так что расхождение между тем, что просит инструмент, и тем, что на самом деле required у поставщика, ловится тестом, а не отказом в проде на десятом вызове.

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

Токен выпускается в настройках самого аккаунта Финтабло (значок профиля → Настройки аккаунта → API) — без одобрения заявки. Дальше — источник в Mira, и агент получает доступ ко всему финучёту компании: может свести операции по направлению, найти незакрытые обязательства, посчитать сдельную зарплату по сделке или завести новую статью ОПиУ — голосом или текстом, без интерфейса Финтабло вовсе.