Odoo 20 : migrer de XML-RPC vers l’API JSON-2 en Python

Pourquoi migrer vos intégrations XML-RPC maintenant ?

Si un script, un connecteur ou un outil maison lit ou écrit dans Odoo par XML-RPC, il repose sur un mécanisme que l'éditeur retire par étapes. Voici le calendrier, tel que nous le comprenons à partir de la documentation officielle.

Quels sont les prérequis ?

• Une instance Odoo 20 (ou une copie de test de votre base)
• Un utilisateur dédié à l'intégration, avec seulement les droits nécessaires
• Une clé API générée pour cet utilisateur
• Python 3 et la bibliothèque requests (pip install requests)

Pour la clé API, ouvrez les préférences de l'utilisateur d'intégration et cherchez la section de sécurité du compte. Les libellés exacts peuvent varier d'une version à l'autre : vérifiez-les dans votre instance. Copiez la clé tout de suite, elle ne sera plus affichée.

Étape 1 : comment faire un premier appel JSON-2 ?

Un appel JSON-2 suit toujours le même modèle : une requête POST vers /json/2/<modèle>/<méthode>, la clé API dans Authorization, et les arguments de la méthode dans le corps JSON. Testons-le d'abord avec curl.

curl -X POST "https://mon-odoo.example.com/json/2/res.partner/search_read" \
  -H "Authorization: bearer VOTRE_CLE_API" \
  -H "X-Odoo-Database: ma_base" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"domain": [["is_company", "=", true]], "fields": ["name", "email"], "limit": 5}' 

Si tout est bien configuré, la réponse est une liste JSON de cinq contacts au plus. Passons maintenant à Python, avec une petite fonction réutilisable.

import requests

BASE_URL = "https://mon-odoo.example.com"
API_KEY = "VOTRE_CLE_API"
DB = "ma_base"

session = requests.Session()
session.headers.update({
    "Authorization": f"bearer {API_KEY}",
    "X-Odoo-Database": DB,
    "Content-Type": "application/json; charset=utf-8",
})

def call(model, method, **payload):
    """Appelle une méthode d'un modèle via l'API JSON-2."""
    r = session.post(f"{BASE_URL}/json/2/{model}/{method}", json=payload, timeout=30)
    r.raise_for_status()
    return r.json()

contacts = call(
    "res.partner", "search_read",
    domain=[["is_company", "=", True]],
    fields=["name", "email"],
    limit=5,
)
print(contacts)

Étape 2 : comment créer, modifier et supprimer des enregistrements ?

Les méthodes classiques de l'ORM s'appellent de la même façon. Les arguments portent leur nom dans le corps JSON : vals_list pour créer, ids et vals pour modifier, ids pour supprimer.

# Créer un contact (vals_list est une liste de dictionnaires)
nouveaux = call("res.partner", "create", vals_list=[{"name": "Client test API"}])
partner_id = nouveaux[0]
print("Créé :", partner_id)

# Modifier ce contact
call("res.partner", "write", ids=[partner_id], vals={"phone": "514 555 0100"})

# Relire le résultat
print(call("res.partner", "search_read",
           domain=[["id", "=", partner_id]],
           fields=["name", "phone"]))

# Supprimer le contact de test
call("res.partner", "unlink", ids=[partner_id])

Étape 3 : comment convertir un appel XML-RPC existant ?

Voici un appel typique en XML-RPC. Il demande deux requêtes distinctes (authentification, puis appel) et passe les arguments par position.

import xmlrpc.client

url, db, user, password = "https://mon-odoo.example.com", "ma_base", "api@exemple.com", "motdepasse"

common = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/common")
uid = common.authenticate(db, user, password, {})

models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object")
partners = models.execute_kw(
    db, uid, password,
    "res.partner", "search_read",
    [[["is_company", "=", True]]],
    {"fields": ["name", "email"], "limit": 5},
)

Le même appel en JSON-2 devient une seule requête, avec des arguments nommés.

partners = call(
    "res.partner", "search_read",
    domain=[["is_company", "=", True]],
    fields=["name", "email"],
    limit=5,
)

Étape 4 : comment gérer les erreurs et plusieurs bases ?

Dans la fonction call, raise_for_status() transforme un statut HTTP d'erreur en exception Python. Le corps de la réponse contient le détail de l'erreur, utile à journaliser. Ajoutons-le proprement.

import requests

class OdooApiError(Exception):
    pass

def call(model, method, **payload):
    r = session.post(f"{BASE_URL}/json/2/{model}/{method}", json=payload, timeout=30)
    if not r.ok:
        raise OdooApiError(f"{r.status_code} sur {model}.{method} : {r.text[:500]}")
    return r.json()

Pour un serveur qui héberge plusieurs bases, gardez une session par base, chacune avec son en-tête X-Odoo-Database. Ne mettez jamais la clé API dans le code source : lisez-la depuis une variable d'environnement.

Comment planifier la bascule sans interrompre vos opérations ?

• Lister tous les scripts, connecteurs et outils tiers qui appellent Odoo
• Vérifier si chaque outil tiers offre déjà une version compatible JSON-2
• Convertir vos propres scripts un par un et les tester sur une copie de la base
• Comparer les résultats ancien et nouveau appel sur les mêmes données
• Basculer en production en dehors des heures de pointe, avec un plan de retour

Les intégrations avec une boutique en ligne, un outil de paie ou un système d'expédition touchent souvent plusieurs modules à la fois. Si vous hésitez sur la portée du chantier, un partenaire Odoo peut en faire l'inventaire avec vous.

Foire aux questions sur l'API JSON-2 d'Odoo 20