API ülevaade

Iga RolChati REST-lõpp-punkt järgib üht lepingut: sama baas-URL, sama vastuse ümbris, sama lehekülgedeks jaotamine, sama vea kuju. Õpi see üks kord selgeks ja iga lõpp-punktide perekond lõpp-punktide viites loeb samamoodi.

Baas-URL ja versioonimine

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

Versioon on teekonnas. Valikuliste väljade, uute lõpp-punktide või vaikeväärtustega uute päringuparameetrite lisamine ei ole ühilduvust rikkuv muudatus ega tõsta versiooni. Ühilduvust rikkuvad muudatused ilmuvad versioonina v2 ning aegunuks märgitud v1 lõpp-punktid töötavad pärast teatamist edasi vähemalt kuus kuud (vaata Aegunuks märkimine).

Autentimine

Meetod	Päis	Kasutatakse
JWT bearer	Authorization: Bearer <access_token>	Interaktiivsed seansid (veebirakendus, mobiilirakendused)
API-võti	Authorization: Bearer rcp_<secret>	Masinatevahelised väljakutsed, pistikprogrammide API-võtmed
HMAC-allkiri	X-RolChat-Signature: sha256=…	Sinu süsteemidest sissetulevad veebihaagid, vaata Veebihaagid
Puudub	-	Avalikud vidina lõpp-punktid (/widget/…, /forms/…), piiratud saidi ja päritoluga

Integratsioonide jaoks kasuta API-võtit (isiklik juurdepääsuluba). Võtmed luuakse jaotises Seaded → Pistikprogrammid → RolChati API-võtmed, neid näidatakse üks kord ja salvestatakse ainult räsina. Võti ei saa kunagi teha rohkem kui liige, kes selle lõi: selle ulatusi kontrollitakse iga väljakutse korral selle liikme praeguste õiguste vastu. JWT eluea, päise X-Account-Id ja mitme ettevõtte seansside kohta vaata Autentimine.

Vastuse ümbris

Üks ressurss:

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

Loend:

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

Sisuta vastused (204 No Content pärast kustutamist) kannavad siiski päist X-Request-Id.

Viga:

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

code on masinloetav snake_case väärtus ja see on väärtus, mille järgi hargneda; message on ingliskeelne ja mõeldud logide jaoks. field ja details on olemas siis, kui need aitavad, ega sisalda kunagi isikuandmeid. API ei vasta kunagi koodiga 200 koos massiiviga errors: kui vead on olemas, on olekukood 400 või kõrgem. Täielik koodide loend on lehel Vead.

Lehekülgedeks jaotamine

Kasvada võivad loendi lõpp-punktid kasutavad kursoripõhist lehekülgedeks jaotamist. Küsi esimest lehte ilma kursorita ja saada seejärel tagasi saadud next_cursor muutmata kujul:

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

• limit on vaikimisi 50 ja maksimaalselt 200; suuremad väärtused lükatakse tagasi vastusega 400 validation_failed.
• Kursorid on läbipaistmatud ja aeguvad 24 tunni järel (400 validation_failed koos code: cursor_expired).
• Tulemused on järjepidevad esimesel lehel tehtud hetktõmmise suhtes: lehtede vahel kustutatud kirjed kaovad, uued kirjed ilmuvad alles siis, kui alustad uuesti ilma kursorita.
• Klientidele, kes seda eelistavad, saadetakse ka päis Link väärtustega rel="next" ja rel="prev".

Idempotentsus

Saada iga POST-, PATCH- või DELETE-päringuga päis Idempotency-Key (UUID või ULID, kuni 255 märki):

• Esimene võtmega päring käivitatakse ning selle olekukood ja sisu salvestatakse 24 tunniks.
• Kordus sama võtme ja sama sisuga tagastab salvestatud vastuse ilma kõrvalmõjusid uuesti käivitamata.
• Kordus sama võtmega, kuid erineva sisuga lükatakse tagasi vastusega 409 idempotency_key_conflict.

Kasuta seda iga väljakutse jaoks, mis loob kõrvalmõjudega midagi: sõnumi, e-kirja või SMS-i saatmine, kõne tegemine, kõik, mis toob kaasa arve. GET-päringud on alati idempotentsed ja eiravad seda päist.

Kasutuspiirangud

Piiranguid loetakse minuti kaupa ning need seotakse konto, API-võtme või kasutajaga (IP-aadressiga marsruutidel, mis sisselogimist ei nõua). Vaikepiirid:

Ämber	Vaikepiir	Minutis
Päringud ilma sisselogimiseta (IP järgi)	60	IP kohta
Sisselogitud kasutaja (juhtpaneel)	1 000	kasutaja kohta
API-võti	1 000	võtme kohta
Avalikud vidina lõpp-punktid	60 külastaja kohta ja 600 võrguaadressi kohta	minutis
Sisselogimine (/auth/login)	5	IP kohta
Sissetulevad veebihaagid	300	minutis
MCP-server	600	minutis
OAuthi lõpp-punktid	600	minutis

Piirid on platvormi vaikeväärtused ja operaator saab neid muuta; teie pakett neid ei korruta ning Enterprise’i piirid lepitakse kokku lepingus. Kasutuspiiranguga lõpp-punktid tagastavad:

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

Piiri ületamisel on vastus 429, milles on errors-massiivis code: rate_limited ja päis Retry-After sekundites. Oodake nii kaua enne järgmist kutset. Kümme ebaõnnestunud sisselogimist lukustavad konto 30 minutiks.

Suurused ja ajalõpud

Kategooria	Päringu sisu maksimum	Serveri ajalõpp
Vaikimisi	1 MB	30 s
Sõnum koos manustega	25 MB	30 s
CSV-import	50 MB	tagastab 202 ja töötab taustal
Teadmusbaasi pildid	10 MB	30 s
Hulgi-API	10 MB	30 s
Otsing	1 MB	10 s
AI-päringud	1 MB	60 s
Vidina lõpp-punktid	100 KB	30 s

Liiga suur sisu saab vastuse 413 payload_too_large. Ajalõpu ületanud ülesvoolu teenus vastab 504 koos code: upstream_timeout ja vihjega retry_after, kui kordus võib aidata.

Sisutüübid, kuupäevad ja ID-d

• Päringud ja vastused on application/json; charset=utf-8. Failide üleslaadimine kasutab multipart/form-data; CSV-eksport tagastab text/csv. Vigane UTF-8 lükatakse tagasi vastusega 400 validation_failed.
• Ajatemplid on ISO-8601 vormingus UTC-s millisekundi täpsusega: 2026-04-20T14:23:45.123Z. Sisendis aktsepteeritakse mis tahes ISO-8601 nihet ja see normaliseeritakse UTC-ks.
• Identifikaatorid on läbipaistmatud ULID-id või UUID-d. Numbrilisi ID-sid pole ning e-posti aadressid või telefoninumbrid ei ilmu kunagi URL-i.

Rentnike isoleerimine ja õigused

Iga autenditud päring töötab ühe konto sees. Ressurss, mis kuulub teisele kontole või saidile, mida väljakutsuja roll ei kata, vastab 404 not_found, mitte 403, et kirjete olemasolu kunagi ei lekiks. Kehtiv token ilma nõutava õiguseta (näiteks contacts.delete) vastab 403 forbidden. Mõnel õigusel on ulatuse järelliide (conversations.read:own, :team, :all), mis kitsendab, mida loend tagastab.

PATCH aktsepteerib ainult kirjutatavaid välju. id, account_id, created_at, updated_at ja olekuväljad, näiteks resolved_at, on ainult lugemiseks; mõne neist saatmine tagastab 400 validation_failed koos väljaga details.forbidden_fields. Olekumuutused käivad eraldi toimingute kaudu, näiteks POST /tickets/:id/resolve.

Iga kirjutamine salvestatakse konto auditilogisse.

Jälgitavuse päised

Iga vastus kannab:

X-Request-Id: req_01HK…

Logi X-Request-Id. See on esimene asi, mida tugi küsib.

CORS

Brauseri töölaua päritolu on https://app.rolchat.com. Avalikud vidina lõpp-punktid lubavad mis tahes päritolu või ainult neid päritolusid, mille oled saidi jaoks kinnitanud. API-võtmega serveritevahelistele väljakutsetele CORS ei kehti.

Aegunuks märkimine

1. Muudatusest teatatakse muudatuste logis ja mõjutatud lõpp-punkt hakkab saatma päist Deprecation: true ja päist Sunset eemaldamise kuupäevaga.
2. Avalikud lõpp-punktid töötavad pärast teatamist edasi vähemalt kuus kuud.
3. Eemaldamine toimub ainult uues põhiversioonis. Versiooni v1 sees on muudatused ainult lisavad.

Tervis

Iga teenus avaldab /healthz (elusolek) ja /readyz (valmisolek).