Prehľad API

Každý endpoint REST RolChat sa riadi jedným kontraktom: rovnaká základná URL, rovnaká obálka odpovede, rovnaké stránkovanie, rovnaký tvar chýb. Naučte sa ho raz a každá rodina endpointov v referencii endpointov sa bude čítať rovnako.

Základná URL a verzovanie

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

Verzia je súčasťou cesty. Pridanie voliteľných polí, nových endpointov alebo nových parametrov dotazu s predvolenými hodnotami nie je nekompatibilná zmena a verziu nezvyšuje. Nekompatibilné zmeny vychádzajú ako v2 a endpointy v1, pri ktorých sa končí podpora, fungujú ešte najmenej šesť mesiacov od oznámenia (pozrite Ukončovanie podpory).

Overovanie

Metóda	Hlavička	Použitie
JWT bearer	Authorization: Bearer <access_token>	Interaktívne relácie (webová aplikácia, mobilné aplikácie)
Kľúč API	Authorization: Bearer rcp_<secret>	Volania medzi strojmi, kľúče API pluginov
Podpis HMAC	X-RolChat-Signature: sha256=…	Prichádzajúce webhooky z vašich systémov, pozrite Webhooky
Žiadna	-	Verejné endpointy widgetu (/widget/…, /forms/…), obmedzené webom a pôvodom

Na integrácie používajte kľúč API (osobný prístupový token). Kľúče sa vytvárajú v Nastavenia → Pluginy → Kľúče API RolChat, zobrazia sa iba raz a ukladajú sa len ako hash. Kľúč nikdy nesmie viac než člen, ktorý ho vytvoril: jeho rozsahy sa pri každom volaní overujú voči aktuálnym oprávneniam tohto člena. Životnosť JWT, hlavičku X-Account-Id a relácie viacerých firiem opisuje stránka Overovanie.

Obálka odpovede

Jeden zdroj:

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

Zoznam:

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

Odpovede bez tela (204 No Content po zmazaní) stále nesú hlavičku X-Request-Id.

Chyba:

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

code je strojovo čitateľná hodnota v snake_case a podľa nej sa má vetviť logika; message je v angličtine a je určená pre logy. field a details sú prítomné, keď pomáhajú, a nikdy neobsahujú osobné údaje. API nikdy neodpovie 200 s poľom errors: ak sú chyby, stav je 400 alebo vyšší. Úplný zoznam kódov je na stránke Chyby.

Stránkovanie

Endpointy zoznamov, ktoré môžu rásť, používajú stránkovanie kurzorom. Vyžiadajte si prvú stránku bez kurzora a potom vracajte prijatý next_cursor bez zmeny:

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

• limit je predvolene 50 a najviac 200; vyššie hodnoty sa odmietnu s 400 validation_failed.
• Kurzory sú nepriehľadné a exspirujú po 24 hodinách (400 validation_failed s code: cursor_expired).
• Výsledky sú konzistentné voči snímke vytvorenej pri prvej stránke: záznamy zmazané medzi stránkami zmiznú, nové sa objavia až vtedy, keď začnete odznova bez kurzora.
• Pre klientov, ktorí to uprednostňujú, sa posiela aj hlavička Link s rel="next" a rel="prev".

Idempotencia

Posielajte hlavičku Idempotency-Key (UUID alebo ULID, najviac 255 znakov) s každým POST, PATCH alebo DELETE:

• Prvá požiadavka s daným kľúčom sa vykoná a jej stav a telo sa uložia na 24 hodín.
• Opakovanie s rovnakým kľúčom a rovnakým telom vráti uloženú odpoveď bez opätovného vyvolania vedľajších účinkov.
• Opakovanie s rovnakým kľúčom, ale iným telom sa odmietne s 409 idempotency_key_conflict.

Používajte ho pri každom volaní, ktoré vytvára niečo s vedľajšími účinkami: odoslanie správy, e-mailu alebo SMS, uskutočnenie hovoru, čokoľvek, čo sa účtuje. Požiadavky GET sú vždy idempotentné a hlavičku ignorujú.

Limity požiadaviek

Limity sa počítajú za minútu podľa účtu, kľúča API alebo používateľa (pri trasách bez prihlásenia podľa IP adresy). Predvolené stropy:

