Brancher un CRM sans intégration native sur un agent IA n8n

Ouvre la liste des intégrations de n8n et cherche ton CRM. S’il s’appelle HubSpot ou Pipedrive, il y est, avec son nœud dédié et ses menus déroulants. S’il s’appelle Axonaut, Sellsy ou n’importe quel outil plus proche de ton marché, il n’y est pas. Et tous les tutoriels d’agents que tu trouveras supposent qu’il y est. Débrouille-toi, frérot.

Ce trou dans la liste cache pourtant une assez bonne nouvelle. Tout CRM sérieux expose une API HTTP documentée, et n8n sait parler à n’importe quelle API avec son nœud HTTP Request, y compris en tant que tool d’un agent. La méthode que tu vas apprendre ici, la lecture de la doc, la credential propre, le tool, les paramètres dynamiques, se transpose ensuite à tous les outils absents de la liste, CRM ou pas.

Le fil rouge sera Axonaut, un CRM français répandu dans les PME, et le point d’arrivée est concret : donner au sous-agent FAQ de l’organisme de formation, celui du système multi-agents n8n, un accès réel aux fiches clients pour répondre « oui, cette société a un compte chez nous, voici son contact » sans qu’un humain n’ouvre le CRM. Brancher un CRM sur un agent IA, proprement, avec les erreurs 401 et 422 traitées comme des informations plutôt que comme des punitions.

Une précision honnête avant de commencer : il existe un node communautaire Axonaut, installable depuis le marché des community nodes. Communautaire n’est pas natif : maintenance non garantie, audit à ta charge, installation impossible sur certaines instances gérées. La méthode HTTP que couvre cet article ne dépend de personne, et c’est exactement pour ça qu’elle vaut la peine d’être apprise.

Ce qu’il te faut

• n8n en version 1.90 ou plus récente, le point précis est expliqué plus bas
• un compte CRM avec l’accès API activé et une clé générée
• la documentation API de ton CRM ouverte dans un onglet
• l’article sur le système multi-agents en toile de fond utile, pas obligatoire
• environ 1 h 30, tests compris

Lire une doc API comme un plan de branchement

Avant d’ouvrir n8n, il faut extraire cinq informations de la documentation de l’API, toujours les mêmes, quel que soit le CRM. C’est un quart d’heure de lecture qui économise une soirée de tâtonnements.

Un, la méthode d’authentification. Chez Axonaut, c’est une clé API passée dans un header nommé userApiKey. Le nom exact compte au caractère près : UserApiKey, user-api-key ou Authorization renverront tous un 401. D’autres CRM utilisent Authorization: Bearer, d’autres encore un paramètre de requête, la doc tranche.

Deux, l’URL de base. Pour Axonaut, https://axonaut.com/api/v2. Toutes tes requêtes la préfixeront, et le v2 te dit au passage qu’une v1 a existé : les exemples de blog qui traînent peuvent pointer vers l’ancienne.

Trois, le format des erreurs. Cherche la section « errors » ou provoque une erreur volontaire dès tes premiers tests. Savoir à quoi ressemble un refus bien formé t’évitera de confondre plus tard un problème d’authentification avec un problème de données.

Quatre, la pagination. Paramètre de page, curseur, ou lien « suivant » dans la réponse : les trois écoles existent, et n8n gère les trois, mais pas avec la même configuration. Axonaut a choisi une quatrième voie, l’en-tête HTTP : quand une liste déborde, son API répond « Too many results. Use page header », un message d’erreur qui vend lui-même sa solution.

Cinq, les limites de débit. Un agent qui boucle peut appeler l’API plusieurs fois par seconde. Le plafond du CRM, requêtes par minute ou par heure, déterminera plus loin comment tu bornes le tool.

Ces cinq réponses en main, le branchement devient une suite de gestes mécaniques, et le premier concerne la clé.

La credential Header Auth propre, pas un JWT en dur

Le réflexe naturel, et c’est celui qu’il faut désapprendre tout de suite, consiste à ouvrir le nœud HTTP Request, ajouter un header userApiKey dans la section dédiée et coller la clé dedans. Ça fonctionne, et c’est précisément le problème : la clé vit maintenant en clair dans la définition du workflow. Elle part dans chaque export JSON, apparaît dans chaque copie d’écran, se retrouve dans le dépôt si tu versionnes tes workflows, et se dupliquera dans chaque nouveau nœud qui parle au CRM. Ce raccourci, c’est non.

La documentation du nœud HTTP Request prévoit le rangement correct : dans le nœud, choisis Generic Credential Type, puis Header Auth, puis crée la credential :

