Pregled API-ja

Svaka REST krajnja točka RolChata slijedi jedan ugovor: isti osnovni URL, ista omotnica odgovora, isto straničenje, isti oblik grešaka. Naučite ga jednom i svaka obitelj krajnjih točaka u referenci krajnjih točaka čita se na isti način.

Osnovni URL i verzioniranje

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

Verzija je dio putanje. Dodavanje neobaveznih polja, novih krajnjih točaka ili novih parametara upita sa zadanim vrijednostima nije nekompatibilna promjena i ne povećava verziju. Nekompatibilne promjene izlaze kao v2, a krajnje točke v1 koje se ukidaju rade još najmanje šest mjeseci od najave (pogledajte Ukidanje).

Autentifikacija

Metoda	Zaglavlje	Namjena
JWT bearer	Authorization: Bearer <access_token>	Interaktivne sesije (web aplikacija, mobilne aplikacije)
API ključ	Authorization: Bearer rcp_<secret>	Pozivi između strojeva, API ključevi dodataka
HMAC potpis	X-RolChat-Signature: sha256=…	Dolazni webhookovi iz vaših sustava, pogledajte Webhookovi
Bez	-	Javne krajnje točke widgeta (/widget/…, /forms/…), ograničene stranicom i izvorom

Za integracije koristite API ključ (osobni pristupni token). Ključevi se izrađuju u Postavke → Dodaci → RolChat API ključevi, prikazuju se samo jednom i pohranjuju samo kao sažetak. Ključ nikada ne može više od člana koji ga je izradio: njegovi se opsezi pri svakom pozivu provjeravaju prema trenutačnim ovlastima tog člana. Trajanje JWT-a, zaglavlje X-Account-Id i sesije za više tvrtki opisani su na stranici Autentifikacija.

Omotnica odgovora

Jedan resurs:

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

Popis:

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

Odgovori bez tijela (204 No Content nakon brisanja) i dalje nose zaglavlje X-Request-Id.

Greška:

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

code je strojno čitljiva vrijednost u snake_caseu i prema njoj treba granati logiku; message je na engleskom i namijenjen je zapisnicima. field i details prisutni su kada pomažu i nikada ne sadrže osobne podatke. API nikada ne odgovara s 200 i poljem errors: ako postoje greške, status je 400 ili viši. Potpuni popis kodova nalazi se na stranici Greške.

Straničenje

Krajnje točke popisa koji mogu rasti koriste straničenje kursorom. Zatražite prvu stranicu bez kursora, a zatim vraćajte primljeni next_cursor doslovno:

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

• limit je zadano 50, a najviše 200; veće vrijednosti odbijaju se s 400 validation_failed.
• Kursori su neprozirni i istječu nakon 24 sata (400 validation_failed s code: cursor_expired).
• Rezultati su dosljedni prema snimci napravljenoj pri prvoj stranici: zapisi izbrisani između stranica nestaju, a novi se pojavljuju tek kada krenete ispočetka bez kursora.
• Za klijente koji to više vole šalje se i zaglavlje Link s rel="next" i rel="prev".

Idempotentnost

Uz svaki POST, PATCH ili DELETE šaljite zaglavlje Idempotency-Key (UUID ili ULID, do 255 znakova):

• Prvi zahtjev s ključem se izvršava, a njegov status i tijelo pohranjuju se na 24 sata.
• Ponavljanje s istim ključem i istim tijelom vraća pohranjeni odgovor bez ponovnog izazivanja nuspojava.
• Ponavljanje s istim ključem, ali drugačijim tijelom odbija se s 409 idempotency_key_conflict.

Koristite ga za svaki poziv koji stvara nešto s nuspojavama: slanje poruke, e-pošte ili SMS-a, upućivanje poziva, sve što se naplaćuje. Zahtjevi GET uvijek su idempotentni i zanemaruju zaglavlje.

Ograničenja zahtjeva

Ograničenja se broje po minuti i vežu se uz račun, API ključ ili korisnika (po IP adresi na rutama koje ne traže prijavu). Zadana gornja ograničenja:

