API áttekintés

Minden RolChat REST-végpont ugyanazt a szerződést követi: ugyanaz az alap-URL, ugyanaz a válaszboríték, ugyanaz a lapozás, ugyanaz a hibaformátum. Tanuld meg egyszer, és a végpontreferencia minden végpontcsaládja ugyanúgy olvasható.

Alap-URL és verziókezelés

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

A verzió az útvonalban szerepel. Opcionális mezők, új végpontok vagy alapértelmezett értékkel rendelkező új lekérdezési paraméterek hozzáadása nem visszafelé nem kompatibilis változás, és nem növeli a verziószámot. A visszafelé nem kompatibilis változások v2 néven jelennek meg, az elavult v1 végpontok pedig a bejelentésüktől számítva legalább hat hónapig tovább működnek (lásd: Elavulttá nyilvánítás).

Hitelesítés

Módszer	Fejléc	Mire használható
JWT bearer	`Authorization: Bearer <access_token>`	Interaktív munkamenetek (a webalkalmazás, mobilalkalmazások)
API-kulcs	`Authorization: Bearer rcp_<secret>`	Gépek közötti hívások, plugin API-kulcsok
HMAC-aláírás	`X-RolChat-Signature: sha256=…`	A saját rendszereidből érkező bejövő webhookok, lásd: Webhookok
Nincs	-	Nyilvános widget-végpontok (`/widget/…`, `/forms/…`), webhely és eredet szerint korlátozva

Integrációkhoz API-kulcsot (személyes hozzáférési tokent) használj. A kulcsok a Beállítások → Pluginek → RolChat API-kulcsok menüben hozhatók létre, egyszer jelennek meg, és csak hash formájában tárolódnak. Egy kulcs soha nem tehet többet, mint az a tag, aki létrehozta: a hatóköreit minden hívásnál összevetjük a tag aktuális jogosultságaival. A JWT-élettartamokról, az X-Account-Id fejlécről és a több céget érintő munkamenetekről lásd a Hitelesítés oldalt.

Válaszboríték

Egyetlen erőforrás:

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

Egy lista:

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

A törzs nélküli válaszok (204 No Content törlés után) is tartalmazzák az X-Request-Id fejlécet.

Egy hiba:

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

A code gép által olvasható snake_case érték, és erre érdemes elágazni; a message angol nyelvű, és naplókba szánt. A field és a details akkor szerepel, ha segít, és soha nem tartalmaz személyes adatot. Az API soha nem ad 200 választ errors tömbbel: ha hibák vannak, az állapotkód 400 vagy magasabb. A teljes kódlista a Hibák oldalon található.

Lapozás

A növekedni képes listavégpontok kurzoros lapozást használnak. Az első oldalt kurzor nélkül kérd le, majd add vissza szó szerint a kapott next_cursor értéket:

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

A limit alapértéke 50, felső határa 200; a nagyobb értékeket 400 validation_failed hibával elutasítjuk.
A kurzorok átlátszatlanok, és 24 óra után lejárnak (400 validation_failed, code: cursor_expired).
Az eredmények az első oldalon készült pillanatképhez képest konzisztensek: az oldalak között törölt rekordok eltűnnek, az új rekordok pedig csak akkor jelennek meg, ha kurzor nélkül újrakezded.
Azoknak a klienseknek, amelyek ezt kedvelik, egy rel="next" és rel="prev" értékeket tartalmazó Link fejlécet is küldünk.

Idempotencia

Küldj Idempotency-Key fejlécet (UUID vagy ULID, legfeljebb 255 karakter) bármely POST, PATCH vagy DELETE kéréssel:

A kulccsal érkező első kérés lefut, az állapotkódját és törzsét pedig 24 órán át tároljuk.
Az ugyanazzal a kulccsal és ugyanazzal a törzzsel érkező ismétlés a tárolt választ adja vissza, a mellékhatások újbóli végrehajtása nélkül.
Az ugyanazzal a kulccsal, de eltérő törzzsel érkező ismétlést 409 idempotency_key_conflict hibával elutasítjuk.

Használd minden olyan hívásnál, amely mellékhatással járó dolgot hoz létre: üzenet, e-mail vagy SMS küldése, hívás indítása, bármi, ami számlázással jár. A GET kérések mindig idempotensek, és figyelmen kívül hagyják a fejlécet.

Sebességkorlátok

A korlátokat percenként számoljuk, és a fiókhoz, az API-kulcshoz vagy a felhasználóhoz kötjük (a bejelentkezést nem igénylő útvonalakon az IP-címhez). Az alapértelmezett felső korlátok:

Csoport	Alapértelmezett korlát	Percenként
Bejelentkezés nélküli kérések (IP-cím szerint)	60	IP-címenként
Bejelentkezett felhasználó (vezérlőpult)	1 000	felhasználónként
API-kulcs	1 000	kulcsonként
Nyilvános widget-végpontok	látogatónként 60, hálózati címenként 600	percenként
Bejelentkezés (`/auth/login`)	5	IP-címenként
Bejövő webhookok	300	percenként
MCP-kiszolgáló	600	percenként
OAuth-végpontok	600	percenként

A korlátok a platform alapértelmezései, és az üzemeltető módosíthatja őket; a csomagod nem szorozza meg őket, az Enterprise korlátokról pedig a szerződésben állapodunk meg. A sebességkorlátos végpontok a következőket adják vissza:

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

Ha túllépsz egy korlátot, a válasz 429 lesz, az errors tömbben code: rate_limited értékkel, és másodpercben megadott Retry-After fejléccel. Ennyit várj a következő hívás előtt. Tíz sikertelen bejelentkezés 30 percre zárolja a fiókot.

Méretek és időkorlátok

Kategória	Kéréstörzs maximális mérete	Szerveroldali időkorlát
Alapértelmezett	1 MB	30 s
Üzenet mellékletekkel	25 MB	30 s
CSV-importálás	50 MB	`202` választ ad, és a háttérben fut
Tudásbázisképek	10 MB	30 s
Tömeges API	10 MB	30 s
Keresés	1 MB	10 s
AI-kérések	1 MB	60 s
Widget-végpontok	100 KB	30 s

A túl nagy törzsek 413 payload_too_large választ kapnak. Egy időtúllépésbe futó upstream szolgáltatás esetén a válasz 504 code: upstream_timeout értékkel, és retry_after javaslattal, ha az újrapróbálkozás segíthet.

Tartalomtípusok, dátumok és azonosítók

A kérések és válaszok típusa application/json; charset=utf-8. A fájlfeltöltések multipart/form-data típust használnak; a CSV-exportok text/csv típust adnak vissza. Az érvénytelen UTF-8-at 400 validation_failed hibával elutasítjuk.
Az időbélyegek ISO-8601 formátumúak, UTC-ben, ezredmásodperces pontossággal: 2026-04-20T14:23:45.123Z. Bemenetként bármely ISO-8601 eltolást elfogadunk, és UTC-re normalizáljuk.
Az azonosítók átlátszatlan ULID-ek vagy UUID-k. Numerikus azonosítók nincsenek, és e-mail-címek vagy telefonszámok soha nem szerepelnek URL-ben.

Bérlői elkülönítés és jogosultságok

Minden hitelesített kérés egyetlen fiókon belül fut. Egy másik fiókhoz vagy a hívó szerepköre által le nem fedett webhelyhez tartozó erőforrás 403 helyett 404 not_found választ ad, így a rekordok létezése soha nem szivárog ki. A szükséges jogosultság (például contacts.delete) nélküli érvényes token 403 forbidden választ kap. Egyes jogosultságok hatókör-utótagot viselnek (conversations.read:own, :team, :all), amely szűkíti, mit ad vissza egy lista.

A PATCH csak írható mezőket fogad el. Az id, az account_id, a created_at, az updated_at és az olyan állapotmezők, mint a resolved_at, csak olvashatók; ha ilyet küldesz, 400 validation_failed választ kapsz details.forbidden_fields mezővel. Az állapotváltozások dedikált műveleteken keresztül történnek, például POST /tickets/:id/resolve.

Minden írás bekerül a fiók auditnaplójába.

Megfigyelhetőségi fejlécek

Minden válasz tartalmazza:

X-Request-Id: req_01HK…

Naplózd az X-Request-Id értéket. Az ügyfélszolgálat elsőként ezt kéri.

CORS

A böngészős irányítópult eredete https://app.rolchat.com. A nyilvános widget-végpontok bármely eredetet engedélyeznek, vagy csak azokat, amelyeket egy webhelyhez ellenőriztél. Az API-kulccsal végzett szerverek közötti hívásokra a CORS nem vonatkozik.

Elavulttá nyilvánítás

A változást a változásnaplóban jelentjük be, az érintett végpont pedig elkezdi küldeni a Deprecation: true fejlécet és egy Sunset fejlécet az eltávolítás dátumával.
A nyilvános végpontok a bejelentéstől számítva legalább hat hónapig tovább működnek.
Eltávolítás csak új főverzióban történik. A v1 verzión belül a változások csak bővítő jellegűek.

Állapot

Minden szolgáltatás elérhetővé teszi a /healthz (életjel) és a /readyz (készenlét) végpontot.