Przegląd API

Każdy endpoint REST RolChat działa według jednego kontraktu: ten sam bazowy URL, ta sama koperta odpowiedzi, ta sama paginacja, ten sam format błędów. Poznaj go raz, a każda rodzina endpointów w dokumentacji endpointów będzie czytelna w ten sam sposób.

Bazowy URL i wersjonowanie

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

Wersja jest częścią ścieżki. Dodanie opcjonalnych pól, nowych endpointów lub nowych parametrów zapytania z wartościami domyślnymi nie jest zmianą niekompatybilną i nie podnosi wersji. Zmiany niekompatybilne trafiają do v2, a wycofywane endpointy v1 działają jeszcze co najmniej sześć miesięcy od ogłoszenia (zobacz Wycofywanie).

Uwierzytelnianie

Metoda	Nagłówek	Zastosowanie
JWT bearer	`Authorization: Bearer <access_token>`	Sesje interaktywne (aplikacja webowa, aplikacje mobilne)
Klucz API	`Authorization: Bearer rcp_<secret>`	Wywołania maszyna-maszyna, klucze API wtyczek
Podpis HMAC	`X-RolChat-Signature: sha256=…`	Przychodzące webhooki z Twoich systemów, zobacz Webhooki
Brak	-	Publiczne endpointy widżetu (`/widget/…`, `/forms/…`), ograniczone do strony i pochodzenia

Do integracji używaj klucza API (osobistego tokenu dostępu). Klucze tworzy się w Ustawienia → Wtyczki → Klucze API RolChat; są pokazywane raz i przechowywane tylko jako skrót. Klucz nigdy nie może więcej niż członek, który go utworzył: jego zakresy są sprawdzane względem bieżących uprawnień tego członka przy każdym wywołaniu. Czas życia JWT, nagłówek X-Account-Id i sesje wielu firm opisuje strona Uwierzytelnianie.

Koperta odpowiedzi

Pojedynczy zasób:

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

Lista:

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

Odpowiedzi bez treści (204 No Content po usunięciu) nadal zawierają nagłówek X-Request-Id.

Błąd:

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

code to czytelna dla maszyn wartość w snake_case i to według niej należy rozgałęziać logikę; message jest po angielsku i przeznaczone do logów. field i details pojawiają się, gdy pomagają, i nigdy nie zawierają danych osobowych. API nigdy nie odpowiada 200 z tablicą errors: jeśli są błędy, status wynosi 400 lub więcej. Pełna lista kodów jest na stronie Błędy.

Paginacja

Endpointy list, które mogą rosnąć, używają paginacji kursorowej. Poproś o pierwszą stronę bez kursora, a potem odsyłaj otrzymany next_cursor bez zmian:

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

limit domyślnie wynosi 50, maksymalnie 200; większe wartości są odrzucane z 400 validation_failed.
Kursory są nieprzezroczyste i wygasają po 24 godzinach (400 validation_failed z code: cursor_expired).
Wyniki są spójne względem migawki wykonanej przy pierwszej stronie: rekordy usunięte między stronami znikają, a nowe pojawiają się dopiero, gdy zaczniesz od nowa bez kursora.
Dla klientów, którzy wolą to rozwiązanie, wysyłany jest też nagłówek Link z rel="next" i rel="prev".

Idempotentność

Wysyłaj nagłówek Idempotency-Key (UUID lub ULID, do 255 znaków) z każdym POST, PATCH lub DELETE:

Pierwsze żądanie z danym kluczem jest wykonywane, a jego status i treść są przechowywane przez 24 godziny.
Powtórzenie z tym samym kluczem i tą samą treścią zwraca zapisaną odpowiedź bez ponownego wywoływania skutków ubocznych.
Powtórzenie z tym samym kluczem, ale inną treścią jest odrzucane z 409 idempotency_key_conflict.

Używaj go przy każdym wywołaniu, które tworzy coś ze skutkami ubocznymi: wysłanie wiadomości, e-maila lub SMS-a, wykonanie połączenia, wszystko, co generuje opłaty. Żądania GET są zawsze idempotentne i ignorują ten nagłówek.

Limity żądań

Limity są liczone na minutę i przypisane do konta, klucza API lub użytkownika (do adresu IP w trasach niewymagających logowania). Domyślne progi:

