Connecter une API sans coder : un premier échange entre deux applications

Une API permet à votre application de demander une information ou de déclencher une action dans un autre service. Voici un premier échange lisible, puis les règles à ajouter pour gérer les clés, les erreurs et les tentatives répétées.

Une API est une porte d’échange prévue par un service. Votre application lui envoie une demande dans un format défini ; elle reçoit une réponse qu’elle doit comprendre. Connecter une API sans coder vous-même reste possible avec un outil visuel ou un assistant, à condition de préciser l’information cherchée, les autorisations nécessaires et ce qui doit se passer en cas d’échec.

Commençons par un exemple public qui ne demande ni clé privée ni donnée client : retrouver une commune à partir d’un code postal avec l’API française de découpage administratif. Ensuite, nous transposerons la méthode à une connexion qui crée des dossiers. La lecture d’une information et la création d’une action ont des conséquences différentes.

Commencer par une demande que vous pouvez comprendre

La documentation de l’API des communes présente les critères de recherche et les champs de réponse. Pour notre essai, le critère est le code postal 78000. Les informations demandées sont le nom de la commune, son code administratif et ses codes postaux. Vous pouvez ouvrir cette requête publique dans votre navigateur.

Lors de la vérification du 2 octobre 2026, cette requête a renvoyé Versailles, le code 78646 et le code postal 78000. C’est un échange de lecture effectivement vérifié. Ce résultat ne vaut pas vérification d’une application entière, d’un formulaire ou de tous les codes postaux possibles. Il fournit un point de départ simple que vous pouvez reproduire.

Un code postal peut correspondre à plusieurs communes. Votre interface doit donc savoir présenter une liste, puis laisser choisir la bonne commune. Elle ne devrait pas prendre systématiquement le premier résultat. Décider ce comportement évite une erreur métier avant même de construire le formulaire.

Lire une réponse sans apprendre un langage de programmation

La réponse utilise un format nommé JSON : des informations rangées sous des noms de champs. Dans notre exemple, « nom » contient Versailles, « code » contient 78646 et « codesPostaux » contient une liste. Il n’est pas nécessaire de modifier cette réponse ; il faut comprendre quelle valeur votre application doit utiliser.

Demandez à l’assistant de vous montrer trois éléments côte à côte dans son explication : le champ reçu, sa signification et son usage dans votre écran. Le code administratif peut servir de référence stable. Le nom sert à l’affichage. Les confondre peut créer des doublons si un libellé évolue ou si deux communes portent un nom proche.

Votre premier objectif peut rester modeste : afficher les communes correspondant au code saisi, puis conserver le choix de l’utilisateur. La géolocalisation, le calcul d’itinéraire et la vérification d’une adresse complète sont d’autres besoins. Une API qui retourne des communes ne les réalise pas automatiquement.

Pour comprendre · illustration du guide

Préparer la connexion dans votre outil

Dans un outil visuel, vous devez généralement indiquer l’adresse de l’API, la méthode et les paramètres. Pour une lecture comme celle-ci, la méthode utilisée est GET. Le module HTTP Request de n8n documente ces réglages. Les noms d’écrans peuvent varier dans un autre outil, mais les informations à transmettre restent explicites.

Avec un assistant de code, demandez une seule connexion à la fois. Un brief clair serait : « Quand le code postal comporte cinq chiffres, cherche les communes. Affiche un choix lorsqu’il y en a plusieurs. Si aucun résultat n’arrive ou si la demande échoue, explique-le et laisse corriger le code. N’invente jamais une commune. »

Ajoutez une règle de rythme : une frappe ne doit pas déclencher une avalanche de demandes. Prévoyez un court délai ou une validation explicite, selon le formulaire. Le résultat d’une ancienne recherche ne doit pas remplacer celui d’une recherche plus récente. Vous pouvez vérifier ce cas en modifiant rapidement la saisie pendant un essai.

Séparer les informations publiques et les secrets

Notre exemple public ne demande pas de clé. De nombreux services exigent en revanche une identification ou un accès autorisé. Une clé peut permettre de lire, modifier ou facturer des opérations. Elle doit être traitée selon ses permissions et les recommandations du fournisseur, pas collée dans une capture ou un texte public.

Pour une clé secrète, demandez un échange côté serveur et un stockage dans les réglages secrets de l’environnement. Le navigateur de l’utilisateur ne doit pas recevoir cette clé. Certains services proposent aussi des identifiants publics : leur présence dans l’interface n’est pas automatiquement un défaut, mais elle ne remplace jamais les règles d’accès aux données.

Créez des accès distincts pour les essais et la production lorsque le service le permet. Notez leur propriétaire, les permissions accordées et la procédure de révocation. Si la connexion appartient au compte personnel d’un prestataire qui part, votre activité peut se retrouver bloquée malgré une application dont vous possédez le code.

Décrire chaque erreur comme une situation utilisateur

Un échec ne devrait pas devenir une liste vide sans explication. Un service indisponible, une autorisation refusée et une recherche sans résultat appellent des messages différents. Les codes de réponse HTTP donnent des indications techniques ; l’interface doit en faire une information utile, sans exposer de secret.

Pour notre formulaire, une absence de commune invite à vérifier la saisie. Une panne temporaire invite à réessayer. Un accès refusé dans une API privée doit être transmis au responsable de la connexion. Répéter la même demande indéfiniment ne corrige pas un droit manquant et peut aggraver la consommation ou le bruit dans les alertes.

Conservez une trace limitée : moment, opération, référence du dossier et type d’échec. Évitez de recopier dans les journaux toute la réponse si elle contient des informations personnelles. Le but est de comprendre l’incident, pas de créer une seconde base de données difficile à protéger et à supprimer.

Être plus exigeant lorsqu’une API crée quelque chose

Lire une commune ne crée pas de commande. Ajouter un dossier, envoyer un message ou déclencher un paiement exige des protections supplémentaires. Une réponse peut se perdre alors que l’action a déjà été effectuée. Si l’application réessaie aveuglément, elle peut créer deux dossiers ou envoyer deux messages.

Donnez à l’action une référence stable et vérifiez le mécanisme proposé par le fournisseur pour éviter les doublons. On parle souvent d’idempotence : répéter la même opération ne doit pas produire un nouvel effet à chaque fois. L’implémentation varie selon l’API ; demandez qu’elle soit expliquée et vérifiée avec votre scénario.

Dans un exemple fictif de demande d’achat, la référence ACH-017 reste la même lors d’une reprise. Avant de déclarer la transmission réussie, l’application doit savoir quel dossier distant lui correspond. Si le résultat reste incertain, elle affiche une vérification nécessaire. Elle ne fabrique ni succès ni échec définitif pour rendre le tableau plus propre.

Écrire la recette avant de connecter de vraies données

Préparez des entrées connues et leurs résultats attendus. Pour les communes, utilisez le cas documenté de Versailles et un cas à plusieurs réponses choisi dans le service. Ajoutez une saisie incomplète, une absence de résultat et une interruption de connexion. Ne présentez pas un échec réseau comme la preuve que le code postal n’existe pas.

• Réponse normale : le nom et la référence choisis sont correctement conservés après réouverture.
• Plusieurs résultats : l’utilisateur choisit ; aucun résultat n’est imposé silencieusement.
• Recherche précédente plus lente : elle ne remplace pas le résultat de la nouvelle saisie.
• Service indisponible : un message distinct apparaît et aucune donnée existante n’est effacée.
• Création répétée dans un environnement de test : une seule opération métier est produite.
• Accès retiré : la connexion cesse proprement et l’incident parvient au responsable prévu.

La fiche de connexion API contient la requête publique vérifiée, la lecture de sa réponse et une partie à compléter pour votre service. Les autres scénarios sont des essais à réaliser sur votre application. Gardez leurs résultats séparés des attentes pour ne pas transformer une liste de contrôle en preuve imaginaire.

Garder la connexion compréhensible dans le temps

Documentez qui fournit chaque donnée et ce que vous faites si le fournisseur change son format. Une colonne renommée ou une permission modifiée peut interrompre un échange qui fonctionnait hier. Fixez une personne responsable du suivi, même lorsque l’automatisation est discrète et que personne n’ouvre son écran chaque jour.

Dans Maestro, vous pouvez décrire le besoin d’échange, joindre une documentation publique et demander une construction progressive avec ses limites. La présence d’un service dans ce guide ne signifie pas qu’une intégration native est déjà fournie. Commencez par une lecture compréhensible, puis augmentez les conséquences des actions seulement lorsque les erreurs et les reprises sont maîtrisées.