Bookivox Documentation

À quoi ça sert

L’intégration Zelty permet à vos agents de consulter vos commandes, vos clients et vos établissements pendant l’appel. Par exemple : vérifier si une commande vient d’être passée, retrouver la fiche d’un client habitué, ou retrouver l’identifiant d’un point de vente avant de filtrer ses commandes. Comme pour les autres intégrations, vous branchez votre propre compte : Bookivox ne fournit aucun identifiant. La clé se génère directement dans le back-office Zelty.

L’intégration est en lecture seule : toutes les actions sont des requêtes GET. Bookivox ne demande aucune permission d’écriture, et ne peut donc ni modifier une commande, ni encaisser, ni changer un prix.

Ce qu’il faut préparer

Élément	D’où il vient	Format attendu
Clé API	Back-office Zelty : Marketplace → votre application → Statut	Chaîne base64, 16 à 128 caractères
Identifiant d’établissement	Action Lister les établissements, ou le back-office	Identifiant interne Zelty
Une application	Marketplace Zelty	Une application dédiée à Bookivox

Zelty n’affiche la clé que quelques minutes après sa génération, puis la masque (MTY123••••IHA=). Copiez-la immédiatement : si vous la perdez, il faut générer une nouvelle clé.

Connecter Zelty

Générer la clé

Dans le back-office Zelty, ouvrez Marketplace, sélectionnez votre application, puis l’onglet Statut. Copiez la clé affichée sans attendre.

Coller la clé

Dans Intégrations → Zelty, collez la clé. Le formulaire vérifie le format base64 avant l’envoi.

Cocher les actions

Sélectionnez les actions utiles. Chacune devient un outil indépendant.

Vérifier la connexion

Cliquez sur Créer les outils. Bookivox appelle GET /restaurants avec la clé : un bandeau vert confirme la connexion, une erreur est affichée sinon.

Attacher les outils

Rattachez les outils utiles à un nœud agent. Ils s’exécutent pendant l’appel.

Ce que l’agent peut faire

Action	Usage	Exemple de demande
Lister les commandes (`list_orders`)	Liste les commandes d’un établissement sur une période	« Qu’est-ce qui a été commandé ce midi ? »
Lister les établissements (`list_restaurants`)	Liste les points de vente accessibles avec la clé	« Quel est l’identifiant du restaurant ? »
Lister les clients (`list_customers`)	Liste les fiches clients rattachées	« Retrouvez la fiche de ce client. »

L’agent fournit restaurant_id, et s’il le souhaite from, to et status pour les commandes. La clé n’est jamais un paramètre : elle est injectée par la credential.

restaurant_id est obligatoire pour lister les commandes : demandez-le à l’agent avec l’action Lister les établissements, ou figez-le dans la description de l’outil.

Cas d’usage

Cas d’usage	Ce que fait l’agent	Résultat pour le client
Reconnaître un client	L’agent appelle `list_customers` et retrouve la fiche rattachée à la clé correspondant à l’appelant.	Le client est accueilli avec son historique, sans redonner son nom.
Reconstituer une commande	L’agent appelle `list_orders` avec le `restaurant_id` et une période `from` / `to`.	Le détail de la commande est restitué, ligne par ligne.
Filtrer le service en cours	L’agent appelle `list_orders` avec `status` pour ne garder que les commandes utiles.	L’équipe et le client parlent du même périmètre.
Trouver le restaurant avant d’interroger les commandes	L’agent appelle `list_restaurants` pour obtenir le `restaurant_id` exigé par `list_orders`.	L’appel aboutit même quand l’identifiant n’est pas connu d’avance.

Comment ça marche

Bookivox crée une credential bearer_token : la clé devient l’en-tête Authorization: Bearer <clé> sur chaque requête.
Les paramètres (restaurant_id, from, to, status) partent en query params sur l’URL fixe https://api.zelty.fr/2.7 : le chemin n’est jamais construit à partir d’une valeur du modèle.
Chaque action cochée devient un outil http_api avec config.provider = "zelty", config.operation et un timeout de 15 000 ms.
Zelty renvoie le résultat en JSON, que l’outil restitue à l’agent.

Rédiger la description de l’outil

La description décide quand l’agent consulte Zelty. Rédigez-la comme une consigne :

Utiliser cet outil quand le client parle d'une commande déjà passée.
Commencer par l'établissement concerné, puis limiter la période à la journée
mentionnée. Ne jamais inventer une commande : si la réponse est vide, le dire.

Les montants et les libellés sont affichés tels que Zelty les renvoie. Précisez dans le prompt que l’agent doit les répéter à l’identique, sans recalculer de taxe ni arrondir.

Sécurité

Risque	Ce que fait le preset
Clé exposée	Elle vit dans une credential chiffrée, jamais dans la définition de l’outil ni dans un prompt. Elle n’est jamais réaffichée.
Écriture non voulue	Toutes les actions sont des `GET` : aucune commande ne peut être créée, modifiée ou annulée.
Détournement d’URL	L’URL de base est figée sur `https://api.zelty.fr/2.7` : l’outil ne peut pas viser un autre service.
Injection de chemin	Les valeurs dynamiques partent en query params ; aucun segment de chemin n’est construit depuis le modèle.
Erreur silencieuse	La connexion est testée avant validation avec `GET /restaurants`.

Une clé Zelty donne accès à tous les établissements de l’application. Si vous partagez une application entre plusieurs usages, créez une application dédiée à Bookivox pour pouvoir la révoquer sans interrompre les autres.

Ce qui est déconseillé

Usage	Pourquoi
Clé partagée entre outils	Révoquer la clé coupe toutes les intégrations qui l’utilisent.
Recherche de catalogue	Zelty n’expose pas de route catalogue prévisible avec une clé : utilisez Popina pour les produits et les catégories.
Période omise	Sans `from` et `to`, la réponse peut être volumineuse et noyer l’agent.
Tâches planifiées	Un outil d’agent s’exécute pendant l’appel, pas en tâche de fond.

Limites et dépannage

Symptôme	Cause probable	Correction
Erreur `401`	Clé invalide, mal recopiée ou expirée.	Générer une nouvelle clé dans la Marketplace et la recopier en entier.
Erreur `403`	Message « You’ve been blocked » : la clé a été révoquée.	Réactiver l’application, générer une clé, puis recréer les outils.
Erreur `5xx`	Incident côté Zelty.	Réessayer plus tard ; contacter Zelty si cela dure.
Le test de connexion échoue	La clé ne donne accès à aucun établissement.	Vérifier l’application et ses droits dans la Marketplace.
`restaurant_id` manquant	L’action Lister les commandes a été cochée seule.	Ajouter Lister les établissements, ou figer l’identifiant dans la description.
L’agent répond « de tête »	L’outil n’est pas attaché à l’agent, ou il est inactif.	L’activer et l’attacher au nœud agent.

Intégrations

Toutes les intégrations et les catégories d’outils.

API HTTP

Comprendre les outils HTTP : paramètres, presets, credentials.

Prise en main

LABS

Construire

Préparer

Piloter

Revendeur (White-label)

Intégration : Zelty

À quoi ça sert

Ce qu’il faut préparer

Connecter Zelty

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage

Intégrations

API HTTP

​À quoi ça sert

​Ce qu’il faut préparer

​Connecter Zelty

​Ce que l’agent peut faire

​Cas d’usage

​Comment ça marche

​Rédiger la description de l’outil

​Sécurité

​Ce qui est déconseillé

​Limites et dépannage

Intégrations

API HTTP

À quoi ça sert

Ce qu’il faut préparer

Connecter Zelty

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage