# API: sold, licențe, retrageri și facturi

_API · 7 min de citit · Actualizat 2026-10-22 · https://lanachat.ai/guides/ro/api-billing/_

LanaChat se plătește dintr-un **sold** preplătit în dolari americani: din acesta se scad **licențele** (una per cont Telegram, 30 de zile) și o **comision** din vânzările nete. Îl reîncarci cu depozite în criptomonede. Câștigurile din afiliere pot fi **retrase**. Fiecare endpoint de facturare necesită un token de **owner**: în exemple, `$LANACHAT_TOKEN` deține unul.

## Endpoints

| Method | Path | Descriere | Permisiune | Stare |
|---|---|---|---|---|
| GET | `/billing/balance` | Soldul, vânzările nete ale lunii și nivelul comisionului | `owner` | Planned |
| GET | `/billing/ledger` | Toate mișcările: depozite, licențe, comision, rambursări | `owner` | Planned |
| GET | `/billing/ledger.csv` | Același registru în format CSV (`from=`, `to=`) | `owner` | Planned |
| GET | `/billing/deposit-addresses` | O adresă de depozit per blockchain (cu memo pe Solana) | `owner` | Planned |
| GET | `/billing/deposits` | Depozite și confirmările lor | `owner` | Planned |
| GET | `/billing/licences` | Licențe în stoc și atribuite, cu zile rămase | `owner` | Planned |
| POST | `/billing/licences/buy` | Cumpără licențe: individuală sau pachet de 10, 25 sau 50 | `owner` | Planned |
| POST | `/billing/licences/assign` | Atribuie o licență din stoc unui cont | `owner` | Planned |
| POST | `/billing/licences/unassign` | Ia licența înapoi în stoc cu zilele rămase | `owner` | Planned |
| PATCH | `/billing/licences/auto-renew` | Activează sau dezactivează reînnoirea automată pentru un cont | `owner` | Planned |
| GET | `/billing/withdrawals` | Retrageri din afiliere și starea lor | `owner` | Planned |
| POST | `/billing/withdrawals` | Cere o retragere a câștigurilor din afiliere (de la $500) | `owner` | Planned |
| GET | `/billing/invoices` | Declarații lunare (`year=`) | `owner` | Planned |
| GET | `/billing/invoices/{id}.pdf` | O declarație în format PDF | `owner` | Planned |
| PUT | `/billing/details` | Numele companiei, adresă și cod TVA pe declarații | `owner` | Planned |

## Prețuri într-un tabel

| Ce | Preț |
|---|---|
| O licență (un cont Telegram, 30 zile) | $19 |
| Pachet de 10 licențe | $170 |
| Pachet de 25 licențe | $375 |
| Pachet de 50 licențe | $650 |
| Comision până la $30k vânzări nete în lună | 12% din vânzările AI, 4% din cele manuale |
| Comision de la $30k la $100k | 10% și 3% |
| Comision peste $100k | 8% și 2% |

Contorul este vânzarea netă a întregului workspace în luna calendaristică; se resetează pe 1. Telegram Stars contează ca $0.013 fiecare în vânzări nete.

## Obiectul sold

```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
}
```

| Câmp | Tip | Descriere |
|---|---|---|
| `balance_cents` | integer | Soldul preplătit, în cenți USD |
| `month` | string | Luna calendaristică calculată, `YYYY-MM` |
| `net_sales_cents` | integer | Vânzările nete ale workspace-ului în această lună |
| `tier` | object | Nivelul curent: plafonul `up_to_cents`, rata AI și rata manuală în puncte de bază |
| `licences` | object | Licențe `in_stock`, `assigned` și cele atribuite care expiră în 7 zile (`expiring_7d`) |
| `low_balance` | boolean | `true` când soldul nu acoperă următoarele 7 zile de licențe |

Ratele sunt în puncte de bază: `1200` înseamnă 12%.

## Obiectul intrării în registru

