API icmalı

Hər RolChat REST endpoint-i vahid müqaviləyə əməl edir: eyni əsas URL, eyni cavab zərfi, eyni səhifələmə, eyni xəta strukturu. Onu bir dəfə öyrənin və endpoint istinadındakı hər endpoint ailəsi eyni şəkildə oxunacaq.

Əsas URL və versiyalaşdırma

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

Versiya yolun içindədir. İstəyə bağlı sahələrin, yeni endpoint-lərin və ya standart dəyərli yeni sorğu parametrlərinin əlavə edilməsi uyğunluğu pozan dəyişiklik deyil və versiyanı artırmır. Uyğunluğu pozan dəyişikliklər v2 kimi buraxılır, köhnəlmiş v1 endpoint-ləri isə elan edildikdən sonra ən azı altı ay işləməyə davam edir (baxın: Köhnəlmə).

Autentifikasiya

Üsul	Başlıq	İstifadə sahəsi
JWT bearer	`Authorization: Bearer <access_token>`	İnteraktiv sessiyalar (veb tətbiq, mobil tətbiqlər)
API açarı	`Authorization: Bearer rcp_<secret>`	Maşından maşına çağırışlar, plagin API açarları
HMAC imzası	`X-RolChat-Signature: sha256=…`	Sistemlərinizdən daxil olan webhook-lar, baxın: Webhook-lar
Yoxdur	-	Sayt və origin ilə məhdudlaşdırılmış açıq vidcet endpoint-ləri (`/widget/…`, `/forms/…`)

İnteqrasiyalar üçün API açarından (şəxsi giriş tokeni) istifadə edin. Açarlar Parametrlər → Plaginlər → RolChat API açarları bölməsində yaradılır, bir dəfə göstərilir və yalnız hash kimi saxlanılır. Açar heç vaxt onu yaradan üzvdən artıq iş görə bilməz: onun scope-ları hər çağırışda həmin üzvün cari icazələri ilə yoxlanılır. JWT müddətləri, X-Account-Id başlığı və çoxşirkətli sessiyalar üçün Autentifikasiya səhifəsinə baxın.

Cavab zərfi

Tək resurs:

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

Siyahı:

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

Gövdəsi olmayan cavablar (silmədən sonra 204 No Content) yenə də X-Request-Id başlığını daşıyır.

Xəta:

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

code maşın tərəfindən oxunan snake_case dəyəridir və məntiqinizi məhz ona görə budaqlandırmalısınız; message ingilis dilindədir və loglar üçün nəzərdə tutulub. field və details faydalı olduqda mövcuddur və heç vaxt şəxsi məlumat ehtiva etmir. API heç vaxt errors massivi ilə 200 cavabı vermir: xətalar varsa, status 400 və ya daha yüksəkdir. Tam kod siyahısı Xətalar səhifəsindədir.

Səhifələmə

Böyüyə bilən siyahı endpoint-ləri kursorla səhifələmədən istifadə edir. İlk səhifəni kursorsuz istəyin, sonra aldığınız next_cursor dəyərini olduğu kimi geri göndərin:

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

limit standart olaraq 50-dir və maksimum 200 ola bilər; daha böyük dəyərlər 400 validation_failed ilə rədd edilir.
Kursorlar qeyri-şəffafdır və 24 saatdan sonra etibarsız olur (code: cursor_expired ilə 400 validation_failed).
Nəticələr ilk səhifədə götürülmüş snapshot-a görə ardıcıldır: səhifələr arasında silinən qeydlər yox olur, yeni qeydlər yalnız kursorsuz yenidən başlayanda görünür.
Buna üstünlük verən müştərilər üçün rel="next" və rel="prev" ilə Link başlığı da göndərilir.

İdempotentlik

İstənilən POST, PATCH və ya DELETE ilə Idempotency-Key başlığı (UUID və ya ULID, 255 simvola qədər) göndərin:

Açarla edilən ilk sorğu icra olunur və onun statusu və gövdəsi 24 saat saxlanılır.
Eyni açar və eyni gövdə ilə təkrar sorğu yan təsirləri yenidən icra etmədən saxlanılmış cavabı qaytarır.
Eyni açar, lakin fərqli gövdə ilə təkrar sorğu 409 idempotency_key_conflict ilə rədd edilir.

Yan təsirli nəsə yaradan hər çağırış üçün istifadə edin: mesaj, e-poçt və ya SMS göndərmək, zəng etmək, ödənişlə bağlı hər şey. GET sorğuları həmişə idempotentdir və başlığı nəzərə almır.

Sorğu limitləri

Limitlər dəqiqə üzrə sayılır və hesaba, API açarına və ya istifadəçiyə görə (giriş tələb etməyən marşrutlarda IP ünvanına görə) tətbiq olunur. Standart həddlər:

