API LanaChat: avvio rapido, autenticazione ed errori

Tutto ciò che il tuo team fa nella Console, può farlo anche il tuo codice. L'API LanaChat legge e modifica l'intero workspace: creators, account Telegram, AI Brains, script, Vault, fans e conversazioni, link di tracciamento, fatturazione e il tuo team. È semplice JSON su HTTPS, un URL per ogni risorsa, con le stesse autorizzazioni della Console. I webhook inviano eventi al tuo server, e il server MCP permette a un assistente AI come Claude o Cursor di lavorare nel tuo workspace con lo stesso token.

Cosa puoi costruire #

• Un cruscotto vendite nei tuoi strumenti: ricavi di oggi per creator, per link, per fonte.
• Avvisi su Slack o Telegram quando un fan acquista, quando una conversazione necessita revisione o quando un account perde la connessione.
• Uno script di configurazione che aggiunge una creator, collega i suoi account, carica il suo Vault e scrive il suo primo script.
• Una pipeline di tracciamento: crea un link per ogni annuncio, leggi clic, conversazioni e acquirenti ogni ora.
• Un assistente AI che prepara bozze di script e modifiche di persona da revisionare, tramite MCP.

Avvio rapido in 5 minuti #

1. Nella Console, apri Users › API & MCP e premi Create token.
2. Dagli un nome (per esempio "Reporting script"), scegli Custom permissions e seleziona ciò che serve, per esempio Read fans and conversations e Read sales.
3. Salva, poi premi Copy token. Il token viene mostrato una sola volta.

4. Conserva il token in una variabile d'ambiente, così non resta mai nel codice:

export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"

5. Fai la tua prima chiamata. Restituisce il workspace e cosa può fare il token:

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

Ecco fatto: ogni altro endpoint funziona allo stesso modo. Script pronti all'uso sono in API quick recipes.

Ogni risorsa #

URL base e versioni #

Ogni percorso in queste guide è relativo a:

https://api.lanachat.ai/v1

La versione è nel percorso. Un cambiamento incompatibile genera una nuova versione (/v2); nuovi campi e endpoint si aggiungono a /v1 senza preavviso, quindi ignora i campi che non conosci.

Autenticazione #

Ogni richiesta porta il token nell'intestazione Authorization, dopo la parola Bearer:

Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f

• Crea, modifica, ruota e revoca token in Users › API & MCP, o con gli endpoint token. Solo il proprietario del workspace e i proprietari dell'agenzia possono aprire quella pagina.
• Un token viene mostrato una sola volta, quando lo crei. Conservalo come una password; Rotate o Revoke dalla stessa pagina.
• Una richiesta senza token valido risponde 401. Un token senza l'autorizzazione richiesta dall'endpoint risponde 403.
• I token non vanno mai messi in un URL o nel codice del browser: chiama l'API dal tuo server.
• Usa un token per script o assistente, così ognuno può essere modificato o revocato singolarmente.

Workspaces #

Un token appartiene a un workspace, quello in cui è stato creato. Ogni richiesta legge e scrive solo in quel workspace; non c'è un id workspace nei percorsi. Un token owner (il workspace che gestisce più agenzie) può agire su una delle sue agenzie con l'intestazione LanaChat-Workspace: ws_…; qualsiasi altro token che invia quell'intestazione riceve 403.

Permessi #

Ogni endpoint indica il permesso richiesto. Sono quelli che selezioni quando crei un token:

• Disattivare Access AI configuration (can_engine) disattiva anche pubblicazione, Advanced AI e report esperimenti.
• can_chat, can_tracking e il token owner sono pianificati: la Console non li offre ancora.

Richieste e risposte #

• I corpi sono JSON (Content-Type: application/json), in UTF-8. Gli upload passano tramite un URL firmato, mai tramite l'API stessa.
• Gli id sono stringhe con un prefisso che indica cosa sono: cr_ creator, acc_ account Telegram, pool_, sto_ story, br_ brain, scr_ script, med_ media, fan_, conv_ conversazione, msg_, lnk_ link, px_ pixel, mem_ membro, tok_ token.
• I tempi sono ISO 8601 in UTC (2026-10-06T14:05:00Z). I giorni nelle statistiche sono giorni UTC.
• Il denaro è in centesimi di dollaro USA (amount_cents: 1900 è $19.00). Telegram Stars sono numeri interi (stars: 250).
• PATCH modifica solo i campi che invii. PUT sostituisce l'intero oggetto.
• Un POST che crea qualcosa risponde 201 con il nuovo oggetto; altre chiamate di successo rispondono 200.

Paginazione #

Ogni lista risponde con una pagina e un cursore per la successiva:

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 va da 1 a 100, default 25.
• next_cursor è null nell'ultima pagina. Un cursore è opaco: passalo così com'è, non crearne uno.
• Le liste sono ordinate dal più recente a meno che l'endpoint non dica altro.

Per leggere tutte le pagine, cicla finché next_cursor è diverso da 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")

Errori #

Un errore risponde con uno status 4xx o 5xx e sempre lo stesso corpo:

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

message è una frase in inglese semplice da mostrare a una persona. Gestisci il codice con code, mai con message.

Limiti di velocità #

Ogni token può inviare 600 richieste al minuto. Ogni risposta include RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (secondi al reset della finestra). Superato il limite l'API risponde 429 con l'intestazione Retry-After. Inviare messaggi a un fan è anche soggetto ai limiti di Telegram: vedi le regole dei pool.

Un piccolo helper che aspetta e ritenta su 429 e 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');
}

Usalo ovunque: await lanachat('GET', '/creators'), await lanachat('POST', '/links', { … }).

Idempotenza #

Invia un'intestazione Idempotency-Key (qualsiasi stringa unica fino a 255 caratteri, un UUID va bene) in ogni POST. Se la stessa chiave arriva entro 24 ore, l'API risponde con il primo risultato invece di eseguire due volte l'azione: un errore di rete non invia mai due volte un messaggio o un acquisto.

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 stessa chiave con un corpo diverso risponde 409. In shell, $(uuidgen) crea una nuova chiave per ogni azione.

Webhook #

Invece di interrogare l'API ogni minuto, lascia che LanaChat ti chiami. Un webhook invia un POST HTTPS al tuo server quando un fan scrive per la prima volta, acquista, viene rimborsato, quando un media è pronto o un account perde la connessione. Ogni consegna è firmata (HMAC-SHA256) e ritentata per 24 ore. Eventi, payload e verifica firma in Node e Python sono in Webhooks.

MCP per assistenti AI #

MCP è uno standard aperto che permette a un assistente AI di usare strumenti in un'app. Il server MCP di LanaChat permette a Claude, Cursor o qualsiasi client MCP di leggere i tuoi creators, preparare bozze di script, modificare una bozza di brain e leggere le tue vendite, con lo stesso token di accesso e le stesse autorizzazioni. In Claude Code, un comando lo collega:

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

La configurazione per ogni assistente e la lista degli strumenti sono in API & MCP.