API de LanaChat: inicio rápido, autenticación y errores

Todo lo que tu equipo hace en la Console, tu código también puede hacerlo. La API de LanaChat lee y modifica todo tu espacio de trabajo: creadoras, cuentas de Telegram, AI Brains, scripts, el Vault, fans y conversaciones, enlaces de seguimiento, facturación y tu equipo. Es JSON simple sobre HTTPS, una URL por recurso, con los mismos permisos que la Console. Los webhooks envían eventos a tu servidor, y el servidor MCP permite que un asistente AI como Claude o Cursor trabaje en tu espacio con el mismo token.

Qué puedes construir #

• Un panel de ventas en tus propias herramientas: ingresos de hoy por creadora, por enlace, por fuente.
• Alertas en Slack o Telegram cuando un fan compra, cuando una conversación necesita revisión o cuando una cuenta pierde su conexión.
• Un script de configuración que añade una creadora, conecta sus cuentas, sube su Vault y escribe su primer script.
• Una canalización de seguimiento: crea un enlace por anuncio, lee clics, conversaciones y compradores cada hora.
• Un asistente AI que redacta scripts y cambios de persona para que los revises, a través de MCP.

Inicio rápido en 5 minutos #

1. En la Console, abre Users › API & MCP y presiona Create token.
2. Ponle un nombre (por ejemplo "Reporting script"), elige Custom permissions y marca lo que necesita, por ejemplo Read fans and conversations y Read sales.
3. Guarda y luego presiona Copy token. El token se muestra una sola vez.

4. Guárdalo en una variable de entorno, para que nunca esté en tu código:

export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"

5. Haz tu primera llamada. Devuelve tu espacio de trabajo y lo que el token puede hacer:

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

const res = await fetch('https://api.lanachat.ai/v1/workspace', {
  headers: { Authorization: `Bearer ${process.env.LANACHAT_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const workspace = await res.json();
console.log(workspace.name, workspace.token.permissions);

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/workspace",
    headers={"Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["name"])

{
  "id": "ws_7Hq2",
  "name": "Mia Agency",
  "kind": "agency",
  "timezone": "Europe/Paris",
  "token": { "id": "tok_31", "name": "Reporting script", "permissions": ["can_fan_read", "can_sales_read"], "expires_at": "2027-01-06T00:00:00Z" }
}

Eso es todo: todos los demás endpoints funcionan igual. Scripts listos están en API quick recipes.

Cada recurso #

URL base y versiones #

Cada ruta en estas guías es relativa a:

https://api.lanachat.ai/v1

La versión está en la ruta. Un cambio incompatible recibe una nueva versión (/v2); nuevos campos y endpoints se añaden a /v1 sin aviso, así que ignora los campos que no conozcas.

Autenticación #

Cada solicitud lleva tu token en el encabezado Authorization, después de la palabra Bearer:

Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f

• Crea, edita, rota y revoca tokens en Users › API & MCP, o con los endpoints de tokens. Solo el dueño del espacio y los dueños de agencias pueden abrir esa página.
• Un token se muestra una vez, cuando lo creas. Guárdalo como una contraseña; Rotate o Revoke desde la misma página.
• Una solicitud sin token válido responde 401. Un token sin el permiso que el endpoint necesita responde 403.
• Los tokens nunca van en una URL ni en código de navegador: llama a la API desde tu servidor.
• Usa un token por script o asistente, para que cada uno pueda cambiarse o revocarse por separado.

Espacios de trabajo #

Un token pertenece a un espacio de trabajo, el donde fue creado. Cada solicitud lee y escribe solo en ese espacio; no hay id de espacio en las rutas. Un token de dueño (el espacio que gestiona varias agencias) puede actuar en una de sus agencias con el encabezado LanaChat-Workspace: ws_…; cualquier otro token que envíe ese encabezado recibe 403.

Permisos #

Cada endpoint lista el permiso que necesita. Son los que marcas al crear un token:

• Apagar Access AI configuration (can_engine) también apaga publicación, AI Avanzada e informes de experimentos.
• can_chat, can_tracking y el token owner están planeados: la Console aún no los ofrece.

Solicitudes y respuestas #

• Los cuerpos son JSON (Content-Type: application/json), en UTF-8. Las subidas van por una URL firmada, nunca por la API.
• Los ids son cadenas con un prefijo que indica qué son: cr_ creadora, acc_ cuenta Telegram, pool_, sto_ historia, br_ brain, scr_ script, med_ medio, fan_, conv_ conversación, msg_, lnk_ enlace, px_ píxel, mem_ miembro, tok_ token.
• Los tiempos son ISO 8601 en UTC (2026-10-06T14:05:00Z). Los días en estadísticas son días UTC.
• El dinero está en centavos de dólar (amount_cents: 1900 es $19.00). Telegram Stars son números enteros (stars: 250).
• PATCH cambia solo los campos que envías. PUT reemplaza todo el objeto.
• Un POST que crea algo responde 201 con el nuevo objeto; otras llamadas exitosas responden 200.

Paginación #

Cada lista responde una página y un cursor para la siguiente:

curl "https://api.lanachat.ai/v1/fans?limit=50&cursor=eyJpZCI6ImZhbl85MjAifQ" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"

{
  "data": [ { "id": "fan_921", "display_name": "Marco", "creator_id": "cr_lea" } ],
  "next_cursor": "eyJpZCI6ImZhbl85NzAifQ"
}

• limit es de 1 a 100, 25 por defecto.
• next_cursor es null en la última página. Un cursor es opaco: pásalo tal cual, nunca crees uno.
• Las listas están ordenadas del más nuevo al más antiguo salvo que el endpoint diga otra cosa.

Para leer todas las páginas, haz un bucle hasta que next_cursor sea null:

async function all(path) {
  const items = [];
  let cursor = null;
  do {
    const url = new URL('https://api.lanachat.ai/v1' + path);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.LANACHAT_TOKEN}` } });
    if (!res.ok) throw new Error((await res.json()).error.message);
    const page = await res.json();
    items.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);
  return items;
}

