Модульбанк через API и MCP: выписка, платёжное поручение и почему подписание — это трата, а не создание

Обзор

Модульбанк — один из немногих российских банков для бизнеса с открытым и машиночитаемым API: не PDF-страница с примерами, а настоящая Swagger-спецификация прямо на боевом хосте. Подключиться можно самому, без заявок и одобрений — в личном кабинете есть кнопка «Интеграция с банком», которая выдаёт токен доступа сразу.

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

Что доступно

Подписание — это трата, создание — нет

Самое неочевидное место всего API. Загрузка платёжного поручения (POST /operation-upload) не двигает ни рубля — она кладёт документ в личный кабинет черновиком. Деньги трогает только отдельный вызов подписания (POST /operation-upload/sign): спецификация говорит об этом дословно — «после подписания платежи отправляются в банк и проводятся». Барьер записи в Mira делит пишущие действия на «просто меняет» и «ещё и тратит деньги» — и здесь эти два действия оказываются в разных категориях, хотя интуитивно кажется, что именно создание платежа должно быть самым опасным шагом.

Что здесь важно и для агента, и для человека: подписание требует Base64-подписи, изготовленной КриптоПро над строкой идентификаторов платежей с помощью квалифицированного сертификата компании. Это физическое действие с аппаратным токеном или файлом сертификата — агент такую подпись сделать не может, и не пытается. Инструмент передаёт банку уже готовую подпись, которую подготовил человек, — курьер, а не изготовитель подписи.

Тот же приём — в отчётности по номинальным счетам

Номинальные счета (эскроу-подобная конструкция для платформ, которые держат чужие деньги) требуют ежедневной отчётности о бенефициарных владельцах по 115-ФЗ — и подписания отчётов усиленной квалифицированной подписью. Устройство точно такое же: инструмент передаёт банку готовую подпись (Signature), а не изготавливает её сам.

Один self-service токен, а не OAuth-приложение

У Модульбанка есть два способа авторизации. Первый — self-service: человек сам генерирует токен в личном кабинете, привязанный к его учётной записи, без заявок и одобрений. Второй — партнёрский OAuth-поток для сторонних приложений, которые хотят авторизовывать ЛЮБОГО клиента банка через страницу согласия; он требует регистрации приложения по почте и отдельной пары ключей. Mira использует первый способ — он мгновенный и не требует ничьего одобрения. Второй остаётся зафиксированным долгом: он понадобится, если Mira когда-нибудь станет партнёрским приложением банка, а не просто читает данные одного подключённого пользователя.

Выписка листается сама

История операций по счёту отдаётся страницами до 50 записей и курсором skip/records. Инструмент добавляет составное действие operations_all, которое пролистывает всё само, до разумного потолка страниц — агенту нужна сводка за период, а не выгрузка истории счёта целиком за один вызов.

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

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