How to Integrate API and Publish API Data via OptiSync – OptiSigns

L'intégration de votre API avec OptiSigns offre de nombreuses possibilités et permet d'afficher facilement des données à mise à jour automatique sur vos écrans. Dans ce guide, nous vous expliquerons comment connecter votre API - aucune expérience en génie logiciel n'est requise.

Ce que l'intégration API peut faire
Ce dont vous aurez besoin pour commencer
Comment configurer une requête API
Comment mapper les données API dans Designer
- Étape 1 : Créer une source de données API
- Étape 2 : Maintenir le mappage des éléments
En savoir plus sur les cas d'utilisation d'OptiSync

REMARQUE : L'intégration API n'est disponible qu'avec un forfait Pro Plus ou supérieur.

Ce que l'intégration API peut faire

OptiSigns permet une intégration facile avec les API des utilisateurs. Cela permet d'afficher les données provenant de l'API d'un utilisateur sur n'importe lequel de vos écrans d'affichage numérique. Cela permet des mises à jour dynamiques pour :

Tableaux de menus numériques - Intégrez-vous à vos systèmes de point de vente et obtenez une mise à jour automatique du tableau de menu numérique, et modifiez le format de votre tableau de menu numérique à l'aide de l'application Designer quand vous le souhaitez.
Mises à jour RH automatisées - Utilisez l'API de vos systèmes RH pour afficher automatiquement les anniversaires ou les anniversaires de travail sur les écrans.
Suivi des stocks d'entrepôt - Utilisez l'API de votre entrepôt pour afficher les niveaux de stock avec des mises à jour automatiques dans toute votre organisation
Tout autre cas d'utilisation d'affichage d'informations nécessitant de consommer des données API et d'afficher ces données sur les écrans.

Cette intégration API peut être réalisée dans OptiSigns avec peu ou pas de codage, la rendant accessible à ceux qui n'ont pas de formation en génie logiciel. Dans ce guide, nous vous expliquerons comment la configurer avec l'exemple ci-dessous utilisant une API du système de point de vente Clover.

Ce dont vous aurez besoin pour commencer

Vous aurez besoin de votre :

URL du point de terminaison API
Jeton d'autorisation API

Ces éléments sont nécessaires pour qu'OptiSigns puisse se connecter à l'API souhaitée. Assurez-vous de les avoir dans un endroit facilement accessible avant d'essayer de configurer votre requête API dans le portail Web OptiSigns. Vous devriez pouvoir les obtenir auprès d'un professionnel informatique de votre organisation ou par l'intermédiaire de votre administrateur de système de point de vente.

Comment configurer une requête API

La passerelle API est un outil puissant qui permet aux utilisateurs de gérer centralement les API, ainsi que de configurer et tester les API.

Maintenant que vous avez tout ce dont vous avez besoin, commençons par configurer une requête API. Avec une requête API, vous pouvez :

Utiliser le Keystore API d'OptiSigns pour stocker et utiliser de manière sécurisée les clés API d'autres systèmes.
Tester les points de terminaison API, avec la possibilité de modifier les en-têtes et les paramètres.
Utiliser des paramètres de substitution et des règles de pré-traitement et de post-traitement pour gérer des intégrations complexes. Les règles de pré-traitement peuvent vous aider à gérer les situations d'intégration API qui nécessitent un appel supplémentaire pour obtenir un jeton d'authentification avant d'effectuer l'appel API. Le post-traitement vous permettra de traiter les données retournées et de les adapter pour mieux répondre à vos besoins.

Pour commencer, ouvrez votre portail Web OptiSigns.

Une fois là, naviguez vers le coin supérieur droit de l'écran et survolez le nom de votre compte.

Survolez Plus → Sources de données

Vous verrez l'écran ci-dessous.

Vous êtes maintenant prêt à commencer.

Étape 1 : Stocker votre jeton d'autorisation API dans le Keystore API d'OptiSigns

La première étape consiste à prendre votre jeton d'autorisation API et à le stocker dans le Keystore API d'OptiSigns.

Cette étape est techniquement facultative : vous pouvez entrer votre jeton d'autorisation API dans une requête API individuelle. Cependant, le Keystore présente quelques avantages majeurs :

