Журнал изменений API

Все изменения публичного API: новые маршруты, поля, события вебхуков и коды ошибок. Новые записи добавляются сверху, даты указаны по UTC. Изменение, ломающее совместимость, отмечается словом несовместимо и объясняет, что должен сделать интегратор.

2026-09-13, комиссия сети

Несовместимо для кода, который проверяет fees.network.status инвойса по перечню quoted, pending, settled. У инвойса нет отдельной комиссии сети: затраты сети на приём входят в комиссию сервиса, и fees.network.status теперь всегда included. Прежние значения больше не приходят. Ключи сохранены: quote, quote_rate и actual — всегда null, payer — всегда merchant. Если интеграция проверяет перечень строго, добавьте included. См. комиссии. То же — в событиях invoice.* и в ответах API кабинета и страницы оплаты.
Коды 422 network_fee_payer_not_supported и 503 network_fee_quote_unavailable остаются: покупатель комиссию сети не несёт. Изменились только их сообщения.
У выплаты новое поле fees.network: payer — всегда merchant, amount — фиксированная комиссия сети, записанная в выплату при создании, charged — сколько списано с баланса проекта. То же — в данных событий payout.confirmed и payout.failed. См. комиссию сети.
Комиссия сети списывается с баланса проекта при подтверждении выплаты, отдельной проводкой реестра; выплата, провалившаяся в цепи, её не несёт. Получатель по-прежнему получает ровно amount.
Административный API: тариф комиссии сети за выплату — GET /admin/v1/payout-fees и POST /admin/v1/payout-fees, коды payout_fee_confirmation_required и payout_fee_valid_from_in_past; новый вид счёта реестра network_cost_recovery в GET /admin/v1/balances и в проводках — административный API.

2026-09-13, комиссия сервиса

У инвойса новые поля: amount_requested — цена мерчанта, amount_credited — полученное за вычетом удержанных комиссий, fees — комиссия сервиса и комиссия сети. Поля только добавлены, прежние не меняют смысла: amount_expected — по-прежнему сумма, которую должен заплатить покупатель. См. комиссии.
Проверьте интеграцию. Если в проекте комиссию сервиса платит покупатель, amount_expected больше цены на эту комиссию. Код, который сравнивает amount_expected со своей ценой заказа, должен сравнивать amount_requested. В проектах, где комиссию платит мерчант (так по умолчанию), amount_expected равен цене, как раньше.
Идемпотентность POST /v1/invoices по order_id сравнивает amount запроса с ценой amount_requested: повтор присылает цену, а не сумму с комиссией.
Комиссия сервиса удерживается с каждого подтверждённого платежа отдельной проводкой реестра и уменьшает баланс мерчанта. Ставка записывается в инвойс при создании: смена тарифа не меняет уже выставленные инвойсы.
Те же поля — в данных событий invoice.* (вебхуки) и в ответе маршрута страницы оплаты; страница оплаты показывает разбивку «Цена · Комиссия сервиса · Итого», когда комиссию платит покупатель (страница оплаты).
Новый код 503 network_fee_quote_unavailable: проект настроен так, что комиссию сети платит покупатель, а посчитать её сейчас нельзя. Такую настройку API кабинета больше не принимает — 422 network_fee_payer_not_supported.
Административный API: тарифы комиссии сервиса — GET /admin/v1/service-fees, POST /admin/v1/service-fees/platform, GET /admin/v1/merchants/{id}/service-fees, POST /admin/v1/merchants/{id}/service-fees, коды service_fee_confirmation_required и service_fee_valid_from_in_past — административный API. GET /admin/v1/fees остался отчётом о комиссиях сети.

2026-09-13, проверка проектов и настройки проекта

