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

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

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.

> Note: Esta es la referencia pública de la API. Los endpoints marcados como **Planned** son el contrato publicado desde el que se construye el backend: aún no responden. La [conexión MCP](https://lanachat.ai/guides/es/api-mcp/) usa los mismos tokens de acceso.

## 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](https://lanachat.ai/guides/es/api-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:

```bash
export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"
```

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

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

```js
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);
```

```python
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"])
```

```json
{
  "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](https://lanachat.ai/guides/es/api-recipes/).

## Cada recurso

| Recurso | Qué cubre | Guía |
|---|---|---|
| Workspace | `GET /workspace`: el espacio de trabajo y los permisos del token | Esta página |
| Creators | Creadoras, identidad, persona y progreso de configuración | [Creators](https://lanachat.ai/guides/es/api-creators/) |
| Telegram accounts | Cuentas, pools, configuración de pools e historias | [Telegram accounts](https://lanachat.ai/guides/es/api-telegram-accounts/) |
| AI Brains | Brains, borradores, publicación, versiones y Playground | [AI Brains](https://lanachat.ai/guides/es/api-ai-brains/) |
| Scripts | Scripts, pasos y carpetas | [Scripts](https://lanachat.ai/guides/es/api-scripts/) |
| Vault | Medios, carpetas y subidas firmadas | [Vault](https://lanachat.ai/guides/es/api-vault/) |
| Fans and conversations | Fans, listas, ventas de un fan, mensajes, takeover | [Conversations](https://lanachat.ai/guides/es/api-conversations/) |
| Tracking | Enlaces, dominios, píxeles, eventos y estadísticas | [Tracking](https://lanachat.ai/guides/es/api-tracking/) |
| Billing | Saldo, libro mayor, depósitos, licencias, retiros, facturas | [Billing](https://lanachat.ai/guides/es/api-billing/) |
| Team | Miembros, roles y tokens de acceso | [Team](https://lanachat.ai/guides/es/api-team/) |
| Webhooks | Eventos enviados a tu servidor, firmas y reintentos | [Webhooks](https://lanachat.ai/guides/es/api-webhooks/) |
| MCP | El servidor para asistentes AI y sus herramientas | [MCP](https://lanachat.ai/guides/es/api-mcp/) |

## URL base y versiones

Cada ruta en estas guías es relativa a:

```text
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`:

```text
Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f
```

- Crea, edita, rota y revoca tokens en **Users › API & MCP**, o con los [endpoints de tokens](https://lanachat.ai/guides/es/api-team/). 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:

| Permiso | En la Console | Da acceso a |
|---|---|---|
| `can_setup` | Gestionar configuración del espacio | Creadoras, medios, cuentas de Telegram, scripts y miembros del equipo |
| `can_engine` | Acceder a configuración AI | Borradores de AI Brain, ajustes AI de scripts y pruebas |
| `can_publish` | Publicar borradores de AI Brain | Publicar un borrador de brain (requiere `can_engine`) |
| `can_ai_test` | Probar borradores de AI Avanzada | Probar borradores que usan AI Avanzada (solo espacio dueño) |
| `can_ai_tune` | Ajustar configuración AI Avanzada | Cambiar sensibilidad de AI Avanzada (solo espacio dueño) |
| `can_ai_publish` | Publicar perfiles AI Avanzada | Publicar perfiles que usan AI Avanzada (solo espacio dueño) |
| `can_commercial_reports` | Leer informes de experimentos comerciales | Experimentos y sus informes de revisión (solo espacio dueño) |
| `can_fan_read` | Leer fans y conversaciones | Fans, conversaciones y mensajes, solo lectura |
| `can_fan_import` | Importar historial de fans | Importar fans y mensajes pasados |
| `can_sales_read` | Leer ventas | Ventas, estadísticas y números del panel |
| `can_chat` | Nuevo: chatear con fans | Enviar mensajes, reacciones y tomar control de una conversación |
| `can_tracking` | Nuevo: gestionar seguimiento | Enlaces, dominios, pools, píxeles y eventos |
| `owner` | Token de dueño | Facturación, roles, webhooks y tokens de acceso; solo el dueño del espacio puede crearlo |

- 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](https://lanachat.ai/guides/es/api-vault/), 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:

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

```json
{
  "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`:

```js
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');
```

```python
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:

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

| Estado | `code` | Cuándo |
|---|---|---|
| 400 | `invalid_request` | Falta un campo o tiene formato incorrecto; `message` indica cuál |
| 401 | `unauthorized` | Sin token, o token revocado o expirado |
| 402 | `insufficient_balance` | El saldo no cubre una compra |
| 403 | `forbidden` | El token no tiene el permiso que el endpoint necesita |
| 404 | `not_found` | El id no existe en este espacio |
| 409 | `conflict` | El cambio rompería una regla (un slug duplicado, la última cuenta de envío de una creadora) |
| 429 | `rate_limited` | Demasiadas solicitudes; espera los segundos de `Retry-After` |
| 500 | `server_error` | Fallo de nuestro lado; reintenta luego con la misma `Idempotency-Key` |

`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](https://lanachat.ai/guides/es/api-telegram-accounts/).

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

```js
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.

```bash
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](https://lanachat.ai/guides/es/api-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:

```bash
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](https://lanachat.ai/guides/es/api-mcp/).

## Artículos relacionados

- [Recetas rápidas de API: copiar, pegar, ejecutar](https://lanachat.ai/guides/es/api-recipes/)
- [API y MCP: conecta un asistente de IA](https://lanachat.ai/guides/es/api-mcp/)
- [API: webhooks, eventos y firmas](https://lanachat.ai/guides/es/api-webhooks/)