Преглед на API

Секоја REST крајна точка на RolChat следи еден договор: ист основен 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 клуч (личен токен за пристап). Клучевите се креираат во Поставки → Плагини → API клучеви на RolChat, се прикажуваат еднаш и се чуваат само како хаш. Клучот никогаш не може да прави повеќе од членот што го креирал: неговите опсези се проверуваат според тековните дозволи на тој член при секој повик. Погледнете Автентикација за траењето на 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 никогаш не одговара со 200 и низа errors: ако има грешки, статусот е 400 или повисок. Целосната листа на кодови е на страницата Грешки.

Пагинација

Крајните точки за листи што можат да растат користат пагинација со курсор. Побарајте ја првата страница без курсор, потоа вратете го добиениот next_cursor непроменет:

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

• limit стандардно е 50, а најмногу 200; поголемите вредности се одбиваат со 400 validation_failed.
• Курсорите се непроѕирни и истекуваат по 24 часа (400 validation_failed со code: cursor_expired).
• Резултатите се конзистентни со снимката направена на првата страница: записите избришани меѓу страниците исчезнуваат, а новите се појавуваат само кога ќе почнете одново без курсор.
• За клиентите што го претпочитаат, се испраќа и заглавие Link со rel="next" и rel="prev".

Идемпотентност

Испраќајте заглавие Idempotency-Key (UUID или ULID, до 255 знаци) со секое POST, PATCH или DELETE:

• Првото барање со клуч се извршува, а неговиот статус и тело се чуваат 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

Кога ќе го надминете ограничувањето, одговорот е 429 со code: rate_limited во низата errors и заглавие 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. Ако сервисот нагоре не одговори навреме, се враќа 504 со code: upstream_timeout и совет retry_after кога повторен обид може да помогне.

Типови содржина, датуми и идентификатори

• Барањата и одговорите се application/json; charset=utf-8. Прикачувањето датотеки користи multipart/form-data; CSV извозите враќаат text/csv. Неважечки UTF-8 се одбива со 400 validation_failed.
• Временските ознаки се ISO-8601 во UTC со прецизност до милисекунда: 2026-04-20T14:23:45.123Z. На влез се прифаќа кое било ISO-8601 поместување и се нормализира во UTC.
• Идентификаторите се непроѕирни ULID или UUID. Нема нумерички ID, а адреси за е-пошта или телефонски броеви никогаш не се појавуваат во URL.

Изолација на клиентите и дозволи

Секое автентицирано барање се извршува во една сметка. Ресурс што припаѓа на друга сметка или на сајт што улогата на повикувачот не го покрива враќа 404 not_found наместо 403, за постоењето на записите никогаш да не протече. Важечки токен без потребната дозвола (на пример contacts.delete) враќа 403 forbidden. Некои дозволи имаат суфикс за опсег (conversations.read:own, :team, :all) што го стеснува она што го враќа листата.

PATCH прифаќа само полиња во кои може да се запишува. id, account_id, created_at, updated_at и полињата за состојба како resolved_at се само за читање; нивното испраќање враќа 400 validation_failed со details.forbidden_fields. Промените на состојбата одат преку посебни акции како POST /tickets/:id/resolve.

Секое запишување се евидентира во дневникот за ревизија на сметката.

Заглавија за набљудливост

Секој одговор содржи:

X-Request-Id: req_01HK…

Запишувајте го X-Request-Id во логот. Тоа е првото нешто што ќе го побара поддршката.

CORS

Потеклото на контролната табла во прелистувачот е https://app.rolchat.com. Јавните крајни точки на виџетот дозволуваат кое било потекло или само потеклата што сте ги потврдиле за сајтот. Повиците меѓу сервери со API клуч не подлежат на CORS.

Застарување

1. Промената се најавува во дневникот на промени, а засегнатата крајна точка почнува да испраќа Deprecation: true и заглавие Sunset со датумот на отстранување.
2. Јавните крајни точки продолжуваат да работат најмалку шест месеци по најавата.
3. Отстранување има само во нова главна верзија. Во рамки на v1 промените само додаваат.

Состојба на сервисите

Секој сервис изложува /healthz (жив) и /readyz (подготвен).