# API: saldo, licenze, prelievi e fatture

_API · 7 min di lettura · Aggiornato 2026-10-22 · https://lanachat.ai/guides/it/api-billing/_

LanaChat si paga da un unico **saldo** prepagato in dollari USA: da questo vengono scalate le **licenze** (una per account Telegram, 30 giorni) e una **commissione** sulle vendite nette. Lo ricarichi con depositi in crypto. I guadagni da affiliato possono essere **prelevati**. Ogni endpoint di fatturazione richiede un token **owner**: negli esempi, `$LANACHAT_TOKEN` ne contiene uno.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/billing/balance` | Il saldo, le vendite nette del mese e la fascia di commissione | `owner` | Planned |
| GET | `/billing/ledger` | Ogni movimento: depositi, licenze, commissioni, rimborsi | `owner` | Planned |
| GET | `/billing/ledger.csv` | Lo stesso registro in CSV (`from=`, `to=`) | `owner` | Planned |
| GET | `/billing/deposit-addresses` | Un indirizzo di deposito per ogni chain (con memo su Solana) | `owner` | Planned |
| GET | `/billing/deposits` | Depositi e loro conferme | `owner` | Planned |
| GET | `/billing/licences` | Licenze in stock e assegnate, con giorni residui | `owner` | Planned |
| POST | `/billing/licences/buy` | Acquista licenze: singola o pacchetti da 10, 25 o 50 | `owner` | Planned |
| POST | `/billing/licences/assign` | Assegna una licenza dallo stock a un account | `owner` | Planned |
| POST | `/billing/licences/unassign` | Ritorna allo stock con i giorni residui | `owner` | Planned |
| PATCH | `/billing/licences/auto-renew` | Attiva o disattiva il rinnovo automatico per un account | `owner` | Planned |
| GET | `/billing/withdrawals` | Prelievi affiliati e loro stato | `owner` | Planned |
| POST | `/billing/withdrawals` | Richiedi un prelievo dei guadagni affiliati (da $500) | `owner` | Planned |
| GET | `/billing/invoices` | Estratti conto mensili (`year=`) | `owner` | Planned |
| GET | `/billing/invoices/{id}.pdf` | Un estratto conto in PDF | `owner` | Planned |
| PUT | `/billing/details` | Nome azienda, indirizzo e partita IVA sugli estratti conto | `owner` | Planned |

## Prezzi in una tabella

| Cosa | Prezzo |
|---|---|
| Una licenza (un account Telegram, 30 giorni) | $19 |
| Pacchetto da 10 licenze | $170 |
| Pacchetto da 25 licenze | $375 |
| Pacchetto da 50 licenze | $650 |
| Commissione fino a $30k di vendite nette nel mese | 12% sulle vendite AI, 4% su vendite manuali |
| Commissione da $30k a $100k | 10% e 3% |
| Commissione sopra $100k | 8% e 2% |

Il contatore è sulle vendite nette di tutto lo workspace nel mese solare; si azzera il 1°. I Telegram Stars valgono $0.013 ciascuno nelle vendite nette.

## L’oggetto balance

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

| Campo | Tipo | Descrizione |
|---|---|---|
| `balance_cents` | integer | Saldo prepagato, in centesimi di dollaro |
| `month` | string | Mese solare considerato, `YYYY-MM` |
| `net_sales_cents` | integer | Vendite nette dello workspace in questo mese |
| `tier` | object | Fascia attuale: limite `up_to_cents`, tasso AI e tasso manuale in basis points |
| `licences` | object | Licenze `in_stock`, `assigned` e assegnate che scadono entro 7 giorni (`expiring_7d`) |
| `low_balance` | boolean | `true` se il saldo non copre i prossimi 7 giorni di licenze |

I tassi sono in basis points: `1200` significa 12%.

## L’oggetto ledger entry

Ogni riga di **Billing › Activity** nella 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
}
```

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | La riga |
| `at` | string | ISO 8601, UTC |
| `kind` | string | `deposit`, `licences`, `commission`, `refund`, `affiliate` o `other` |
| `label` | string | Testo della riga, come in Console |
| `amount_cents` | integer | Positivo se entrano soldi, negativo se escono |
| `balance_after_cents` | integer | Saldo dopo questa riga |

Una riga `commission` appartiene a una vendita: la Console mostra il fan, la fascia, chi ha inviato l’offerta (AI o manuale), come è stato calcolato il netto ("12,500 ★ × $0.013") e il tasso.

## L’oggetto deposit

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

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | Il deposito |
| `at` | string | Quando è stato visto, ISO 8601 |
| `chain` | string | `usdc-eth`, `usdc-sol`, `usdt-sol`, `usdt-tron` o `usdt-eth` |
| `sent_cents`, `fee_cents`, `credited_cents` | integer | Quanto hai inviato, la fee, quanto arriva sul saldo |
| `status` | string | `pending` poi `confirmed` |
| `confirmations` | string | Conferme di rete contate, mentre è pending |

USDC su Ethereum è accreditato 1:1 senza fee. Ogni altra chain ha una fee dell’1%: il deposito viene convertito in USDC (ERC20) all’arrivo. Il minimo è $25 per ricarica.

## L’oggetto licence

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

| Campo | Tipo | Descrizione |
|---|---|---|
| `account_id` | string | L’account Telegram su cui gira la licenza |
| `creator_id` | string | La sua creator |
| `days_left` | integer | Giorni prima della scadenza, su 30 |
| `expires_at` | string | Quando scade |
| `auto_renew` | boolean | Rinnova dallo stock (o compra singola) alla scadenza |