Проект, который бизнес заводит сам, принимает платежи только после проверки. Пока он не одобрен или если отклонён, POST /v1/invoices и POST /v1/addresses отвечают новым кодом 403 merchant_not_approved. Ключи API при этом работают, чтение инвойсов тоже. Все мерчанты, созданные раньше, одобрены: для существующих интеграций ничего не меняется.
Владелец может выключить приём в активе для своего проекта. Тогда POST /v1/invoices в этом активе отвечает новым кодом 422 asset_disabled_by_merchant, а POST /v1/addresses не включает актив в список assets. Уже открытые инвойсы оплачиваются и закрываются, повтор принятого запроса возвращает инвойс.
403 merchant_disabled теперь означает выключение и оператором, и владельцем проекта.
Проект без адреса вебхуков событий не получает: они не ставятся в очередь и после появления адреса не досылаются (вебхуки).
Административный API: у мерчанта новые поля — review_status, review_reason, reviewed_at, reviewed_by, site_url, description, network_fee_payer, service_fee_payer, disabled_by. Появились фильтр GET /admin/v1/merchants?review_status=, маршруты POST /admin/v1/merchants/{id}/approve и POST /admin/v1/merchants/{id}/reject — административный API. Несовместимо для клиентов административного API: webhook_url мерчанта может быть null. Консоль обновлена в том же изменении.
Маршруты /cabinet/v1 для приложения кабинета: служебные, снаружи недоступны и в GET /v1/openapi.json не входят.

2026-09-13, переключатели приёма и выплат

Оператор может временно выключить приём или выплаты в активе. Пока приём выключен, POST /v1/invoices в этом активе отвечает новым кодом 422 asset_payments_disabled, а POST /v1/addresses не включает актив в список assets. Пока выключены выплаты, POST /v1/payouts отвечает новым кодом 422 asset_payouts_disabled.
Повторы запросов, принятых раньше, отвечают как прежде: инвойс по тому же order_id и выплата по тому же reference возвращаются.
Уже открытые инвойсы оплачиваются и закрываются, уже созданные выплаты исполняются: переключатель касается только нового.
Административный API: PATCH /admin/v1/assets/{id}, поля payments_enabled и payouts_enabled в объекте актива, новые коды asset_not_found и asset_flag_locked — административный API.

2026-09-13, административный API консоли

Маршруты /admin/v1 для консоли оператора: мерчанты и их ключи, инвойсы, остатки счетов реестра, движение средств, комиссии сети, каталог активов, доставки вебхуков и журнал аудита — административный API. Доступ по токену консоли ADMIN_API_TOKEN и заголовку оператора X-Operator; без токена маршрутов нет (ADR-0033).
Адреса возврата мерчанта return_url и cancel_url видны в объекте мерчанта и меняются PATCH /admin/v1/merchants/{id} по правилам страницы оплаты.
Новые коды ошибок, только у этих маршрутов: merchant_not_found, api_key_not_found, delivery_not_found, delivery_not_failed.
Маршруты /v1 и описание GET /v1/openapi.json не изменились: административные маршруты в него не входят.

2026-09-13, страница оплаты и адреса возврата

У инвойса новое поле checkout_url — ссылка на страницу оплаты, если оператор её настроил, иначе null.
Необязательные поля return_url и cancel_url в POST /v1/invoices: куда страница оплаты вернёт покупателя. Допускаются только в пределах origin адресов, заданных у мерчанта оператором; иначе новый код 422 redirect_url_not_allowed. Те же поля появились в ответе инвойса.
Повтор POST /v1/invoices с другими return_url или cancel_url — 409 order_id_conflict, как повтор с другой суммой. Запросы без этих полей ведут себя как раньше.
Возврат покупателя подписан: параметры invoice_id, order_id, status, ts, signature, подпись HMAC-SHA256 секретом вебхуков. Формат и код проверки — в странице оплаты. Решение — ADR-0032.
GET /checkout/v1/invoices/{id} — служебный маршрут сервера страницы оплаты, без ключа API, в приватной сети. Мерчантам он не нужен.

2026-09-12, USDC в сети TRON

