Справочник 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, журналах или обращениях в поддержку.