La brique API

• 1. Qu'est-ce que la brique API?
• 2. Configurer la connexion API
• 3. Configurer la brique API depuis le formulaire
• 4. Cas pratiques

Une API (Application Programming Interface) est un ensemble de règles et de protocoles qui permettent à différentes applications logicielles de communiquer et d'échanger des données entre elles. En d'autres termes, une API fait office d'intermédiaire entre deux applications ou services. Elle définit comment ces systèmes peuvent interagir et partager des informations de manière sécurisée.

1. Qu'est-ce que la brique API?

La brique API permet aux administrateurs de créer des calls API en cours d’intervention. Cette fonctionnalité vous permet d'envoyer et de recevoir des informations en temps réel, qui pourront s’intégrer dans vos rapports de fin d’intervention. Vous pourrez également effectuer des actions par call API afin de mettre à jour les données souhaitées. (ex : mettre à jour des attributs d’interventions…).

2. Configurer la connexion API

2.1. Autoriser le rôle utilisateur

1. Rendez-vous dans section rôle de votre utilisateur. Au niveau de la section “Intégration”, activez l’option: Afficher le menu d’intégration.

Une fois cette option est cochée, une nouvelle section sous le nom de “Intégration” apparaitra dans le menu principale de Causeway Ermeo.

2.2. Créer une nouvelle connexion

1. Cliquez sur le bouton : Nouvelle connexion
2. Remplissez les information générales liées à l’API à laquelle vous souhaitez vous connecter (Nom, Base URL).
3. Sélectionnez votre authentification.

Vous aurez 4 choix possibles :

• Sans authentification (None): vous pourrez directement valider votre connexion.

• Authentification Basic: Vous devrez renseigner un utilisateur et un mot de passe en deuxième étape.

• Header auth: Vous renseignerez un à plusieurs headers avec leur clé et valeur associée.

• Query Parameters: Comme pour header auth, vous devrez renseigner vos paramètres url, avec leur clé et valeur associée.

• Oauth2 : Pour finaliser votre authentification, vous devrez compléter les informations suivantes : l’url d’authentification Oauth 2, l’url token Oauth2, votre client id et secret, ainsi que votre scope, telle que le présente la vidéo ci-dessous:

Pour votre information, l’url de redirection à utiliser par votre api, se trouve en bas de la modale, dans “Informations de connexion” :

💡

Notes

• La base url doit terminer avec un “/” à fin, si ce n’est pas le cas, il s’ajoutera automatiquement.
• Si vous avez des query params dans l’url, ces derniers devront être renseignés dans votre path lorsque vous configurerez la requête dans le studio.
• Dans le cadre d’une connexion Oauth2 :
• Votre url de redirection est la suivante, elle se trouve en bas de votre modale de configuration : https://platform.ermeo.com/integration/authentication/oauth2
• Votre refresh token pourrait expirer après une période d'inactivité de votre connexion qui varie selon votre API (vérifiez ce détail dans votre documentation). Si cela se produit, vous devrez vous reconnecter pour continuer à l’utiliser :

2.2. Modifier la connexion

Vous pouvez modifier votre connexion si vous le souhaitez en cliquant sur ”Modifier” sur la connexion choisie.

Dans le cas d’une modification d’une connexion d’authentification Basic, le mot de passe est uniquement à renseigner si vous souhaitez le changer.

2.3. Supprimer la connexion

Vous pouvez supprimer une connexion API créée.

Si cette connexion est utilisée dans la configuration de vos briques API, vous aurez la mention du nombre de brique(s) utilisant cette connexion.

3. Configurer la brique API depuis le formulaire

3.1. Configurer la requête API

1. Rendez vous dans le studio d’édition de votre formulaire.
2. Glissez puis déposez la brique API qui se trouve dans la section “Workflows”
3. Dans le paramétrage de la brique, commencez la configuration de votre requête

4. Sélectionnez une connexion configurée dans votre page “Intégrations”.

5. Renseignez la méthode choisie : POST, GET, PUT, DELETE
6. Vous pourrez ensuite compléter le path de votre url, et y ajouter si besoin des tags présents dans votre formulaire. Si vous avez des query params, ils seront à renseigner dans votre path
7. Choisissez le format contenu dans la requête entre JSON et XML

8. Vous pouvez renseigner des headers dans votre requête, ainsi qu’un body. La valeur d’un header et le body pourront également contenir des tags

9. En étape 4, choisissez le format de réponse attendu entre JSON et XML
10. Vous enfin pouvez testez votre requête et sauvegarder sa création :

• Si vous avez mis des tags dans votre requête, et que vous souhaitez la tester, vous devrez renseigner une valeur à chacun des tags en cliquant sur le bouton “Renseigner des tags”
• Vous pouvez également valider la création de votre requête sans la tester. En revanche, nous vous recommandons de tester, afin d’éviter toute erreur de configuration.

11. Finaliser le paramétrage des options de votre brique API :

Vous pourrez automatiser le clic sur votre brique API, pour éviter à celui qui répond au formulaire de cliquer sur le bouton qui lance votre call API, et vous pourrez également cacher cette nouvelle brique à l’utilisateur.

Toutefois, pour pouvoir “Automatiser le clic”, vous devrez avoir des conditions d’affiches sur votre brique API.

3.2. Configurer votre tag API pour afficher la réponse à votre requête dans une autre brique

3.2.1. Le format de votre API path

