Pregled API-ja

Vsaka končna točka REST RolChat sledi eni pogodbi: isti osnovni URL, ista ovojnica odgovora, isto ostranjevanje, ista oblika napak. Naučite se je enkrat in vsaka družina končnih točk v referenci končnih točk se bere enako.

Osnovni URL in različice

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

Različica je del poti. Dodajanje neobveznih polj, novih končnih točk ali novih parametrov poizvedbe s privzetimi vrednostmi ni nezdružljiva sprememba in ne poviša različice. Nezdružljive spremembe izidejo kot v2, opuščene končne točke v1 pa delujejo še najmanj šest mesecev po objavi (glejte Opuščanje).

Preverjanje pristnosti

Način	Glava	Uporaba
JWT bearer	Authorization: Bearer <access_token>	Interaktivne seje (spletna aplikacija, mobilne aplikacije)
Ključ API	Authorization: Bearer rcp_<secret>	Klici med stroji, ključi API vtičnikov
Podpis HMAC	X-RolChat-Signature: sha256=…	Dohodni webhooki iz vaših sistemov, glejte Webhooki
Brez	-	Javne končne točke widgeta (/widget/…, /forms/…), omejene na spletno mesto in izvor

Za integracije uporabite ključ API (osebni žeton za dostop). Ključi se ustvarijo v Nastavitve → Vtičniki → Ključi API RolChat, prikazani so samo enkrat in shranjeni samo kot zgoščena vrednost. Ključ nikoli ne zmore več kot član, ki ga je ustvaril: njegovi obsegi se pri vsakem klicu preverijo glede na trenutna dovoljenja tega člana. Življenjska doba JWT, glava X-Account-Id in seje za več podjetij so opisane na strani Preverjanje pristnosti.

Ovojnica odgovora

En vir:

{
  "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
  }
}

Odgovori brez telesa (204 No Content po brisanju) še vedno vsebujejo glavo X-Request-Id.

Napaka:

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

code je strojno berljiva vrednost v snake_case in po njej razvejajte logiko; message je v angleščini in namenjen dnevnikom. field in details sta prisotna, ko pomagata, in nikoli ne vsebujeta osebnih podatkov. API nikoli ne odgovori z 200 in poljem errors: če so napake, je stanje 400 ali več. Celoten seznam kod je na strani Napake.

Ostranjevanje

Končne točke seznamov, ki lahko rastejo, uporabljajo ostranjevanje s kazalcem. Zahtevajte prvo stran brez kazalca, nato dobesedno vračajte prejeti next_cursor:

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

• limit je privzeto 50 in največ 200; večje vrednosti so zavrnjene z 400 validation_failed.
• Kazalci so neprosojni in potečejo po 24 urah (400 validation_failed s code: cursor_expired).
• Rezultati so dosledni glede na posnetek, narejen ob prvi strani: zapisi, izbrisani med stranmi, izginejo, novi pa se prikažejo šele, ko začnete znova brez kazalca.
• Za odjemalce, ki jim je to ljubše, se pošlje tudi glava Link z rel="next" in rel="prev".

Idempotentnost

Z vsakim POST, PATCH ali DELETE pošljite glavo Idempotency-Key (UUID ali ULID, do 255 znakov):

• Prva zahteva s ključem se izvede, njeno stanje in telo pa se shranita za 24 ur.
• Ponovitev z istim ključem in istim telesom vrne shranjeni odgovor, ne da bi znova sprožila stranske učinke.
• Ponovitev z istim ključem, a drugačnim telesom je zavrnjena z 409 idempotency_key_conflict.

Uporabite ga pri vsakem klicu, ki ustvari nekaj s stranskimi učinki: pošiljanje sporočila, e-pošte ali SMS-a, klicanje, vse, kar se zaračuna. Zahteve GET so vedno idempotentne in glavo prezrejo.

Omejitve zahtev

Omejitve se štejejo na minuto in se vežejo na račun, ključ API ali uporabnika (na poteh brez prijave na IP naslov). Privzete zgornje meje:

Vedro	Privzeta omejitev	Na minuto
Zahteve brez prijave (po IP naslovu)	60	na IP naslov
Prijavljen uporabnik (nadzorna plošča)	1 000	na uporabnika
Ključ API	1 000	na ključ
Javne končne točke pripomočka	60 na obiskovalca in 600 na omrežni naslov	na minuto
Prijava (/auth/login)	5	na IP naslov
Dohodni webhooki	300	na minuto
Strežnik MCP	600	na minuto
Končne točke OAuth	600	na minuto

Zgornje meje so privzete vrednosti platforme, ki jih lahko spremeni operater; vaš paket jih ne množi, omejitve Enterprise pa so dogovorjene v pogodbi. Končne točke z omejitvami vrnejo:

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

Ko presežete omejitev, je odgovor 429 s code: rate_limited v polju errors in glavo Retry-After v sekundah. Pred naslednjim klicem počakajte toliko časa. Deset neuspešnih prijav zaklene račun za 30 minut.

Velikosti in časovne omejitve

Kategorija	Največje telo zahteve	Časovna omejitev strežnika
Privzeto	1 MB	30 s
Sporočilo s prilogami	25 MB	30 s
Uvoz CSV	50 MB	vrne 202 in teče v ozadju
Slike baze znanja	10 MB	30 s
Bulk API	10 MB	30 s
Iskanje	1 MB	10 s
Zahteve AI	1 MB	60 s
Končne točke widgeta	100 KB	30 s

Prevelika telesa dobijo 413 payload_too_large. Potek časa pri storitvi vrne 504 s code: upstream_timeout in namigom retry_after, ko lahko ponovni poskus pomaga.

Vrste vsebine, datumi in identifikatorji

• Zahteve in odgovori so application/json; charset=utf-8. Nalaganje datotek uporablja multipart/form-data; izvozi CSV vrnejo text/csv. Neveljaven UTF-8 je zavrnjen z 400 validation_failed.
• Časovni žigi so v obliki ISO-8601 v UTC z natančnostjo na milisekunde: 2026-04-20T14:23:45.123Z. Na vhodu je sprejet kateri koli zamik ISO-8601 in normaliziran v UTC.
• Identifikatorji so neprosojni ULID-ji ali UUID-ji. Številskih ID-jev ni, e-poštni naslovi ali telefonske številke pa se nikoli ne pojavijo v URL-ju.

Izolacija najemnikov in dovoljenja

Vsaka zahteva s preverjeno pristnostjo teče v okviru enega računa. Vir, ki pripada drugemu računu ali spletnemu mestu, ki ga vloga klicatelja ne pokriva, odgovori z 404 not_found, ne 403, da se obstoj zapisov nikoli ne razkrije. Veljaven žeton brez zahtevanega dovoljenja (na primer contacts.delete) odgovori z 403 forbidden. Nekatera dovoljenja imajo pripono obsega (conversations.read:own, :team, :all), ki zoži, kaj seznam vrne.

PATCH sprejme samo zapisljiva polja. id, account_id, created_at, updated_at in polja stanja, kot je resolved_at, so samo za branje; pošiljanje katerega od njih vrne 400 validation_failed z details.forbidden_fields. Spremembe stanja potekajo prek namenskih dejanj, kot je POST /tickets/:id/resolve.

Vsak zapis se zabeleži v revizijski dnevnik računa.

Glave za opazovanje

Vsak odgovor vsebuje:

X-Request-Id: req_01HK…

Beležite X-Request-Id. To je prva stvar, ki jo bo zahtevala podpora.

CORS

Izvor nadzorne plošče v brskalniku je https://app.rolchat.com. Javne končne točke widgeta dovoljujejo kateri koli izvor ali samo izvore, ki jih potrdite za spletno mesto. Klici med strežniki s ključem API niso podvrženi CORS.

Opuščanje

1. Sprememba je objavljena v dnevniku sprememb, prizadeta končna točka pa začne pošiljati Deprecation: true in glavo Sunset z datumom odstranitve.
2. Javne končne točke delujejo najmanj šest mesecev po objavi.
3. Odstranitev se zgodi samo v novi glavni različici. Znotraj v1 so spremembe samo dodajanja.

Stanje storitev

Vsaka storitev izpostavi /healthz (liveness) in /readyz (readiness).