Новый актив USDC_TRON: инвойсы и выплаты в USDC принимаются наравне с USDT, 6 знаков после запятой, 20 подтверждений. Контракт TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 — прочитан в сети, а не взят из статьи: symbol() = USDC, name() = USD Coin, decimals() = 6. Обоснование и граница решения — в ADR-0026.
USDC на адресе приёма больше не считается неожиданным активом. Для TRON unexpected_asset теперь означает токен, которого нет в каталоге.
TRX платёжным активом пока не стал: в режиме сжигания энергии (SWEEP_ENERGY_MODE=burn) комиссию за свип платит сам адрес приёма, поэтому TRX на него кладёт оператор — и с включённым флагом эти операционные деньги были бы зачислены как чей-то платёж. Сначала правило, отличающее переводы с наших адресов, и тест; потом флаг. Выплаты в TRX не появятся и после: суточные лимиты складывают суммы в одной единице, что верно только для привязанных к доллару активов.
Активы тестовых сетей не изменились: проверяемого контракта USDC в Nile и Shasta нет.

2026-09-12, домен в установщике

POST /setup/domain — панель находит у провайдера DNS зону, которой принадлежит указанное имя, создаёт или исправляет запись A на адрес этого сервера и возвращает то, что видно в публичном DNS прямо сейчас. Проверяется не своя запись, а ответ сети: записанное и видимое — разные утверждения, и работает только второе.
Если зоны у провайдера нет, панель создаёт её сама и показывает NS-серверы, которые нужно прописать у регистратора домена: без делегирования зону не видит никто, какими бы правильными ни были записи в ней. Зона создаётся под регистрируемым именем — последние две метки.
Ответ маршрута говорит, видит ли провайдер делегирование (delegated), создавалась ли зона (zone_created) и какие NS-серверы нужны (nameservers).
Шаг «Домен» стоит первым и необязателен: без домена сервис доступен по адресу сервера. Переменные SETUP_DOMAIN и BUNNY_API_KEY пишет сама панель; ключ провайдера используется только для записи и проверки и обратно не показывается.
Панель первого запуска теперь открывается в браузере по адресу сервера — порт API публикуется на время установки одной переменной и возвращается на loopback после неё (ADR-0025). Маршруты /v1 не изменились.

2026-09-12, установщик записывает конфигурацию сам

Страница первого запуска больше не печатает блок переменных для вставки руками: она записывает файл окружения на сервере — POST /setup/env. Значения проверяются теми же разборщиками, которыми сервис читает конфигурацию при старте, поэтому записанный файл — это файл, с которым сервис запускается. Маршруты /v1 не изменились.
POST /setup/signer-values и GET /setup/signer-env — выбор владельца для сервера подписи и готовый файл окружения для него вместе с командами по порядку. Пароль роли базы и два значения сида в него не попадают: первый уже есть на этом сервере, вторые создаются на том.
Шаги «Сеть и узлы» и «Файл окружения» — новые и обязательные. Второй закрывается только когда значения не просто записаны, но и применены: переменные читаются один раз, при старте.
Секрет, принятый страницей, обратно не отдаётся: в ответе GET /setup/state у него только признак «задано». Пустое поле означает «не менять».
Поле, в которое вставили 12 или 24 коротких слова, отвергается: мнемоника не вводится на этой странице ни в одно поле. Обоснование и границы — в ADR-0024.

2026-09-12, страница первого запуска

Пока настройка сервиса не завершена, API отдаёт страницу GET /setup, которая ведёт по шагам и проверяет каждый. Когда все обязательные шаги закрыты, её маршруты отвечают 404. Мерчантов это не касается: маршруты /v1 не изменились.
Служебные маршруты страницы: GET /setup/state, POST /setup/verify, POST /setup/steps/{key}, POST /setup/merchant. Доступны только из приватной сети и только с одноразовым кодом из лога сервиса. См. первый запуск.
Страница не принимает и не создаёт мнемонику, парольную фразу и приватную половину операторского ключа — обоснование в ADR-0024.

2026-09-12, отправка выплат

