API Odoo : utiliser le report à 2028 pour migrer vers JSON-2

Odoo a corrigé sa documentation 19 : les services XML-RPC et JSON-RPC historiques ne sont plus annoncés comme supprimés dans Odoo 20, mais dans Odoo 22, prévu à l’automne 2028. Ils restent dépréciés et l’API externe JSON-2 demeure leur remplaçante.

Ce report est une marge de manœuvre, pas une raison d’oublier le sujet. Pour une entreprise belge ou française, les connecteurs Odoo alimentent souvent l’e-commerce, la logistique, la finance, les outils décisionnels ou des applications métier. Une rupture d’API peut donc bloquer bien davantage qu’un échange technique.

Ce qui change — et ce qui ne change pas

Les points d’accès /xmlrpc, /xmlrpc/2 et /jsonrpc restent disponibles plus longtemps. Les contrôleurs personnalisés déclarés avec @route(type='jsonrpc') ne sont pas visés par cet avis de dépréciation. Il faut donc distinguer les services RPC externes génériques des routes développées dans des modules.

JSON-2 est disponible à partir d’Odoo 19. Les appels utilisent une URL de la forme /json/2/<modèle>/<méthode>, un corps JSON à arguments nommés et une clé API transmise comme jeton Bearer. Lorsque plusieurs bases partagent un domaine, l’en-tête X-Odoo-Database permet de choisir la base.

Pourquoi une simple réécriture du transport ne suffit pas

Authentification et droits

Les anciens appels transmettent couramment la base, l’identifiant utilisateur et le mot de passe à chaque requête. JSON-2 s’appuie sur des clés API. La migration doit prévoir un compte technique par intégration, des droits minimaux, une durée de vie adaptée, la rotation des clés et une procédure de révocation. Une clé ne contourne pas les droits Odoo de l’utilisateur auquel elle appartient.

Arguments et contrats

JSON-2 impose des arguments nommés. Les appels construits autour de paramètres positionnels doivent donc être cartographiés méthode par méthode. La documentation dynamique de chaque base, accessible sous /doc, aide à vérifier les méthodes et leurs signatures réelles.

Transactions

Chaque appel JSON-2 s’exécute dans sa propre transaction SQL. Enchaîner « créer, confirmer, puis écrire dans un autre objet » par plusieurs requêtes ne garantit pas l’atomicité de l’ensemble. Lorsqu’une opération métier doit réussir ou échouer en bloc, Odoo recommande une méthode dédiée dans un module, appelée en une seule requête.

Impact sur les migrations Odoo

Une entreprise en Odoo 16, 17 ou 18 ne peut pas simplement basculer son client vers JSON-2 : cette API apparaît avec Odoo 19. Le scénario doit donc être aligné avec la trajectoire de version. Il est possible de préparer dès maintenant une couche d’adaptation, des tests de contrat et l’inventaire des usages, puis d’activer JSON-2 sur l’environnement Odoo 19 de recette.

Pour les nouveaux connecteurs sur Odoo 19, démarrer directement sur JSON-2 évite d’ajouter une dette annoncée. Pour les intégrations existantes, la priorité dépend de leur criticité, de leur fréquence, de leur propriétaire et de leur couverture de tests — pas seulement du nombre d’appels.

Analyse Underside : traiter l’API comme un portefeuille de contrats

Nous recommandons de ne pas lancer une conversion globale et aveugle. Constituez un registre indiquant, pour chaque flux, le système appelant, la version Odoo, le compte technique, les modèles et méthodes utilisés, les volumes, la criticité, les données sensibles, les règles de reprise et le responsable métier.

Ce registre révèle souvent des scripts sans propriétaire, des clés partagées ou des séquences qui supposent à tort qu’une série d’appels forme une transaction. Le délai supplémentaire doit servir à corriger ces risques d’architecture. Une double exécution contrôlée, avec comparaison des résultats mais sans doubles écritures, est plus sûre qu’une bascule « big bang ».

Feuille de route recommandée

• Recenser les usages de /xmlrpc, /xmlrpc/2 et /jsonrpc dans le code, les iPaaS et les scripts d’exploitation.
• Séparer les API externes génériques des contrôleurs JSON-RPC personnalisés.
• Classer les flux par criticité métier et dépendance à une version Odoo.
• Créer des comptes techniques et clés distincts, avec droits minimaux et rotation testée.
• Documenter les contrats actuels : entrées, sorties, erreurs, idempotence et limites de volume.
• Regrouper dans une méthode serveur dédiée les séquences qui exigent une transaction atomique.
• Tester JSON-2 sur une copie représentative, y compris les refus d’accès, délais, doublons et reprises.
• Planifier le retrait de l’ancien client avant Odoo 22, avec une période de coexistence mesurée.

Cette démarche doit être intégrée au plan de migration Odoo et au modèle de sécurité et de droits d’accès, car les risques techniques et métier sont étroitement liés.

Sources officielles

• Odoo 19 — API externe JSON-2 et migration depuis XML-RPC/JSON-RPC.
• Odoo 19 — API RPC externe dépréciée.
• Odoo documentation — report officiel de la suppression à Odoo 22.