Kubełek	Domyślny limit	Na minutę
Żądania bez logowania (według IP)	60	na IP
Zalogowany użytkownik (panel)	1 000	na użytkownika
Klucz API	1 000	na klucz
Publiczne endpointy widżetu	60 na odwiedzającego i 600 na adres sieciowy	na minutę
Logowanie (`/auth/login`)	5	na IP
Webhooki przychodzące	300	na minutę
Serwer MCP	600	na minutę
Endpointy OAuth	600	na minutę

Progi to domyślne wartości platformy i operator może je zmienić; plan ich nie mnoży, a limity Enterprise są ustalane w umowie. Endpointy z limitami zwracają:

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

Po przekroczeniu limitu odpowiedź to 429 z code: rate_limited w tablicy errors i nagłówkiem Retry-After w sekundach. Zaczekaj tyle czasu przed kolejnym wywołaniem. Dziesięć nieudanych logowań blokuje konto na 30 minut.

Rozmiary i limity czasu

Kategoria	Maks. treść żądania	Limit czasu serwera
Domyślnie	1 MB	30 s
Wiadomość z załącznikami	25 MB	30 s
Import CSV	50 MB	zwraca `202` i działa w tle
Obrazy bazy wiedzy	10 MB	30 s
Bulk API	10 MB	30 s
Wyszukiwanie	1 MB	10 s
Żądania AI	1 MB	60 s
Endpointy widżetu	100 KB	30 s

Zbyt duże treści otrzymują 413 payload_too_large. Przekroczenie czasu po stronie usługi daje 504 z code: upstream_timeout i podpowiedzią retry_after, gdy ponowienie może pomóc.

Typy treści, daty i identyfikatory

Żądania i odpowiedzi mają typ application/json; charset=utf-8. Przesyłanie plików używa multipart/form-data; eksporty CSV zwracają text/csv. Nieprawidłowy UTF-8 jest odrzucany z 400 validation_failed.
Znaczniki czasu są w formacie ISO-8601 w UTC z dokładnością do milisekund: 2026-04-20T14:23:45.123Z. Na wejściu akceptowane jest dowolne przesunięcie ISO-8601, które jest normalizowane do UTC.
Identyfikatory to nieprzezroczyste ULID lub UUID. Nie ma identyfikatorów liczbowych, a adresy e-mail i numery telefonów nigdy nie pojawiają się w URL.

Izolacja najemców i uprawnienia

Każde uwierzytelnione żądanie działa w obrębie jednego konta. Zasób należący do innego konta albo do strony, której nie obejmuje rola wywołującego, odpowiada 404 not_found, a nie 403, aby nigdy nie ujawniać istnienia rekordów. Prawidłowy token bez wymaganego uprawnienia (na przykład contacts.delete) odpowiada 403 forbidden. Niektóre uprawnienia mają sufiks zakresu (conversations.read:own, :team, :all), który zawęża wyniki listy.

PATCH przyjmuje tylko pola zapisywalne. id, account_id, created_at, updated_at i pola stanu, takie jak resolved_at, są tylko do odczytu; wysłanie któregoś z nich zwraca 400 validation_failed z details.forbidden_fields. Zmiany stanu odbywają się przez dedykowane akcje, takie jak POST /tickets/:id/resolve.

Każdy zapis trafia do dziennika audytu konta.

Nagłówki obserwowalności

Każda odpowiedź zawiera:

X-Request-Id: req_01HK…

Loguj X-Request-Id. To pierwsza rzecz, o którą zapyta wsparcie.

CORS

Pochodzenie panelu w przeglądarce to https://app.rolchat.com. Publiczne endpointy widżetu dopuszczają dowolne pochodzenie albo tylko pochodzenia zweryfikowane dla strony. Wywołania serwer-serwer z kluczem API nie podlegają CORS.

Wycofywanie

Zmiana jest ogłaszana w dzienniku zmian, a endpoint, którego dotyczy, zaczyna wysyłać Deprecation: true i nagłówek Sunset z datą usunięcia.
Publiczne endpointy działają co najmniej sześć miesięcy od ogłoszenia.
Usunięcie następuje tylko w nowej wersji głównej. W obrębie v1 zmiany są wyłącznie addytywne.

Stan usług

Każda usługa udostępnia /healthz (liveness) i /readyz (readiness).