# API LanaChat: început rapid, autentificare și erori

_API · 8 min de citit · Actualizat 2026-10-22 · https://lanachat.ai/guides/ro/api-overview/_

Tot ce face echipa ta în Console, poate face și codul tău. API-ul LanaChat citește și modifică întregul tău workspace: creatoare, conturi Telegram, AI Brains, scripturi, Vault, fani și conversații, linkuri de tracking, facturare și echipa ta. Este JSON simplu peste HTTPS, un URL per resursă, cu aceleași permisiuni ca în Console. Webhook-urile trimit evenimente către serverul tău, iar serverul MCP permite unui asistent AI precum Claude sau Cursor să lucreze în workspace-ul tău cu același token.

> Note: Aceasta este referința publică a API-ului. Endpoint-urile marcate **Planned** sunt contractul publicat pe baza căruia este construit backend-ul: încă nu răspund. Conexiunea [MCP](https://lanachat.ai/guides/ro/api-mcp/) folosește aceleași token-uri de acces.

## Ce poți construi

- Un dashboard de vânzări în propriile tale unelte: venitul de azi per creatoare, per link, per sursă.
- Alarme în Slack sau Telegram când un fan cumpără, când o conversație necesită revizuire sau când un cont își pierde conexiunea.
- Un script de configurare care adaugă o creatoare, îi conectează conturile, încarcă Vault-ul și scrie primul script.
- Un pipeline de tracking: creează un link per reclamă, citește click-urile, conversațiile și cumpărătorii la fiecare oră.
- Un asistent AI care redactează scripturi și modificări de persona pentru revizuirea ta, prin [MCP](https://lanachat.ai/guides/ro/api-mcp/).

## Început rapid în 5 minute

1. În Console, deschide **Users › API & MCP** și apasă **Create token**.
2. Denumește-l (de exemplu „Reporting script”), alege **Custom permissions** și bifează ce are nevoie, de exemplu **Read fans and conversations** și **Read sales**.
3. Salvează, apoi apasă **Copy token**. Token-ul este afișat o singură dată.

**4. Păstrează-l într-o variabilă de mediu**, ca să nu stea niciodată în codul tău:

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

**5. Fă primul apel.** Îți returnează workspace-ul și ce poate face token-ul:

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

Cam asta e: toate celelalte endpoint-uri funcționează la fel. Scripturi gata făcute găsești în [API quick recipes](https://lanachat.ai/guides/ro/api-recipes/).

## Fiecare resursă

| Resursă | Ce acoperă | Ghid |
|---|---|---|
| Workspace | `GET /workspace`: workspace-ul și permisiunile token-ului | Această pagină |
| Creators | Creatoare, identitate, persona și progresul configurării | [Creators](https://lanachat.ai/guides/ro/api-creators/) |
| Telegram accounts | Conturi, pool-uri, setări pool și povești | [Telegram accounts](https://lanachat.ai/guides/ro/api-telegram-accounts/) |
| AI Brains | Brains, drafturi, publicare, versiuni și Playground | [AI Brains](https://lanachat.ai/guides/ro/api-ai-brains/) |
| Scripts | Scripturi, pași și foldere | [Scripts](https://lanachat.ai/guides/ro/api-scripts/) |
| Vault | Media, foldere și upload-uri semnate | [Vault](https://lanachat.ai/guides/ro/api-vault/) |
| Fans and conversations | Fani, liste, vânzări ale unui fan, mesaje, preluare | [Conversations](https://lanachat.ai/guides/ro/api-conversations/) |
| Tracking | Linkuri, domenii, pixeli, evenimente și statistici | [Tracking](https://lanachat.ai/guides/ro/api-tracking/) |
| Billing | Sold, registru, depozite, licențe, retrageri, facturi | [Billing](https://lanachat.ai/guides/ro/api-billing/) |
| Team | Membri, roluri și token-uri de acces | [Team](https://lanachat.ai/guides/ro/api-team/) |
| Webhooks | Evenimente trimise către serverul tău, semnături și retry-uri | [Webhooks](https://lanachat.ai/guides/ro/api-webhooks/) |
| MCP | Serverul pentru asistenți AI și uneltele sale | [MCP](https://lanachat.ai/guides/ro/api-mcp/) |

## URL de bază și versiuni

Fiecare cale din aceste ghiduri este relativă la:

```text
https://api.lanachat.ai/v1
```

Versiunea este în cale. O schimbare majoră primește o versiune nouă (`/v2`); câmpuri noi și endpoint-uri noi se adaugă în `/v1` fără notificare, deci ignoră câmpurile necunoscute.

## Autentificare

Fiecare cerere poartă token-ul tău în header-ul `Authorization`, după cuvântul `Bearer`:

```text
Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f
```

- Creează, editează, rotește și revocă token-uri în **Users › API & MCP**, sau cu [endpoint-urile pentru token](https://lanachat.ai/guides/ro/api-team/). Doar proprietarul workspace-ului și proprietarii agențiilor pot accesa acea pagină.
- Un token este afișat o singură dată, când îl creezi. Păstrează-l ca pe o parolă; **Rotate** sau **Revoke** îl poți face din aceeași pagină.
- O cerere fără token valid răspunde cu `401`. Un token fără permisiunea necesară unui endpoint răspunde cu `403`.
- Token-urile nu trebuie niciodată puse în URL sau în cod de browser: apelează API-ul de pe serverul tău.
- Folosește câte un token per script sau asistent, ca să poți schimba sau revoca fiecare separat.

## Workspaces

Un token aparține unui singur workspace, cel în care a fost creat. Fiecare cerere citește și scrie doar în acel workspace; nu există id de workspace în căi. Un token de owner (workspace-ul care gestionează mai multe agenții) poate acționa asupra uneia dintre agențiile sale cu header-ul `LanaChat-Workspace: ws_…`; orice alt token care trimite acest header primește `403`.

## Permisiuni

Fiecare endpoint listează permisiunea de care are nevoie. Sunt cele pe care le bifezi când creezi un token:

| Permisiune | În Console | Oferă |
|---|---|---|
| `can_setup` | Gestionare setup workspace | Creatoare, media, conturi Telegram, scripturi și membri echipă |
| `can_engine` | Acces configurare AI | Drafturi AI Brain, setări AI scripturi și teste |
| `can_publish` | Publicare drafturi AI Brain | Publicarea unui draft de brain (necesită `can_engine`) |
| `can_ai_test` | Testare drafturi AI Avansat | Testarea drafturilor care folosesc AI Avansat (doar workspace owner) |
| `can_ai_tune` | Ajustare setări AI Avansat | Modificarea sensibilității AI Avansat (doar workspace owner) |
| `can_ai_publish` | Publicare profile AI Avansat | Publicarea profilelor care folosesc AI Avansat (doar workspace owner) |
| `can_commercial_reports` | Citire rapoarte experimente comerciale | Experimente și rapoartele lor de revizuire (doar workspace owner) |
| `can_fan_read` | Citire fani și conversații | Fani, conversații și mesaje, doar citire |
| `can_fan_import` | Import istoric fani | Importarea fanilor și mesajelor din trecut |
| `can_sales_read` | Citire vânzări | Vânzări, statistici și cifre din dashboard |
| `can_chat` | Nou: Chat cu fanii | Trimitere mesaje, reacții și preluare conversație |
| `can_tracking` | Nou: Gestionare tracking | Linkuri, domenii, pool-uri, pixeli și evenimente |
| `owner` | Token owner | Facturare, roluri, webhook-uri și token-uri de acces; doar owner-ul workspace-ului îl poate crea |

- Dezactivarea permisiunii **Access AI configuration** (`can_engine`) dezactivează și publicarea, AI Avansat și rapoartele de experimente.
- `can_chat`, `can_tracking` și token-ul `owner` sunt planificate: Console încă nu le oferă.

## Cereri și răspunsuri

- Corpurile sunt JSON (`Content-Type: application/json`), în UTF-8. Upload-urile se fac printr-un [URL semnat](https://lanachat.ai/guides/ro/api-vault/), niciodată prin API.
- Id-urile sunt șiruri cu prefix care indică ce sunt: `cr_` creatoare, `acc_` cont Telegram, `pool_`, `sto_` poveste, `br_` brain, `scr_` script, `med_` media, `fan_`, `conv_` conversație, `msg_`, `lnk_` link, `px_` pixel, `mem_` membru, `tok_` token.
- Timpurile sunt ISO 8601 în UTC (`2026-10-06T14:05:00Z`). Zilele în statistici sunt zile UTC.
- Banii sunt în cenți americani (`amount_cents: 1900` înseamnă $19.00). Telegram Stars sunt numere întregi (`stars: 250`).
- `PATCH` modifică doar câmpurile trimise. `PUT` înlocuiește obiectul complet.
- Un `POST` care creează ceva răspunde cu `201` și obiectul nou; alte apeluri reușite răspund cu `200`.

## Paginare

Fiecare listă răspunde cu o pagină și un cursor către următoarea:

```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` este între 1 și 100, implicit 25.
- `next_cursor` este `null` pe ultima pagină. Cursorul este opac: trimite-l înapoi așa cum este, nu-l construi tu.
- Listele sunt sortate cu cele mai noi primele, dacă endpoint-ul nu spune altfel.

Ca să citești toate paginile, fă un loop până când `next_cursor` este `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")
```

## Erori

O eroare răspunde cu un status 4xx sau 5xx și întotdeauna același corp:

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

| Status | `code` | Când |
|---|---|---|
| 400 | `invalid_request` | Un câmp lipsește sau are format greșit; `message` spune care |
| 401 | `unauthorized` | Fără token, sau token revocat ori expirat |
| 402 | `insufficient_balance` | Soldul nu acoperă o achiziție |
| 403 | `forbidden` | Token-ul nu are permisiunea necesară endpoint-ului |
| 404 | `not_found` | Id-ul nu există în acest workspace |
| 409 | `conflict` | Modificarea ar încălca o regulă (slug duplicat, ultimul cont de trimitere al unei creatoare) |
| 429 | `rate_limited` | Prea multe cereri; așteaptă `Retry-After` secunde |
| 500 | `server_error` | Eroare pe partea noastră; încearcă mai târziu cu același `Idempotency-Key` |

`message` este o propoziție simplă în engleză pe care o poți afișa unei persoane. Ramifică codul după `code`, niciodată după `message`.

## Limite de rată

Fiecare token poate trimite **600 cereri pe minut**. Fiecare răspuns conține `RateLimit-Limit`, `RateLimit-Remaining` și `RateLimit-Reset` (secunde până la resetarea ferestrei). Peste limită API-ul răspunde cu `429` și header `Retry-After`. Trimiterea unui mesaj către un fan este și ea limitată de regulile Telegram: vezi [pool rules](https://lanachat.ai/guides/ro/api-telegram-accounts/).

Un mic helper care așteaptă și încearcă din nou la `429` și `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');
}
```

Folosește-l peste tot: `await lanachat('GET', '/creators')`, `await lanachat('POST', '/links', { … })`.

## Idempotență

Trimite un header `Idempotency-Key` (orice șir unic până la 255 caractere, un UUID este perfect) la fiecare `POST`. Dacă același key revine în 24 de ore, API-ul răspunde cu primul rezultat în loc să facă munca de două ori: o eroare de rețea nu trimite un mesaj sau nu cumpără un pachet de două ori.

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

Același key cu un corp diferit răspunde cu `409`. În shell, `$(uuidgen)` generează o cheie nouă pentru fiecare acțiune.

## Webhook-uri

În loc să întrebi API-ul la fiecare minut, lasă LanaChat să te sune. Un webhook trimite un `POST` HTTPS către serverul tău când un fan scrie prima dată, cumpără, primește refund, când un media este gata sau un cont își pierde conexiunea. Fiecare livrare este semnată (HMAC-SHA256) și retrimisă timp de 24 de ore. Evenimentele, payload-urile și verificarea semnăturii în Node și Python sunt în [Webhooks](https://lanachat.ai/guides/ro/api-webhooks/).

## MCP pentru asistenți AI

MCP este un standard deschis care permite unui asistent AI să folosească unelte într-o aplicație. Serverul MCP al LanaChat permite lui Claude, Cursor sau oricărui client MCP să citească creatoarele tale, să redacteze scripturi, să editeze un draft de brain și să citească vânzările tale, cu același token de acces și aceleași permisiuni. În Claude Code, o comandă îl conectează:

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

Configurarea pentru fiecare asistent și lista de unelte sunt în [API & MCP](https://lanachat.ai/guides/ro/api-mcp/).

## Articole conexe

- [Rețete rapide API: copiază, lipește, rulează](https://lanachat.ai/guides/ro/api-recipes/)
- [API & MCP: conectează un asistent AI](https://lanachat.ai/guides/ro/api-mcp/)
- [API: webhook-uri, evenimente și semnături](https://lanachat.ai/guides/ro/api-webhooks/)