API биллинга и treasury
Сервисный баланс аккаунта и его пополнение.
Эти endpoints требуют JWT продавца и действуют для аккаунта, а не для платежей покупателей отдельного проекта.
| Метод | Путь | Назначение |
|---|---|---|
| GET | /billing/me | Баланс, ставка и статус аккаунта |
| GET | /billing/ledger?page=1&limit=20 | История баланса с пагинацией |
| POST | /treasury/deposits | Создать намерение пополнения |
| GET | /treasury/deposits | Список пополнений |
| GET | /treasury/deposits/:id | Прочитать пополнение |
| POST | /treasury/deposits/:id/cancel | Отменить PENDING |
Деньги — десятичные строки. Доступные способы пополнения берите из коллекции treasury ответа GET /assets/routes. Кошелёк продавца и маршруты покупательского checkout здесь не используются.
Создание принимает { assetId, amount, idempotencyKey }. Сохраните неизменные тело и ключ до запроса. Неизвестный исход повторяйте с ними же. Повтор может восстановить старое намерение даже после отключения маршрута для новых пополнений. Ответ создания может не содержать связанный asset: перед показом реквизитов прочитайте принадлежащее аккаунту пополнение по ID. Каждый read требует JWT владельца; ID не является секретом доступа.
Отправьте точный expectedAmount один раз на возвращённый адрес, в указанном активе/сети и до expiresAt. Attribution-v3 зачисляет номинальный requestedAmount; добавка нужна для сопоставления. creditedAmount отражает полученный перевод и может отличаться от прибавки к балансу. Исторические v2-пополнения сохраняют расчёт по фактически полученному; не пересчитывайте их.
Маршрут после создания неизменен. EXPIRED скрывает инструкции новой отправки, но своевременный перевод может подтвердиться позднее и стать CREDITED. CANCELLED не зачисляется автоматически. Ошибочные и поздние переводы требуют разбора; найденная транзакция не означает ручное зачисление или возврат.
Поля баланса и тарифа
GET /billing/me возвращает десятичные строки commissionBalance (B), commissionCreditLimit (C), remainingCommission (B+C), commissionDebt, а также creditRevision, status, tierRate, monthlyVolumeUsd, rollingVolumeUsd, billingPolicy (WEEKLY_V2 или LEGACY_V1), activationAt, period, recognitionPolicy: "FEE_POSTING_TIME". period содержит startAt/endAt/windowStartAt/windowEndAt/volumeUsd; без активного недельного периода — null. tierRate может отражать индивидуальный тариф. Объём месяца не равен основе периода.
GET /billing/notifications и PUT /billing/notifications управляют общими напоминаниями. PUT: { "enabled": true, "thresholdUsd": "5" }; порог — положительная десятичная строка до 18 дробных цифр и $1 000 000. Настройки писем не меняют допуск B+C. Реферальные награды имеют отдельную историю /referrals.