API шолуы

RolChat-тың әр REST эндпоинті бір келісімшартқа бағынады: бірдей базалық URL, бірдей жауап конверті, бірдей беттеу, қателердің бірдей пішіні. Оны бір рет үйреніңіз, сонда эндпоинттер анықтамасындағы әр эндпоинттер тобы бірдей оқылады.

Базалық URL және нұсқалау

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

Нұсқа жолда көрсетіледі. Міндетті емес өрістерді, жаңа эндпоинттерді немесе әдепкі мәні бар жаңа сұрау параметрлерін қосу үйлесімсіз өзгеріс болып саналмайды және нұсқаны өзгертпейді. Үйлесімсіз өзгерістер v2 ретінде шығады, ал ескірген v1 эндпоинттері жарияланғаннан кейін кемінде алты ай жұмыс істей береді (Қолданыстан шығару бөлімін қараңыз).

Аутентификация

Әдіс	Тақырып	Не үшін қолданылады
JWT bearer	`Authorization: Bearer <access_token>`	Интерактивті сессиялар (веб-қолданба, мобильді қолданбалар)
API кілті	`Authorization: Bearer rcp_<secret>`	Жүйелер арасындағы шақырулар, плагиндердің API кілттері
HMAC қолтаңбасы	`X-RolChat-Signature: sha256=…`	Сіздің жүйелеріңізден келетін кіріс вебхуктар, Вебхуктарды қараңыз
Жоқ	-	Сайт пен дереккөз бойынша шектелген виджеттің жария эндпоинттері (`/widget/…`, `/forms/…`)

Интеграциялар үшін API кілтін (жеке қол жеткізу токенін) пайдаланыңыз. Кілттер Баптаулар → Плагиндер → RolChat API кілттері бөлімінде жасалады, бір рет көрсетіледі және тек хеш түрінде сақталады. Кілт оны жасаған мүшеден артық ештеңе істей алмайды: оның қол жеткізу аймақтары әр шақыруда сол мүшенің ағымдағы рұқсаттарымен салыстырылады. JWT жарамдылық мерзімі, X-Account-Id тақырыбы және бірнеше компаниядағы сессиялар туралы Аутентификация бетін қараңыз.

Жауап конверті

Бір ресурс:

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

Тізім:

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

Денесі жоқ жауаптарда (жойғаннан кейінгі 204 No Content) бәрібір X-Request-Id тақырыбы болады.

Қате:

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

code - snake_case түріндегі машина оқитын мән, логиканы дәл соған қарап тармақтау керек; message ағылшын тілінде және логтарға арналған. field пен details пайдалы болғанда ғана беріледі және ешқашан жеке деректерді қамтымайды. API ешқашан errors жиымымен 200 деп жауап бермейді: қателер болса, күй 400 немесе одан жоғары болады. Кодтардың толық тізімі Қателер бетінде.

Беттеу

Өсуі мүмкін тізім эндпоинттері курсорлық беттеуді қолданады. Алғашқы бетті курсорсыз сұраңыз, содан кейін алған next_cursor мәнін өзгертпей қайтарыңыз:

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

limit әдепкі бойынша 50, ең көбі 200; үлкенірек мәндер 400 validation_failed қатесімен қабылданбайды.
Курсорлар мөлдір емес және 24 сағаттан кейін ескіреді (code: cursor_expired бар 400 validation_failed).
Нәтижелер бірінші бетте түсірілген суретке сәйкес келеді: беттер арасында жойылған жазбалар жоғалады, ал жаңалары курсорсыз қайта бастағанда ғана пайда болады.
Қалайтын клиенттер үшін rel="next" және rel="prev" бар Link тақырыбы да жіберіледі.

Идемпотенттілік

Кез келген POST, PATCH немесе DELETE сұрауымен бірге Idempotency-Key тақырыбын (UUID немесе ULID, 255 таңбаға дейін) жіберіңіз:

Кілті бар алғашқы сұрау орындалады, оның күйі мен денесі 24 сағатқа сақталады.
Сол кілтпен және сол денемен қайталау жанама әсерлерді қайта орындамай, сақталған жауапты қайтарады.
Сол кілтпен, бірақ басқа денемен қайталау 409 idempotency_key_conflict қатесімен қабылданбайды.

Оны жанама әсері бар бірдеңе жасайтын әр шақыруда қолданыңыз: хабарлама, электрондық хат немесе SMS жіберу, қоңырау шалу, ақы алынатын кез келген әрекет. GET сұраулары әрқашан идемпотентті және бұл тақырыпты елемейді.

Сұрау лимиттері

Лимиттер минутына есептеледі және аккаунтқа, API кілтіне немесе пайдаланушыға байланады (кіруді қажет етпейтін маршруттарда - IP мекенжайына). Әдепкі шектер:

