--- title: "API externe Odoo : XML-RPC, JSON-RPC et la nouvelle API JSON-2" url: "https://digitalcrafting.tech/veille/api-externe-odoo-xml-rpc-json-2/" description: "API externe Odoo : XML-RPC, JSON-RPC et nouvelle API JSON-2 d’Odoo 19. Authentification par clé, méthodes utiles, droits, limites d’Odoo Online." published: "2026-09-25" updated: "2026-09-25" author: "François Legrand" site: "DigitalCrafting" rubrique: "Odoo" --- # API externe Odoo : XML-RPC, JSON-RPC et la nouvelle API JSON-2 > API externe Odoo : XML-RPC, JSON-RPC et nouvelle API JSON-2 d’Odoo 19. Authentification par clé, méthodes utiles, droits, limites d’Odoo Online. En bref - Jusqu’à Odoo 18, on appelle Odoo de l’extérieur en **XML-RPC** (ou JSON-RPC) avec `execute_kw`. - **Odoo 19 introduit l’API JSON-2** : un simple `POST /json/2//` avec une clé API en en-tête. XML-RPC et JSON-RPC y sont dépréciés. - Dans tous les cas, les appels respectent les **droits d’accès et règles d’enregistrement** de l’utilisateur : créez un utilisateur dédié aux intégrations. - Sur Odoo Online, l’API externe n’est disponible qu’avec l’offre **Custom**, et les appels doivent rester modérés. Dès qu’un site web, un outil d’emailing ou un tableur doit lire ou écrire dans Odoo, on passe par l’API externe. C’est la base de la plupart des intégrations que je fabrique. Or cette API change de visage avec Odoo 19 : il est temps de faire le point, documentation officielle à l’appui. ## Ce que dit la documentation, version par version ### Odoo 17 et 18 : XML-RPC (et JSON-RPC) La page « External API » des versions 17 et 18 décrit un protocole unique, XML-RPC, en deux temps. On s’authentifie d’abord auprès du service `common` (base, identifiant, mot de passe ou clé API), qui renvoie un identifiant utilisateur (`uid`). On appelle ensuite n’importe quelle méthode de modèle via `execute_kw` sur le service `object`. Le même mécanisme existe en JSON-RPC, sur l’URL `/jsonrpc` : le tutoriel « Web Services » des versions 17 et 18 montre que les exemples XML-RPC se transposent directement. ``` import xmlrpc.client url, db = "https://mon-odoo.example.com", "ma_base" login, key = "integration@example.com", "CLE_API" common = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/common") uid = common.authenticate(db, login, key, {}) models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object") clients = models.execute_kw( db, uid, key, "res.partner", "search_read", [[["is_company", "=", True]]], {"fields": ["name", "email"], "limit": 20, "context": {"lang": "fr_FR"}}, ) ``` ### Odoo 19 : l’API JSON-2 Odoo 19 ajoute une page « External JSON-2 API », marquée comme nouveauté de la 19.0. Le principe est beaucoup plus simple : pas de session ni d’`uid`, chaque appel est une requête HTTP autonome. - URL : `POST /json/2//`, par exemple `/json/2/res.partner/search_read`. - Authentification : en-tête `Authorization: bearer `. - Base de données : en-tête `X-Odoo-Database`, seulement si plusieurs bases partagent le même domaine. - Corps : un objet JSON avec les **paramètres nommés** de la méthode (`domain`, `fields`, `limit`, `context`…) et `ids` pour les méthodes d’enregistrement. Les arguments positionnels ne sont pas possibles. - Réponse : la valeur de retour en JSON (code 200), ou une erreur structurée en 4xx/5xx, par exemple 401 pour une clé invalide. ``` import requests r = requests.post( "https://mon-odoo.example.com/json/2/res.partner/search_read", headers={"Authorization": "bearer CLE_API", "User-Agent": "mon-integration/1.0"}, json={ "domain": [["is_company", "=", True]], "fields": ["name", "email"], "limit": 20, "context": {"lang": "fr_FR"}, }, timeout=30, ) r.raise_for_status() clients = r.json() ``` La page « External RPC API » de la 19.0, qui regroupe désormais XML-RPC et JSON-RPC, les marque comme dépréciés et présente JSON-2 comme leur remplaçant. La date de suppression annoncée a changé selon les révisions de la documentation : vérifiez la page de *votre* version avant de planifier une migration. Les routes JSON que vous écrivez vous-même dans un module (`@route(type="jsonrpc")`) ne sont pas concernées. ## Les méthodes à connaître | Méthode | À quoi elle sert | Bon réflexe | | --- | --- | --- | | `search_read` | Chercher et lire en un seul appel | Toujours préciser `fields` : sans liste, Odoo renvoie tous les champs lisibles | | `search_count` | Compter les enregistrements d’un domaine | Utile pour paginer avec `limit` et `offset` | | `read` | Lire des ids connus | Même règle : limiter les champs | | `fields_get` | Découvrir les champs d’un modèle | Filtrer les attributs (`string`, `type`, `help`) | | `create` / `write` | Créer, modifier | Les champs One2many / Many2many utilisent les commandes de `write` | | `unlink` | Supprimer | À réserver aux intégrations qui en ont vraiment besoin | ## Clés API et droits : là où tout se joue Depuis Odoo 14, on peut remplacer le mot de passe par une **clé API**, créée depuis les préférences de l’utilisateur, onglet « Sécurité du compte ». En Odoo 19, une clé a obligatoirement une durée de validité, limitée à trois mois selon la documentation JSON-2 : prévoyez la rotation dès la conception. Surtout, un appel API n’est jamais « admin par défaut » : il s’exécute avec les droits d’accès, les règles d’enregistrement et les accès aux champs de l’utilisateur authentifié. La documentation JSON-2 recommande un **utilisateur dédié**, avec le minimum de droits nécessaires. Astuce Je crée systématiquement un utilisateur « Intégration » par système connecté. Quand quelque chose écrit de travers dans Odoo, le suivi des modifications (chatter) dit immédiatement quel outil est en cause, et on peut couper une intégration sans toucher aux autres. ## Les pièges d’Odoo Online - **Offre requise** : la documentation précise que l’API externe n’est disponible que sur les offres *Custom*, pas sur « One App Free » ni « Standard ». - **Mot de passe local** : les utilisateurs Odoo Online se connectent via odoo.com ; pour XML-RPC, il faut leur définir un mot de passe local ou, mieux, une clé API. - **Débit** : la politique d’usage acceptable d’Odoo Cloud demande de limiter les appels (de l’ordre d’un appel par seconde, sans appels parallèles) et oriente les gros volumes vers l’import par lots ou Odoo.sh. - **Transactions** : en JSON-2, chaque appel est une transaction séparée. Pour une opération qui doit être « tout ou rien », on écrit une méthode dédiée dans un module et on l’appelle en une fois. ## En pratique : que faire de vos intégrations existantes ? Si vous êtes en Odoo 16, 17 ou 18, rien ne presse : XML-RPC fonctionne et reste la seule API documentée. En revanche, toute **nouvelle** intégration destinée à vivre après une montée en Odoo 19 gagne à isoler les appels dans une petite couche (une fonction `call(model, method, **params)`) : le jour de la migration, on change le transport à un seul endroit. Pour l’écriture dans Odoo déclenchée par un événement externe, pensez aussi aux **webhooks** des règles d’automatisation (Odoo 17 et suivants) : Odoo peut recevoir un appel sur une URL générée, ou envoyer lui-même un POST quand un enregistrement change. C’est souvent plus simple qu’un script qui interroge Odoo toutes les cinq minutes. ## Questions fréquentes ### Faut-il migrer tout de suite de XML-RPC vers JSON-2 ? Non, pas avant d’être en Odoo 19. XML-RPC reste documenté jusqu’à Odoo 18 et encore disponible en 19, où il est déprécié. Préparez la bascule en isolant les appels dans une seule fonction. ### L’API externe permet-elle de contourner les droits ? Non. Chaque appel s’exécute avec les droits d’accès et les règles d’enregistrement de l’utilisateur authentifié. D’où l’intérêt d’un utilisateur dédié par intégration, avec des droits minimaux. ### Peut-on utiliser l’API externe sur Odoo Online ? Oui, mais uniquement avec l’offre Custom selon la documentation officielle, et en respectant un débit modéré. Pour de gros volumes, Odoo oriente vers l’import par lots ou vers Odoo.sh. ## Sources - [Odoo 18 — External API (XML-RPC)](https://www.odoo.com/documentation/18.0/developer/reference/external_api.html) Odoo 17 et 18 - [Odoo 17 — External API](https://www.odoo.com/documentation/17.0/developer/reference/external_api.html) - [Odoo 18 — Web Services (JSON-RPC)](https://www.odoo.com/documentation/18.0/developer/howtos/web_services.html) - [Odoo 19 — External JSON-2 API](https://www.odoo.com/documentation/19.0/developer/reference/external_api.html) nouveauté 19.0 - [Odoo 19 — External RPC API (XML-RPC, JSON-RPC, dépréciés)](https://www.odoo.com/documentation/19.0/developer/reference/external_rpc_api.html) - [Odoo 19 — Webhooks des règles d’automatisation](https://www.odoo.com/documentation/19.0/applications/studio/automated_actions/webhooks.html) - [Odoo — Politique d’usage acceptable (Odoo Cloud)](https://www.odoo.com/acceptable-use) - [Odoo — Offres et tarifs](https://www.odoo.com/pricing-plan) Documentation consultée le 25 septembre 2026. ## Pour aller plus loin - [Intégrations API & data : faire parler vos logiciels entre eux](https://digitalcrafting.tech/integrations/) - [Modules Odoo sur mesure](https://digitalcrafting.tech/odoo/) - [Brancher Odoo à un assistant IA avec MCP](https://digitalcrafting.tech/veille/mcp-odoo-assistant-ia/) - [Listes de prix Odoo : distinguer un vrai bug d’un comportement normal](https://digitalcrafting.tech/veille/listes-de-prix-odoo-bug-ou-comportement-normal/)