# Баланс

Баланс один на аккаунт, с него списываются запросы всех ключей. Баланс и историю операций
читает [ключ управления](https://souz.ai/docs/management-key.md). Обычный API-ключ баланса не видит и о нехватке
узнаёт по ответу `402`.

```bash tab="cURL"
curl https://api.souz.ai/v1/balance \
  -H "Authorization: Bearer $SOUZ_MANAGEMENT_KEY"
```

```python tab="Python"
import os
import httpx

balance = httpx.get(
    "https://api.souz.ai/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_MANAGEMENT_KEY']}"},
).json()
print(balance["spendable_micro"] / 1_000_000)
```

```ts tab="TypeScript"
const res = await fetch("https://api.souz.ai/v1/balance", {
  headers: { Authorization: `Bearer ${process.env.SOUZ_MANAGEMENT_KEY}` },
});
const balance = await res.json();
console.log(balance.spendable_micro / 1_000_000);
```

<!-- openapi: #/components/schemas/BalanceResponse -->
```json
{
  "available_micro": 482500000,
  "overdraft_limit_micro": 0,
  "spendable_micro": 470100000,
  "spent_total_micro": 1250000000,
  "currency": "RUB",
  "mock_topup": false
}
```

## Поля баланса

| Поле | Что значит |
|---|---|
| `available_micro` | Зачисленное минус списания за завершённые запросы. |
| `overdraft_limit_micro` | Согласованный лимит овердрафта, `0` если его нет. |
| `spendable_micro` | Доступно для новых запросов: баланс плюс овердрафт минус занятое выполняющимися запросами. |
| `spent_total_micro` | Сумма списаний за всё время, обновляется в течение минуты. |
| `currency` | Валюта сумм, `RUB`. |
| `mock_topup` | Тестовое пополнение на сервере; в рабочем API всегда `false`. |

Без овердрафта баланс не становится отрицательным. С овердрафтом `available_micro` уходит в
минус не дальше `overdraft_limit_micro`, следующее пополнение гасит долг. Итог больше
остатка описан в [Цены и списание](https://souz.ai/docs/pricing.md).

## Пополните баланс

Пополняют владелец и администратор в кабинете, через API баланс не пополняется. Зачисляется
вся оплаченная сумма, комиссию платёжной системы платит Союз. Чеки и возврат описаны на
странице [Команда](https://souz.ai/docs/account.md).

Бонусы списываются первыми. Бонус — объём со скидкой 100%, а не деньги, и он не
возвращается.

## Прочитайте историю операций

`GET /v1/balance/history` возвращает операции, новые первыми. `?kind=` оставляет один вид
операций, страницы листаются по `limit` и `before` (см. [Запросы и ответы](https://souz.ai/docs/conventions.md)).

```bash
curl "https://api.souz.ai/v1/balance/history?limit=2" \
  -H "Authorization: Bearer $SOUZ_MANAGEMENT_KEY"
```

<!-- openapi: #/components/schemas/BalanceHistoryResponse -->
```json
{
  "currency": "RUB",
  "items": [
    {
      "id": "job_abc123",
      "kind": "charge",
      "amount_micro": 3900000,
      "created_at": "2026-10-15T12:00:00Z",
      "job_id": "job_abc123",
      "canonical_model": "nano-banana-2",
      "modality": "image",
      "api_key_name": "production",
      "api_key_kind": "user"
    },
    {
      "id": "dep_42",
      "kind": "deposit",
      "source": "payment",
      "amount_micro": 1000000000,
      "created_at": "2026-10-14T09:00:00Z",
      "topup": {
        "remaining_micro": 482500000,
        "refunded_micro": 0,
        "refund_pending_micro": 0,
        "reversed_micro": 0,
        "method": "sbp",
        "receipt_url": "https://souz.ai/receipts/dep_42"
      }
    }
  ],
  "next_before": "1758600000123456.4211"
}
```

Суммы приходят без знака, направление задаёт `kind`:

| `kind` | Операция | Баланс |
|---|---|---|
| `deposit` | Пополнение. `source`: `payment` — оплата, `bonus` — бонус. | растёт |
| `charge` | Одно списание за успешный запрос по фактической цене, запрос в `job_id`. | уменьшается |
| `refund` | Возврат остатка через поддержку. | уменьшается |
| `reversal` | Отмена начисления поддержкой, в `source` что отменено. Баланс не уходит в минус. | уменьшается |

Объект `topup` пополнения показывает, что стало с деньгами:

| Поле | Что значит |
|---|---|
| `remaining_micro` | Остаток, включая сумму к возврату. |
| `refunded_micro` | Уже возвращено. |
| `refund_pending_micro` | Часть остатка, удержанная для возврата. |
| `reversed_micro` | Отменено поддержкой; это не расход и не возврат. |
| `receipt_url` | Ссылка на чек, когда он доступен. |
| `method` | `card`, `sbp` или `other`, появляется в течение минуты после оплаты. |

Бонус от поддержки подписан `label`: `topup_bonus`, `compensation` (запрос в `job_id`) или
`bonus`. Приветственный бонус и бонус по приглашению идут без `label`.

## Посмотрите расходы по запросам

Чтобы разобрать расход по запросам, используйте учёт расходов:

| Метод | Что возвращает |
|---|---|
| `GET /v1/usage` | Запросы, новые первыми, с фильтрами по модели, ключу и статусу. Все фильтры — в справочнике API. |
| `GET /v1/usage/summary` | Расход по дням (`days`, до 365) или часам (`bucket=hour`, до 48) и топ моделей. |
| `GET /v1/usage/{id}` | Один запрос: цена, параметры, результат и ошибка. |

Разработчик видит только запросы своих ключей, остальные роли — все запросы аккаунта.

## Аккаунт без баланса

Если в `GET /v1/auth/me` стоит `has_balance: false`, расход учитывается по факту в
`GET /v1/usage`, а баланс, история и пополнение недоступны. Лимиты трат ключей и участников
действуют как обычно.

| Код | Когда | Что делать |
|---|---|---|
| `403 account_without_balance` | Баланс, история или пополнение у аккаунта без баланса. | Смотрите расход в `GET /v1/usage`. |
| `403 forbidden`, `reason: requires_management_key` | Баланс запрошен обычным API-ключом. | Используйте [ключ управления](https://souz.ai/docs/management-key.md). |

**Дальше**

- [Цены и списание](https://souz.ai/docs/pricing.md) — как считается итог.
- [Ключ управления](https://souz.ai/docs/management-key.md) — доступ к балансу из скрипта.
- [Команда](https://souz.ai/docs/account.md) — пополнение, бонусы и возврат.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.