ЮKassa через API и MCP: 34 метода, один конверт отказа и ключ идемпотентности не на всех POST

Обзор

Важная оговорка сразу: это не про то, как Mira принимает вашу оплату подписки — свой биллинг у неё есть и живёт отдельно. Это про ВАШ магазин: если вы принимаете платежи через ЮKassa, у вас есть личный кабинет со своей парой shop_id и secret_key, и именно этими ключами агент читает и меняет данные ВАШЕЙ кассы — платежи, возвраты, чеки, выплаты, сделки.

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

Что доступно

Идемпотентность — не на всех POST

Правило «на каждый создающий запрос — заголовок Idempotence-Key (UUID), чтобы повтор после сетевого сбоя не создал платёж дважды» звучит абсолютным. Спецификация говорит иначе: у деактивации и реактивации кассовой ссылки — тоже POST, но заголовок не заявлен вовсе. Отправить его туда, где поставщик не ждёт, не смертельно, но и не гарантированно безопасно — мы сверили это по каждому пути спецификации, а не по общему правилу «раз POST — значит нужен», и таблица вызовов несёт это знание полем идемпотентно, а не единым флагом на весь HTTP-метод.

Создание платежа не тратит деньги

Барьер записи в Mira делит пишущие действия на «просто меняет» и «ещё и тратит деньги». Возврат и выплата — очевидный расход: деньги уходят со счёта магазина. А вот создание платежа, хоть и стоит под тем же барьером как видимое снаружи действие (счёт, выставленный живому покупателю), деньгами магазина не считается — они, наоборот, ПРИХОДЯТ. Подтверждение платежа (capture) — по той же логике: оно завершает списание с покупателя в пользу магазина. А вот отмена платежа деньги ОСТАНАВЛИВАЕТ, а не тратит — снимает удержание с карты, не потратив ничего.

Один конверт отказа на весь API

В отличие от площадок с семью формами ошибки по разделам (например, у Авито), ЮKassa отвечает одной формой всегда:

{"type": "error", "code": "invalid_request",
 "description": "Invalid amount value", "parameter": "amount"}

Разбор — одна функция, а не таблица форм: description — человеческий текст, code и parameter уточняют его, и оба необязательны.

Постраничный обход одним действием

Списки платежей, возвратов, чеков, сделок и выплат ходят курсором (cursor/next_cursor), лимит — 100 записей за страницу. Инструмент добавляет составное действие list_all, которое пролистывает курсор само, до разумного потолка страниц — агенту нужна сводка за период, а не выгрузка истории магазина целиком за один вызов.

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

Ключей для боевой пары shop_id/secret_key нет — раздел появится, когда владелец магазина их даст. Разбор запроса, подстановка пути, барьер записи и заголовки проверены против собственного HTTP-сервера в тестах (перехват на транспорте — тот же приём, что у Авито и Ozon Performance), а не против api.yookassa.ru.