Custom Elements : API

Une interface API est un formulaire dont les valeurs saisies sont envoyées par Skava au format JSON vers une adresse que vous définissez (votre backend). Vous pouvez ainsi connecter Skava en toute sécurité à vos propres systèmes.

Configurer une interface API

Une interface se compose de champs de saisie (qui forment le JSON), de l'adresse cible et de l'authentification.

1. Créer des champs : Chaque champ reçoit une clé JSON. À droite, vous voyez en direct l'aperçu JSON, qui est envoyé à votre backend exactement de cette manière.
2. Adresse (URL) : l'adresse https:// de votre backend. Seules les adresses HTTPS et accessibles publiquement sont autorisées (voir Sécurité ci-dessous).
3. Méthode : POST (par défaut), PUT, PATCH ou GET. Avec GET, les valeurs sont ajoutées en tant que paramètres de requête au lieu d'être envoyées dans le corps.
4. Authentification : Définissez le nom de l'en-tête (par ex. Authorization) et le préfixe de la valeur (par ex. Bearer ), puis enregistrez le jeton. Définissez éventuellement une date d'expiration.
5. Champs de réponse (facultatif) : Définissez par chemin quelles valeurs de la réponse du backend doivent être affichées : par ex. order.id ou items[0].sku.
6. Vérifiez avec Ping et Test Request, puis Release.

Stockage sécurisé du jeton

Le jeton est stocké chiffré et n’est jamais renvoyé aux clients : l’application n’affiche que si un jeton est défini et sa date d’expiration. Lors de l’envoi, Skava l’ajoute côté serveur à l’en-tête configuré. Si vous définissez une date d’expiration, Skava refuse l’appel après expiration et vous demande de renouveler le jeton.

Tests : Ping et Requête de test

• Ping : une simple vérification d'accessibilité. Il ne vérifie que si votre adresse répond, sans envoyer de jeton ou de données de formulaire au passage. Affiche l'accessibilité, le statut et le temps de réponse. Idéal comme première étape.
• Requête de test : le vrai essai : envoie des données d'exemple incluant le jeton à votre adresse et vous affiche la réponse complète ainsi que les champs de réponse extraits.

En tant qu'administrateur, vous pouvez exécuter les deux en mode brouillon pour vérifier l'intégration avant la mise en ligne.

Brouillon et publication

Chaque interface commence en tant que brouillon et peut être modifiée librement. Une fois tout prêt, vous la publiez via Publier.

Sécurité

Comment l'équipe utilise une interface publiée

Une fois une interface publiée, tous les membres de l'entreprise peuvent la déclencher directement depuis un chat, sans éditeur. Il n'y a ni entrée collective ni dialogue intermédiaire : chaque élément publié figure dans le menu plus sous son propre nom, avec le logo de l'entreprise qui le propose.

1. Dans le chat, touchez Plus en bas, puis touchez l'élément souhaité, par exemple Commande de matériaux.
2. Remplissez le formulaire et Envoyez.
3. Le résultat s'affiche sous forme de carte dans le chat, visible par tous les participants.

Laissez l'IA créer un élément

En tant qu'administrateur de l'entreprise, vous n'avez pas besoin d'utiliser l'éditeur vous-même. Dites à l'assistant Skava dans le chat, par exemple « crée-moi un formulaire de commande pour mon catalogue avec quantité et adresse de livraison ». Il en crée un brouillon, peut modifier les champs un par un plus tard, et connaît votre catalogue d'articles téléversé : pour les commandes, il suggère le sélecteur de produits plutôt qu'un champ texte pour le numéro d'article.

Ce qu'il peut aussi configurer : point de terminaison et méthode ainsi que le public cible (« membres de l'entreprise uniquement » ou « aussi des externes dans le même chat »). Pour le public cible, il demande d'abord au lieu de simplement le définir, car cela détermine qui peut exécuter quelque chose depuis l'extérieur.

