# API LanaChat: avvio rapido, autenticazione ed errori

_API · 8 min di lettura · Aggiornato 2026-10-22 · https://lanachat.ai/guides/it/api-overview/_

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.

> Note: Questa è la documentazione pubblica dell'API. Gli endpoint contrassegnati come **Planned** sono il contratto pubblicato su cui si basa il backend: non rispondono ancora. La [connessione MCP](https://lanachat.ai/guides/it/api-mcp/) usa gli stessi token di accesso.

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

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

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

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

Ecco fatto: ogni altro endpoint funziona allo stesso modo. Script pronti all'uso sono in [API quick recipes](https://lanachat.ai/guides/it/api-recipes/).

## Ogni risorsa

| Risorsa | Cosa copre | Guida |
|---|---|---|
| Workspace | `GET /workspace`: il workspace e le autorizzazioni del token | Questa pagina |
| Creators | Creators, identità, persona e progresso configurazione | [Creators](https://lanachat.ai/guides/it/api-creators/) |
| Account Telegram | Account, pool, impostazioni pool e stories | [Telegram accounts](https://lanachat.ai/guides/it/api-telegram-accounts/) |
| AI Brains | Brains, bozze, pubblicazione, versioni e Playground | [AI Brains](https://lanachat.ai/guides/it/api-ai-brains/) |
| Scripts | Scripts, step e cartelle | [Scripts](https://lanachat.ai/guides/it/api-scripts/) |
| Vault | Media, cartelle e upload firmati | [Vault](https://lanachat.ai/guides/it/api-vault/) |
| Fans e conversazioni | Fans, liste, vendite di un fan, messaggi, takeover | [Conversations](https://lanachat.ai/guides/it/api-conversations/) |
| Tracking | Link, domini, pixel, eventi e statistiche | [Tracking](https://lanachat.ai/guides/it/api-tracking/) |
| Billing | Saldo, registro, depositi, licenze, prelievi, fatture | [Billing](https://lanachat.ai/guides/it/api-billing/) |
| Team | Membri, ruoli e token di accesso | [Team](https://lanachat.ai/guides/it/api-team/) |
| Webhooks | Eventi inviati al tuo server, firme e ritentativi | [Webhooks](https://lanachat.ai/guides/it/api-webhooks/) |
| MCP | Il server per assistenti AI e i suoi strumenti | [MCP](https://lanachat.ai/guides/it/api-mcp/) |

## URL base e versioni

Ogni percorso in queste guide è relativo a:

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

```text
Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f
```

- Crea, modifica, ruota e revoca token in **Users › API & MCP**, o con gli [endpoint token](https://lanachat.ai/guides/it/api-team/). 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:

| Permesso | In Console | Permette di |
|---|---|---|
| `can_setup` | Gestire la configurazione del workspace | Creators, media, account Telegram, script e membri del team |
| `can_engine` | Accedere alla configurazione AI | Bozze AI Brain, impostazioni AI degli script e test |
| `can_publish` | Pubblicare bozze AI Brain | Pubblicare una bozza di brain (richiede `can_engine`) |
| `can_ai_test` | Testare bozze Advanced AI | Provare bozze che usano Advanced AI (solo workspace owner) |
| `can_ai_tune` | Regolare impostazioni Advanced AI | Modificare sensibilità Advanced AI (solo workspace owner) |
| `can_ai_publish` | Pubblicare profili Advanced AI | Pubblicare profili che usano Advanced AI (solo workspace owner) |
| `can_commercial_reports` | Leggere report esperimenti commerciali | Esperimenti e loro report di revisione (solo workspace owner) |
| `can_fan_read` | Leggere fans e conversazioni | Fans, conversazioni e messaggi, solo lettura |
| `can_fan_import` | Importare cronologia fan | Importare fans e messaggi passati |
| `can_sales_read` | Leggere vendite | Vendite, statistiche e numeri del cruscotto |
| `can_chat` | Nuovo: Chat con fans | Inviare messaggi, reazioni e prendere il controllo di una conversazione |
| `can_tracking` | Nuovo: Gestire il tracciamento | Link, domini, pool, pixel ed eventi |
| `owner` | Token owner | Fatturazione, ruoli, webhook e token di accesso; solo il proprietario del workspace può crearlo |

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

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

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

## Errori

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

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

| Stato | `code` | Quando |
|---|---|---|
| 400 | `invalid_request` | Un campo manca o ha formato errato; `message` indica quale |
| 401 | `unauthorized` | Nessun token, o token revocato o scaduto |
| 402 | `insufficient_balance` | Il saldo non copre un acquisto |
| 403 | `forbidden` | Il token non ha il permesso richiesto dall'endpoint |
| 404 | `not_found` | L'id non esiste in questo workspace |
| 409 | `conflict` | La modifica violerebbe una regola (slug duplicato, ultimo account di invio di una creator) |
| 429 | `rate_limited` | Troppe richieste; attendi i secondi indicati in `Retry-After` |
| 500 | `server_error` | Errore lato server; riprova più tardi con la stessa `Idempotency-Key` |

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

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

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.

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

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

## Articoli correlati

- [Ricette rapide API: copia, incolla, esegui](https://lanachat.ai/guides/it/api-recipes/)
- [API e MCP: collega un assistente AI](https://lanachat.ai/guides/it/api-mcp/)
- [API: webhook, eventi e firme](https://lanachat.ai/guides/it/api-webhooks/)