# API: баланс, ліцензії, виведення коштів та рахунки

_API · Читання 7 хв · Оновлено 2026-10-22 · https://lanachat.ai/guides/uk/api-billing/_

LanaChat оплачується з одного передплаченого **балансу** в доларах США: з нього списуються **ліцензії** (одна на акаунт Telegram, 30 днів) та **комісія** з чистих продажів. Ви поповнюєте баланс криптовалютними депозитами. Партнерські заробітки можна **виводити**. Для кожного billing endpoint потрібен токен **owner**: у прикладах `$LANACHAT_TOKEN` його містить.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/billing/balance` | Баланс, чисті продажі за цей місяць та рівень комісії | `owner` | Planned |
| GET | `/billing/ledger` | Всі рухи: депозити, ліцензії, комісія, повернення | `owner` | Planned |
| GET | `/billing/ledger.csv` | Той самий журнал у CSV (`from=`, `to=`) | `owner` | Planned |
| GET | `/billing/deposit-addresses` | Одна адреса депозиту на кожен блокчейн (з memo для Solana) | `owner` | Planned |
| GET | `/billing/deposits` | Депозити та їх підтвердження | `owner` | Planned |
| GET | `/billing/licences` | Ліцензії на складі та призначені, з кількістю днів до кінця | `owner` | Planned |
| POST | `/billing/licences/buy` | Купити ліцензії: одну або пакети по 10, 25 чи 50 | `owner` | Planned |
| POST | `/billing/licences/assign` | Призначити ліцензію з наявних акаунту | `owner` | Planned |
| POST | `/billing/licences/unassign` | Повернути ліцензію на склад з її залишком днів | `owner` | Planned |
| PATCH | `/billing/licences/auto-renew` | Увімкнути або вимкнути автооновлення для акаунту | `owner` | Planned |
| GET | `/billing/withdrawals` | Виведення партнерських коштів та їх статус | `owner` | Planned |
| POST | `/billing/withdrawals` | Запит на виведення партнерських заробітків (від $500) | `owner` | Planned |
| GET | `/billing/invoices` | Місячні звіти (`year=`) | `owner` | Planned |
| GET | `/billing/invoices/{id}.pdf` | Один звіт у PDF | `owner` | Planned |
| PUT | `/billing/details` | Назва компанії, адреса та VAT у звітах | `owner` | Planned |

## Ціни в одній таблиці

| Що | Ціна |
|---|---|
| Одна ліцензія (один акаунт Telegram, 30 днів) | $19 |
| Пакет з 10 ліцензій | $170 |
| Пакет з 25 ліцензій | $375 |
| Пакет з 50 ліцензій | $650 |
| Комісія до $30 тис чистих продажів за місяць | 12% від AI-продажів, 4% від ручних продажів |
| Комісія від $30 тис до $100 тис | 10% та 3% |
| Комісія понад $100 тис | 8% та 2% |

Лічильник, це чисті продажі всього робочого простору за календарний місяць; обнуляється 1-го числа. Telegram Stars рахується по $0.013 за штуку в чистих продажах.

## Об’єкт балансу

```json
{
  "balance_cents": 48210,
  "month": "2026-10",
  "net_sales_cents": 1870400,
  "tier": { "up_to_cents": 3000000, "ai_rate_bp": 1200, "manual_rate_bp": 300 },
  "licences": { "in_stock": 4, "assigned": 11, "expiring_7d": 2 },
  "low_balance": false
}
```

| Поле | Тип | Опис |
|---|---|---|
| `balance_cents` | integer | Передплачений баланс у центрах долара США |
| `month` | string | Календарний місяць у форматі `YYYY-MM` |
| `net_sales_cents` | integer | Чисті продажі робочого простору за цей місяць |
| `tier` | object | Поточний рівень: верхня межа `up_to_cents`, ставки AI та ручних продажів у базисних пунктах |
| `licences` | object | Ліцензії на складі `in_stock`, призначені `assigned` та ті, що закінчуються за 7 днів (`expiring_7d`) |
| `low_balance` | boolean | `true`, якщо балансу не вистачає на наступні 7 днів ліцензій |

Ставки в базисних пунктах: `1200` = 12%.

## Об’єкт запису журналу

Кожен рядок у **Billing › Activity** в Консолі.

```json
{
  "id": "led_90211",
  "at": "2026-10-06T14:40:00Z",
  "kind": "licences",
  "label": "Licences · pack of 10",
  "amount_cents": -17000,
  "balance_after_cents": 31210
}
```

| Поле | Тип | Опис |
|---|---|---|
| `id` | string | Ідентифікатор рядка |
| `at` | string | ISO 8601, UTC |
| `kind` | string | `deposit`, `licences`, `commission`, `refund`, `affiliate` або `other` |
| `label` | string | Текст рядка, як у Консолі |
| `amount_cents` | integer | Позитивне, коли надходять гроші, негативне, коли списуються |
| `balance_after_cents` | integer | Баланс після цього рядка |

Рядок `commission` належить одному продажу: у Консолі показано фаната, рівень, хто надіслав пропозицію (AI чи вручну), як рахували чистий дохід ("12,500 ★ × $0.013") та ставку.

## Об’єкт депозиту

```json
{
  "id": "dep_4",
  "at": "2026-10-06T13:52:00Z",
  "chain": "usdt-tron",
  "sent_cents": 100000,
  "fee_cents": 1000,
  "credited_cents": 99000,
  "status": "pending",
  "confirmations": "12/19"
}
```

| Поле | Тип | Опис |
|---|---|---|
| `id` | string | Ідентифікатор депозиту |
| `at` | string | Час фіксації, ISO 8601 |
| `chain` | string | `usdc-eth`, `usdc-sol`, `usdt-sol`, `usdt-tron` або `usdt-eth` |
| `sent_cents`, `fee_cents`, `credited_cents` | integer | Надіслано, комісія, зараховано на баланс |
| `status` | string | `pending` або `confirmed` |
| `confirmations` | string | Підтвердження мережі під час очікування |

USDC на Ethereum зараховується 1:1 без комісії. Інші мережі мають комісію 1%: депозит конвертується в USDC (ERC20) при надходженні. Мінімум для поповнення, $25.

## Об’єкт ліцензії

```json
{
  "account_id": "acc_1001",
  "creator_id": "cr_lea",
  "days_left": 18,
  "expires_at": "2026-10-24T09:00:00Z",
  "auto_renew": true
}
```

| Поле | Тип | Опис |
|---|---|---|
| `account_id` | string | Telegram акаунт, на якому діє ліцензія |
| `creator_id` | string | Її авторка |
| `days_left` | integer | Кількість днів до закінчення з 30 |
| `expires_at` | string | Дата закінчення |
| `auto_renew` | boolean | Автоматичне поновлення з наявних ліцензій або купівля одиночної при закінченні |

Ліцензії на складі рахуємо, не перераховуємо поштучно: кожна має свій залишок днів (30 для нової).

## Об’єкт виведення коштів

```json
{ "id": "wd_118", "status": "pending_review", "amount_cents": 50000, "requested_at": "2026-10-06T15:00:00Z", "tx_hash": null }
```

| Поле | Тип | Опис |
|---|---|---|
| `id` | string | Ідентифікатор виведення |
| `status` | string | `pending_review`, `sent` (з `tx_hash`) або `rejected` з причиною |
| `amount_cents` | integer | Запитана сума, не менше 50000 ($500) |
| `requested_at` | string | ISO 8601, UTC |
| `tx_hash` | string або null | Транзакція після відправлення |

## Об’єкт рахунку

```json
{
  "id": "LC-2026-09",
  "month": "2026-09",
  "licences_cents": 22800,
  "commission_cents": 930000,
  "total_cents": 952800,
  "status": "paid",
  "pdf_url": "https://api.lanachat.ai/v1/billing/invoices/LC-2026-09.pdf"
}
```

| Поле | Тип | Опис |
|---|---|---|
| `id` | string | Номер звіту, `LC-YYYY-MM` |
| `month` | string | Місяць, який охоплює |
| `licences_cents`, `commission_cents`, `total_cents` | integer | Ліцензії, комісія та загальна сума за місяць |
| `status` | string | Оплачено, в процесі (поточний місяць) або неуспішно |
| `pdf_url` | string | PDF звіту |

## Баланс і журнал

### Отримати баланс

`GET /billing/balance` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/balance \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Відповідь, це об’єкт балансу.

### Переглянути журнал

`GET /billing/ledger` · `owner`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `from`, `to` | string | Ні | Дні у форматі `YYYY-MM-DD`, UTC, включно |
| `limit`, `cursor` | number, string | Ні | [Пагінація](https://lanachat.ai/guides/uk/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/billing/ledger?from=2026-10-01&to=2026-10-06" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "led_90211", "at": "2026-10-06T14:40:00Z", "kind": "licences", "label": "Licences · pack of 10", "amount_cents": -17000, "balance_after_cents": 31210 },
    { "id": "led_90207", "at": "2026-10-06T13:20:00Z", "kind": "commission", "label": "Lea · Marco", "amount_cents": -468, "balance_after_cents": 48210 },
    { "id": "led_90150", "at": "2026-10-05T09:02:00Z", "kind": "deposit", "label": "Deposit · USDC on Ethereum", "amount_cents": 300000, "balance_after_cents": 48678 }
  ],
  "next_cursor": "eyJpZCI6ImxlZF85MDE0OSJ9"
}
```

