API pārskats

Katrs RolChat REST galapunkts ievēro vienu līgumu: tas pats bāzes URL, tā pati atbildes aploksne, tā pati lapošana, tā pati kļūdu forma. Apgūstiet to vienreiz, un katra galapunktu saime galapunktu atsaucē lasāma tāpat.

Bāzes URL un versijas

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

Versija ir norādīta ceļā. Neobligātu lauku, jaunu galapunktu vai jaunu vaicājuma parametru ar noklusējuma vērtībām pievienošana nav nesaderīga izmaiņa un nepalielina versiju. Nesaderīgas izmaiņas tiek izlaistas kā v2, un novecojušie v1 galapunkti turpina darboties vismaz sešus mēnešus pēc paziņojuma (skatiet Novecošana).

Autentifikācija

Metode	Galvene	Lieto
JWT bearer	Authorization: Bearer <access_token>	Interaktīvām sesijām (tīmekļa lietotne, mobilās lietotnes)
API atslēga	Authorization: Bearer rcp_<secret>	Mašīna-mašīna izsaukumiem, spraudņu API atslēgām
HMAC paraksts	X-RolChat-Signature: sha256=…	Ienākošajiem webhook no jūsu sistēmām, skatiet Webhooks
Nav	-	Publiskajiem logrīka galapunktiem (/widget/…, /forms/…), ierobežoti ar vietni un izcelsmi

Integrācijām izmantojiet API atslēgu (personīgās piekļuves marķieri). Atslēgas izveido sadaļā Iestatījumi → Spraudņi → RolChat API atslēgas, tās tiek parādītas vienreiz un glabātas tikai kā jaucējvērtība. Atslēga nekad nevar izdarīt vairāk nekā dalībnieks, kurš to izveidoja: tās tvērumi katrā izsaukumā tiek pārbaudīti pret šī dalībnieka pašreizējām atļaujām. Par JWT derīguma termiņiem, galveni X-Account-Id un vairāku uzņēmumu sesijām skatiet Autentifikācija.

Atbildes aploksne

Viens resurss:

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

Saraksts:

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

Atbildes bez satura (204 No Content pēc dzēšanas) tik un tā satur galveni X-Request-Id.

Kļūda:

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

code ir mašīnlasāms snake_case, un tieši pēc tā vērtības jāveido zarošanās; message ir angļu valodā un paredzēts žurnāliem. field un details ir klāt, kad tie palīdz, un nekad nesatur personas datus. API nekad neatbild ar 200 kopā ar masīvu errors: ja ir kļūdas, statuss ir 400 vai augstāks. Pilns kodu saraksts ir lapā Kļūdas.

Lapošana

Saraksta galapunkti, kas var augt, izmanto kursora lapošanu. Pieprasiet pirmo lapu bez kursora, pēc tam nododiet atpakaļ saņemto next_cursor burtiski:

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

• limit pēc noklusējuma ir 50 un nepārsniedz 200; lielākas vērtības tiek noraidītas ar 400 validation_failed.
• Kursori ir necaurredzami un beidzas pēc 24 stundām (400 validation_failed ar code: cursor_expired).
• Rezultāti ir konsekventi attiecībā pret momentuzņēmumu, kas izveidots pirmajā lapā: starp lapām dzēsti ieraksti pazūd, jauni ieraksti parādās tikai tad, kad sākat no jauna bez kursora.
• Klientiem, kas to dod priekšroku, tiek sūtīta arī galvene Link ar rel="next" un rel="prev".

Idempotence

Nosūtiet galveni Idempotency-Key (UUID vai ULID, līdz 255 rakstzīmēm) ar jebkuru POST, PATCH vai DELETE:

• Pirmais pieprasījums ar atslēgu tiek izpildīts, un tā statuss un saturs tiek glabāti 24 stundas.
• Atkārtojums ar to pašu atslēgu un to pašu saturu atgriež saglabāto atbildi, atkārtoti neizpildot blakusefektus.
• Atkārtojums ar to pašu atslēgu, bet citu saturu tiek noraidīts ar 409 idempotency_key_conflict.

Izmantojiet to katram izsaukumam, kas izveido kaut ko ar blakusefektiem: ziņojuma, e-pasta vai SMS sūtīšanai, zvana veikšanai, jebkam, par ko tiek izrakstīts rēķins. GET pieprasījumi vienmēr ir idempotenti un ignorē šo galveni.

Ātruma ierobežojumi

Ierobežojumi tiek skaitīti minūtē un piesaistīti kontam, API atslēgai vai lietotājam (maršrutos, kuriem nav jāpiesakās, — IP adresei). Noklusējuma augšējās robežas:

Grupa	Noklusējuma ierobežojums	Minūtē
Pieprasījumi bez pieteikšanās (pēc IP)	60	katrai IP
Pieteicies lietotājs (panelis)	1 000	katram lietotājam
API atslēga	1 000	katrai atslēgai
Publiskie logrīka galapunkti	60 katram apmeklētājam un 600 katrai tīkla adresei	minūtē
Pieteikšanās (/auth/login)	5	katrai IP
Ienākošie webhook	300	minūtē
MCP serveris	600	minūtē
OAuth galapunkti	600	minūtē

Šīs robežas ir platformas noklusējuma vērtības, un operators tās var mainīt; jūsu plāns tās nepalielina, bet Enterprise ierobežojumi tiek saskaņoti līgumā. Galapunkti ar ātruma ierobežojumu atgriež:

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

Kad pārsniedzat ierobežojumu, atbilde ir 429 ar code: rate_limited masīvā errors un galveni Retry-After sekundēs. Pirms nākamā izsaukuma pagaidiet tik ilgi. Desmit neveiksmīgas pieteikšanās bloķē kontu uz 30 minūtēm.

Izmēri un noildzes

Kategorija	Maks. pieprasījuma saturs	Servera noildze
Noklusējums	1 MB	30 s
Ziņojums ar pielikumiem	25 MB	30 s
CSV imports	50 MB	atgriež 202 un darbojas fonā
Zināšanu bāzes attēli	10 MB	30 s
Lielapjoma API	10 MB	30 s
Meklēšana	1 MB	10 s
AI pieprasījumi	1 MB	60 s
Logrīka galapunkti	100 KB	30 s

Pārāk liels saturs saņem 413 payload_too_large. Augšupējais serviss, kuram iestājusies noildze, atbild ar 504 un code: upstream_timeout, kā arī norādi retry_after, ja atkārtojums var palīdzēt.

Satura tipi, datumi un ID

• Pieprasījumi un atbildes ir application/json; charset=utf-8. Failu augšupielāde izmanto multipart/form-data; CSV eksports atgriež text/csv. Nederīgs UTF-8 tiek noraidīts ar 400 validation_failed.
• Laika zīmogi ir ISO-8601 formātā UTC ar milisekunžu precizitāti: 2026-04-20T14:23:45.123Z. Ievadē tiek pieņemta jebkura ISO-8601 nobīde, un tā tiek normalizēta uz UTC.
• Identifikatori ir necaurredzami ULID vai UUID. Skaitlisku ID nav, un e-pasta adreses vai tālruņa numuri nekad neparādās URL.

Nomnieku izolācija un atļaujas

Katrs autentificēts pieprasījums darbojas viena konta ietvaros. Resurss, kas pieder citam kontam vai vietnei, ko izsaucēja loma neaptver, atbild ar 404 not_found, nevis 403, lai ierakstu esamība nekad netiktu atklāta. Derīgs marķieris bez nepieciešamās atļaujas (piemēram, contacts.delete) atbild ar 403 forbidden. Dažām atļaujām ir tvēruma sufikss (conversations.read:own, :team, :all), kas sašaurina saraksta atgriezto.

PATCH pieņem tikai rakstāmus laukus. id, account_id, created_at, updated_at un stāvokļa lauki, piemēram, resolved_at, ir tikai lasāmi; to nosūtīšana atgriež 400 validation_failed ar details.forbidden_fields. Stāvokļa izmaiņas notiek caur atsevišķām darbībām, piemēram, POST /tickets/:id/resolve.

Katra rakstīšana tiek reģistrēta konta audita žurnālā.

Novērojamības galvenes

Katra atbilde satur:

X-Request-Id: req_01HK…

Reģistrējiet X-Request-Id. Tas ir pirmais, ko prasa atbalsts.

CORS

Pārlūka informācijas paneļa izcelsme ir https://app.rolchat.com. Publiskie logrīka galapunkti atļauj jebkuru izcelsmi vai tikai tās izcelsmes, ko esat verificējis vietnei. Servera-servera izsaukumiem ar API atslēgu CORS neattiecas.

Novecošana

1. Izmaiņa tiek paziņota izmaiņu žurnālā, un attiecīgais galapunkts sāk sūtīt Deprecation: true un galveni Sunset ar noņemšanas datumu.
2. Publiskie galapunkti turpina darboties vismaz sešus mēnešus pēc paziņojuma.
3. Noņemšana notiek tikai jaunā galvenajā versijā. v1 ietvaros izmaiņas ir tikai papildinošas.

Stāvoklis

Katrs serviss nodrošina /healthz (dzīvīgums) un /readyz (gatavība).