Référence API
Interfaces pour développeurs : points de terminaison publics, widget de chat, connexion et API REST avec clés API.
La référence de l'API décrit les interfaces de Zentor App que vous pouvez appeler depuis vos propres sites web et programmes : points de terminaison publics pour les formulaires, le configurateur de produit et le contenu, le widget de chat, le chatbot de démonstration ainsi que la connexion, y compris l'authentification unique (SSO). Chaque page de point de terminaison indique la méthode, le chemin, l'authentification, les paramètres, un exemple de requête et de réponse, et les codes d'erreur documentés.
Authentification : les points de terminaison pour les formulaires, le configurateur de produit et le contenu sont accessibles sans connexion. Les points de terminaison du widget de chat attendent le jeton d'intégration de votre widget dans l'en-tête `X-Widget-Token` et n'acceptent les appels que depuis les domaines approuvés pour le widget. Les points de terminaison de connexion délivrent un jeton d'accès (JWT) et un jeton de renouvellement (refresh token) pour les sessions utilisateur.
Accès API avec clé API : pour vos propres programmes et les connexions serveur à serveur, l'API REST est disponible à l'URL de base `https://zentor-app.de/api/v1`. Zentor active l'accès API pour votre compte sur demande. Les administrateurs créent ensuite leurs propres clés dans le tableau de bord sous « Clés API » et définissent leurs autorisations (scopes) – pour les rendez-vous et réservations, le chatbot, la communication, les fichiers, la base de connaissances, les rapports et les données web. Chaque domaine dispose d'un scope de lecture (`<domaine>.read`, uniquement GET) et d'un scope d'écriture (`<domaine>.write`, incluant la lecture), par exemple `appointments.read` ou `knowledge.write`. Envoyez la clé dans l'en-tête `Authorization: Bearer <clé API>` ou, alternativement, dans l'en-tête `X-API-Key`. Utilisez `GET /api/v1/me` pour vérifier à quel compte et à quels scopes une clé est associée.
La clé complète n'est affichée qu'une seule fois, lors de sa création. Conservez-la en sécurité et uniquement côté serveur, jamais dans le code du navigateur ou dans des applications mobiles. Les clés peuvent recevoir une date d'expiration, être renouvelées et révoquées. Via l'API REST, seules les fonctions incluses dans votre formule sont accessibles, et toutes les données restent limitées à votre compte. Erreurs typiques : 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` ou `API_KEY_REVOKED` (clé manquante, incorrecte, expirée ou révoquée), 403 `API_ACCESS_NOT_ENABLED` (accès API non activé pour le compte), 403 `API_SCOPE_MISSING` (la clé n'a pas le scope nécessaire), 403 `TENANT_NOT_ACTIVE` ou `TENANT_LOCKED` (compte inactif ou verrouillé) et 404 `API_ENDPOINT_NOT_AVAILABLE` (point de terminaison non disponible via l'API REST).
Réponses et limites : tous les points de terminaison répondent en JSON. Une réponse réussie a un statut 2xx et `"ok": true` ; une réponse d'erreur contient un code d'erreur lisible par machine (dans le champ `error` ou `error.code`) et un message. 2 000 requêtes sont possibles par adresse IP en 15 minutes ; des limites plus strictes s'appliquent aux points de terminaison de formulaire, de confirmation et de connexion, indiquées sur la page concernée. En cas de dépassement, le serveur répond 429 `RATE_LIMIT_EXCEEDED`. Les points de terminaison marqués comme non idempotents ne doivent pas être relancés automatiquement après une interruption de connexion, sous peine de créer des requêtes ou des messages en double.
Transmettez mots de passe, jetons, clés API et codes de confirmation uniquement dans le corps de la requête ou dans des en-têtes via HTTPS – jamais dans des URL, des journaux ou des demandes d'assistance.