### Експортувати журнал у CSV

`GET /billing/ledger.csv` · `owner`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `from`, `to` | string | Ні | Дні у форматі `YYYY-MM-DD`, UTC |

```bash
curl "https://api.lanachat.ai/v1/billing/ledger.csv?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $LANACHAT_TOKEN" -o ledger-2026-09.csv
```

Ті самі рядки, що й у **Export CSV** в **Billing › Activity**, готові для вашого бухгалтера.

## Депозити

### Отримати адреси депозитів

`GET /billing/deposit-addresses` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/deposit-addresses \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Відповідь містить по одній адресі на кожен блокчейн (Ethereum, Solana, Tron) і memo для Solana.

> Warning: На Solana депозит без memo не можна прив’язати до вашого робочого простору. Завжди надсилайте і адресу, і memo.

Ви можете надсилати USDC на Ethereum (ERC20), USDC на Solana, USDT на Solana, USDT на Tron (TRC20) або USDT на Ethereum (ERC20). Мережеву комісію за переказ сплачуєте зі свого гаманця.

### Переглянути депозити

`GET /billing/deposits` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/deposits \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "dep_4", "at": "2026-10-06T13:52:00Z", "chain": "usdt-tron", "sent_cents": 100000, "fee_cents": 1000, "credited_cents": 99000, "status": "pending", "confirmations": "12/19" },
    { "id": "dep_3", "at": "2026-10-05T09:02:00Z", "chain": "usdc-eth", "sent_cents": 300000, "fee_cents": 0, "credited_cents": 300000, "status": "confirmed", "confirmations": null }
  ],
  "next_cursor": null
}
```

Баланс зараховується автоматично, коли депозит `confirmed`; це також рядок `deposit` у журналі.

## Ліцензії

### Переглянути ліцензії

`GET /billing/licences` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/licences \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Відповідь містить ліцензії на складі та по одному об’єкту ліцензії на кожен призначений акаунт з кількістю днів до кінця.

### Купити ліцензії

`POST /billing/licences/buy` · `owner`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `pack` | integer | Так | `1` (одна, $19), `10` ($170), `25` ($375) або `50` ($650) |
| `qty` | integer | Так | Кількість таких пакетів |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/buy \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"pack": 10, "qty": 1}'
```

