Atelier 6 : Connecter un outil

Niveau intégrer · Durée ~45 min · Prérequis Atelier 2 et Atelier 5

Un logiciel qui vit seul finit toujours par se faire ressaisir. Cet atelier ouvre votre application à un programme extérieur, dans le bon ordre : d'abord ce qu'il aura le droit de faire, ensuite comment il se connecte, et enfin comment on lui coupe l'accès.

Vous n'avez pas besoin de savoir programmer. Tout se fait avec des commandes curl à copier, ou depuis l'explorateur d'API de cette documentation.

Un terminal, ou rien du tout

Sous macOS et Linux, curl est déjà installé. Sous Windows, il l'est aussi depuis PowerShell. Si vous préférez ne rien installer, l'explorateur d'API fait les lectures dans votre navigateur et vous donne les commandes d'écriture toutes faites.

Étape 1 : Décider ce que l'outil a le droit de faire

C'est l'étape que l'on saute, et c'est celle qui compte. Notre scénario : un site web extérieur dépose des demandes de devis. Il doit donc pouvoir créer des devis et relire ceux qu'il a créés. Rien d'autre : ni les clients, ni les lignes, ni la suppression.

1. Administration → onglet Utilisateurs & droits → Rôles → Nouveau rôle : Intégration site web.
2. Studio → objet Devis → onglet Permissions : sur la ligne du rôle, cocher Lire et Créer. Laisser Modifier et Supprimer décochés.

✅ Point de contrôle

Le rôle existe et n'accorde qu'un seul objet. Un rôle qui accorde tout n'apprend rien et ne protège rien.

Étape 2 : Créer le jeton

Administration → onglet Applications → section 🔌 API (outils tiers) → Nouveau jeton :

1. Nom : Site web (atelier).
2. Rôles accordés : cocher Intégration site web.
3. Limite d'appels / min : 60.
4. Expiration : dans un mois.
5. Créer le jeton.

Le secret s'affiche une seule fois. Copiez-le tout de suite dans un fichier temporaire, vous en aurez besoin pendant tout l'atelier.

export GESHOMS=https://votre-domaine
export JETON=ght_…

Étape 3 : Se présenter avant de travailler

curl -H "Authorization: Bearer $JETON" $GESHOMS/api/v1/health/

{"ok": true, "token": "Site web (atelier)", "rate_limit_per_min": 60,
 "objects": [{"code": "devis", "name": "Devis", "actions": ["create", "read"]}]}

✅ Point de contrôle

Un seul objet, deux actions. Cet appel est le réflexe à prendre : il répond à « ce jeton a-t-il vraiment le droit que je crois ? », et évite une demi-heure de recherche dans la mauvaise direction.

Étape 4 : Créer un devis depuis l'extérieur

curl -X POST $GESHOMS/api/v1/data/devis/ \
  -H "Authorization: Bearer $JETON" -H "Content-Type: application/json" \
  -d '{"reference": "WEB-001", "client": "Boulangerie Martin", "date": "2026-08-20", "statut": "brouillon"}'

La réponse est la fiche créée, avec son id. Ouvrez la liste des devis dans GesHoms : elle est là.

Le statut s'envoie par son code

"statut": "Brouillon" n'échoue pas, et c'est bien le problème : la valeur est enregistrée telle quelle, et la fiche porte un statut que la liste de choix ne connaît pas. L'API attend le code de l'option (brouillon), pas son libellé ; le code se lit dans le Studio, sur le champ. C'est la première cause d'intégration bancale, et elle ne se voit qu'à l'écran.

Étape 5 : Provoquer un refus, et le comprendre

Un bon intégrateur connaît les erreurs avant de les rencontrer en production. Provoquons-les.

Un champ obligatoire manquant :

curl -X POST $GESHOMS/api/v1/data/devis/ \
  -H "Authorization: Bearer $JETON" -H "Content-Type: application/json" -d '{}'

400, avec le nom du champ en clair. Rien n'a été créé.

Un objet hors du rôle :

curl -i -H "Authorization: Bearer $JETON" $GESHOMS/api/v1/data/ligne/

404, alors que l'objet ligne existe bel et bien. C'est volontaire : un 403 confirmerait à un inconnu qu'un objet porte ce nom chez vous. Devant un 404 inattendu, retournez voir /api/v1/health/.

Une action non accordée :

curl -i -X DELETE $GESHOMS/api/v1/data/devis/1/ -H "Authorization: Bearer $JETON"

403 : l'objet est bien accordé, mais pas cette action.

✅ Point de contrôle

Vous savez maintenant lire les trois refus : 400 la donnée, 403 l'action, 404 l'objet (ou la fiche) hors de portée.

Étape 6 : Voir son API telle qu'elle est

curl -H "Authorization: Bearer $JETON" $GESHOMS/api/v1/openapi.json

Ce fichier décrit votre API, avec vos objets et vos champs, limitée à ce que le jeton peut faire. Il s'importe tel quel dans Postman ou Insomnia. La même chose en plus lisible : l'explorateur d'API, où vous collez l'adresse et le jeton.

Étape 7 : Couper l'accès