Avant propos : Un "path" dans une requête API est une syntaxe utilisée pour naviguer et extraire des données spécifiques au format JSON ou XML. Pour plus d’informations, vous pouvez consulter cet article.

3.2.2. Paramétrer votre tag en fonction de la réponse souhaitée

• Dans une valeur par défaut, un titre, une description, vous pouvez sélectionner le tag de votre brique API
• Une fois sélectionné, cliquez sur le petit crayon à droite sur le tag :

• Une modale de configuration s’ouvre et vous invite à renseigner votre path :

• Vous pouvez ensuite prévisualiser ce que vous avez paramétrer dans le studio et le publier :

3.3. Conditions d’affichage sur la brique API

Si vous souhaitez une explication sur le rôle des conditions d’affichage, vous pouvez consulter cet article.

Dans la cadre de cette fonctionnalité, il vous est possible d’afficher d’autres tâches si la requête de la brique API a été un succès et/ou si elle a échouée.

Exemple : J’affiche ma brique texte 3, uniquement si le call a été effectué et que ma requête est valide. Ce qui signifie que si ma requête est invalide, ma tâche texte ne s’affichera pas.

Si vous souhaitez que le call soit simplement effectué, que la requête soit valide ou invalide, vous pouvez sélectionner, “La tâche est remplie” :

3.4. L’affichage d’un call qui a échoué sur l’application

Il peut arriver que votre appel API échoue pour diverses raisons, telles qu'une erreur de configuration, une valeur de tag incorrectement renseignée par un utilisateur, un manque de connexion Internet au moment du call, ou un problème de permission sur l'API utilisée…

Dans ce cadre, même si elle est cachée, la brique API s’affichera sur l’application et indiquera qu’il y a eu une erreur, permettant ainsi de relancer le call.

Deux types de messages peuvent s’afficher :

• Si l’utilisateur n’a pas internet, le call ne peut donc pas être effectuer. En cliquant sur le bouton “Charger des données” lorsqu’il aura du réseau, le call API pourra être à nouveau réalisé (voir capture 1)
• En cas d’autre type d’erreur, un second message s’affichera (voir capture 2). Ce message invite l’utilisateur à vérifier les informations saisies, notamment si l’erreur est liée aux tags, et à réessayer. Si l’erreur persiste, l’utilisateur est conseillé de contacter son administrateur car il peut s’agir d’une erreur de paramétrage.

4. Cas pratiques

4.1. Collecter des informations externes en cours d’intervention

Cet exemple décrit un scénario où vous allez récupérer le nom d’une commune en se basant sur le code postal qui va être saisi durant l’intervention.

L’objectif de la brique api dans ce cas, est de récupérer le nom de la commune depuis cette source externe.

1. Premièrement, créez votre connexion depuis la section “Intégrations”.

Pour ce test, vous pouvez utiliser la connexion: https://geo.api.gouv.fr/ en choisissant le type “Sans authentification” comme type d’authentification.

2. Une fois votre formulaire est créé, glissez puis déposez :

• Une brique nombre (qui va servir à définir le code postal)
• La brique API avec le logo HTTP (la brique api qui va récupérer le nom de la commune)
• Une brique texte (qui affichera le nom de la commune)

3. Afin de paramétrer la requête de votre brique api, cliquez sur “Configurer la requête”.
4. Sélectionnez la connexion que vous avez créé auparavant.
5. Choisissez “GET” comme méthode HTTP
6. Copiez l’URL suivant: communes?codePostal=tag de la brique nombre.

Par exemple: communescodePostal=##number_jXKVLmOK##

Dans cet exemple, nous n’avons pas besoin de remplir le body de la requête. Vous pouvez passer directement à l’étape de test de la requête.

7. Afin de vérifier si la requête fonctionne correctement, saisissez un code postal via le bouton “Renseignez des tags” puis cliquez sur “tester”.
8. Si votre test est valide, cliquez sur “Valider”.
9. Vous pouvez désormais prévisualiser le résultat de votre paramétrage. La vidéo ci dessous retranscrit les étapes suivies de ce cas pratique.

4.2 Planifier une intervention automatiquement sur Ermeo durant la réalisation d’une autre intervention

📌

Prérequis En amont, nous vous recommandons de consulter notre documentation afin comprendre au mieux comment communiquer avec l’API Causeway Ermeo :

Create an intervention | API Documentation

Create an intervention according to the body sent with this request. Powered by Stoplight.

ermeo.stoplight.io

4.2.1. Créer votre connexion dans votre page intégration

1. L’url que vous allez utiliser est la suivante : https://api.ermeo.com/
2. Sélectionner le type d’authentification “Oauth2“ et renseigner les champs demandés pour créer votre connexion.

4.2.2. Configuration dans le studio

1. Configurez votre formulaire et déposez la brique API où vous souhaitez que l’intervention soit créée comme dans la vidéo ci-dessous :

1.1. Glissez et déposez votre brique API dans le studio et cliquez sur “Configurer la requête”.



1.2. Sélectionnez la connexion créée.



1.3. Paramétrez votre requête (vidéo ci dessous) :

2. Masquez votre brique si vous ne souhaitez pas qu’elle soit visible une fois le formulaire publié.
3. Sur l’application, la création de l’intervention est transparente pour l’opérateur terrain.

4. Dans votre onglet intervention, la nouvelle intervention créée par l’opérateur :

Votre attribut d’intervention a bien été mis à jour en fonction de ce que le technicien aura rempli :