La différence n’est pas cosmétique. La valeur est chiffrée en base avec la clé d’instance N8N_ENCRYPTION_KEY, masquée à l’écran après la saisie, et absente des exports de workflow. Et surtout, elle n’existe qu’à un endroit : le jour où la clé fuite ou expire, tu la régénères dans le CRM, tu la remplaces dans la credential, et les douze nœuds qui s’en servent suivent sans être touchés.

Avant d’aller plus loin, valide l’authentification isolément, hors de tout agent. Un nœud HTTP Request classique, la credential fraîchement créée, et l’endpoint le plus simple de l’API, chez Axonaut GET /me qui renvoie les informations du compte. Une réponse 200 ici prouve que le trio header, clé, base URL est correct. C’est ton point de repère fixe : quoi qu’il se casse ensuite, tu sauras que l’authentification, elle, fonctionne. Trente secondes de test pour des heures de doute en moins : le meilleur taux horaire de ta semaine.

Transformer un endpoint en tool d’agent

L’authentification validée, on peut donner l’endpoint à l’agent, et c’est là que le vocabulaire change : le même nœud HTTP Request, attaché sous un AI Agent, devient un tool, une capacité que le modèle choisit d’utiliser ou pas selon la demande reçue.

Le schéma montre quatre maillons, et le plus décisif tient en un simple champ de texte : la description du tool, celle que le modèle lit pour décider quand s’en servir. « Recherche une société dans le CRM par son nom et renvoie ses informations de compte. À utiliser quand l’email mentionne une entreprise dont il faut vérifier l’existence ou les coordonnées. » Précise, bornée, avec le cas d’usage. Une description vague produit un agent qui appelle le CRM pour tout et n’importe quoi, ou jamais. Une bonne description, c’est Jarvis qui sait quand proposer l’armure : l’assistant de Tony Stark dans Iron Man ne sort pas un canon pour ouvrir une porte.

Le second maillon décisif est Optimize Response, une section d’options qui n’apparaît que quand le nœud est attaché à un agent, et que presque tout le monde ignore à la première configuration. Sans elle, chaque appel déverse la réponse brute de l’API dans le contexte du modèle : une fiche société Axonaut complète, avec ses adresses, ses champs personnalisés et ses métadonnées, pèse vite plusieurs kilo-octets dont le modèle n’a besoin que de trois lignes. Autant vider un camion de déménagement pour retrouver un trousseau de clés.

Le paragraphe qui suit la configuration mérite d’être retenu comme une règle : tout ce qui entre dans le contexte du modèle coûte des jetons et de l’attention. Un tool bien optimisé renvoie le minimum utile, et c’est aussi une protection : moins de données du CRM transitent par le fournisseur du modèle, moins la question de la confidentialité se pose. Pour le versant données personnelles de cette question, le nœud Guardrails complète ce que l’optimisation commence.

Les paramètres dynamiques avec $fromAI

Le tool sait où appeler, il reste à décider quoi chercher, et cette valeur change à chaque email : c’est le nom de la société mentionnée dans la demande. Le paramètre de recherche ne peut donc pas être écrit en dur, il doit être rempli par le modèle au moment de l’appel. C’est le rôle de $fromAI(), la même fonction que dans les tools du système multi-agents n8n, utilisée ici dans un champ du HTTP Request Tool :

Parametre de requete "search" :
{{ $fromAI('nom_societe', 'Le nom de la societe mentionnee dans l\'email, tel quel, sans le deviner ni le completer', 'string') }}

Les trois arguments font chacun un travail : la clé nomme le paramètre, la description dit au modèle comment le remplir, le type verrouille le format. La description est le vrai levier, et sa règle est la même que dans le système multi-agents : le modèle déduit une valeur présente dans le contexte, il ne l’invente pas. « Tel quel, sans le deviner ni le compléter » fait toute la différence entre chercher la société écrite dans l’email et chercher une société plausible. Et une société plausible, en production, ça s’appelle une erreur.

Un mot pour ceux qui suivent un tutoriel antérieur à 2025 : tu y verras des {placeholder} entre accolades avec une section « Placeholder Definitions » dans le nœud. Cette interface a été retirée autour de la version 1.90 de n8n, comme le documente l’issue GitHub #15085, et les accolades seules ne font plus rien. Si ton écran ne ressemble pas à celui du tutoriel, tu n’y es pour rien : utilise $fromAI(), partout où une valeur doit venir du modèle.

La pagination sans perdre de données