```json
{ "licences_added": 10, "amount_cents": 17000, "balance_cents": 31210, "ledger_id": "led_90211" }
```

Ліцензії одразу потрапляють на ваш склад. Якщо баланс замалий, відповідь буде `402` (`insufficient_balance`). Ліцензії на складі не мають терміну дії, куплені ліцензії не повертаються.

### Призначити ліцензію

`POST /billing/licences/assign` · `owner`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `account_id` | string | Так | Telegram акаунт, якому призначають ліцензію |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/assign \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_1001"}'
```

Відповідь, це об’єкт ліцензії акаунту. Спочатку використовується ліцензія зі складу з найменшим залишком днів: її залишок або 30 днів, якщо нова. Автооновлення увімкнено за замовчуванням.

### Повернути ліцензію

`POST /billing/licences/unassign` · `owner`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `account_id` | string | Так | Акаунт, що повертає ліцензію |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/unassign \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_1001"}'
```

Ліцензія повертається на склад з її залишком днів. AI одразу припиняє відповідати на цьому акаунті. Щоб перенести ліцензію на інший акаунт, спочатку поверніть її, потім призначте знову: вона збереже свої дні безкоштовно.

### Увімкнути або вимкнути автооновлення

`PATCH /billing/licences/auto-renew` · `owner`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `account_id` | string | Так | Акаунт |
| `auto_renew` | boolean | Так | `true` для поновлення при закінченні днів |

