<!-- /docs/billing (ru) -->

# Биллинг

Все суммы — в франках (₣): внутренней учётной единице платформы (1₣ = 1 ₽ при расчётном курсе). Франк — не валюта и не платёжный инструмент.

## Как устроен цикл списания

1. **Резерв (hold)** — при запуске операции стоимость резервируется на балансе (`reserved`).
2. **Выполнение** — задача выполняется у провайдера.
3. **Списание (confirm)** — по факту списывается реальное потребление; если провайдер вернул меньше — излишек резерва автоматически возвращается.
4. **Возврат (refund)** — при ошибке резерв возвращается полностью.

Типы транзакций в журнале: `topup` (пополнение), `reservation`, `confirm`, `refund`; `debit` — редкие легаси-строки.

## Эндпоинты

| Что | Эндпоинт |
|---|---|
| Баланс | `GET /v1/billing/balance` |
| Тарифный план | `GET /v1/billing/tariff` |
| Транзакции | `GET /v1/billing/transactions` |
| Выписка CSV | `GET /v1/billing/transactions/export?format=csv` |
| Расход по дням | `GET /v1/billing/usage/daily` |
| Витрина цен | `GET /v1/billing/pricing/catalog` |
| Оценка стоимости | `POST /v1/billing/pricing/estimate` |
| Пополнение (ссылка на оплату) | `POST /v1/billing/payment/link` (Idempotency-Key) |
| История пополнений | `GET /v1/billing/payment/history` |
| Счета юрлицам | `POST/GET /v1/billing/legal-invoices/*` |

## Транзакции

Постраничный журнал с фильтрами:

```bash
curl -H "X-API-Key: $FRANKLAB_KEY" \
  "https://apergrex.ru/franklab/api/v1/billing/transactions?type=confirm&page=1&limit=50"
```

Параметры: `type` (topup/reservation/confirm/refund/debit), `attribution` (all/company/personal — чьи пополнения включать), `dateFrom`/`dateTo` (ISO 8601), `page` (≥1), `limit` (1–100, по умолчанию 20). CSV-выгрузка принимает те же фильтры и отдаёт до 10 000 строк; при превышении — последняя строка-комментарий `# truncated: …` с полным количеством.

## Пополнение

`POST /v1/billing/payment/link` с обязательным заголовком `Idempotency-Key` (до 128 символов) создаёт ссылку на оплату картой через T-Bank. Повторный вызов с тем же ключом возвращает ту же ссылку, пока платёж не завершён отказом — новый заказ у банка не создаётся.

Фискальный чек (54-ФЗ) формируется автоматически на email аккаунта партнёра, от имени которого выпущен API-ключ, и уходит в платёжный терминал вместе с запросом Init — отдельно передавать адрес плательщика не нужно и нельзя.

## Тарифы

Тарифный уровень применяется автоматически по накопленному расходу (lifetime-спенд):

| Уровень | Скидка от базовой цены | Порог |
|---|---|---|
| BASE | — | — |
| PRO | 12.5% | > 5 000 ₣ |
| MAX | 25% | > 15 000 ₣ |
| ULTRA | 35% | > 50 000 ₣ |

Достигнутый уровень не понижается. Текущий план и прогресс до следующего уровня — `GET /v1/billing/tariff`; точная цена под вашим тарифом — `POST /v1/billing/pricing/estimate`.

## Оценка стоимости

Оценка учитывает ваш тариф, параметры модели и промо-окна. Никаких побочных эффектов: оценка не резервирует средства и не создаёт задач.

```bash
curl -X POST -H "X-API-Key: $FRANKLAB_KEY" -H "Content-Type: application/json" \
  -d '{"modelId":"mars-v1-5","duration":5,"resolution":"720p","operation":"text_to_video"}' \
  https://apergrex.ru/franklab/api/v1/billing/pricing/estimate
```

Для моделей с референсами передавайте счётчики (`referenceImageCount` и т.п.) — сами URL не нужны, они появляются только при запуске.