API apžvalga

Kiekvienas RolChat REST galinis taškas laikosi vienos sutarties: tas pats bazinis URL, tas pats atsakymo apvalkalas, tas pats puslapiavimas, ta pati klaidų forma. Išmokite ją vieną kartą, ir kiekviena galinių taškų šeima galinių taškų žinyne skaitoma taip pat.

Bazinis URL ir versijos

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

Versija nurodoma kelyje. Neprivalomų laukų, naujų galinių taškų ar naujų užklausos parametrų su numatytosiomis reikšmėmis pridėjimas nėra nesuderinamas pakeitimas ir versijos nekeičia. Nesuderinami pakeitimai išleidžiami kaip v2, o nebepalaikomi v1 galiniai taškai veikia dar bent šešis mėnesius po paskelbimo (žr. Nebepalaikymas).

Autentifikavimas

Metodas	Antraštė	Naudojama
JWT bearer	Authorization: Bearer <access_token>	Interaktyvioms sesijoms (žiniatinklio programa, mobiliosios programėlės)
API raktas	Authorization: Bearer rcp_<secret>	Iškvietimams tarp sistemų, įskiepių API raktams
HMAC parašas	X-RolChat-Signature: sha256=…	Gaunamiems webhook’ams iš jūsų sistemų, žr. Webhook’ai
Nėra	-	Viešiems valdiklio galiniams taškams (/widget/…, /forms/…), apribotiems svetaine ir kilme

Integracijoms naudokite API raktą (asmeninį prieigos žetoną). Raktai kuriami skiltyje Nustatymai → Įskiepiai → RolChat API raktai, parodomi vieną kartą ir saugomi tik kaip maiša. Raktas niekada negali padaryti daugiau nei jį sukūręs narys: jo aprėptys kiekvieno iškvietimo metu tikrinamos pagal dabartinius to nario leidimus. Žr. Autentifikavimas apie JWT galiojimo laiką, antraštę X-Account-Id ir kelių įmonių sesijas.

Atsakymo apvalkalas

Vienas išteklius:

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

Sąrašas:

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

Atsakymai be turinio (204 No Content po ištrynimo) vis tiek turi antraštę X-Request-Id.

Klaida:

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

code yra mašinai skaitomas snake_case ir būtent pagal jį reikia šakoti logiką; message yra anglų kalba ir skirtas žurnalams. field ir details pateikiami, kai padeda, ir niekada neturi asmens duomenų. API niekada neatsako 200 su masyvu errors: jei yra klaidų, būsena yra 400 ar didesnė. Visas kodų sąrašas pateiktas puslapyje Klaidos.

Puslapiavimas

Galintys augti sąrašų galiniai taškai naudoja puslapiavimą žymekliu. Pirmo puslapio prašykite be žymeklio, tada nepakeistą grąžinkite gautą next_cursor:

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

• limit numatytai yra 50, o didžiausia reikšmė 200; didesnės reikšmės atmetamos su 400 validation_failed.
• Žymekliai yra nepermatomi ir nustoja galioti po 24 valandų (400 validation_failed su code: cursor_expired).
• Rezultatai nuoseklūs pagal momentinę kopiją, padarytą pirmame puslapyje: tarp puslapių ištrinti įrašai dingsta, nauji įrašai atsiranda tik pradėjus iš naujo be žymeklio.
• Klientams, kurie tai renkasi, taip pat siunčiama antraštė Link su rel="next" ir rel="prev".

Idempotentiškumas

Su bet kuria POST, PATCH ar DELETE užklausa siųskite antraštę Idempotency-Key (UUID arba ULID, iki 255 simbolių):

• Pirma užklausa su raktu įvykdoma, o jos būsena ir turinys saugomi 24 valandas.
• Pakartojimas su tuo pačiu raktu ir tuo pačiu turiniu grąžina išsaugotą atsakymą, šalutinių poveikių nevykdant iš naujo.
• Pakartojimas su tuo pačiu raktu, bet kitu turiniu atmetamas su 409 idempotency_key_conflict.

Naudokite jį kiekvienam iškvietimui, kuris sukuria ką nors su šalutiniais poveikiais: žinutės, el. laiško ar SMS siuntimui, skambučiui, viskam, kas apmokestinama. GET užklausos visada idempotentiškos ir antraštę ignoruoja.

Užklausų limitai

Limitai skaičiuojami per minutę ir susiejami su paskyra, API raktu arba naudotoju (maršrutuose be prisijungimo – su IP adresu). Numatytosios ribos:

