> ## Documentation Index
> Fetch the complete documentation index at: https://whalescorp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Справочник 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.

```text theme={null}
{
  "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`

```text theme={null}
{ "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`

```text theme={null}
{ "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 строк.

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

```text theme={null}
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`

```text theme={null}
{ "action": "generate_invoice", "billingPeriod": "2026-03" }
```

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

## `finalize_invoice` / `void_invoice`

```text theme={null}
{ "action": "finalize_invoice", "invoiceId": "uuid" }
{ "action": "void_invoice", "invoiceId": "uuid", "reason": "Wrong period" }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.