Přehled API

Každý endpoint REST RolChat se řídí jedním kontraktem: stejná základní URL, stejná obálka odpovědi, stejné stránkování, stejný tvar chyb. Naučte se ho jednou a každá rodina endpointů v referenci endpointů se bude číst stejně.

Základní URL a verzování

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

Verze je součástí cesty. Přidání volitelných polí, nových endpointů nebo nových parametrů dotazu s výchozími hodnotami není nekompatibilní změna a verzi nezvyšuje. Nekompatibilní změny vycházejí jako v2 a endpointy v1, u kterých končí podpora, fungují ještě nejméně šest měsíců od oznámení (viz Ukončování podpory).

Ověřování

Metoda	Hlavička	Použití
JWT bearer	`Authorization: Bearer <access_token>`	Interaktivní relace (webová aplikace, mobilní aplikace)
Klíč API	`Authorization: Bearer rcp_<secret>`	Volání mezi stroji, klíče API pluginů
Podpis HMAC	`X-RolChat-Signature: sha256=…`	Příchozí webhooky z vašich systémů, viz Webhooky
Žádná	-	Veřejné endpointy widgetu (`/widget/…`, `/forms/…`), omezené webem a původem

Pro integrace používejte klíč API (osobní přístupový token). Klíče se vytvářejí v Nastavení → Pluginy → Klíče API RolChat, zobrazí se jen jednou a ukládají se pouze jako hash. Klíč nikdy nesmí víc než člen, který ho vytvořil: jeho rozsahy se při každém volání ověřují vůči aktuálním oprávněním tohoto člena. Životnost JWT, hlavičku X-Account-Id a relace více firem popisuje stránka Ověřování.

Obálka odpovědi

Jeden zdroj:

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

Seznam:

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

Odpovědi bez těla (204 No Content po smazání) stále nesou 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 strojově čitelná hodnota ve snake_case a podle ní se má větvit logika; message je anglicky a je určena pro logy. field a details jsou přítomny, když pomáhají, a nikdy neobsahují osobní údaje. API nikdy neodpoví 200 s polem errors: pokud jsou chyby, stav je 400 nebo vyšší. Úplný seznam kódů je na stránce Chyby.

Stránkování

Endpointy seznamů, které mohou růst, používají stránkování kurzorem. Vyžádejte si první stránku bez kurzoru a pak vracejte přijatý next_cursor beze změny:

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

limit je výchozí 50 a maximálně 200; vyšší hodnoty se odmítnou s 400 validation_failed.
Kurzory jsou neprůhledné a vyprší po 24 hodinách (400 validation_failed s code: cursor_expired).
Výsledky jsou konzistentní vůči snímku pořízenému u první stránky: záznamy smazané mezi stránkami zmizí, nové se objeví až tehdy, když začnete znovu bez kurzoru.
Pro klienty, kteří to preferují, se posílá i hlavička Link s rel="next" a rel="prev".

Idempotence

Posílejte hlavičku Idempotency-Key (UUID nebo ULID, až 255 znaků) s každým POST, PATCH nebo DELETE:

První požadavek s daným klíčem se provede a jeho stav a tělo se uloží na 24 hodin.
Opakování se stejným klíčem a stejným tělem vrátí uloženou odpověď bez opětovného vyvolání vedlejších účinků.
Opakování se stejným klíčem, ale jiným tělem se odmítne s 409 idempotency_key_conflict.

Používejte ho u každého volání, které vytváří něco s vedlejšími účinky: odeslání zprávy, e-mailu nebo SMS, uskutečnění hovoru, cokoli, co se účtuje. Požadavky GET jsou vždy idempotentní a hlavičku ignorují.

Limity požadavků

Limity se počítají za minutu podle účtu, klíče API nebo uživatele (podle IP adresy u tras, které nevyžadují přihlášení). Výchozí stropy:

Kbelík	Výchozí limit	Za minutu
Požadavky bez přihlášení (podle IP)	60	na IP
Přihlášený uživatel (administrace)	1 000	na uživatele
Klíč API	1 000	na klíč
Veřejné endpointy widgetu	60 na návštěvníka a 600 na síťovou adresu	za minutu
Přihlášení (`/auth/login`)	5	na IP
Příchozí webhooky	300	za minutu
Server MCP	600	za minutu
Endpointy OAuth	600	za minutu

Stropy jsou výchozí hodnoty platformy a provozovatel je může změnit; váš tarif je nenásobí a limity Enterprise se sjednávají ve smlouvě. Endpointy s limity vracejí:

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

Po překročení limitu je odpověď 429 s code: rate_limited v poli errors a hlavičkou Retry-After v sekundách. Před dalším voláním tak dlouho počkejte. Deset neúspěšných přihlášení zablokuje účet na 30 minut.

Velikosti a časové limity

Kategorie	Max. tělo požadavku	Časový limit serveru
Výchozí	1 MB	30 s
Zpráva s přílohami	25 MB	30 s
Import CSV	50 MB	vrací `202` a běží na pozadí
Obrázky znalostní báze	10 MB	30 s
Bulk API	10 MB	30 s
Vyhledávání	1 MB	10 s
Požadavky AI	1 MB	60 s
Endpointy widgetu	100 KB	30 s

Příliš velká těla dostanou 413 payload_too_large. Vypršení času u služby vrátí 504 s code: upstream_timeout a nápovědou retry_after, když opakování může pomoci.

Typy obsahu, data a identifikátory

Požadavky a odpovědi jsou application/json; charset=utf-8. Nahrávání souborů používá multipart/form-data; exporty CSV vracejí text/csv. Neplatné UTF-8 se odmítne s 400 validation_failed.
Časová razítka jsou ve formátu ISO-8601 v UTC s přesností na milisekundy: 2026-04-20T14:23:45.123Z. Na vstupu se přijímá jakýkoli posun ISO-8601 a normalizuje se na UTC.
Identifikátory jsou neprůhledné ULID nebo UUID. Neexistují číselná ID a e-mailové adresy ani telefonní čísla se nikdy neobjevují v URL.

Izolace tenantů a oprávnění

Každý ověřený požadavek běží v rámci jednoho účtu. Zdroj, který patří jinému účtu nebo webu, na který se role volajícího nevztahuje, odpoví 404 not_found, ne 403, aby se nikdy neprozradila existence záznamů. Platný token bez požadovaného oprávnění (například contacts.delete) odpoví 403 forbidden. Některá oprávnění mají příponu rozsahu (conversations.read:own, :team, :all), která zužuje, co seznam vrátí.

PATCH přijímá jen zapisovatelná pole. id, account_id, created_at, updated_at a stavová pole jako resolved_at jsou jen pro čtení; odeslání některého z nich vrátí 400 validation_failed s details.forbidden_fields. Změny stavu probíhají přes vyhrazené akce, například POST /tickets/:id/resolve.

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

Hlavičky pro observabilitu

Každá odpověď obsahuje:

X-Request-Id: req_01HK…

Logujte X-Request-Id. Je to první věc, na kterou se podpora zeptá.

CORS

Původ administrace v prohlížeči je https://app.rolchat.com. Veřejné endpointy widgetu povolují jakýkoli původ, nebo jen původy, které pro web ověříte. Volání mezi servery s klíčem API se CORS netýká.

Ukončování podpory

Změna se oznámí v přehledu změn a dotčený endpoint začne posílat Deprecation: true a hlavičku Sunset s datem odstranění.
Veřejné endpointy fungují nejméně šest měsíců od oznámení.
K odstranění dochází jen v nové hlavní verzi. V rámci v1 jsou změny pouze aditivní.

Stav služeb

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