Довідник API

Інтерфейси для розробників: публічні кінцеві пункти, чат-віджет, вхід і REST API з API-ключами.

Довідник API описує інтерфейси Zentor App, до яких ви можете звертатися з власних сайтів і програм: публічні кінцеві пункти для форм, конфігуратора продуктів і контенту, чат-віджет, демо-чат-бот, а також вхід, включно з єдиним входом (SSO). На сторінці кожного кінцевого пункту вказано метод, шлях, автентифікацію, параметри, приклад запиту та відповіді, а також документовані коди помилок.

Автентифікація: кінцеві пункти для форм, конфігуратора продуктів і контенту доступні без входу. Кінцеві пункти чат-віджета очікують embed-токен вашого віджета в заголовку `X-Widget-Token` і приймають виклики лише з доменів, дозволених для цього віджета. Кінцеві пункти входу видають для сесій користувачів токен доступу (JWT) і refresh-токен.

Доступ до API через API-ключ: для власних програм і серверних інтеграцій доступний REST API за базовою адресою `https://zentor-app.de/api/v1`. Zentor вмикає доступ до API для вашого акаунта за запитом. Після цього адміністратори створюють у панелі керування в розділі «API-ключі» власні ключі та визначають їхні права (скоупи) — для зустрічей і бронювань, чат-бота, комунікації, файлів, бази знань, звітів і веб-даних. Для кожної області є скоуп на читання (`<область>.read`, лише GET) і скоуп на запис (`<область>.write`, включає читання), наприклад `appointments.read` або `knowledge.write`. Надсилайте ключ у заголовку `Authorization: Bearer <API-ключ>` або, альтернативно, у заголовку `X-API-Key`. За допомогою `GET /api/v1/me` ви перевіряєте, якому акаунту та яким скоупам належить ключ.

Повний ключ відображається лише один раз, під час створення. Зберігайте його безпечно та виключно на стороні сервера, ніколи в коді браузера чи мобільних застосунках. Ключам можна задати термін дії, їх можна змінити (ротація) і відкликати. Через REST API доступні лише функції, що входять у ваш пакет, і всі дані обмежені вашим акаунтом. Типові помилки: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` або `API_KEY_REVOKED` (ключ відсутній, неправильний, застарілий або відкликаний), 403 `API_ACCESS_NOT_ENABLED` (доступ до API не ввімкнено для акаунта), 403 `API_SCOPE_MISSING` (ключу не вистачає потрібного скоупу), 403 `TENANT_NOT_ACTIVE` або `TENANT_LOCKED` (акаунт не активний або заблокований) і 404 `API_ENDPOINT_NOT_AVAILABLE` (кінцевий пункт недоступний через REST API).

Відповіді та ліміти: усі кінцеві пункти відповідають у форматі JSON. Успішна відповідь має статус 2xx і `"ok": true`; відповідь з помилкою містить машинозчитуваний код помилки (у полі `error` або `error.code`) і повідомлення. На одну IP-адресу можливо 2000 запитів за 15 хвилин; для кінцевих пунктів форм, підтвердження та входу діють суворіші ліміти, вказані на відповідній сторінці. У разі перевищення сервер відповідає кодом 429 `RATE_LIMIT_EXCEEDED`. Кінцеві пункти, позначені як неідемпотентні, не слід автоматично повторювати після обриву з’єднання, оскільки це може призвести до дублювання запитів або повідомлень.

Передавайте паролі, токени, API-ключі та коди підтвердження лише в тілі запиту або в заголовках через HTTPS — ніколи в URL, журналах чи звертаннях до підтримки.

Автентифікація (5)Вхід, оновлення токена, скидання пароля, завершення SSO — і доступ до API за API-ключем.Публічні форми (11)Контакти, запит консультації, запит доступу, оплата та активація акаунта.Конфігуратор продукту (5)Каталог пакетів, попередній розрахунок ціни, підтвердження email і надсилання конфігурації.Публічний контент (6)Юридичні тексти, маркетингові сторінки, тема та кольори тексту сайту.Чат-віджет (9)Усі ендпоінти, які використовує вбудований чат-віджет на вашому сайті.Демо-чат-бот і SSO (13)Публічний демо-чат-бот і ендпоінти для єдиного входу (SAML/OIDC).
← Повернутися до огляду