События payout.confirmed и payout.failed: выплата подтверждена сетью или её транзакция попала в блок неуспешной. Поля — в вебхуках. Как и раньше, тело вебхука — сигнал «сходи проверь»: состояние выплаты берите из GET /v1/payouts/{id}.
Выплата в failed не повторяется автоматически: новая попытка требует нового reference.
Остальное в этом обновлении внутреннее: подпись выплат с горячего кошелька, вторая независимая проверка вайтлиста вместе с подписью оператора, предохранитель, останавливающий выплаты сам. Публичные маршруты не изменились.

2026-09-12, выплаты

POST /v1/payouts — создание выплаты, идемпотентное по reference. Ответ 202 у созданной выплаты, 200 у повтора. См. выплаты.
GET /v1/payouts/{id} — текущее состояние выплаты с её статусом и причинами ожидания.
Выплата возможна только на адрес из вайтлиста мерчанта и только после задержки перед первым использованием. Переход лимита выплату не отклоняет: она принимается со статусом pending_review и ждёт подтверждения человека, а review_reasons называет перейденные пределы. См. лимиты.
Новые коды ошибок: payout_not_found, reference_conflict, asset_not_payable, address_not_whitelisted, payouts_halted. См. коды ошибок.
Отправка выплат в сеть и события вебхуков payout.confirmed и payout.failed появятся в следующем обновлении: пока выплата доходит до статуса queued и ждёт исполнения.

2026-09-12, свипы

Инвойс доходит до статуса settled: средства по нему перенесены в холодное хранилище. Для мерчанта это то же, что confirmed, вебхука у перехода нет — товар отдаётся на confirmed, как и раньше. См. статусы.
Остальное в этом обновлении внутреннее: подпись и отправка свипов, подтверждение их в цепи и проводки в реестре. Публичные маршруты и события вебхуков не изменились.

2026-09-11, операционные маршруты

GET /admin/health — состояние сервиса для оператора и мониторинга: отставание сканера в блоках и глубина очереди вебхуков. См. операционное состояние.
GET /metrics — те же показатели в текстовом формате Prometheus.
Оба маршрута служебные: аутентификации не требуют, данных мерчантов не содержат и доступны только в приватной сети.

2026-09-11, доставка вебхуков

События из очереди уходят на URL мерчанта с подписью X-Signature и заголовком X-Timestamp, с повторами по расписанию из описания вебхуков. До этого события только записывались.
Заголовок User-Agent исходящих вебхуков содержит название продукта.
Ответ 3xx не считается успешной доставкой и не выполняется.

2026-09-11, сканер платежей

Инвойсы меняют статус по переводам в сети: seen, confirmed, underpaid, expired, paid_late. См. статусы.
В ответе GET /v1/invoices/{id} поле deposits заполняется платежами по инвойсу.
Сервис формирует события вебхуков invoice.seen, invoice.confirmed, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.paid_late, deposit.confirmed и deposit.orphaned. См. события. Отправка событий на URL мерчанта включится в следующем обновлении.

2026-09-11, адреса и инвойсы

Аутентификация по заголовку X-Api-Key и лимиты запросов по ключу и по IP-адресу — см. аутентификацию.
POST /v1/addresses — постоянный адрес пользователя для мерчантов в режиме per_user. См. адреса.
POST /v1/invoices — создание инвойса, идемпотентное по order_id. См. инвойсы.
GET /v1/invoices/{id} — текущее состояние инвойса с его платежами.
GET /v1/openapi.json — машиночитаемое описание API в формате OpenAPI 3.1.
Новые коды ошибок: validation_failed, unauthorized, merchant_disabled, invoice_not_found, address_mode_mismatch, order_id_conflict, asset_not_supported, amount_below_minimum, rate_limited, addresses_exhausted. См. коды ошибок.

2026-09-11, служебные маршруты

Добавлены служебные маршруты GET /healthz и GET /readyz — см. мониторинг.
Введён единый формат ошибок { "error": { "code", "message" } } и коды bad_request, route_not_found, internal_error, service_unavailable — см. коды ошибок.
Каждый ответ содержит заголовок X-Request-Id для поиска запроса в логах.