Fiecare linie din **Billing › Activity** în Console.

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

| Câmp | Tip | Descriere |
|---|---|---|
| `id` | string | Linia |
| `at` | string | ISO 8601, UTC |
| `kind` | string | `deposit`, `licences`, `commission`, `refund`, `affiliate` sau `other` |
| `label` | string | Textul liniei, ca în Console |
| `amount_cents` | integer | Pozitiv când intră bani, negativ când ies |
| `balance_after_cents` | integer | Soldul după această linie |

O linie `commission` aparține unei vânzări: Console arată fanul, nivelul, cine a trimis oferta (AI sau manual), cum s-a calculat netul ("12,500 ★ × $0.013") și rata.

## Obiectul depozitului

```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"
}
```

| Câmp | Tip | Descriere |
|---|---|---|
| `id` | string | Depozitul |
| `at` | string | Când a fost văzut, ISO 8601 |
| `chain` | string | `usdc-eth`, `usdc-sol`, `usdt-sol`, `usdt-tron` sau `usdt-eth` |
| `sent_cents`, `fee_cents`, `credited_cents` | integer | Ce ai trimis, taxa, ce ajunge în sold |
| `status` | string | `pending` apoi `confirmed` |
| `confirmations` | string | Confirmările din rețea, cât timp e în așteptare |

USDC pe Ethereum este creditat 1:1 fără taxă. Orice alt blockchain are o taxă de 1%: depozitul se convertește în USDC (ERC20) la sosire. Minim $25 per reîncărcare.

## Obiectul licenței

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

| Câmp | Tip | Descriere |
|---|---|---|
| `account_id` | string | Contul Telegram pe care rulează licența |
| `creator_id` | string | Creatoarea ei |
| `days_left` | integer | Zile rămase până expiră, din 30 |
| `expires_at` | string | Când expiră |
| `auto_renew` | boolean | Reînnoiește din stoc (sau cumpără o licență individuală) când expiră |

Licențele din stoc sunt numărate, nu listate individual: fiecare păstrează zilele rămase (30 pentru una nouă).

## Obiectul retragerii

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

| Câmp | Tip | Descriere |
|---|---|---|
| `id` | string | Retragerea |
| `status` | string | `pending_review`, `sent` (cu `tx_hash`) sau `rejected` cu motiv |
| `amount_cents` | integer | Sumă cerută, cel puțin 50000 ($500) |
| `requested_at` | string | ISO 8601, UTC |
| `tx_hash` | string sau null | Tranzacția, odată trimisă |

## Obiectul facturii

```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"
}
```

| Câmp | Tip | Descriere |
|---|---|---|
| `id` | string | Numărul declarației, `LC-YYYY-MM` |
| `month` | string | Luna acoperită |
| `licences_cents`, `commission_cents`, `total_cents` | integer | Licențe, comision și totalul lunii |
| `status` | string | Plătit, în curs (luna curentă) sau eșuat |
| `pdf_url` | string | PDF-ul declarației |

## Sold și registru

### Obține soldul

`GET /billing/balance` · `owner`

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

Răspunsul este obiectul sold.

### Listează registrul