const fans = await all('/fans?creator_id=cr_lea');

import os
import requests

def all_items(path, **params):
    items, cursor = [], None
    while True:
        r = requests.get(
            "https://api.lanachat.ai/v1" + path,
            params={**params, "limit": 100, **({"cursor": cursor} if cursor else {})},
            headers={"Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}"},
            timeout=30,
        )
        r.raise_for_status()
        page = r.json()
        items += page["data"]
        cursor = page["next_cursor"]
        if not cursor:
            return items

fans = all_items("/fans", creator_id="cr_lea")

Errores #

Un error responde con un estado 4xx o 5xx y siempre el mismo cuerpo:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is $12.40 and this pack costs $170.00. Top up first."
  }
}

message es una frase en inglés simple que puedes mostrar a una persona. Ramifica tu código según code, nunca según message.

Límites de tasa #

Cada token puede enviar 600 solicitudes por minuto. Cada respuesta lleva RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (segundos hasta que se reinicia la ventana). Sobre el límite la API responde 429 con un encabezado Retry-After. Enviar un mensaje a un fan también está sujeto a los límites propios de Telegram: consulta las reglas de pools.

Un pequeño ayudante que espera y reintenta en 429 y 5xx:

async function lanachat(method, path, body) {
  const key = crypto.randomUUID();   // one key per action: a retry never does the work twice
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch('https://api.lanachat.ai/v1' + path, {
      method,
      headers: {
        Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
        'Content-Type': 'application/json',
        ...(method === 'POST' ? { 'Idempotency-Key': key } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt;
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const data = await res.json();
    if (!res.ok) throw Object.assign(new Error(data.error.message), { code: data.error.code, status: res.status });
    return data;
  }
  throw new Error('LanaChat API: too many retries');
}

Úsalo en todas partes: await lanachat('GET', '/creators'), await lanachat('POST', '/links', { … }).

Idempotencia #

Envía un encabezado Idempotency-Key (cualquier cadena única hasta 255 caracteres, un UUID sirve) en cada POST. Si la misma clave vuelve en 24 horas, la API responde el primer resultado otra vez en vez de hacer el trabajo dos veces: un error de red nunca envía un mensaje ni compra un paquete dos veces.

curl -X POST https://api.lanachat.ai/v1/billing/licences/buy \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: 4b7f2a8e-1c3d-4e5f-9a0b-6c7d8e9f0a1b" \
  -H "Content-Type: application/json" \
  -d '{"pack": 10, "qty": 1}'

La misma clave con un cuerpo diferente responde 409. En shell, $(uuidgen) crea una clave nueva para cada acción.

Webhooks #

En vez de preguntar a la API cada minuto, deja que LanaChat te llame. Un webhook envía un POST HTTPS a tu servidor cuando un fan escribe por primera vez, compra, recibe un reembolso, cuando un medio está listo o una cuenta pierde conexión. Cada entrega está firmada (HMAC-SHA256) y se reintenta durante 24 horas. Los eventos, cargas útiles y la verificación de firma en Node y Python están en Webhooks.

MCP para asistentes AI #

MCP es un estándar abierto que permite a un asistente AI usar herramientas en una app. El servidor MCP de LanaChat permite que Claude, Cursor o cualquier cliente MCP lean tus creadoras, redacten scripts, editen un borrador de brain y lean tus ventas, con el mismo token de acceso y permisos. En Claude Code, un comando lo conecta:

claude mcp add --transport http lanachat https://app.lanachat.ai/mcp \
  --header "Authorization: Bearer $LANACHAT_TOKEN"

La configuración para cada asistente y la lista de herramientas están en API & MCP.