Intégrer Odoo 19 à d'autres systèmes : API, webhooks, connecteurs et middleware

Très peu d'entreprises fonctionnent avec un seul système. Même lorsqu'Odoo est l'ERP central, il doit généralement dialoguer avec une passerelle de paiement, un transporteur, une banque, une boutique en ligne, une pointeuse ou une application historique. La qualité de ces liaisons détermine si vos données sont fiables ou si votre équipe passe chaque mois à rapprocher les écarts à la main.

Odoo 19 Enterprise propose une boîte à outils à plusieurs niveaux : des connecteurs intégrés configurés depuis les applications, une API externe pour les développeurs, des règles d'automatisation capables de recevoir et d'envoyer des webhooks, et des imports de fichiers lorsqu'une connexion en temps réel n'est pas possible. Des outils de middleware viennent s'ajouter à ces éléments lorsque vous avez besoin d'orchestrer de nombreux systèmes.

Une remarque sur les sources : cet article s'appuie sur la documentation officielle d'Odoo pour la version 19.0 (le dépôt odoo/documentation). Les menus, les options et les conditions des formules peuvent changer selon les versions et les types d'hébergement ; vérifiez donc toujours chaque étape dans une base de test ou une base dupliquée avant de l'appliquer en production.

Choisir le bon modèle d'intégration

Partez du besoin métier, pas de la technologie. Demandez-vous quelles données doivent circuler, dans quel sens, à quelle vitesse et qui détient l'enregistrement de référence. Choisissez ensuite l'option la plus légère qui répond au besoin.

• Utilisez un connecteur intégré lorsqu'Odoo prend déjà en charge le fournisseur, comme un fournisseur de paiement répertorié, un transporteur, un prestataire de synchronisation bancaire ou le connecteur Amazon.
• Utilisez l'API externe lorsqu'une autre application doit lire ou écrire des enregistrements Odoo selon son propre calendrier.
• Utilisez un webhook entrant lorsqu'un système externe doit transmettre un événement à Odoo dès qu'il se produit.
• Utilisez un webhook sortant lorsqu'Odoo doit notifier un autre système après une modification, par exemple lorsqu'un enregistrement est créé ou qu'un champ est mis à jour.
• Utilisez un middleware lorsque plusieurs systèmes sont impliqués, que les données nécessitent d'importantes transformations ou que vous avez besoin de nouvelles tentatives et d'une supervision centralisées.
• Utilisez l'import de fichiers lorsque l'autre partie ne fournit que des fichiers, comme des relevés bancaires aux formats CAMT.053, OFX, QIF, CSV ou XLSX.

L'API externe d'Odoo 19 : JSON-2 et clés API

Odoo 19 introduit l'API JSON-2, qui expose une partie de l'ORM via HTTP. Chaque appel est une requête POST vers un point de terminaison de la forme /json/2/ suivi du nom du modèle et du nom de la méthode, par exemple la méthode search_read du modèle res.partner. Le corps de la requête transmet les arguments de la méthode au format JSON.

L'authentification repose sur une clé API envoyée dans l'en-tête Authorization sous forme de jeton bearer. Il n'y a pas d'étape de connexion distincte avec un identifiant utilisateur et un mot de passe : la clé identifie l'utilisateur, et l'intégration agit avec les droits d'accès de celui-ci.

Pour créer une clé manuellement, ouvrez les Préférences de votre utilisateur, allez dans Sécurité du compte et choisissez Nouvelle clé API. Une description et une durée sont obligatoires, et la valeur de la clé n'est affichée qu'une seule fois ; stockez-la donc immédiatement dans un coffre-fort de secrets sécurisé. La documentation indique que les clés ne peuvent pas être créées pour plus de trois mois ; prévoyez donc dès le départ une routine de renouvellement des clés.

Lorsqu'un serveur héberge plusieurs bases de données, l'en-tête facultatif X-Odoo-Database indique à Odoo la base visée par l'appel. Derrière un proxy inverse, assurez-vous que l'en-tête Host parvient correctement à Odoo.

Chaque appel JSON-2 s'exécute dans sa propre transaction de base de données : il est validé en cas de succès et annulé en cas d'erreur. Vous ne pouvez pas enchaîner plusieurs appels dans une même transaction ; privilégiez donc une méthode unique qui réalise l'ensemble du travail lié, comme un search_read ou une méthode métier, plutôt que de nombreux petits appels susceptibles de laisser des données à moitié mises à jour.