Permet d'envoyer votre jeton d'autorisation API à plusieurs requêtes API, sans avoir besoin de le saisir manuellement à chaque fois
Offre une sécurité supérieure pour votre jeton d'autorisation API, rendant beaucoup plus difficile sa découverte par des acteurs externes

Par conséquent, nous recommandons fortement cette étape.

Pour accéder au Keystore, trouvez l'icône de cadenas et cliquez dessus.

Cela ouvrira le Keystore API.

Cliquez sur Ajouter une clé.

Il y a deux champs ici.

Premier champ - Entrez le nom de la clé ici. Nous recommandons quelque chose qui vous aidera à vous en souvenir. Vous l'utiliserez pour configurer une requête API.
Deuxième champ - Le code d'accès unique réel pour vos communications API.

Une fois que vous avez entré votre jeton d'autorisation API, cliquez sur Enregistrer. Lorsque vous souhaitez exécuter une requête en utilisant cette clé API, vous utiliserez le terme : {{apiKeystore.<<key>>}} où "<<key>>" est remplacé par le nom que vous avez inséré précédemment. Dans cet exemple, nous nommerons notre requête "clover".

Maintenant, nous sommes prêts à configurer votre requête API.

Étape 2 : Configurer et tester la requête API

Avant de continuer dans OptiSigns, nous recommandons de tester votre connexion API en utilisant un outil gratuit, tel que Postman. Cela présente plusieurs avantages, notamment :

Vérifier le formatage de vos données
S'assurer que les données correctes sont fournies
Vérifier votre authentification
Identifier les problèmes d'intégration ou les erreurs de connexion

Les paramètres de test, les points de terminaison et les authentificateurs peuvent ensuite être utilisés dans OptiSigns pour configurer votre requête API. Voici comment procéder.

Cliquez sur le bouton Ajouter une requête, cela lancera la fenêtre pour vous permettre de configurer et tester la requête API.

Nom d'affichage - Ceci sera affiché dans la liste de la passerelle API, principalement pour aider les utilisateurs à identifier la requête API.
Nom - Ceci est utilisé comme référence à la requête API, c'est un nom technique qui sera utilisé plus tard dans le chemin pour faire référence aux données de la requête API.
URL - C'est le point de terminaison API, vous pouvez utiliser la méthode GET ou POST selon la requête API, par exemple, si vous utilisez GraphQL, alors toutes les requêtes utiliseront POST.
Params - Permet de définir les paramètres dans votre requête API. Vous pouvez voir des paramètres dans votre URL de point de terminaison API, ceux-ci seront précédés d'un signe "?". Ceux-ci peuvent être utilisés dans le code de requête de pré et post-traitement pour automatiser davantage votre requête API.
En-têtes - Le ou les en-têtes de la requête API. C'est ici que vous devrez entrer votre jeton d'authentification API.
Pré-requête - Un morceau de code facultatif qui prépare le contexte avant la requête API. Par exemple, vous devrez peut-être appeler une autre API pour obtenir un jeton d'authentification à courte durée de vie avant d'appeler l'API, ou vous devez calculer certaines variables à utiliser dans la requête API.
Post-requête - Un morceau de code facultatif qui modifie les données reçues de la requête. Par exemple, si les données que vous recevez ne sont pas exactement comme vous souhaitez les afficher, vous pouvez écrire un peu de code pour les modifier selon vos besoins d'affichage numérique.
Activer le Webhook - Génère un lien webhook et un jeton associé. Ce webhook peut être utilisé pour nous notifier d'un changement dans les données, ce qui actualisera la requête API et mettra à jour vos écrans automatiquement.
Activer cette requête - Définit le statut de la requête API.

Pour tester la requête, nous devons configurer l'en-tête. C'est là que le Keystore entre en jeu. Dans la deuxième case, tapez Bearer {{apiKeystore.<<key>>}}, où Bearer est le type de jeton et {{apiKeystore.<<key>>}} récupère le jeton stocké dans le Keystore. Dans cet exemple, nous utiliserons le nom "clover" comme référencé ci-dessus.

Une fois cela fait, cliquez sur "Tester". Si le code de réponse est 200, l'API a retourné les données avec succès. S'il y a un autre code, il y a un problème dans la requête API.

