# API: balance, licencias, retiros y facturas

_API · 7 min de lectura · Actualizado 2026-10-22 · https://lanachat.ai/guides/es/api-billing/_

LanaChat se paga desde un único **balance** prepago en dólares estadounidenses: de ahí se descuentan las **licences** (una por cuenta de Telegram, 30 días) y una **commission** sobre las ventas netas. Lo recargas con depósitos en cripto. Las ganancias de afiliada se pueden **withdrawn**. Cada endpoint de facturación requiere un token de **owner**: en los ejemplos, `$LANACHAT_TOKEN` contiene uno.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/billing/balance` | El balance, ventas netas del mes y nivel de comisión | `owner` | Planned |
| GET | `/billing/ledger` | Todos los movimientos: depósitos, licencias, comisión, reembolsos | `owner` | Planned |
| GET | `/billing/ledger.csv` | El mismo ledger en CSV (`from=`, `to=`) | `owner` | Planned |
| GET | `/billing/deposit-addresses` | Una dirección de depósito por red (con memo en Solana) | `owner` | Planned |
| GET | `/billing/deposits` | Depósitos y sus confirmaciones | `owner` | Planned |
| GET | `/billing/licences` | Licencias en stock y asignadas, con días restantes | `owner` | Planned |
| POST | `/billing/licences/buy` | Comprar licencias: una sola o packs de 10, 25 o 50 | `owner` | Planned |
| POST | `/billing/licences/assign` | Asignar una licencia del stock a una cuenta | `owner` | Planned |
| POST | `/billing/licences/unassign` | Recuperarla al stock con sus días restantes | `owner` | Planned |
| PATCH | `/billing/licences/auto-renew` | Activar o desactivar auto-renovación para una cuenta | `owner` | Planned |
| GET | `/billing/withdrawals` | Retiros de afiliada y su estado | `owner` | Planned |
| POST | `/billing/withdrawals` | Solicitar retiro de ganancias de afiliada (desde $500) | `owner` | Planned |
| GET | `/billing/invoices` | Extractos mensuales (`year=`) | `owner` | Planned |
| GET | `/billing/invoices/{id}.pdf` | Un extracto en PDF | `owner` | Planned |
| PUT | `/billing/details` | Nombre de empresa, dirección y VAT en los extractos | `owner` | Planned |

## Precios en una tabla

| What | Price |
|---|---|
| Una licencia (una cuenta de Telegram, 30 días) | $19 |
| Pack de 10 licencias | $170 |
| Pack de 25 licencias | $375 |
| Pack de 50 licencias | $650 |
| Comisión hasta $30k de ventas netas en el mes | 12% de ventas AI, 4% de ventas manuales |
| Comisión de $30k a $100k | 10% y 3% |
| Comisión sobre $100k | 8% y 2% |

El contador es la suma de ventas netas de todo el workspace en el mes calendario; se reinicia el día 1. Telegram Stars cuentan a $0.013 cada una en ventas netas.

## El objeto 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
}
```

| Field | Type | Description |
|---|---|---|
| `balance_cents` | integer | Balance prepago, en centavos de dólar |
| `month` | string | Mes calendario contado, `YYYY-MM` |
| `net_sales_cents` | integer | Ventas netas del workspace este mes |
| `tier` | object | Nivel actual: su tope `up_to_cents`, tasa AI y manual en basis points |
| `licences` | object | Licencias `in_stock`, `assigned` y asignadas que terminan en 7 días (`expiring_7d`) |
| `low_balance` | boolean | `true` si el balance no cubre los próximos 7 días de licencias |

Las tasas están en basis points: `1200` es 12%.

## El objeto ledger entry

Cada línea de **Billing › Activity** en la 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 | La línea |
| `at` | string | ISO 8601, UTC |
| `kind` | string | `deposit`, `licences`, `commission`, `refund`, `affiliate` o `other` |
| `label` | string | El texto de la línea, como en la Console |
| `amount_cents` | integer | Positivo si entra dinero, negativo si sale |
| `balance_after_cents` | integer | El balance después de esta línea |

Una línea de `commission` corresponde a una venta: la Console muestra el fan, el nivel, quién envió la oferta (AI o manual), cómo se calculó el neto ("12,500 ★ × $0.013") y la tasa.

## El objeto 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"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | El depósito |
| `at` | string | Cuándo se vio, ISO 8601 |
| `chain` | string | `usdc-eth`, `usdc-sol`, `usdt-sol`, `usdt-tron` o `usdt-eth` |
| `sent_cents`, `fee_cents`, `credited_cents` | integer | Lo que enviaste, la comisión, lo que llega al balance |
| `status` | string | `pending` y luego `confirmed` |
| `confirmations` | string | Confirmaciones de red, mientras está pendiente |

USDC en Ethereum se acredita 1:1 sin comisión. Las demás redes tienen 1% de comisión: el depósito se convierte a USDC (ERC20) al llegar. El mínimo es $25 por recarga.

## El objeto licence