Les erreurs sont renvoyées avec un statut HTTP 4xx ou 5xx et un corps JSON comprenant un nom et un message. Votre code client doit lire et journaliser les deux.

XML-RPC et JSON-RPC historiques : planifier la migration

De nombreuses intégrations existantes utilisent les anciens points de terminaison XML-RPC ou le point de terminaison JSON-RPC. Dans Odoo 19, ils sont dépréciés, et la documentation officielle indique que leur suppression est prévue dans Odoo 22. Ils fonctionnent encore aujourd'hui, mais les nouveaux projets doivent être bâtis sur JSON-2, et les intégrations existantes doivent être recensées et migrées dans le cadre de votre feuille de route de mise à niveau.

• Recensez chaque script, connecteur et outil tiers qui appelle les anciens points de terminaison.
• Remplacez l'authentification par identifiant et mot de passe par des clés API dédiées à chaque intégration.
• Réécrivez les séquences en plusieurs étapes en appels uniques lorsque c'est possible, en raison du fonctionnement à une transaction par appel.
• Testez la version migrée sur une base dupliquée avant de basculer le trafic de production.

La formule souscrite compte aussi. La documentation précise que l'accès aux données via l'API externe n'est disponible qu'avec les formules tarifaires Odoo Personnalisé, et non avec Une application gratuite ou Standard. Vérifiez votre abonnement avant de concevoir une intégration par API sur Odoo Online.

Webhooks et règles d'automatisation

Les règles d'automatisation permettent à Odoo de réagir à des événements sans module personnalisé. Dans Odoo 19 Enterprise, vous les gérez depuis Studio via le menu Automatisations, et les webhooks entrants disposent aussi de leur propre entrée Webhooks dans Studio. Le mode développeur offre davantage de contrôle, notamment le choix du modèle cible.

Pour un webhook entrant, créez une règle avec le déclencheur Sur webhook. Odoo génère automatiquement l'URL ; le système externe envoie une requête POST avec une charge utile JSON à cette URL. Le code de l'enregistrement cible indique à Odoo à quel enregistrement se rapporte la charge utile, et l'onglet Actions à faire définit la suite, généralement une action Exécuter du code lorsque vous devez créer des enregistrements plutôt qu'en mettre un à jour.

Activez Journaliser les appels pendant la construction et le dépannage. Cette option enregistre l'historique des requêtes adressées à l'URL, que vous pouvez consulter depuis le bouton intelligent Journaux de la règle.

Traitez l'URL du webhook comme un secret. La documentation avertit que la partager peut ouvrir un accès non souhaité à la base de données. Si elle est exposée, utilisez Renouveler le secret pour générer une nouvelle URL et mettez à jour le système externe.

Pour les notifications sortantes, ajoutez l'action Envoyer une notification webhook à une règle. Elle envoie une requête POST contenant les valeurs des champs sélectionnés à l'URL indiquée, et un exemple de charge utile vous aide à vérifier la structure avant la mise en production.

Lorsque vous rédigez des actions Exécuter du code, utilisez la fonction log pour écrire des messages dans la table de journalisation de la base de données, afin que les échecs soient visibles par les utilisateurs fonctionnels et pas uniquement dans les journaux du serveur.

Studio fait partie d'Odoo Enterprise. Dans Community, il n'existe pas d'interface Studio ; les mêmes besoins sont donc généralement couverts par une configuration en mode développeur ou par de petits modules personnalisés maintenus par un développeur.

Connecteurs intégrés pour les intégrations courantes

Avant d'écrire du code, vérifiez si Odoo prend déjà en charge le fournisseur. Les connecteurs intégrés sont maintenus à chaque version et constituent généralement le choix le plus sûr.

