API: saldo, licenze, prelievi e fatture

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 #

Prezzi in una tabella #

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 #

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

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

L’oggetto ledger entry #

Ogni riga di Billing › Activity nella Console.

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

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 #

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

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 #

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

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

L’oggetto withdrawal #

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

L’oggetto invoice #

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

Saldo e registro #

Ottieni il saldo #

GET /billing/balance · owner

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

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

{
  "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

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

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.

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

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

{
  "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

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

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

{ "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

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

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

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.

Prelievi affiliati #

Elenca i prelievi #

GET /billing/withdrawals · owner

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

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

{ "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

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

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

Imposta i dettagli di fatturazione #

PUT /billing/details · owner

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": "[email protected]", "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.