Grupė	Numatytasis limitas	Per minutę
Užklausos be prisijungimo (pagal IP)	60	vienam IP
Prisijungęs naudotojas (skydelis)	1 000	vienam naudotojui
API raktas	1 000	vienam raktui
Vieši valdiklio galiniai taškai	60 vienam lankytojui ir 600 vienam tinklo adresui	per minutę
Prisijungimas (/auth/login)	5	vienam IP
Gaunami webhook’ai	300	per minutę
MCP serveris	600	per minutę
OAuth galiniai taškai	600	per minutę

Ribos yra platformos numatytosios ir operatorius gali jas keisti; jūsų planas jų nedaugina, o Enterprise limitai nustatomi sutartyje. Ribojami galiniai taškai grąžina:

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

Viršijus limitą, atsakymas yra 429 su code: rate_limited masyve errors ir antrašte Retry-After sekundėmis. Palaukite tiek laiko prieš kitą iškvietimą. Dešimt nesėkmingų prisijungimų užrakina paskyrą 30 minučių.

Dydžiai ir laiko limitai

Kategorija	Didžiausias užklausos turinys	Serverio laiko limitas
Numatytasis	1 MB	30 s
Žinutė su priedais	25 MB	30 s
CSV importas	50 MB	grąžina 202 ir vykdoma fone
Žinių bazės paveikslėliai	10 MB	30 s
Masinių operacijų API	10 MB	30 s
Paieška	1 MB	10 s
AI užklausos	1 MB	60 s
Valdiklio galiniai taškai	100 KB	30 s

Per dideli turiniai gauna 413 payload_too_large. Laiku neatsakiusi aukštesnio lygio tarnyba atsako 504 su code: upstream_timeout ir užuomina retry_after, kai pakartojimas gali padėti.

Turinio tipai, datos ir ID

• Užklausos ir atsakymai yra application/json; charset=utf-8. Failų įkėlimai naudoja multipart/form-data; CSV eksportas grąžina text/csv. Netinkamas UTF-8 atmetamas su 400 validation_failed.
• Laiko žymos yra ISO-8601 UTC laiku milisekundžių tikslumu: 2026-04-20T14:23:45.123Z. Įvestyje priimamas bet koks ISO-8601 poslinkis, kuris normalizuojamas į UTC.
• Identifikatoriai yra nepermatomi ULID arba UUID. Skaitinių ID nėra, o el. pašto adresai ar telefono numeriai niekada nepatenka į URL.

Nuomininkų izoliacija ir leidimai

Kiekviena autentifikuota užklausa vykdoma vienos paskyros viduje. Išteklius, priklausantis kitai paskyrai arba svetainei, kurios iškvietėjo vaidmuo neapima, atsako 404 not_found, o ne 403, kad niekada neatsiskleistų įrašų egzistavimas. Galiojantis žetonas be reikiamo leidimo (pavyzdžiui, contacts.delete) atsako 403 forbidden. Kai kurie leidimai turi aprėpties priesagą (conversations.read:own, :team, :all), kuri susiaurina, ką grąžina sąrašas.

PATCH priima tik rašomus laukus. id, account_id, created_at, updated_at ir būsenos laukai, tokie kaip resolved_at, yra tik skaitymui; išsiuntus kurį nors iš jų, grąžinama 400 validation_failed su details.forbidden_fields. Būsenos keičiamos per atskirus veiksmus, pavyzdžiui, POST /tickets/:id/resolve.

Kiekvienas rašymas įrašomas į paskyros audito žurnalą.

Stebėjimo antraštės

Kiekvienas atsakymas turi:

X-Request-Id: req_01HK…

Registruokite X-Request-Id. Tai pirmas dalykas, kurio paprašys palaikymo komanda.

CORS

Naršyklės skydelio kilmė yra https://app.rolchat.com. Vieši valdiklio galiniai taškai leidžia bet kokią kilmę arba tik tas kilmes, kurias patvirtinate svetainei. Iškvietimams tarp serverių su API raktu CORS netaikomas.

Nebepalaikymas

1. Pakeitimas paskelbiamas pakeitimų žurnale, o paveiktas galinis taškas pradeda siųsti Deprecation: true ir antraštę Sunset su pašalinimo data.
2. Vieši galiniai taškai veikia dar bent šešis mėnesius po paskelbimo.
3. Pašalinama tik naujoje pagrindinėje versijoje. v1 viduje pakeitimai tik papildo.

Būklė

Kiekviena tarnyba pateikia /healthz (gyvybingumas) ir /readyz (parengtis).