Топ	Әдепкі лимит	Минутына
Кірусіз сұраулар (IP бойынша)	60	IP-ге
Кірген пайдаланушы (дашборд)	1 000	пайдаланушыға
API кілті	1 000	кілтке
Виджеттің ашық эндпоинттері	келушіге 60 және желі мекенжайына 600	минутына
Кіру (`/auth/login`)	5	IP-ге
Кіріс вебхуктар	300	минутына
MCP сервері	600	минутына
OAuth эндпоинттері	600	минутына

Шектер - платформаның әдепкі мәндері, оларды оператор өзгерте алады; жоспарыңыз оларды көбейтпейді, ал enterprise лимиттері келісімшартта келісіледі. Лимитке ұшыраған эндпоинттер мынаны қайтарады:

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

Лимиттен асқанда жауап - errors массивінде code: rate_limited бар 429 және секундпен берілген Retry-After тақырыбы. Келесі шақырудан бұрын сонша уақыт күтіңіз. Он сәтсіз кіру әрекеті аккаунтты 30 минутқа бұғаттайды.

Өлшемдер мен күту уақыттары

Санат	Сұрау денесінің ең үлкен өлшемі	Сервердің күту уақыты
Әдепкі	1 MB	30 s
Тіркемелері бар хабарлама	25 MB	30 s
CSV импорты	50 MB	`202` қайтарып, фонда орындалады
Білім базасының суреттері	10 MB	30 s
Bulk API	10 MB	30 s
Іздеу	1 MB	10 s
AI сұраулары	1 MB	60 s
Виджет эндпоинттері	100 KB	30 s

Тым үлкен денелер 413 payload_too_large алады. Жоғары тұрған сервис уақытында жауап бермесе, code: upstream_timeout бар 504 қайтарылады, ал қайталау көмектесуі мүмкін болса, retry_after кеңесі беріледі.

Мазмұн түрлері, күндер және идентификаторлар

Сұраулар мен жауаптар - application/json; charset=utf-8. Файлдарды жүктеу multipart/form-data қолданады; CSV экспорты text/csv қайтарады. Жарамсыз UTF-8 400 validation_failed қатесімен қабылданбайды.
Уақыт белгілері миллисекундқа дейінгі дәлдікпен UTC бойынша ISO-8601 пішімінде: 2026-04-20T14:23:45.123Z. Кірісте кез келген ISO-8601 ығысуы қабылданып, UTC-ге келтіріледі.
Идентификаторлар - мөлдір емес ULID немесе UUID. Сандық ID жоқ, ал электрондық пошта мекенжайлары мен телефон нөмірлері ешқашан URL-де көрінбейді.

Клиенттерді оқшаулау және рұқсаттар

Әр аутентификацияланған сұрау бір аккаунт аясында орындалады. Басқа аккаунтқа немесе шақырушының рөлі қамтымайтын сайтқа тиесілі ресурс 403 емес, 404 not_found деп жауап береді, сондықтан жазбалардың бар екені ешқашан ашылмайды. Қажетті рұқсаты жоқ жарамды токен (мысалы, contacts.delete) 403 forbidden алады. Кейбір рұқсаттарда тізім қайтаратын нәрсені тарылтатын аймақ жұрнағы (conversations.read:own, :team, :all) болады.

PATCH тек жазуға болатын өрістерді қабылдайды. id, account_id, created_at, updated_at және resolved_at сияқты күй өрістері тек оқуға арналған; оларды жіберу details.forbidden_fields бар 400 validation_failed қайтарады. Күй өзгерістері POST /tickets/:id/resolve сияқты арнайы әрекеттер арқылы жүзеге асады.

Әр жазба аккаунттың аудит журналына тіркеледі.

Бақылау тақырыптары

Әр жауапта мыналар бар:

X-Request-Id: req_01HK…

X-Request-Id мәнін логқа жазыңыз. Қолдау қызметі ең алдымен соны сұрайды.

CORS

Браузердегі басқару тақтасының дереккөзі - https://app.rolchat.com. Виджеттің жария эндпоинттері кез келген дереккөзге немесе сайт үшін расталған дереккөздерге ғана рұқсат береді. API кілті бар серверлер арасындағы шақыруларға CORS қолданылмайды.

Қолданыстан шығару

Өзгеріс өзгерістер журналында жарияланады, ал тиісті эндпоинт Deprecation: true және жойылу күні көрсетілген Sunset тақырыбын жібере бастайды.
Жария эндпоинттер жарияланғаннан кейін кемінде алты ай жұмыс істей береді.
Жою тек жаңа негізгі нұсқада болады. v1 ішінде өзгерістер тек қосылады.

Сервистердің күйі

Әр сервис /healthz (тірілік) және /readyz (дайындық) ұсынады.