Ce qu'il ne touche explicitement pas : le jeton d'accès. Il ne le demande jamais et n'en accepte jamais, car les messages du chat sont stockés. Vous le saisissez vous-même dans l'éditeur, sinon aucun appel n'est envoyé. Et il ne peut pas publier : la dernière étape reste entre vos mains, pour que rien ne devienne visible aux clients sans vérification.

Qui peut l'exécuter

L'onglet « Point de terminaison » indique qui peut utiliser un élément. Par défaut, il s'agit des membres de votre entreprise. Le deuxième paramètre l'ouvre aux externes, mais uniquement dans un chat où quelqu'un de votre entreprise est également présent : exactement le cas pour lequel il est prévu, le client qui vous passe commande. Lorsque votre entreprise quitte le chat, l'autorisation prend fin d'elle-même.

Produits de votre propre catalogue

Une fois votre catalogue d’articles importé, le constructeur propose un bloc sélecteur de produits. Aucune option à maintenir : la liste est votre catalogue. La personne qui commande y recherche, voit l’image, le nom et le numéro d’article, et votre backend reçoit le numéro d’article. Skava rejette un numéro absent de votre catalogue. Pour la quantité, placez un champ numérique standard à côté.

Définissez la carte vous-même

Votre backend décide du contenu de la carte. Skava ne vérifie que la structure, la taille et la sécurité, jamais le sens : elle ne connaît ni les états de commande, ni les noms de champs. Pour cela, répondez avec un objet card :

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v doit être l’entier 1. Sans cela, la réponse n’est pas considérée comme une carte et la correspondance de réponse configurée dans l’élément s’applique.
• state ne contient que la couleur et l'icône : ok, pending, warn ou error. Tout ce qui porte du sens va dans status_text en texte libre.
• fields est une liste de libellés et de valeurs, avec un maximum de 20 entrées. Les valeurs trop longues sont raccourcies plutôt que rejetées, pour qu'une commande ne rate jamais à cause d'un détail.

Les saisies de l'utilisateur appartiennent au serveur : elles restent intactes, quelle que soit la réponse de votre backend. Elles constituent la trace dans le chat de ce qui a réellement été soumis.

Signaler l'état ultérieurement

Lors de l'exécution de l'élément, Skava envoie deux valeurs supplémentaires : callback_url et callback_token. Signalez un nouvel état à cet endroit plus tard et une nouvelle carte apparaîtra dans le chat, y compris sur le téléphone, même si quelqu'un est en train de consulter. L'ancienne reste visible, ce qui permet de savoir quel état a été signalé. Envoyez le même objet card que ci-dessus, via POST avec l'en-tête Authorization: Bearer <callback_token>. Trois valeurs facultatives accompagnent la carte :

• seq : votre propre compteur. Un rapport avec une valeur inférieure ou égale est ignoré, ce qui empêche deux rapports de se dépasser.
• final : clôture l'interaction. Le jeton devient invalide et la carte est définitive.
• notify : définissez sur false pour publier la carte silencieusement, sans compteur de non-lus et sans notification. Idéal pour les étapes intermédiaires qui ne doivent réveiller personne. Sans cela, la carte est un message parfaitement normal.

Une interaction peut publier au maximum 50 cartes. Envoyer deux fois le même rapport ne génère pas une seconde carte.

Skava répond par 200 et une liste de hints si quelque chose a été raccourci ou supprimé, et par 422 si la carte était inutilisable. Une interaction accepte les rapports pendant 90 jours.

Les cartes sont publiées par l'expéditeur système de Skava, et non par la personne qui a exécuté l'élément ni par un compte de votre entreprise. Le titre de la carte indique quel système a effectué l'écriture.

Un exemple complet à copier se trouve dans le dépôt sous example_order_server/ et s'exécute sur api.skava.io.

Liens connexes

Vous souhaitez plutôt créer un modèle de document remplissable ? Consultez Éléments personnalisés : Documents.

Questions fréquentes