La recherche par nom renvoie une poignée de résultats, mais tôt ou tard un tool devra lister : toutes les factures impayées, tous les contacts d’un segment. Et les API sérieuses ne renvoient jamais tout d’un coup, elles paginent. Le nœud HTTP Request propose trois modes dans sa section Pagination, documentés sur la même page officielle : Off, Update a Parameter in Each Request pour les API à numéro de page, et Response Contains Next URL pour celles qui donnent le lien de la page suivante. Deux variables servent la logique : $pageCount, le nombre de pages déjà récupérées, et $response, la dernière réponse complète avec corps, headers et code.

La mécanique est simple, la vraie question est ailleurs, et elle est propre aux agents : faut-il vraiment paginer dans un tool ? Cinquante pages de résultats déversées dans le contexte du modèle, c’est le contraire de l’optimisation du chapitre précédent, et le modèle ne fera rien d’utile de huit cents fiches. Ma règle : un tool d’agent renvoie une réponse bornée, une page, triée par pertinence si l’API le permet, avec une limite explicite. Le traitement exhaustif, lui, appartient à un workflow classique, déclenché par l’agent si besoin mais exécuté hors de sa boucle, là où la pagination complète a du sens et où $pageCount peut grimper sans facturer un jeton.

Cette frontière entre ce que l’agent consulte et ce que le workflow traite rejoint le partage des rôles posé dans le système multi-agents : le modèle décide, les nœuds déterministes exécutent en volume. Chacun son poste, et tout le monde rentre à l’heure.

Débugger les 401 et les 422

Tout est branché, et un matin, ça casse. Les deux codes que tu verras le plus souvent avec une API CRM sont le 401 et le 422, et ils ont le bon goût de désigner chacun leur coupable. La méthode tient dans un arbre court :

Le 401 dit : je ne sais pas qui tu es. Il se joue dans l’authentification, presque jamais ailleurs. Les trois causes dans l’ordre des probabilités : le nom du header inexact (la casse compte), la clé révoquée ou expirée côté CRM, et le classique invisible, un espace ou un retour à la ligne embarqué avec la clé au moment du copier-coller. Le diagnostic utilise ton point de repère fixe : rejoue le GET /me du début avec la même credential. S’il échoue aussi, c’est bien l’authentification ; s’il passe, ton 401 vient d’un endpoint qui exige un droit que ta clé n’a pas.

Le 422 dit : je sais qui tu es, mais je refuse ce que tu m’envoies. Il n’apparaît que sur les écritures, et sa réponse contient presque toujours le détail du refus. Le réflexe que personne n’a au début : dans n8n, ouvre l’exécution échouée et lis le corps de la réponse d’erreur, pas seulement le code. Une API bien élevée y nomme le champ fautif :

{
  "errors": {
    "email": "format invalide",
    "company_id": "obligatoire"
  }
}

La structure exacte varie selon le CRM, l’information est la même : quel champ, quelle règle. Avec un agent dans la boucle, le 422 a une cause supplémentaire qui n’existe pas dans un workflow classique : le modèle a rempli un $fromAI avec une valeur mal formée, un téléphone avec des espaces, un identifiant deviné. C’est le signal qu’une description de paramètre est trop lâche, et la correction se fait dans le texte de la description, pas dans le code. La clé expirée vient du dehors, la description trop lâche vient de chez toi, et on ne corrige bien que ce qui vient de chez soi.

Un 4xx qui apparaît en production sur un tool qui marchait hier n’est pas un mystère : soit la clé a changé, soit l’API a évolué, soit le modèle remplit un paramètre autrement. Les trois se vérifient dans cet ordre, et les deux premiers ne sont pas de ta faute.

Écrire dans le CRM : le cran de sûreté

Jusqu’ici l’agent lit, et la lecture pardonne : une recherche ratée ne casse rien. L’écriture est une autre affaire, et c’est le moment de désamorcer l’enthousiasme qui vient naturellement quand le premier tool fonctionne : non, il ne faut pas donner à l’agent un tool « mettre à jour la fiche client » avec des $fromAI partout.

Le montage prudent sépare la proposition de l’exécution. L’agent produit une intention structurée, la fiche à modifier, le champ, la nouvelle valeur, et cette intention part dans un workflow déterministe qui valide, applique les règles métier et exécute l’appel HTTP d’écriture, avec sa credential, ses retries et son idempotence. Pour les actions engageantes, un devis, un changement de statut commercial, une étape d’approbation humaine s’intercale. C’est exactement la mécanique de la mise à jour du CRM après une signature décrite dans le pipeline de signature électronique : l’événement déclenche, la machine à états applique, personne ne laisse un modèle improviser un PATCH.