```bash
curl -X PATCH https://api.lanachat.ai/v1/billing/licences/auto-renew \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_1001", "auto_renew": false}'
```

Коли дні закінчуються, автооновлення спочатку бере ліцензію зі складу або купує одиночну ($19), якщо склад порожній. Купівля без балансу неможлива: слідкуйте за `low_balance` або webhook `billing.low_balance` [webhook](https://lanachat.ai/guides/uk/api-webhooks/).

## Партнерські виведення коштів

### Переглянути виведення

`GET /billing/withdrawals` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/withdrawals \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Список об’єктів виведення, новіші зверху.

### Запит на виведення

`POST /billing/withdrawals` · `owner`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `amount_cents` | integer | Так | Не менше 50000 ($500), не більше доступного для виведення |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/withdrawals \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 50000}'
```

```json
{ "id": "wd_118", "status": "pending_review", "amount_cents": 50000, "requested_at": "2026-10-06T15:00:00Z", "tx_hash": null }
```

Заробіток надсилається у USDC на гаманець, вказаний у файлі, через 7 днів після закінчення місяця. Виводити можна лише партнерські заробітки, а не передплачений баланс. Запит менше $500 відхиляється.

## Звіти

### Переглянути звіти

`GET /billing/invoices` · `owner`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `year` | integer | Ні | Наприклад, `2026` |

```bash
curl "https://api.lanachat.ai/v1/billing/invoices?year=2026" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Один об’єкт рахунку на місяць.

### Завантажити звіт

`GET /billing/invoices/{id}.pdf` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/invoices/LC-2026-09.pdf \
  -H "Authorization: Bearer $LANACHAT_TOKEN" -o LC-2026-09.pdf
```

> Warning: Перевіряйте свої звіти. Помилки в білінгу потрібно повідомляти протягом 60 днів від дати звіту, де вона виявлена; після цього звіт вважається остаточним.

### Встановити дані для білінгу

`PUT /billing/details` · `owner`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `company` | string | Ні | Назва компанії |
| `email` | string | Ні | Електронна пошта для білінгу |
| `address`, `city`, `postal`, `country` | string | Ні | Поштова адреса |
| `vat` | string | Ні | VAT номер |

```bash
curl -X PUT https://api.lanachat.ai/v1/billing/details \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company": "Mia Agency Ltd", "email": "billing@mia-agency.com", "address": "12 Market Street", "city": "Dublin", "postal": "D02 X285", "country": "IE", "vat": "IE1234567T"}'
```

Ті самі поля, що й у **Billing › Billing details**. Звіти містять ці дані. `PUT` замінює всі поля: пропущене поле очищується.

## Пов’язані статті

- [LanaChat API: швидкий старт, автентифікація та помилки](https://lanachat.ai/guides/uk/api-overview/)
- [Оплата: ліцензії, комісія та баланс](https://lanachat.ai/guides/uk/billing/)