`GET /billing/ledger` · `owner`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `from`, `to` | string | Nu | Zile `YYYY-MM-DD`, UTC, ambele incluse |
| `limit`, `cursor` | number, string | Nu | [Paginare](https://lanachat.ai/guides/ro/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"
}
```

### Exportă registrul ca CSV

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

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `from`, `to` | string | Nu | Zile `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
```

Aceleași linii ca la **Export CSV** în **Billing › Activity**, gata pentru contabilul tău.

## Depozite

### Obține adresele de depozit

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

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

Răspunsul oferă o adresă per blockchain (Ethereum, Solana, Tron) și, pentru Solana, memo-ul.

> Warning: Pe Solana, un depozit trimis fără memo nu poate fi asociat workspace-ului tău. Trimite întotdeauna atât adresa, cât și memo-ul.

Poți trimite USDC pe Ethereum (ERC20), USDC pe Solana, USDT pe Solana, USDT pe Tron (TRC20) sau USDT pe Ethereum (ERC20). Taxa de rețea a transferului este plătită din portofelul tău.

### Listează depozitele

`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
}
```

Soldul este creditat automat când un depozit este `confirmed`; acesta devine și o linie `deposit` în registru.

## Licențe

### Listează licențele

`GET /billing/licences` · `owner`

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

Răspunsul oferă licențele în stoc și un obiect licență per cont atribuit, cu zilele rămase.

### Cumpără licențe

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

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `pack` | integer | Da | `1` (individuală, $19), `10` ($170), `25` ($375) sau `50` ($650) |
| `qty` | integer | Da | Câte pachete din acel tip |

```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" }
```

Licențele intră imediat în stocul tău. Un sold prea mic răspunde cu `402` (`insufficient_balance`). Licențele în stoc nu expiră niciodată, iar cele cumpărate nu sunt rambursabile.

### Atribuie o licență

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

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `account_id` | string | Da | Contul Telegram care primește licența |

```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"}'
```

Răspunsul este obiectul licență al contului. Licența din stoc cu cele mai puține zile rămase este folosită prima: zilele rămase ale acesteia sau 30 dacă e nouă. Reînnoirea automată este activată implicit.

### Ia o licență înapoi

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

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `account_id` | string | Da | Contul care returnează licența |

```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"}'
```

Licența revine în stoc cu zilele rămase. AI încetează să răspundă pe acel cont imediat. Pentru a muta o licență la alt cont, ia-o înapoi, apoi atribuie-o: păstrează zilele, gratuit.

### Activează sau dezactivează reînnoirea automată

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

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `account_id` | string | Da | Contul |
| `auto_renew` | boolean | Da | `true` pentru a reînnoi când zilele expiră |

```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}'
```

Când zilele expiră, reînnoirea automată ia mai întâi o licență din stoc sau cumpără o licență individuală ($19) dacă stocul este gol. Nu poate cumpăra fără sold: urmărește `low_balance` sau webhook-ul `billing.low_balance` [webhook](https://lanachat.ai/guides/ro/api-webhooks/).

## Retrageri din afiliere

### Listează retragerile

`GET /billing/withdrawals` · `owner`

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

O listă de obiecte retragere, cele mai noi primele.

### Cere o retragere

`POST /billing/withdrawals` · `owner`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `amount_cents` | integer | Da | Cel puțin 50000 ($500), maxim suma disponibilă pentru retragere |

```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 }
```

Câștigurile sunt trimise în USDC către portofelul înregistrat, la 7 zile după încheierea lunii. Se pot retrage doar câștigurile din afiliere, niciodată soldul preplătit. Cererile sub $500 sunt refuzate.

## Declarații

### Listează declarațiile

`GET /billing/invoices` · `owner`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `year` | integer | Nu | De exemplu `2026` |

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

Un obiect factură per lună.

### Descarcă o declarație

`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: Verifică-ți declarațiile. O eroare de facturare trebuie raportată în termen de 60 de zile de la declarația care o arată; după aceea, declarația este finală.

### Setează detaliile de facturare

`PUT /billing/details` · `owner`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `company` | string | Nu | Numele companiei |
| `email` | string | Nu | E-mail de facturare |
| `address`, `city`, `postal`, `country` | string | Nu | Adresa poștală |
| `vat` | string | Nu | Cod TVA |

```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"}'
```

Aceleași câmpuri ca în **Billing › Billing details**. Declarațiile conțin aceste detalii. `PUT` le înlocuiește pe toate: un câmp omis este golit.

## Articole conexe

- [API LanaChat: început rapid, autentificare și erori](https://lanachat.ai/guides/ro/api-overview/)
- [Facturare: licențe, comision și sold](https://lanachat.ai/guides/ro/billing/)