• Passerelles de paiement : configurez-les depuis Configuration, puis Fournisseurs de paiement, dans l'application Comptabilité, Site Web ou Ventes. Les fournisseurs répertoriés comprennent Stripe, Adyen, PayPal, Paymob, Mollie, Razorpay et d'autres. Saisissez les identifiants dans l'onglet Identifiants et utilisez d'abord le mode test avec des identifiants de bac à sable, idéalement sur une base dupliquée afin de préserver la numérotation des factures. Le journal de paiement doit être un journal de type Banque.
• Transporteurs : activez-les depuis les paramètres d'Inventaire, dans la section Connecteurs d'expédition. Les connecteurs pris en charge comprennent DHL Express, FedEx, UPS, Sendcloud, EasyPost et d'autres. Chaque mode d'expédition démarre dans un environnement de test ; le passage en production crée de véritables étiquettes que le transporteur peut facturer, vérifiez donc d'abord les tarifs et les étiquettes. L'option Déboguer les requêtes journalise les messages échangés.
• Banques : la synchronisation bancaire importe les transactions par l'intermédiaire de prestataires tiers tels que Plaid, Yodlee, Salt Edge, Ponto, Enable Banking et Basiq, et nécessite un abonnement Enterprise valide. Si votre banque n'est pas couverte, importez des fichiers de relevés depuis le journal de banque du tableau de bord de Comptabilité.
• E-commerce et places de marché : l'application eCommerce d'Odoo partage la même base de données, aucun connecteur n'est donc nécessaire. Pour Amazon, le connecteur Amazon synchronise les commandes sous forme de commandes client et fait correspondre les produits par référence interne.
• Pointeuses : l'application Présences prend en charge le mode kiosque sur un appareil dédié et le pointage depuis le back-end. Les terminaux biométriques d'autres fabricants ne sont pas couverts par la documentation officielle ; ils sont donc généralement connectés via un module personnalisé ou un middleware qui transmet les pointages à Odoo.

Middleware tel que n8n

Les plateformes de middleware comme n8n se placent entre Odoo et les autres systèmes. Ce sont des outils tiers, qui ne font pas partie d'Odoo, et elles communiquent avec Odoo via la même API externe et les mêmes webhooks que ceux décrits ci-dessus.

Elles sont utiles lorsqu'un événement doit mettre à jour plusieurs systèmes, lorsque la correspondance des champs est complexe, ou lorsque vous souhaitez un flux visuel avec une gestion centralisée des erreurs et des nouvelles tentatives. La contrepartie est un composant supplémentaire à héberger, sécuriser, superviser et mettre à niveau, et les mêmes conditions de formule pour l'accès à l'API continuent de s'appliquer.

Règles de conception : idempotence, gestion des erreurs et journalisation

La plupart des problèmes d'intégration proviennent de messages répétés, d'échecs partiels et d'erreurs silencieuses. Prévoyez-les dès le premier jour.

• Rendez chaque écriture idempotente : enregistrez la référence externe sur l'enregistrement Odoo et vérifiez-la avant toute création, afin qu'un webhook renvoyé ou un appel relancé ne crée pas de commande ou de paiement en double.
• Décidez qui est responsable de chaque champ, et ne laissez jamais deux systèmes écraser la même valeur.
• Regroupez autant que possible une opération métier dans un seul appel, car chaque appel JSON-2 constitue sa propre transaction.
• Ne relancez qu'en cas d'échec temporaire, avec des délais croissants, et envoyez les échecs définitifs vers une file de vérification.
• Journalisez la requête, la réponse et la référence de l'enregistrement Odoo pour chaque échange, à l'aide de Journaliser les appels, de Déboguer les requêtes ou de l'historique de votre middleware.
• Surveillez quotidiennement les volumes et les échecs pendant les premières semaines, et rapprochez les totaux, comme les paiements, les expéditions et les soldes bancaires, entre les systèmes.

Liste de contrôle de sécurité

• Créez un utilisateur d'intégration dédié disposant uniquement des droits d'accès nécessaires à l'intégration, et générez sa clé API depuis cet utilisateur.
• Utilisez une clé par intégration, indiquez son usage dans la description, choisissez une durée courte et renouvelez-la avant son expiration.
• Stockez les clés et les URL de webhooks dans un gestionnaire de secrets, jamais dans des feuilles de calcul, des messages de discussion ou du code source.
• Révoquez les clés et renouvelez les secrets des webhooks immédiatement lorsqu'une relation avec un fournisseur prend fin ou qu'une fuite est suspectée.
• Utilisez toujours HTTPS, et construisez et testez chaque intégration sur une base dupliquée avant de l'activer en production.

Comment 1CBMS peut vous aider

1CBMS conçoit et met en œuvre des intégrations Odoo 19 pour des entreprises en Égypte et en Irak : de la configuration des fournisseurs de paiement, des transporteurs et des flux bancaires à la réalisation d'intégrations par API JSON-2 et webhooks, en passant par la migration des scripts XML-RPC historiques et la connexion des pointeuses et des systèmes internes au moyen de modules personnalisés ou de middleware. Nous commençons par cartographier la responsabilité des données et les flux, testons tout sur une base dupliquée, et remettons une documentation et une supervision claires pour que votre équipe puisse se fier aux chiffres. Contactez-nous sur www.1cbms.com pour examiner votre paysage d'intégrations.