Dokumentacja API
Interfejsy dla programistów: publiczne punkty końcowe, widżet czatu, logowanie i REST API z kluczami API.
Dokumentacja API opisuje interfejsy Zentor App, które można wywoływać z własnych stron internetowych i programów: publiczne punkty końcowe dla formularzy, konfiguratora produktu i treści, widżetu czatu, chatbota demonstracyjnego oraz logowania, w tym jednokrotnego logowania (SSO). Każda strona punktu końcowego podaje metodę, ścieżkę, uwierzytelnianie, parametry, przykład żądania i odpowiedzi oraz udokumentowane kody błędów.
Uwierzytelnianie: punkty końcowe dla formularzy, konfiguratora produktu i treści są dostępne bez logowania. Punkty końcowe widżetu czatu oczekują tokena osadzania widżetu w nagłówku `X-Widget-Token` i przyjmują wywołania tylko z domen zatwierdzonych dla tego widżetu. Punkty końcowe logowania wydają token dostępu (JWT) oraz token odświeżania (refresh token) dla sesji użytkowników.
Dostęp do API z kluczem API: do własnych programów i połączeń serwer–serwer dostępne jest REST API pod bazowym adresem URL `https://zentor-app.de/api/v1`. Zentor aktywuje dostęp do API dla Państwa konta na życzenie. Następnie administratorzy tworzą własne klucze w panelu w sekcji „Klucze API” i określają ich uprawnienia (scope) – dla terminów i rezerwacji, chatbota, komunikacji, plików, bazy wiedzy, raportów i danych webowych. Każdy obszar ma scope do odczytu (`<obszar>.read`, tylko GET) i scope do zapisu (`<obszar>.write`, obejmujący odczyt), na przykład `appointments.read` lub `knowledge.write`. Wyślijcie klucz w nagłówku `Authorization: Bearer <klucz API>` lub alternatywnie w nagłówku `X-API-Key`. Za pomocą `GET /api/v1/me` sprawdzają Państwo, do jakiego konta i jakich scope'ów przypisany jest klucz.
Pełny klucz jest wyświetlany tylko raz, podczas tworzenia. Przechowujcie go bezpiecznie i wyłącznie po stronie serwera, nigdy w kodzie przeglądarki lub aplikacjach mobilnych. Kluczom można nadać datę wygaśnięcia, można je rotować i unieważniać. Przez REST API dostępne są tylko funkcje zawarte w Waszym pakiecie, a wszystkie dane pozostają ograniczone do Waszego konta. Typowe błędy: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` lub `API_KEY_REVOKED` (brak klucza, nieprawidłowy, wygasły lub unieważniony), 403 `API_ACCESS_NOT_ENABLED` (dostęp do API nie aktywowany dla konta), 403 `API_SCOPE_MISSING` (kluczowi brakuje wymaganego scope), 403 `TENANT_NOT_ACTIVE` lub `TENANT_LOCKED` (konto nieaktywne lub zablokowane) oraz 404 `API_ENDPOINT_NOT_AVAILABLE` (punkt końcowy niedostępny przez REST API).
Odpowiedzi i limity: wszystkie punkty końcowe odpowiadają w formacie JSON. Udana odpowiedź ma status 2xx i `"ok": true`; odpowiedź błędu zawiera czytelny dla maszyny kod błędu (w polu `error` lub `error.code`) oraz komunikat. Na adres IP możliwych jest 2000 żądań w ciągu 15 minut; dla punktów końcowych formularzy, potwierdzeń i logowania obowiązują ostrzejsze limity, podane na odpowiedniej stronie. Po przekroczeniu limitu serwer odpowiada 429 `RATE_LIMIT_EXCEEDED`. Punktów końcowych oznaczonych jako nieidempotentne nie należy automatycznie powtarzać po przerwaniu połączenia, ponieważ może to prowadzić do zduplikowanych żądań lub wiadomości.
Przesyłajcie hasła, tokeny, klucze API i kody potwierdzające tylko w treści żądania lub w nagłówkach przez HTTPS – nigdy w adresach URL, dziennikach ani zgłoszeniach do wsparcia.