```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 | La cuenta de Telegram donde corre la licencia |
| `creator_id` | string | Su creadora |
| `days_left` | integer | Días antes de que termine, de 30 |
| `expires_at` | string | Cuándo termina |
| `auto_renew` | boolean | Renovar del stock (o comprar una) al terminar |

Las licencias en stock se cuentan, no se listan una a una: cada una mantiene sus días restantes (30 si es nueva).

## El objeto withdrawal

```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 | El retiro |
| `status` | string | `pending_review`, `sent` (con `tx_hash`) o `rejected` con motivo |
| `amount_cents` | integer | Monto solicitado, mínimo 50000 ($500) |
| `requested_at` | string | ISO 8601, UTC |
| `tx_hash` | string or null | La transacción, cuando se envía |

## El objeto 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"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Número de extracto, `LC-YYYY-MM` |
| `month` | string | El mes cubierto |
| `licences_cents`, `commission_cents`, `total_cents` | integer | Licencias, comisión y total del mes |
| `status` | string | Pagado, en curso (el mes actual) o fallido |
| `pdf_url` | string | El PDF del extracto |

## Balance y ledger

### Obtener el balance

`GET /billing/balance` · `owner`

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

La respuesta es el balance object.

### Listar el ledger

`GET /billing/ledger` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `from`, `to` | string | No | Días `YYYY-MM-DD`, UTC, ambos incluidos |
| `limit`, `cursor` | number, string | No | [Pagination](https://lanachat.ai/guides/es/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"
}
```

### Exportar el ledger como CSV

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

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

Las mismas líneas que **Export CSV** en **Billing › Activity**, listo para tu contable.

## Depósitos

### Obtener las direcciones de depósito

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

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

La respuesta da una dirección por red (Ethereum, Solana, Tron) y, para Solana, el memo.

> Warning: En Solana, un depósito sin el memo no puede asociarse a tu workspace. Siempre envía dirección y memo.

Puedes enviar USDC en Ethereum (ERC20), USDC en Solana, USDT en Solana, USDT en Tron (TRC20) o USDT en Ethereum (ERC20). La comisión de red de tu transferencia se paga desde tu wallet.

### Listar depósitos

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

El balance se acredita automáticamente cuando un depósito está `confirmed`; también aparece como línea `deposit` en el ledger.

## Licencias

### Listar licencias

`GET /billing/licences` · `owner`

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

La respuesta da las licencias en stock y un licence object por cuenta asignada, con sus días restantes.

### Comprar licencias

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pack` | integer | Yes | `1` (una, $19), `10` ($170), `25` ($375) o `50` ($650) |
| `qty` | integer | Yes | Cuántos de ese pack |

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

Las licencias van a tu stock al instante. Un balance insuficiente responde `402` (`insufficient_balance`). Las licencias en stock no caducan nunca, y las compradas no son reembolsables.

### Asignar una licencia

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | Yes | La cuenta de Telegram que recibe la licencia |

```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 respuesta es el licence object de la cuenta. Se usa primero la licencia del stock con menos días restantes: sus días, o 30 si es nueva. Auto-renew está activado por defecto.

### Recuperar una licencia

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | Yes | La cuenta que devuelve su licencia |

```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 licencia vuelve a tu stock con sus días restantes. La AI deja de responder en esa cuenta de inmediato. Para mover una licencia a otra cuenta, recupérala y luego asígnala: mantiene sus días, sin coste.

### Activar o desactivar auto-renew

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | Yes | La cuenta |
| `auto_renew` | boolean | Yes | `true` para renovarla al acabar los días |

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

Cuando se acaban los días, auto-renew toma primero una licencia de tu stock, o compra una sola ($19) si el stock está vacío. No puede comprar sin balance: vigila `low_balance` o el webhook `billing.low_balance` [webhook](https://lanachat.ai/guides/es/api-webhooks/).

## Retiros de afiliada

### Listar retiros

`GET /billing/withdrawals` · `owner`

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

Una lista de withdrawal objects, el más reciente primero.

### Solicitar un retiro

`POST /billing/withdrawals` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `amount_cents` | integer | Yes | Al menos 50000 ($500), como máximo lo disponible para retirar |

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

Las ganancias se envían en USDC a la wallet registrada, 7 días después de terminar el mes. Solo se pueden retirar ganancias de afiliada, nunca el balance prepago. Una solicitud menor a $500 es rechazada.

## Extractos

### Listar extractos

`GET /billing/invoices` · `owner`

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

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

Un invoice object por mes.

### Descargar un extracto

`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: Revisa tus extractos. Un error de facturación debe reportarse en los 60 días siguientes al extracto que lo muestra; después, el extracto es definitivo.

### Cambiar los datos de facturación

`PUT /billing/details` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company` | string | No | Nombre de la empresa |
| `email` | string | No | E-mail de facturación |
| `address`, `city`, `postal`, `country` | string | No | Dirección postal |
| `vat` | string | No | Número 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"}'
```

Los mismos campos que **Billing › Billing details**. Los extractos llevan estos datos. `PUT` los reemplaza todos: un campo que omitas se vacía.

## Artículos relacionados

- [API de LanaChat: inicio rápido, autenticación y errores](https://lanachat.ai/guides/es/api-overview/)
- [Facturación: licencias, comisión y saldo](https://lanachat.ai/guides/es/billing/)