Le site web est refait, le prestataire est parti, le jeton traîne dans un fichier de configuration.

1. Administration → Applications → section API → Révoquer sur Site web (atelier).
2. Rejouez l'appel de l'étape 3.

401. L'accès est coupé à la seconde, et aucune donnée n'a bougé : les devis créés par l'outil restent vos devis.

Révoquer plutôt que supprimer

Le jeton révoqué reste dans la liste avec son historique d'usage. C'est ce qui permet de répondre à « depuis quand cet outil n'appelait plus ? ».

À vous de jouer

Exercice 1 — Le jeton qui ne voit rien

Créez un jeton sans lui cocher aucun rôle, et essayez de lister les devis.

Corrigé

La création est refusée : au moins un rôle est exigé. Si vous contournez en cochant un rôle qui n'accorde aucun objet, /api/v1/health/ renvoie une liste objects vide et tous les appels répondent 404. Retenez le raisonnement : l'API n'a pas de droits à elle, elle n'a que ceux de ses rôles. Un jeton qui « ne marche pas » est presque toujours un jeton sans le bon rôle.

Exercice 2 — La limite d'appels

Réglez un jeton à 1 appel par minute, puis lancez trois appels d'affilée.

Corrigé

Le premier passe, les suivants répondent 429. Un programme bien écrit attend et réessaie au lieu d'insister. Sur un import de nuit, mieux vaut une limite haute et un programme qui la respecte, qu'aucune limite et un script qui sature l'application aux heures de bureau.

Exercice 3 — Le champ que l'outil ne doit pas voir

Ajoutez un champ Marge au devis, puis faites en sorte que l'API ne le renvoie jamais, tout en laissant l'outil créer ses devis.

Corrigé

Dans l'onglet Permissions de l'objet, décochez Marge des champs lisibles du rôle Intégration site web. La clé disparaît des réponses de l'API.

Vérifiez ensuite un champ calculé qui s'appuierait sur la marge : lui aussi disparaît. C'est délibéré, et c'est la seule protection sérieuse : servir le calcul rendrait la marge déductible par soustraction. Le même mécanisme protège le portail client.

Exercice 4 — Deux fois le même devis

Rejouez deux fois l'appel de l'étape 4, à l'identique. Que se passe-t-il, et comment l'éviter ?

Corrigé

Deux devis identiques sont créés : l'API fait ce qu'on lui demande, elle ne devine pas qu'un envoi a été rejoué. Deux façons de s'en prémunir :

• côté GesHoms, cocher unique sur le champ Référence : le second appel reçoit alors un 400 « Valeur en doublon » et rien n'est créé ;
• côté programme, chercher avant de créer (GET …/data/devis/?search=WEB-001) et n'écrire que si la recherche ne renvoie rien.

La première est la plus sûre, parce qu'elle tient même si le programme est mal écrit ou rejoué par un autre outil.

Exercice 5 — Ne rapatrier que ce qui vous intéresse

Votre tableau de bord veut les devis envoyés de plus de 1 000 €, du plus récent au plus ancien. Écrivez l'appel.

Corrigé

curl -G $GESHOMS/api/v1/data/devis/ -H "Authorization: Bearer $JETON" \
  --data-urlencode 'filters=[["statut","eq","envoye"],["total_ht","gt",1000]]' \
  --data-urlencode 'order_by=date' --data-urlencode 'order_dir=desc'

Deux pièges classiques. Le premier : statut se compare à son code, comme à l'écriture. Le second : si Total HT est un cumul des lignes, le filtre est refusé par un 400, parce qu'un champ calculé est évalué après la requête et fausserait count et la pagination. Filtrez alors sur un champ stocké, ou remontez les fiches et triez côté programme.

Pour une synchronisation régulière, [["updated_at","in_last",1]] ne rapatrie que ce qui a bougé depuis hier, ce qui vaut mieux que relire toute la table chaque nuit.

Exercice 6 — Un outil qui lit, un outil qui écrit

Votre tableau de bord doit lire tous les objets ; votre formulaire web ne doit créer que des devis. Combien de jetons, combien de rôles ?

Corrigé

Deux jetons, deux rôles. Un jeton par outil, toujours : révoquer le formulaire ne doit pas éteindre le tableau de bord, et le journal doit pouvoir dire lequel des deux a fait quoi. Un jeton partagé entre deux outils devient impossible à retirer sans casser quelque chose, ce qui est la meilleure façon de ne jamais le retirer.

Ce que vous avez appris

• Un jeton n'a pas de droits propres : il porte des rôles, les mêmes que vos utilisateurs, et il est fermé par défaut.
• Le premier appel utile est /api/v1/health/, qui dit ce que le jeton peut vraiment faire.
• Les erreurs se lisent : 400 la donnée ou le filtre, 403 l'action, 404 l'objet hors de portée, 429 le rythme.
• Les valeurs s'envoient dans le format attendu, et une liste de choix s'envoie par son code.
• Un champ masqué le reste, calcul compris.
• On révoque un accès, on ne le supprime pas : l'historique fait partie de la sécurité.

Référence complète des routes et des formats : Connecter vos outils (API). Retour au parcours de formation.