# API: saldo, licenças, saques e faturas

_API · Leitura de 7 min · Atualizado 2026-10-22 · https://lanachat.ai/guides/pt/api-billing/_

LanaChat é pago a partir de um **saldo** pré-pago em dólares americanos: **licenças** (uma por conta do Telegram, 30 dias) e uma **comissão** sobre vendas líquidas são descontadas dele. Você o recarrega com depósitos em criptomoedas. Ganhos de afiliados podem ser **sacados**. Todo endpoint de cobrança precisa de um token de **owner**: nos exemplos, `$LANACHAT_TOKEN` contém um.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/billing/balance` | O saldo, vendas líquidas do mês e nível de comissão | `owner` | Planned |
| GET | `/billing/ledger` | Todos os movimentos: depósitos, licenças, comissão, reembolsos | `owner` | Planned |
| GET | `/billing/ledger.csv` | O mesmo extrato em CSV (`from=`, `to=`) | `owner` | Planned |
| GET | `/billing/deposit-addresses` | Um endereço de depósito por blockchain (com memo na Solana) | `owner` | Planned |
| GET | `/billing/deposits` | Depósitos e suas confirmações | `owner` | Planned |
| GET | `/billing/licences` | Licenças em estoque e atribuídas, com dias restantes | `owner` | Planned |
| POST | `/billing/licences/buy` | Comprar licenças: única ou pacote de 10, 25 ou 50 | `owner` | Planned |
| POST | `/billing/licences/assign` | Atribuir uma licença do estoque a uma conta | `owner` | Planned |
| POST | `/billing/licences/unassign` | Retirar para o estoque com seus dias restantes | `owner` | Planned |
| PATCH | `/billing/licences/auto-renew` | Ativar ou desativar renovação automática para uma conta | `owner` | Planned |
| GET | `/billing/withdrawals` | Saques de afiliados e seus status | `owner` | Planned |
| POST | `/billing/withdrawals` | Solicitar saque de ganhos de afiliado (a partir de $500) | `owner` | Planned |
| GET | `/billing/invoices` | Extratos mensais (`year=`) | `owner` | Planned |
| GET | `/billing/invoices/{id}.pdf` | Um extrato em PDF | `owner` | Planned |
| PUT | `/billing/details` | Nome da empresa, endereço e número de VAT nos extratos | `owner` | Planned |

## Preços em uma tabela

| What | Price |
|---|---|
| Uma licença (uma conta Telegram, 30 dias) | $19 |
| Pacote de 10 licenças | $170 |
| Pacote de 25 licenças | $375 |
| Pacote de 50 licenças | $650 |
| Comissão até $30k de vendas líquidas no mês | 12% das vendas AI, 4% das vendas manuais |
| Comissão de $30k a $100k | 10% e 3% |
| Comissão acima de $100k | 8% e 2% |

O contador é o total de vendas líquidas de todo o workspace no mês calendário; ele zera no dia 1º. Telegram Stars contam como $0.013 cada nas vendas líquidas.

## The balance object

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

| Field | Type | Description |
|---|---|---|
| `balance_cents` | integer | Saldo pré-pago, em centavos de dólar |
| `month` | string | Mês calendário contado, `YYYY-MM` |
| `net_sales_cents` | integer | Vendas líquidas do workspace neste mês |
| `tier` | object | Nível atual: seu teto `up_to_cents`, taxa AI e taxa manual em pontos base |
| `licences` | object | Licenças `in_stock`, `assigned` e as atribuídas que vencem em até 7 dias (`expiring_7d`) |
| `low_balance` | boolean | `true` quando o saldo não cobre os próximos 7 dias de licenças |

As taxas estão em pontos base: `1200` é 12%.

## The ledger entry object

Cada linha de **Billing › Activity** no 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
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | A linha |
| `at` | string | ISO 8601, UTC |
| `kind` | string | `deposit`, `licences`, `commission`, `refund`, `affiliate` ou `other` |
| `label` | string | Texto da linha, como no Console |
| `amount_cents` | integer | Positivo quando entra dinheiro, negativo quando sai |
| `balance_after_cents` | integer | Saldo após esta linha |

Uma linha `commission` pertence a uma venda: o Console mostra o fã, o nível, quem enviou a oferta (AI ou manual), como o líquido foi contado ("12,500 ★ × $0.013") e a taxa.

## The deposit object

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

| Field | Type | Description |
|---|---|---|
| `id` | string | O depósito |
| `at` | string | Quando foi visto, ISO 8601 |
| `chain` | string | `usdc-eth`, `usdc-sol`, `usdt-sol`, `usdt-tron` ou `usdt-eth` |
| `sent_cents`, `fee_cents`, `credited_cents` | integer | O que você enviou, a taxa, o que cai no saldo |
| `status` | string | `pending` e depois `confirmed` |
| `confirmations` | string | Confirmações na rede enquanto pendente |

USDC na Ethereum é creditado 1:1 sem taxa. Todas as outras blockchains têm 1% de taxa: o depósito é convertido para USDC (ERC20) ao chegar. O mínimo é $25 por recarga.

## The licence object

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

| Field | Type | Description |
|---|---|---|
| `account_id` | string | A conta Telegram em que a licença está ativa |
| `creator_id` | string | A criadora dela |
| `days_left` | integer | Dias restantes, de 30 |
| `expires_at` | string | Quando termina |
| `auto_renew` | boolean | Renova do estoque (ou compra uma única) quando terminar |

Licenças em estoque são contadas, não listadas uma a uma: cada uma mantém seus próprios dias restantes (30 para uma nova).

## The withdrawal object

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

| Field | Type | Description |
|---|---|---|
| `id` | string | O saque |
| `status` | string | `pending_review`, `sent` (com `tx_hash`) ou `rejected` com motivo |
| `amount_cents` | integer | Valor solicitado, no mínimo 50000 ($500) |
| `requested_at` | string | ISO 8601, UTC |
| `tx_hash` | string ou null | A transação, quando enviada |

## The invoice object

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

| Field | Type | Description |
|---|---|---|
| `id` | string | Número do extrato, `LC-YYYY-MM` |
| `month` | string | Mês que cobre |
| `licences_cents`, `commission_cents`, `total_cents` | integer | Licenças, comissão e total do mês |
| `status` | string | Pago, em andamento (mês atual) ou falhou |
| `pdf_url` | string | PDF do extrato |

## Balance and ledger

### Get the balance

`GET /billing/balance` · `owner`

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

A resposta é o balance object.

### List the ledger

`GET /billing/ledger` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `from`, `to` | string | No | Dias `YYYY-MM-DD`, UTC, ambos incluídos |
| `limit`, `cursor` | number, string | No | [Paginação](https://lanachat.ai/guides/pt/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 the ledger as CSV

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `from`, `to` | string | No | Dias `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
```

As mesmas linhas de **Export CSV** em **Billing › Activity**, prontas para seu contador.

## Deposits

### Get the deposit addresses

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

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

A resposta traz um endereço por blockchain (Ethereum, Solana, Tron) e, para Solana, o memo.

> Warning: Na Solana, um depósito enviado sem o memo não pode ser associado ao seu workspace. Sempre envie o endereço e o memo.

Você pode enviar USDC na Ethereum (ERC20), USDC na Solana, USDT na Solana, USDT na Tron (TRC20) ou USDT na Ethereum (ERC20). A taxa de rede da sua transferência é paga da sua carteira.

### List deposits

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

O saldo é creditado automaticamente quando um depósito é `confirmed`; ele também vira uma linha `deposit` no extrato.

## Licences

### List licences

`GET /billing/licences` · `owner`

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

A resposta traz as licenças em estoque e um licence object por conta atribuída, com seus dias restantes.

### Buy licences

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pack` | integer | Yes | `1` (única, $19), `10` ($170), `25` ($375) ou `50` ($650) |
| `qty` | integer | Yes | Quantos desse pacote |

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