Skupina	Zadano ograničenje	U minuti
Zahtjevi bez prijave (po IP adresi)	60	po IP adresi
Prijavljeni korisnik (nadzorna ploča)	1 000	po korisniku
API ključ	1 000	po ključu
Javne krajnje točke widgeta	60 po posjetitelju i 600 po mrežnoj adresi	u minuti
Prijava (/auth/login)	5	po IP adresi
Dolazni webhookovi	300	u minuti
MCP poslužitelj	600	u minuti
OAuth krajnje točke	600	u minuti

Ograničenja su zadane vrijednosti platforme i operator ih može promijeniti; vaš paket ih ne množi, a ograničenja za Enterprise dogovaraju se ugovorom. Krajnje točke s ograničenjima vraćaju:

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

Kada prijeđete ograničenje, odgovor je 429 s code: rate_limited u polju errors i zaglavljem Retry-After u sekundama. Toliko pričekajte prije sljedećeg poziva. Deset neuspjelih prijava zaključava račun na 30 minuta.

Veličine i vremenska ograničenja

Kategorija	Najveće tijelo zahtjeva	Vremensko ograničenje poslužitelja
Zadano	1 MB	30 s
Poruka s privicima	25 MB	30 s
CSV uvoz	50 MB	vraća 202 i radi u pozadini
Slike baze znanja	10 MB	30 s
Bulk API	10 MB	30 s
Pretraživanje	1 MB	10 s
AI zahtjevi	1 MB	60 s
Krajnje točke widgeta	100 KB	30 s

Prevelika tijela dobivaju 413 payload_too_large. Istek vremena kod usluge vraća 504 s code: upstream_timeout i savjetom retry_after kada ponavljanje može pomoći.

Vrste sadržaja, datumi i identifikatori

• Zahtjevi i odgovori su application/json; charset=utf-8. Prijenos datoteka koristi multipart/form-data; CSV izvozi vraćaju text/csv. Neispravan UTF-8 odbija se s 400 validation_failed.
• Vremenske oznake su u formatu ISO-8601 u UTC-u s preciznošću u milisekundama: 2026-04-20T14:23:45.123Z. Na ulazu se prihvaća bilo koji ISO-8601 pomak i normalizira na UTC.
• Identifikatori su neprozirni ULID-ovi ili UUID-ovi. Nema brojčanih ID-ova, a adrese e-pošte i telefonski brojevi nikada se ne pojavljuju u URL-u.

Izolacija zakupaca i ovlasti

Svaki autentificirani zahtjev izvršava se unutar jednog računa. Resurs koji pripada drugom računu ili stranici koju uloga pozivatelja ne obuhvaća odgovara s 404 not_found, a ne 403, kako se nikada ne bi otkrilo postojanje zapisa. Valjan token bez potrebne ovlasti (na primjer contacts.delete) odgovara s 403 forbidden. Neke ovlasti imaju sufiks opsega (conversations.read:own, :team, :all) koji sužava ono što popis vraća.

PATCH prihvaća samo polja u koja se može pisati. id, account_id, created_at, updated_at i polja stanja poput resolved_at samo su za čitanje; slanje nekog od njih vraća 400 validation_failed s details.forbidden_fields. Promjene stanja provode se namjenskim radnjama kao što je POST /tickets/:id/resolve.

Svaki upis bilježi se u revizijski zapisnik računa.

Zaglavlja za praćenje

Svaki odgovor sadrži:

X-Request-Id: req_01HK…

Zapisujte X-Request-Id. To je prvo što će podrška zatražiti.

CORS

Izvor nadzorne ploče u pregledniku je https://app.rolchat.com. Javne krajnje točke widgeta dopuštaju bilo koji izvor ili samo izvore koje potvrdite za stranicu. Pozivi između poslužitelja s API ključem ne podliježu CORS-u.

Ukidanje

1. Promjena se najavljuje u popisu promjena, a pogođena krajnja točka počinje slati Deprecation: true i zaglavlje Sunset s datumom uklanjanja.
2. Javne krajnje točke rade najmanje šest mjeseci od najave.
3. Uklanjanje se događa samo u novoj glavnoj verziji. Unutar v1 promjene su samo dodavanja.

Stanje usluga

Svaka usluga izlaže /healthz (liveness) i /readyz (readiness).