Le licenze in stock sono contate, non elencate singolarmente: ognuna mantiene i propri giorni residui (30 per una nuova).

## L’oggetto withdrawal

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

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | Il prelievo |
| `status` | string | `pending_review`, `sent` (con `tx_hash`) o `rejected` con motivo |
| `amount_cents` | integer | Importo richiesto, almeno 50000 ($500) |
| `requested_at` | string | ISO 8601, UTC |
| `tx_hash` | string o null | La transazione, una volta inviata |

## L’oggetto invoice

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

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | Numero estratto conto, `LC-YYYY-MM` |
| `month` | string | Mese coperto |
| `licences_cents`, `commission_cents`, `total_cents` | integer | Licenze, commissioni e totale del mese |
| `status` | string | Pagato, in corso (mese corrente) o fallito |
| `pdf_url` | string | PDF dell’estratto conto |

## Saldo e registro

### Ottieni il saldo

`GET /billing/balance` · `owner`

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

La risposta è l’oggetto balance.

### Elenca il registro

`GET /billing/ledger` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `from`, `to` | string | No | Giorni `YYYY-MM-DD`, UTC, inclusi entrambi |
| `limit`, `cursor` | number, string | No | [Paginazione](https://lanachat.ai/guides/it/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"
}
```

### Esporta il registro in CSV

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `from`, `to` | string | No | Giorni `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
```

Le stesse righe di **Export CSV** in **Billing › Activity**, pronte per il tuo commercialista.

## Depositi

### Ottieni gli indirizzi di deposito

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

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

La risposta fornisce un indirizzo per ogni chain (Ethereum, Solana, Tron) e, per Solana, il memo.

> Warning: Su Solana, un deposito inviato senza memo non può essere associato al tuo workspace. Invia sempre sia l’indirizzo che il memo.

Puoi inviare USDC su Ethereum (ERC20), USDC su Solana, USDT su Solana, USDT su Tron (TRC20) o USDT su Ethereum (ERC20). La fee di rete del trasferimento è a carico del tuo wallet.

### Elenca i depositi

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

Il saldo viene accreditato automaticamente quando un deposito è `confirmed`; è anche una riga `deposit` nel registro.

## Licenze

### Elenca le licenze

`GET /billing/licences` · `owner`

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

La risposta fornisce le licenze in stock e un oggetto licence per ogni account assegnato, con i giorni residui.

### Acquista licenze

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `pack` | integer | Sì | `1` (singola, $19), `10` ($170), `25` ($375) o `50` ($650) |
| `qty` | integer | Sì | Quanti di quel pacchetto |

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

Le licenze vanno subito nel tuo stock. Un saldo troppo basso risponde con `402` (`insufficient_balance`). Le licenze in stock non scadono mai, e le licenze acquistate non sono rimborsabili.

### Assegna una licenza

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `account_id` | string | Sì | L’account Telegram che riceve la licenza |

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

La risposta è l’oggetto licence dell’account. Viene usata prima la licenza in stock con meno giorni residui: i suoi giorni rimanenti, o 30 se nuova. Il rinnovo automatico è attivo di default.

### Riprendi una licenza

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `account_id` | string | Sì | L’account che restituisce la licenza |

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

La licenza torna nel tuo stock con i giorni residui. L’AI smette subito di rispondere su quell’account. Per spostare una licenza a un altro account, riprendila e poi assegnala: mantiene i giorni, gratuitamente.

### Attiva o disattiva il rinnovo automatico

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `account_id` | string | Sì | L’account |
| `auto_renew` | boolean | Sì | `true` per rinnovare quando finiscono i giorni |

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

Quando finiscono i giorni, il rinnovo automatico prende prima una licenza dal tuo stock, o compra una singola ($19) se lo stock è vuoto. Non può comprare senza saldo: controlla `low_balance` o il webhook `billing.low_balance` [webhook](https://lanachat.ai/guides/it/api-webhooks/).

## Prelievi affiliati

### Elenca i prelievi

`GET /billing/withdrawals` · `owner`

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

Una lista di oggetti withdrawal, dal più recente.

### Richiedi un prelievo

`POST /billing/withdrawals` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `amount_cents` | integer | Sì | Almeno 50000 ($500), al massimo quanto disponibile |

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

I guadagni vengono inviati in USDC al wallet registrato, 7 giorni dopo la fine del mese. Possono essere prelevati solo i guadagni da affiliato, mai il saldo prepagato. Una richiesta sotto i $500 viene rifiutata.

## Estratti conto

### Elenca gli estratti conto

`GET /billing/invoices` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `year` | integer | No | Per esempio `2026` |

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

Un oggetto invoice per ogni mese.

### Scarica un estratto conto

`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: Controlla i tuoi estratti conto. Un errore di fatturazione deve essere segnalato entro 60 giorni dall’estratto che lo mostra; dopo di che l’estratto è definitivo.

### Imposta i dettagli di fatturazione

`PUT /billing/details` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `company` | string | No | Nome azienda |
| `email` | string | No | E-mail di fatturazione |
| `address`, `city`, `postal`, `country` | string | No | Indirizzo postale |
| `vat` | string | No | Partita IVA |

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

Gli stessi campi di **Billing › Billing details**. Gli estratti conto riportano questi dati. `PUT` li sostituisce tutti: un campo omesso viene svuotato.

## Articoli correlati

- [API LanaChat: avvio rapido, autenticazione ed errori](https://lanachat.ai/guides/it/api-overview/)
- [Fatturazione: licenze, commissioni e saldo](https://lanachat.ai/guides/it/billing/)