As licenças vão para seu estoque imediatamente. Um saldo insuficiente responde `402` (`insufficient_balance`). Licenças em estoque nunca expiram, e licenças compradas não são reembolsáveis.

### Assign a licence

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | Yes | A conta Telegram que recebe a 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"}'
```

A resposta é o licence object da conta. A licença do estoque com menos dias restantes é usada primeiro: seus dias restantes, ou 30 se for nova. Auto-renew vem ativado por padrão.

### Take a licence back

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | Yes | A conta que devolve a 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"}'
```

A licença volta para seu estoque com seus dias restantes. A AI para de responder nessa conta imediatamente. Para mover uma licença para outra conta, devolva-a e depois atribua: ela mantém seus dias, sem custo.

### Turn auto-renew on or off

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | Yes | A conta |
| `auto_renew` | boolean | Yes | `true` para renovar quando os dias acabarem |

```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 os dias acabam, auto-renew usa uma licença do estoque primeiro, ou compra uma única ($19) se o estoque estiver vazio. Não pode comprar sem saldo: fique de olho em `low_balance` ou no webhook `billing.low_balance` [webhook](https://lanachat.ai/guides/pt/api-webhooks/).

## Affiliate withdrawals

### List withdrawals

`GET /billing/withdrawals` · `owner`

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

Uma lista de withdrawal objects, mais recentes primeiro.

### Ask for a withdrawal

`POST /billing/withdrawals` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `amount_cents` | integer | Yes | Pelo menos 50000 ($500), no máximo o disponível para saque |

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

Os ganhos são enviados em USDC para a carteira cadastrada, 7 dias após o fim do mês. Só ganhos de afiliados podem ser sacados, nunca o saldo pré-pago. Pedido abaixo de $500 é recusado.

## Statements

### List statements

`GET /billing/invoices` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `year` | integer | No | Por exemplo `2026` |

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

Um invoice object por mês.

### Download a statement

`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: Verifique seus extratos. Erros de cobrança devem ser reportados em até 60 dias após o extrato que os mostra; depois disso, o extrato é definitivo.

### Set the billing details

`PUT /billing/details` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company` | string | No | Nome da empresa |
| `email` | string | No | E-mail de cobrança |
| `address`, `city`, `postal`, `country` | string | No | Endereço postal |
| `vat` | string | No | Número de 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"}'
```

Os mesmos campos de **Billing › Billing details**. Os extratos exibem esses dados. `PUT` substitui todos: um campo omitido é esvaziado.

## Artigos relacionados

- [API LanaChat: início rápido, autenticação e erros](https://lanachat.ai/guides/pt/api-overview/)
- [Cobrança: licenças, comissão e saldo](https://lanachat.ai/guides/pt/billing/)