La même porte déterministe sert à construire un lead scoring CRM : les événements sont dédupliqués, le profil et l’engagement sont calculés séparément, puis le CRM n’est mis à jour qu’après contrôle des règles et des oppositions.

La règle qui résume la section, et qui vaut opinion : l’agent est un excellent lecteur et un mauvais greffier. Donne-lui tous les tools de lecture qu’il mérite, et garde les écritures derrière une porte déterministe. Le stylo reste de ton côté du guichet.

Ce qui va te bloquer

Cinq obstacles reviennent sur ce montage, dans un ordre à peu près chronologique.

Les placeholders qui ne marchent plus. Tu suis un tutoriel de 2024, tu écris {nom_societe} dans l’URL, et rien ne se remplit, sans message d’erreur. L’interface des Placeholder Definitions a été retirée autour de n8n 1.90. Remplace chaque accolade par une expression $fromAI() et le tool revit.

La réponse qui explose le contexte. Le tool fonctionne, mais l’agent devient lent, cher, et ses réponses se dégradent au fil de la conversation. Ouvre les logs de l’agent et regarde la taille de ce que le tool renvoie : sans Optimize Response, une liste de sociétés peut peser des dizaines de kilo-octets. Active l’optimisation, liste les champs utiles, garde la limite de caractères.

Le paramètre inventé. L’agent appelle le tool avec une valeur que personne ne lui a donnée, un nom de société approximatif, un email reconstruit. La cause est toujours la même : une description de $fromAI qui n’interdit pas la déduction hasardeuse. Ajoute la consigne négative explicite, « tel quel, sans le deviner », et si le paramètre est introuvable dans le contexte, le tool doit pouvoir répondre « pas trouvé » plutôt que recevoir une invention.

L’espace invisible dans la clé. Le GET /me renvoie 401 alors que la clé vient d’être générée. Avant de soupçonner le CRM, régénère la credential en tapant la clé plutôt qu’en la collant, ou colle-la dans un éditeur de texte d’abord pour voir les caractères parasites. Les gestionnaires de mots de passe ajoutent parfois un retour à la ligne final, et un header ne pardonne pas.

La pagination infinie. Ton workflow de listing tourne sans fin : l’API renvoie toujours un lien « suivant », même sur la dernière page, ou ton paramètre de page repart de zéro. Ajoute une condition d’arrêt explicite sur $pageCount en plus de la condition documentée par l’API, en garde-fou : dix mille pages est un bug, jamais un besoin.

Les limites

Cette méthode a un périmètre qu’il faut nommer. Un tool HTTP par endpoint, ça reste de l’artisanat : au-delà de quatre ou cinq tools CRM, la maintenance se disperse, les descriptions se recouvrent et l’agent choisit moins bien. L’étage au-dessus existe et il est structurel : regrouper les capacités CRM dans un serveur MCP dédié, versionné, testé, avec ses contrôles côté serveur, que n8n comme Claude peuvent consommer. L’artisanat pour démarrer et valider l’usage, le serveur quand l’usage se confirme.

Les limites de débit du CRM ne se négocient pas depuis n8n : si ton plan Axonaut plafonne les requêtes, aucun réglage de nœud ne créera du quota, il faudra mettre en cache les lectures fréquentes, une Data Table fait très bien ce travail de mémoire locale. Enfin, tout ce montage suppose une API stable et documentée : un CRM qui change ses endpoints sans préavis transformera tes tools en champ de mines, et c’est une information sur le CRM, pas sur la méthode.

Matrice de tests avant de laisser l’agent en autonomie

Chaque ligne se joue en quelques minutes, l’ensemble sépare un prototype d’un branchement de production.

La cinquième ligne est la plus révélatrice : un agent qui appelle le CRM sans raison a une description de tool trop vague, et ce défaut ne se voit que sur les cas négatifs, ceux que personne ne pense à tester.

Le sous-agent FAQ de l’organisme de formation a maintenant son accès réel aux fiches clients, et le pipeline complet, de l’email entrant à la réponse sourcée, tient debout de bout en bout. Il existe d’ailleurs une étape d’après, pour les curieux : laisser l’IA construire le workflow elle-même, avec l’AI Workflow Builder de n8n, et auditer ce qu’elle produit.

Et si tu branches un autre CRM avec cette méthode, Sellsy, Folk ou un outil local de ton marché, viens documenter le nom du header et les pièges rencontrés sur le hub lesnocodeurs : c’est exactement le genre de savoir qui n’existe dans aucune doc officielle.