Comment utiliser les paramètres

Les paramètres sont présents dans les URL de tous types. Un paramètre comporte deux éléments :

Ils doivent suivre un signe '?' dans l'URL ;
Ils ont une valeur qui leur est associée

L'onglet Params vous permet de spécifier les paramètres dont vous souhaitez modifier la valeur.

Habituellement, l'onglet Params est utilisé conjointement avec les onglets Pré-requête et Post-requête pour créer des valeurs se mettant à jour automatiquement.

Comment utiliser le traitement pré- et post-requête

Pour utiliser le traitement pré- et post-requête, une certaine connaissance de Javascript est nécessaire.

Quelle est la différence entre les deux ?

Pré-requête : Il s'agit d'un extrait de code normalement défini pour définir le contexte avant la requête API. Cela peut être la récupération d'un jeton d'authentification à partir d'une autre API, ou la modification de paramètres pour permettre plus d'automatisation.

Post-requête : Un morceau de code à appliquer aux données reçues de la requête API. Ce code peut être utilisé pour modifier les données reçues afin de changer la façon dont elles s'affichent sur vos écrans.

L'onglet Pré-requête est l'endroit où vous entrerez le code pour le traitement pré-requête.

Exemple : Pour les systèmes qui nécessitent un jeton d'authentification généré dynamiquement comme Toast, cela peut être utilisé pour appeler une autre API afin de récupérer le jeton d'authentification et le définir dans le contexte de l'API.

Pour en savoir plus sur cet exemple, consultez cet article sur comment connecter votre API Toast.

L'onglet Post-requête est l'endroit où vous entrerez le code pour le traitement post-requête.

Exemple : Vous recevez des données de l'API de votre logiciel de point de vente (PDV), mais certaines données ne s'affichent pas comme vous le souhaiteriez.

Les prix peuvent s'afficher sous forme de nombres entiers (c.-à-d. 1299) au lieu de s'afficher comme un prix approprié (c.-à-d. 12,99 $). Pour cela, nous aurions besoin d'un morceau de code pour convertir le nombre entier en prix, et que ce code soit extensible à toute erreur d'affichage similaire (par exemple 1899 au lieu de 18,99 $).

Pour cet exemple courant, ce morceau de code JavaScript devrait résoudre votre problème. Nous pouvons également configurer la capacité de mapper la disponibilité des produits en même temps.

Cela corrigera les données retournées, leur permettant de s'afficher correctement :

Cela peut également être utilisé pour faire apparaître des données comme "ÉPUISÉ", pour rayer un article s'il n'est pas disponible, ou pour afficher des avertissements dans un système de gestion des stocks. Pour en savoir plus sur cet exemple, consultez notre article sur les tableaux de menus numériques.

Étape 3 (Facultative) : Utiliser des paramètres de substitution à partir des attributs de l'appareil.

De nombreux systèmes de point de vente (PDV) sont sous licence par magasin/emplacement. Il est possible de configurer une seule requête API avec OptiSync et de la faire fonctionner avec différents emplacements en utilisant des paramètres de substitution. Leur saisie permet à votre écran de communiquer ses informations d'identification de magasin ou d'emplacement. Cela signifie qu'une seule requête API peut communiquer différentes données à différents magasins ou emplacements, plutôt que de devoir effectuer des requêtes API individuelles par écran.

Pour commencer, trouvez l'écran que vous souhaitez modifier.

Cliquez sur Avancé → Plus → Attributs supplémentaires de l'appareil.

Deux champs apparaîtront, Clé et Valeur.

Clé - Un paramètre qui sera utilisé lors de l'appel API pour remplacer la valeur de votre magasin. Cela remplacera une partie de votre URL de point de terminaison API.
Valeur - Représente le code unique associé au magasin ou à l'emplacement que vous souhaitez transmettre à votre API.

Dans cet exemple, nous maintenons l'identifiant marchand Clover ici. La valeur saisie devra être obtenue de votre côté car elle sera unique.

Maintenant, retournez à la page de configuration de la requête API. Remplacez le merchantID dans le point de terminaison API par le nom de clé que vous avez défini précédemment.

