API LanaChat: început rapid, autentificare și erori

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.

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.

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

export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"

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

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

Cam asta e: toate celelalte endpoint-uri funcționează la fel. Scripturi gata făcute găsești în API quick recipes.

Fiecare resursă #

URL de bază și versiuni #

Fiecare cale din aceste ghiduri este relativă la:

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:

Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f

• Creează, editează, rotește și revocă token-uri în Users › API & MCP, sau cu endpoint-urile pentru token. 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:

• 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, 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:

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

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

Erori #

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

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

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.

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

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.

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.

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

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.