Справочник API

Все billing-действия выполняются через POST /api/instance-admin с использованием instance JWT или platform admin JWT.

​

Матрица аутентификации

Действие	Минимальная роль	Secure session
get_revenue	finance	No
list_fee_ledger	finance	No
export_revenue_csv	finance	No
list_invoices	finance	No
get_invoice	finance	No
generate_invoice	admin	Yes
finalize_invoice	admin	Yes
void_invoice	admin	Yes
list_settlements (planned)	finance	No
generate_settlement (planned)	admin	Yes
mark_settlement_paid (planned)	admin	Yes
list_rebates (planned)	finance	No

​

get_revenue

Возвращает сводку по выручке для instance.

{
  "summary": [
    { "fee_type": "creation", "collection_status": "collected", "count": 47, "total_fee": "39.95", "total_gross": "1997.50" }
  ],
  "byMerchant": [
    { "merchant_id": "...", "merchant_name": "Acme Corp", "fee_count": 12, "collected": "10.20", "pending": "0.85" }
  ]
}

​

list_fee_ledger

{ "action": "list_fee_ledger", "status": "pending", "page": 1, "pageSize": 50 }

Возвращает { rows, total, page, pageSize }. В каждой строке: id, fee_type, collection_status, fee_amount, gross_amount, billing_period, created_at, merchant_slug.

​

export_revenue_csv

{ "action": "export_revenue_csv", "dateFrom": "2026-01-01", "dateTo": "2026-03-31" }

CSV-колонки: id, fee_type, collection_status, fee_amount, gross_amount, billing_period, created_at, merchant_slug, merchant_name. Максимум 10,000 строк.

Скачивание на стороне клиента:

const blob = new Blob([data.csv], { type: "text/csv" });
const a = Object.assign(document.createElement("a"), {
  href: URL.createObjectURL(blob),
  download: `revenue-export-${new Date().toISOString().slice(0, 10)}.csv`,
});
a.click();

​

generate_invoice

{ "action": "generate_invoice", "billingPeriod": "2026-03" }

Ошибки: 409 при дублирующемся периоде, 422 если нет собранных комиссий.

​

finalize_invoice / void_invoice

{ "action": "finalize_invoice", "invoiceId": "uuid" }
{ "action": "void_invoice", "invoiceId": "uuid", "reason": "Wrong period" }