Lorsque l'appel API est déclenché sur l'appareil, il prendra la valeur de l'appareil et la substituera au moment de l'exécution. Pour chaque écran, vous voudrez effectuer ces mêmes étapes, en gardant le nom de la clé identique tout en changeant la valeur. Cela vous permettra de pousser différentes données vers différents écrans.

Comment mapper les données API dans Designer

Pour pousser des données de votre API vers un écran, elle devra être enregistrée en tant que source de données. Cela permet d'ajouter des éléments de données à l'application Designer d'OptiSigns, où ils peuvent être formatés et incorporés dans n'importe quel design visuel que vous souhaitez afficher.

L'application Designer et les modèles peuvent être utilisés pour effectuer le formatage, et la source de données API gérera le mappage des données. N'importe quelle zone de texte ou élément d'image peut être mappé dans Designer. Lorsque vous mappez un élément d'image, l'URL de l'image sera remplacée au moment de l'exécution.

Étape 1 : Créer une source de données API

Pour commencer, trouvez votre design ou créez-en un nouveau dans l'onglet Fichiers/Ressources.

Avec le design ouvert, cliquez sur "Source de données" dans la colonne de gauche. Ensuite, cliquez sur "Ajouter une source de données" pour ajouter une source de données API au design.

Faites défiler jusqu'à l'endroit où il est écrit "Passerelle API" et cliquez dessus.

Vous devriez voir cet écran :

Sélectionnez la requête API créée ci-dessus. Vous verrez un écran comme celui ci-dessous :

Ici, vous pouvez choisir quelles données spécifiquement vous souhaitez ajouter au design. Si vous voulez toutes les options, cliquez sur "Continuer". Cet écran apparaîtra.

Nom de la source de données est la façon dont cette source de données apparaîtra dans Designer. Nommez-la de manière à vous aider à l'identifier.

Synchronisation vous permet de choisir à quelle fréquence synchroniser avec votre API. Importer une seule fois est logique pour les promotions ponctuelles et similaires. S'il s'agit d'un actif à plus long terme, choisissez Accès direct périodique ou Synchronisation périodique en arrière-plan selon si vous avez besoin d'utiliser les données d'un appareil spécifique pour définir le contexte.

Cliquez sur Terminé, et la source de données est créée.

Elle devrait apparaître dans la colonne de gauche sous "Utilisé dans ce design". Elle apparaîtra certainement dans la section "Autres sources de données". Vous devrez peut-être actualiser la page pour qu'elle apparaisse.

Maintenant, nous passons à l'étape 2.

Étape 2 : Maintenir le mappage des éléments

Une fois que la source de données API a été créée, vous êtes prêt à mapper les données.

Dans Designer, ouvrez votre source de données.

Cliquez dessus et un écran similaire à celui-ci apparaîtra :

L'ouverture de l'un de ces éléments affichera les données extraites de votre API :

En cliquant sur n'importe quelle donnée et en la faisant glisser sur l'écran, les données apparaîtront. Vous aurez l'option d'utiliser les données comme répéteur ou seules.

Dans ce cas, nous voulons l'utiliser seule. Pour les menus, un répéteur est le plus logique.

Pour vérifier la liaison de données, vous pouvez cliquer sur n'importe quel élément mappé, puis cliquer sur Paramètres. Vous verrez le nom de l'élément de ressource là.

Nous avons le nom et le prix de l'article de l'API mappés au design. Lorsqu'il sera publié sur l'écran, la valeur sera automatiquement remplacée par la valeur de l'API. Si des mises à jour sont effectuées dans le système de point de vente Clover, le changement sera reflété automatiquement sur l'écran.

Répétez cette étape pour tous les éléments que vous souhaitez mapper à la source de données API, et enregistrez le design. Votre design est prêt à l'emploi.

Plus de cas d'utilisation d'OptiSync

Si vous souhaitez plus de détails sur les cas d'utilisation de l'intégration API, nous avons plusieurs articles supplémentaires. Veuillez consulter :

C'est tout !

Voici comment vous intégrez les données API et les publiez sur votre écran. Plus important encore, sans codage !

Si vous avez des questions supplémentaires, des préoccupations ou des commentaires sur OptiSigns, n'hésitez pas à contacter notre équipe de support à support@optisigns.com