Qrup	Standart limit	Dəqiqədə
Girişsiz sorğular (IP üzrə)	60	hər IP üçün
Daxil olmuş istifadəçi (panel)	1 000	hər istifadəçi üçün
API açarı	1 000	hər açar üçün
Açıq vidcet endpoint-ləri	hər ziyarətçi üçün 60 və hər şəbəkə ünvanı üçün 600	dəqiqədə
Giriş (`/auth/login`)	5	hər IP üçün
Daxil olan webhook-lar	300	dəqiqədə
MCP serveri	600	dəqiqədə
OAuth endpoint-ləri	600	dəqiqədə

Bu həddlər platformanın standart dəyərləridir və operator tərəfindən dəyişdirilə bilər; planınız onları artırmır, Enterprise limitləri müqavilənizdə razılaşdırılır. Limitli endpoint-lər bunları qaytarır:

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

Limiti aşdıqda cavab errors massivində code: rate_limited ilə 429 olur və saniyələrlə Retry-After başlığı göndərilir. Növbəti çağırışdan əvvəl bu qədər gözləyin. On uğursuz giriş cəhdi hesabı 30 dəqiqəlik bloklayır.

Ölçülər və taym-autlar

Kateqoriya	Maksimum sorğu gövdəsi	Server taym-autu
Standart	1 MB	30 s
Qoşmalı mesaj	25 MB	30 s
CSV idxalı	50 MB	`202` qaytarır və fonda icra olunur
Bilik bazası şəkilləri	10 MB	30 s
Bulk API	10 MB	30 s
Axtarış	1 MB	10 s
AI sorğuları	1 MB	60 s
Vidcet endpoint-ləri	100 KB	30 s

Həddindən böyük gövdələr 413 payload_too_large alır. Vaxtı bitmiş upstream xidmət, təkrar cəhd kömək edə biləcəyi hallarda code: upstream_timeout və retry_after işarəsi ilə 504 cavabı verir.

Məzmun növləri, tarixlər və ID-lər

Sorğular və cavablar application/json; charset=utf-8 formatındadır. Fayl yükləmələri multipart/form-data istifadə edir; CSV ixracları text/csv qaytarır. Yanlış UTF-8 400 validation_failed ilə rədd edilir.
Vaxt damğaları millisaniyə dəqiqliyi ilə UTC-də ISO-8601 formatındadır: 2026-04-20T14:23:45.123Z. Girişdə istənilən ISO-8601 sürüşməsi qəbul edilir və UTC-yə normallaşdırılır.
İdentifikatorlar qeyri-şəffaf ULID və ya UUID-lərdir. Rəqəmsal ID-lər yoxdur və e-poçt ünvanları və ya telefon nömrələri heç vaxt URL-də görünmür.

Tenant izolyasiyası və icazələr

Autentifikasiyadan keçmiş hər sorğu bir hesab daxilində icra olunur. Başqa hesaba və ya çağıranın rolunun əhatə etmədiyi sayta aid resurs qeydlərin mövcudluğunun heç vaxt sızmaması üçün 403 əvəzinə 404 not_found cavabı verir. Tələb olunan icazəsi olmayan (məsələn, contacts.delete) etibarlı token 403 forbidden cavabı alır. Bəzi icazələr siyahının qaytardıqlarını daraldan əhatə şəkilçisi daşıyır (conversations.read:own, :team, :all).

PATCH yalnız yazıla bilən sahələri qəbul edir. id, account_id, created_at, updated_at və resolved_at kimi vəziyyət sahələri yalnız oxumaq üçündür; onlardan birini göndərmək details.forbidden_fields ilə 400 validation_failed qaytarır. Vəziyyət dəyişiklikləri POST /tickets/:id/resolve kimi xüsusi əməliyyatlarla edilir.

Hər yazma əməliyyatı hesabın audit jurnalına yazılır.

Müşahidə başlıqları

Hər cavab bunları daşıyır:

X-Request-Id: req_01HK…

X-Request-Id dəyərini loglayın. Dəstək komandasının ilk soruşduğu budur.

CORS

Brauzerdəki panelin origin-i https://app.rolchat.com-dur. Açıq vidcet endpoint-ləri istənilən origin-ə və ya yalnız sayt üçün təsdiqlədiyiniz origin-lərə icazə verir. API açarı ilə serverdən serverə çağırışlar CORS-a tabe deyil.

Köhnəlmə

Dəyişiklik dəyişikliklər jurnalında elan edilir və təsirə məruz qalan endpoint Deprecation: true və silinmə tarixi ilə Sunset başlığını göndərməyə başlayır.
Açıq endpoint-lər elandan sonra ən azı altı ay işləməyə davam edir.
Silinmə yalnız yeni əsas versiyada baş verir. v1 daxilində dəyişikliklər yalnız əlavələrdən ibarətdir.

Sağlamlıq

Hər xidmət /healthz (liveness) və /readyz (readiness) təqdim edir.