Prezentare generală API

Fiecare endpoint REST RolChat respectă același contract: același URL de bază, aceeași structură a răspunsului, aceeași paginare, aceeași formă a erorilor. Îl înveți o dată și fiecare familie de endpointuri din referința endpointurilor se citește la fel.

URL de bază și versiuni

https://api.rolchat.com/api/v1/

Versiunea se află în cale. Adăugarea de câmpuri opționale, endpointuri noi sau parametri de interogare noi cu valori implicite nu este o modificare incompatibilă și nu schimbă versiunea. Modificările incompatibile sunt publicate ca v2, iar endpointurile v1 depreciate continuă să funcționeze cel puțin șase luni după anunțare (vezi Depreciere).

Autentificare

Metodă	Antet	Folosită pentru
JWT bearer	Authorization: Bearer <access_token>	Sesiuni interactive (aplicația web, aplicațiile mobile)
Cheie API	Authorization: Bearer rcp_<secret>	Apeluri între sisteme, chei API de plugin
Semnătură HMAC	X-RolChat-Signature: sha256=…	Webhook-uri primite de la sistemele tale, vezi Webhook-uri
Niciuna	-	Endpointurile publice ale widgetului (/widget/…, /forms/…), limitate după site și origine

Pentru integrări folosește o cheie API (un token de acces personal). Cheile se creează în Setări → Pluginuri → Chei API RolChat, sunt afișate o singură dată și stocate doar ca hash. O cheie nu poate face niciodată mai mult decât membrul care a creat-o: domeniile ei sunt verificate la fiecare apel în raport cu permisiunile curente ale acelui membru. Vezi Autentificare pentru durata de viață a JWT, antetul X-Account-Id și sesiunile cu mai multe companii.

Structura răspunsului

O singură resursă:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

O listă:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

Răspunsurile fără corp (204 No Content după o ștergere) conțin totuși antetul X-Request-Id.

O eroare:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code este o valoare snake_case care poate fi citită automat și este valoarea pe baza căreia îți construiești logica; message este în engleză și destinat jurnalelor. field și details sunt prezente când ajută și nu conțin niciodată date personale. API-ul nu răspunde niciodată 200 cu un tablou errors: dacă există erori, statusul este 400 sau mai mare. Lista completă a codurilor se află pe pagina Erori.

Paginare

Endpointurile de listare care pot crește folosesc paginare cu cursor. Cere prima pagină fără cursor, apoi trimite înapoi, neschimbat, next_cursor primit:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

• limit are implicit valoarea 50 și maximum 200; valorile mai mari sunt respinse cu 400 validation_failed.
• Cursoarele sunt opace și expiră după 24 de ore (400 validation_failed cu code: cursor_expired).
• Rezultatele sunt consecvente cu instantaneul luat la prima pagină: înregistrările șterse între pagini dispar, iar cele noi apar doar când reiei listarea fără cursor.
• Se trimite și un antet Link cu rel="next" și rel="prev" pentru clienții care îl preferă.

Idempotență

Trimite un antet Idempotency-Key (un UUID sau ULID, de până la 255 de caractere) cu orice POST, PATCH sau DELETE:

• Prima cerere cu o cheie rulează, iar statusul și corpul ei sunt păstrate 24 de ore.
• O repetare cu aceeași cheie și același corp returnează răspunsul păstrat, fără a rula din nou efectele secundare.
• O repetare cu aceeași cheie, dar cu un corp diferit, este respinsă cu 409 idempotency_key_conflict.

Folosește-o pentru fiecare apel care creează ceva cu efecte secundare: trimiterea unui mesaj, a unui e-mail sau a unui SMS, inițierea unui apel, orice se facturează. Cererile GET sunt întotdeauna idempotente și ignoră antetul.

Limite de rată

Limitele se numără pe minut și sunt legate de cont, de cheia API sau de utilizator (de adresa IP pe rutele care nu cer autentificare). Plafoanele implicite:

Găleată	Limită implicită	Pe minut
Cereri fără autentificare (după IP)	60	per IP
Utilizator autentificat (panou)	1 000	per utilizator
Cheie API	1 000	per cheie
Endpointuri publice ale widgetului	60 per vizitator și 600 per adresă de rețea	pe minut
Autentificare (/auth/login)	5	per IP
Webhook-uri primite	300	pe minut
Server MCP	600	pe minut
Endpointuri OAuth	600	pe minut

Plafoanele sunt valorile implicite ale platformei și pot fi schimbate de operator; planul tău nu le înmulțește, iar limitele Enterprise se stabilesc prin contract. Endpointurile cu limită returnează:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

Când depășești o limită, răspunsul este 429 cu code: rate_limited în lista errors și un antet Retry-After în secunde. Așteaptă acest interval înainte de următorul apel. Zece autentificări eșuate blochează contul timp de 30 de minute.

Dimensiuni și timpi limită

Categorie	Corp maxim al cererii	Timp limită pe server
Implicit	1 MB	30 s
Mesaj cu atașamente	25 MB	30 s
Import CSV	50 MB	returnează 202 și rulează în fundal
Imagini din baza de cunoștințe	10 MB	30 s
API pentru operațiuni în masă	10 MB	30 s
Căutare	1 MB	10 s
Cereri AI	1 MB	60 s
Endpointurile widgetului	100 KB	30 s

Corpurile prea mari primesc 413 payload_too_large. Un serviciu din amonte care depășește timpul răspunde 504 cu code: upstream_timeout și o indicație retry_after când o reîncercare poate ajuta.

Tipuri de conținut, date și ID-uri

• Cererile și răspunsurile sunt application/json; charset=utf-8. Încărcările de fișiere folosesc multipart/form-data; exporturile CSV returnează text/csv. UTF-8 invalid este respins cu 400 validation_failed.
• Marcajele de timp sunt ISO-8601 în UTC, cu precizie de milisecundă: 2026-04-20T14:23:45.123Z. Orice decalaj ISO-8601 este acceptat la intrare și normalizat în UTC.
• Identificatorii sunt ULID-uri sau UUID-uri opace. Nu există ID-uri numerice, iar adresele de e-mail sau numerele de telefon nu apar niciodată într-un URL.

Izolarea chiriașilor și permisiuni

Fiecare cerere autentificată rulează în interiorul unui singur cont. O resursă care aparține altui cont sau unui site pe care rolul apelantului nu îl acoperă răspunde 404 not_found, nu 403, pentru ca existența înregistrărilor să nu fie dezvăluită. Un token valid fără permisiunea necesară (de exemplu contacts.delete) răspunde 403 forbidden. Unele permisiuni au un sufix de domeniu (conversations.read:own, :team, :all) care restrânge ce returnează o listă.

PATCH acceptă doar câmpurile care pot fi scrise. id, account_id, created_at, updated_at și câmpurile de stare precum resolved_at sunt doar în citire; trimiterea unuia dintre ele returnează 400 validation_failed cu details.forbidden_fields. Schimbările de stare se fac prin acțiuni dedicate, precum POST /tickets/:id/resolve.

Fiecare scriere este înregistrată în jurnalul de audit al contului.

Antete de observabilitate

Fiecare răspuns conține:

X-Request-Id: req_01HK…

Înregistrează X-Request-Id. Este primul lucru pe care îl cere suportul.

CORS

Originea panoului de control din browser este https://app.rolchat.com. Endpointurile publice ale widgetului permit orice origine sau doar originile pe care le verifici pentru un site. Apelurile de la server la server cu o cheie API nu sunt supuse CORS.

Depreciere

1. Schimbarea este anunțată în jurnalul de modificări, iar endpointul afectat începe să trimită Deprecation: true și un antet Sunset cu data eliminării.
2. Endpointurile publice continuă să funcționeze cel puțin șase luni după anunț.
3. Eliminarea are loc doar într-o nouă versiune majoră. În cadrul v1, modificările sunt doar aditive.

Stare de sănătate

Fiecare serviciu expune /healthz (liveness) și /readyz (readiness).