Общ преглед на 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.

Прекратяване на поддръжката

Промяната се обявява в списъка с промени, а засегнатата крайна точка започва да изпраща Deprecation: true и заглавка Sunset с датата на премахване.
Публичните крайни точки продължават да работят поне шест месеца след обявяването.
Премахване има само в нова основна версия. В рамките на v1 промените са само добавящи.

Състояние на услугите

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