API: balance, licencias, retiros y facturas

7 min de lecturaActualizado 22 oct 2026Markdown

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 #

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

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

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

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

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

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

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

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

Exportar el ledger como CSV #

GET /billing/ledger.csv · owner

Parameter	Type	Required	Description
`from`, `to`	string	No	Días `YYYY-MM-DD`, UTC

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

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.

Advertencia 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

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
}

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

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

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

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

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

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

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.

Retiros de afiliada #

Listar retiros #

GET /billing/withdrawals · owner

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

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 }

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`

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

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

Advertencia 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

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

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