Vedro	Predvolený limit	Za minútu
Požiadavky bez prihlásenia (podľa IP)	60	na IP
Prihlásený používateľ (administrácia)	1 000	na používateľa
Kľúč API	1 000	na kľúč
Verejné endpointy widgetu	60 na návštevníka a 600 na sieťovú adresu	za minútu
Prihlásenie (/auth/login)	5	na IP
Prichádzajúce webhooky	300	za minútu
Server MCP	600	za minútu
Endpointy OAuth	600	za minútu

Stropy sú predvolené hodnoty platformy a prevádzkovateľ ich môže zmeniť; váš plán ich nenásobí a limity Enterprise sa dojednávajú v zmluve. Endpointy s limitmi vracajú:

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

Po prekročení limitu je odpoveď 429 s code: rate_limited v poli errors a hlavičkou Retry-After v sekundách. Pred ďalším volaním počkajte túto dobu. Desať neúspešných prihlásení zablokuje účet na 30 minút.

Veľkosti a časové limity

Kategória	Max. telo požiadavky	Časový limit servera
Predvolené	1 MB	30 s
Správa s prílohami	25 MB	30 s
Import CSV	50 MB	vracia 202 a beží na pozadí
Obrázky bázy znalostí	10 MB	30 s
Bulk API	10 MB	30 s
Vyhľadávanie	1 MB	10 s
Požiadavky AI	1 MB	60 s
Endpointy widgetu	100 KB	30 s

Príliš veľké telá dostanú 413 payload_too_large. Vypršanie času pri službe vráti 504 s code: upstream_timeout a nápovedou retry_after, keď opakovanie môže pomôcť.

Typy obsahu, dátumy a identifikátory

• Požiadavky a odpovede sú application/json; charset=utf-8. Nahrávanie súborov používa multipart/form-data; exporty CSV vracajú text/csv. Neplatné UTF-8 sa odmietne s 400 validation_failed.
• Časové pečiatky sú vo formáte ISO-8601 v UTC s presnosťou na milisekundy: 2026-04-20T14:23:45.123Z. Na vstupe sa prijíma akýkoľvek posun ISO-8601 a normalizuje sa na UTC.
• Identifikátory sú nepriehľadné ULID alebo UUID. Neexistujú číselné ID a e-mailové adresy ani telefónne čísla sa nikdy neobjavujú v URL.

Izolácia tenantov a oprávnenia

Každá overená požiadavka beží v rámci jedného účtu. Zdroj, ktorý patrí inému účtu alebo webu, na ktorý sa rola volajúceho nevzťahuje, odpovie 404 not_found, nie 403, aby sa nikdy neprezradila existencia záznamov. Platný token bez požadovaného oprávnenia (napríklad contacts.delete) odpovie 403 forbidden. Niektoré oprávnenia majú príponu rozsahu (conversations.read:own, :team, :all), ktorá zužuje, čo zoznam vráti.

PATCH prijíma iba zapisovateľné polia. id, account_id, created_at, updated_at a stavové polia ako resolved_at sú iba na čítanie; odoslanie niektorého z nich vráti 400 validation_failed s details.forbidden_fields. Zmeny stavu prebiehajú cez vyhradené akcie, napríklad POST /tickets/:id/resolve.

Každý zápis sa zaznamená do auditného logu účtu.

Hlavičky pre observabilitu

Každá odpoveď obsahuje:

X-Request-Id: req_01HK…

Logujte X-Request-Id. Je to prvá vec, na ktorú sa podpora opýta.

CORS

Pôvod administrácie v prehliadači je https://app.rolchat.com. Verejné endpointy widgetu povoľujú akýkoľvek pôvod alebo len pôvody, ktoré pre web overíte. Volania medzi servermi s kľúčom API sa CORS netýka.

Ukončovanie podpory

1. Zmena sa oznámi v prehľade zmien a dotknutý endpoint začne posielať Deprecation: true a hlavičku Sunset s dátumom odstránenia.
2. Verejné endpointy fungujú najmenej šesť mesiacov od oznámenia.
3. K odstráneniu dochádza len v novej hlavnej verzii. V rámci v1 sú zmeny iba aditívne.

Stav služieb

Každá služba poskytuje /healthz (liveness) a /readyz (readiness).