Referencia API

Interfaces para desarrolladores: endpoints públicos, widget de chat, inicio de sesión y la API REST con claves de API.

La referencia de la API describe las interfaces de Zentor App que puede llamar desde sus propios sitios web y programas: endpoints públicos para formularios, el configurador de producto y contenido, el widget de chat, el chatbot de demostración, así como el inicio de sesión, incluido el inicio de sesión único (SSO). Cada página de endpoint indica el método, la ruta, la autenticación, los parámetros, un ejemplo de solicitud y respuesta, y los códigos de error documentados.

Autenticación: los endpoints de formularios, configurador de producto y contenido son accesibles sin iniciar sesión. Los endpoints del widget de chat esperan el token de inserción de su widget en el encabezado `X-Widget-Token` y solo aceptan llamadas desde los dominios aprobados para ese widget. Los endpoints de inicio de sesión emiten un token de acceso (JWT) y un token de renovación (refresh token) para las sesiones de usuario.

Acceso a la API con clave de API: para sus propios programas y conexiones de servidor a servidor, la API REST está disponible en la URL base `https://zentor-app.de/api/v1`. Zentor activa el acceso a la API para su cuenta a petición. A continuación, los administradores crean sus propias claves en el panel, en «Claves de API», y definen sus permisos (scopes): para citas y reservas, chatbot, comunicación, archivos, base de conocimientos, informes y datos web. Cada ámbito tiene un scope de lectura (`<ámbito>.read`, solo GET) y un scope de escritura (`<ámbito>.write`, que incluye la lectura), por ejemplo `appointments.read` o `knowledge.write`. Envíe la clave en el encabezado `Authorization: Bearer <clave de API>` o, alternativamente, en el encabezado `X-API-Key`. Use `GET /api/v1/me` para comprobar a qué cuenta y qué scopes está asociada una clave.

La clave completa se muestra solo una vez, al crearla. Guárdela de forma segura y exclusivamente en el servidor, nunca en código del navegador ni en aplicaciones móviles. Las claves pueden recibir una fecha de caducidad, rotarse y revocarse. A través de la API REST solo se puede acceder a las funciones incluidas en su paquete, y todos los datos permanecen limitados a su cuenta. Errores típicos: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` o `API_KEY_REVOKED` (clave faltante, incorrecta, caducada o revocada), 403 `API_ACCESS_NOT_ENABLED` (acceso a la API no habilitado para la cuenta), 403 `API_SCOPE_MISSING` (a la clave le falta el scope necesario), 403 `TENANT_NOT_ACTIVE` o `TENANT_LOCKED` (cuenta inactiva o bloqueada) y 404 `API_ENDPOINT_NOT_AVAILABLE` (el endpoint no está disponible a través de la API REST).

Respuestas y límites: todos los endpoints responden con JSON. Una respuesta correcta tiene un estado 2xx y `"ok": true`; una respuesta de error contiene un código de error legible por máquina (en el campo `error` o `error.code`) y un mensaje. Por dirección IP son posibles 2000 solicitudes en 15 minutos; para los endpoints de formularios, confirmación e inicio de sesión se aplican límites más estrictos, indicados en la página correspondiente. Si se supera el límite, el servidor responde 429 `RATE_LIMIT_EXCEEDED`. Los endpoints marcados como no idempotentes no deben repetirse automáticamente tras un fallo de conexión, ya que podrían generarse solicitudes o mensajes duplicados.

Transmita contraseñas, tokens, claves de API y códigos de confirmación únicamente en el cuerpo de la solicitud o en encabezados a través de HTTPS, nunca en URL, registros o solicitudes de soporte.

Autenticación (5)Inicio de sesión, renovación de token, restablecimiento de contraseña, finalización de SSO: y acceso a la API con claves de API.Formularios públicos (11)Contacto, solicitud de asesoramiento, solicitud de acceso, pago y activación de cuenta.Configurador de producto (5)Catálogo de paquetes, vista previa de precios, confirmación por correo electrónico y envío de una configuración.Contenidos públicos (6)Textos legales, páginas de marketing, tema y colores de texto del sitio web.Widget de chat (9)Todos los endpoints que utiliza el widget de chat integrado en su sitio web.Chatbot de demostración y SSO (13)El chatbot de demostración público y los endpoints para el inicio de sesión único (SAML/OIDC).
← Volver al resumen