Éléments personnalisés : API

Une interface API est un formulaire dont les valeurs renseignées sont envoyées par Skava au format JSON à une adresse que vous spécifiez (votre backend). Cela vous permet de connecter Skava de manière sécurisée à vos propres systèmes.

Configurer une interface API

Une interface est constituée de champs de saisie (qui forment le JSON), de l’adresse cible et de l’authentification.

1. Créer des champs : Chaque champ possède une clé JSON. Sur la droite, vous voyez un aperçu JSON en direct, 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 comme 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 exemple Authorization) et le préfixe de la valeur (par exemple Bearer ), puis enregistrez le jeton. Définissez éventuellement une date d'expiration.
5. Champs de réponse (facultatif) : Définissez par chemin les valeurs de la réponse du backend à afficher : par exemple order.id ou items[0].sku.
6. Vérifiez avec Ping et Requête de test, puis Publier.

Stockage sécurisé du jeton

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

Tests : Ping et requête de test

• Ping : une vérification simple de la connectivité. Elle ne sert qu'à vérifier si votre adresse répond, et n'envoie ni jeton ni données de formulaire. Indique la connectivité, le statut et le temps de réponse. Idéal comme première étape.
• Test de requête : le véritable test : envoie des données d'exemple, y compris un jeton à votre adresse et 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 publication.

Brouillon et Publication

Chaque interface commence sous forme de brouillon et peut être modifiée librement. Une fois que tout est prêt, vous la publiez avec Publication.

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 une discussion : aucun éditeur n'est nécessaire. Le processus est le même que pour les modèles de documents : sélectionner, remplir, envoyer.

1. Dans la discussion, appuyez sur Plus en bas et choisissez Élément personnalisé.
2. Sélectionnez le modèle ou l'interface souhaité dans la liste.
3. Remplissez le formulaire et Envoyer.
4. Le résultat apparaît sous forme de carte dans le chat : visible par tous les participants au chat.

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

En tant qu'administrateur de l'entreprise, vous n'êtes pas obligé d'utiliser l'éditeur vous-même. Dites à l'assistant Skava dans la conversation, par exemple "crée-moi un formulaire de commande pour mon catalogue avec quantité et adresse de livraison". Il crée un projet à partir de cela, peut modifier les champs un par un ultérieurement, et il connaît votre catalogue d'articles téléchargé : pour les commandes, il suggère le sélecteur de produits plutôt qu'un champ de texte pour le numéro d'article.

Ce qu'il peut également définir : point de terminaison et méthode ainsi que le public ("membres de l'entreprise uniquement" ou "également des personnes extérieures dans la même conversation"). Pour le public, il pose d'abord la question plutôt que de le définir directement, car cela détermine qui peut exécuter quelque chose depuis l'extérieur.

Ce qu'il ne modifie pas explicitement : le jeton d'accès. Il ne le demande jamais et n'en accepte jamais, car les messages de conversation sont stockés. Vous l'entrez vous-même dans l'éditeur, sinon aucune requête n'est envoyée. Et il ne peut pas publier : la dernière étape vous revient, afin 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 personnes extérieures, mais uniquement dans une conversation où est également présent un membre de votre entreprise : c'est précisément le cas d'utilisation prévu, le client commandant auprès de vous. Lorsque votre entreprise quitte la conversation, l'autorisation prend fin automatiquement.

Produits de votre propre catalogue

Une fois que vous avez importé votre catalogue d'articles, le constructeur propose un bloc sélecteur d'articles. Il n'y a pas d'options à maintenir : la liste est votre catalogue. La personne qui commande le consulte, 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 qui ne figure pas dans votre catalogue. Pour la quantité, indiquez un champ numérique normal à côté.

Définissez la carte vous-même

Votre backend décide de ce que dit la carte. Skava vérifie uniquement la forme, la taille et la sécurité, jamais le sens : il ne connaît ni les états de commande ni les noms de champs. Pour ce faire, 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 comptabilisée comme une carte et la correspondance de réponse configurée dans l'élément s'applique.
• état est une couleur et une icône uniquement : ok, en attente, avertissement ou erreur. Tout ce qui a un sens doit être placé dans status_text sous forme de texte libre.
• champs est une liste d'étiquettes et de valeurs, au maximum 20 entrées. Les valeurs trop longues sont raccourcies plutôt que rejetées, afin qu'une commande ne soit jamais compromise par un détail.

Les saisies de l'utilisateur appartiennent au serveur : elles restent inchangées, quoi que votre backend envoie. Elles constituent l'enregistrement dans le chat de ce qui a été soumis.

Signaler l'état plus tard

Lorsque l'élément s'exécute, Skava envoie deux valeurs supplémentaires : callback_url et callback_token. Signalez un nouvel état là-bas plus tard et une nouvelle carte apparaît dans le chat, sur le téléphone également, pendant que quelqu'un regarde. La précédente reste, de sorte qu'il est lisible quand quel état a été signalé. Envoyez le même objet card comme ci-dessus, via POST avec l'en-tête Authorization: Bearer <callback_token>. Trois valeurs facultatives suivent la carte :

• seq: votre propre compteur. Un rapport avec une valeur inférieure ou égale est ignoré, de sorte que deux rapports ne peuvent pas se dépasser.
• final: clôt l'interaction. Le jeton devient invalide et la carte est finale.
• notify: défini sur false pour publier la carte discrètement, sans compteur de non-lus et sans notification. Pour les étapes intermédiaires qui ne doivent pas réveiller personne. Sans cela, la carte est un message tout à fait normal.

Une interaction peut publier au plus 50 cartes. Le même rapport deux fois ne produit pas une deuxième carte.

Skava répond avec 200 et une liste de hints si quelque chose a été raccourci ou supprimé, et avec 422 si la carte n'était pas utilisable. 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 propre entreprise. Le système qui écrit est indiqué dans le titre de la carte.

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

Sujets connexes

Souhaitez-vous plutôt créer un modèle de document à remplir ? Consultez Éléments personnalisés : Documents.

Questions fréquemment posées