API REST Odoo : Exemples pratiques et tutoriel d'intégration

Selon le rapport 2025 State of APIs de Postman, 73 % des entreprises intègrent désormais leur ERP à au moins trois systèmes externes. Odoo, qui compte plus de 12 millions d'utilisateurs dans le monde, expose l'intégralité de son modèle de données via une riche couche API. Pourtant, la documentation laisse de nombreux développeurs aux prises avec les flux d'authentification, les opérations par lots et la gestion des erreurs de niveau production.

Ce didacticiel fournit des exemples prêts à copier-coller en Python et Node.js pour chaque modèle d'intégration courant. Que vous synchronisiez des commandes Shopify, transfériez des données à partir d'une application mobile ou créiez un tableau de bord personnalisé, ce guide vous couvre.

Points clés à retenir

• Odoo propose trois méthodes d'accès à l'API : XML-RPC (hérité, toutes les versions), JSON-RPC (protocole client Web) et API REST (Odoo 17+ avec clés API) — chacune avec des cas d'authentification et d'utilisation différents.
• L'authentification par clé API (Odoo 17+) est l'approche recommandée pour les intégrations de serveur à serveur : pas de gestion de session, pas de jetons CSRF, des en-têtes HTTP simples.
• Les domaines de recherche utilisent la puissante notation polonaise d'Odoo pour le filtrage : maîtrisez les opérateurs et vous pouvez interroger n'importe quelle combinaison de données.
• Les opérations par lots sont essentielles aux performances : la création de 1 000 enregistrements avec un seul appel d'API est 50 fois plus rapide que 1 000 appels individuels.
• La gestion des erreurs et la limitation du débit sont essentielles pour les intégrations en production — Odoo renvoie des réponses d'erreur structurées que votre code doit analyser et gérer avec élégance.

1. Méthodes d'authentification

Méthode 1 : Clés API (recommandées pour Odoo 17+)

Les clés API constituent la méthode la plus simple et la plus sécurisée pour la communication de serveur à serveur :

# Generate an API key in Odoo:
# Settings → Users → Select user → Account Security → New API Key

# Test authentication
curl -X GET "https://your-odoo.com/api/res.partner" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Python avec clé API :

import requests

class OdooAPI:
    def __init__(self, url, api_key):
        self.url = url.rstrip('/')
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
        })

    def get(self, model, params=None):
        response = self.session.get(
            f'{self.url}/api/{model}',
            params=params or {}
        )
        response.raise_for_status()
        return response.json()

    def post(self, model, data):
        response = self.session.post(
            f'{self.url}/api/{model}',
            json=data
        )
        response.raise_for_status()
        return response.json()

# Usage
odoo = OdooAPI('https://your-odoo.com', 'your-api-key-here')
partners = odoo.get('res.partner', {'limit': 10})

Node.js avec clé API :

const axios = require('axios');

class OdooAPI {
  constructor(url, apiKey) {
    this.client = axios.create({
      baseURL: `${url}/api`,
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      timeout: 30000,
    });
  }

  async get(model, params = {}) {
    const { data } = await this.client.get(`/${model}`, { params });
    return data;
  }

  async post(model, body) {
    const { data } = await this.client.post(`/${model}`, body);
    return data;
  }

  async put(model, id, body) {
    const { data } = await this.client.put(`/${model}/${id}`, body);
    return data;
  }

  async delete(model, id) {
    const { data } = await this.client.delete(`/${model}/${id}`);
    return data;
  }
}

// Usage
const odoo = new OdooAPI('https://your-odoo.com', 'your-api-key');
const partners = await odoo.get('res.partner', { limit: 10 });

Méthode 2 : JSON-RPC (toutes les versions)

JSON-RPC est le protocole utilisé par le client web d'Odoo en interne. Cela fonctionne avec toutes les versions d'Odoo :

import requests
import json

class OdooJsonRpc:
    def __init__(self, url, db, username, password):
        self.url = url.rstrip('/')
        self.db = db
        self.session = requests.Session()
        self.uid = self._authenticate(username, password)

    def _authenticate(self, username, password):
        response = self._call('/web/session/authenticate', {
            'db': self.db,
            'login': username,
            'password': password,
        })
        if not response.get('uid'):
            raise Exception(f"Authentication failed: {response}")
        return response['uid']

    def _call(self, endpoint, params):
        payload = {
            'jsonrpc': '2.0',
            'method': 'call',
            'params': params,
            'id': None,
        }
        response = self.session.post(
            f'{self.url}{endpoint}',
            json=payload,
            headers={'Content-Type': 'application/json'}
        )
        result = response.json()
        if result.get('error'):
            raise Exception(result['error']['data']['message'])
        return result.get('result')

    def search_read(self, model, domain=None, fields=None, limit=80, offset=0, order=None):
        return self._call('/web/dataset/call_kw', {
            'model': model,
            'method': 'search_read',
            'args': [domain or []],
            'kwargs': {
                'fields': fields or [],
                'limit': limit,
                'offset': offset,
                'order': order or '',
            },
        })

    def create(self, model, values):
        return self._call('/web/dataset/call_kw', {
            'model': model,
            'method': 'create',
            'args': [values],
            'kwargs': {},
        })

    def write(self, model, ids, values):
        return self._call('/web/dataset/call_kw', {
            'model': model,
            'method': 'write',
            'args': [ids, values],
            'kwargs': {},
        })

# Usage
odoo = OdooJsonRpc('https://your-odoo.com', 'mydb', 'admin', 'password')
orders = odoo.search_read('sale.order', [('state', '=', 'sale')],
                          fields=['name', 'amount_total', 'partner_id'],
                          limit=20)

Méthode 3 : XML-RPC (hérité, universel)

import xmlrpc.client

url = 'https://your-odoo.com'
db = 'mydb'
username = 'admin'
password = 'password'

# Authenticate
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid = common.authenticate(db, username, password, {})

# Create models proxy
models = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')

# Search and read
partners = models.execute_kw(db, uid, password,
    'res.partner', 'search_read',
    [[('is_company', '=', True), ('country_id.code', '=', 'US')]],
    {'fields': ['name', 'email', 'phone'], 'limit': 10}
)

2. Opérations CRUD

Créer des enregistrements

# Create a single contact
partner_id = odoo.create('res.partner', {
    'name': 'Acme Corporation',
    'is_company': True,
    'email': '[email protected]',
    'phone': '+1-555-0123',
    'street': '123 Main Street',
    'city': 'San Francisco',
    'state_id': 5,  # California
    'country_id': 233,  # United States
    'category_id': [(6, 0, [1, 3])],  # Tags: replace all with IDs 1 and 3
})

# Create a sale order with lines
order_id = odoo.create('sale.order', {
    'partner_id': partner_id,
    'date_order': '2026-03-23',
    'order_line': [
        (0, 0, {
            'product_id': 42,
            'product_uom_qty': 5,
            'price_unit': 99.99,
        }),
        (0, 0, {
            'product_id': 43,
            'product_uom_qty': 2,
            'price_unit': 149.99,
        }),
    ],
})

Équivalent Node.js :

// Create a contact
const partnerId = await odoo.post('res.partner', {
  name: 'Acme Corporation',
  is_company: true,
  email: '[email protected]',
  phone: '+1-555-0123',
  street: '123 Main Street',
  city: 'San Francisco',
  country_id: 233,
});

// Create sale order with lines
const orderId = await odoo.post('sale.order', {
  partner_id: partnerId,
  date_order: '2026-03-23',
  order_line: [
    [0, 0, { product_id: 42, product_uom_qty: 5, price_unit: 99.99 }],
    [0, 0, { product_id: 43, product_uom_qty: 2, price_unit: 149.99 }],
  ],
});

Lire les enregistrements

# Read specific fields from specific records
data = odoo.search_read('sale.order',
    domain=[('state', '=', 'sale'), ('amount_total', '>', 500)],
    fields=['name', 'partner_id', 'amount_total', 'date_order', 'state'],
    limit=50,
    offset=0,
    order='date_order desc'
)

# Read a single record by ID (REST API)
# GET /api/sale.order/42?fields=name,amount_total

// Node.js — read with pagination
async function fetchAllOrders(odoo) {
  const pageSize = 100;
  let offset = 0;
  let allOrders = [];

  while (true) {
    const orders = await odoo.get('sale.order', {
      domain: JSON.stringify([['state', '=', 'sale']]),
      fields: 'name,partner_id,amount_total',
      limit: pageSize,
      offset,
      order: 'date_order desc',
    });

    allOrders = allOrders.concat(orders);
    if (orders.length < pageSize) break;
    offset += pageSize;
  }

  return allOrders;
}

Mettre à jour les enregistrements

# Update a single record
odoo.write('res.partner', [partner_id], {
    'phone': '+1-555-9999',
    'website': 'https://acme.com',
})

# Update multiple records at once
draft_orders = odoo.search_read('sale.order',
    [('state', '=', 'draft'), ('date_order', '<', '2026-01-01')],
    fields=['id']
)
ids = [o['id'] for o in draft_orders]
odoo.write('sale.order', ids, {'note': 'Reviewed Q1 2026'})

Supprimer les enregistrements

# Delete records (use with caution)
odoo.write('res.partner', [obsolete_id], {'active': False})  # Prefer archiving

# Actually delete (rarely needed)
# models.execute_kw(db, uid, password, 'res.partner', 'unlink', [[obsolete_id]])

3. Domaines de recherche avancés

Les domaines de recherche d'Odoo utilisent la notation polonaise (notation de préfixe) pour combiner les conditions. L'opérateur par défaut entre les conditions est AND. Utilisez le tube '|' pour OR et esperluette '&' pour AND explicite. Chaque feuille est un tuple de nom de champ, d'opérateur et de valeur. Odoo prend en charge la notation par points pour filtrer les champs de modèle associés, tels que « partner_id.country_id.code » pour filtrer les commandes par pays du client.

# Complex domain examples

# Orders from US customers with amount > $1000, created this year
domain = [
    ('partner_id.country_id.code', '=', 'US'),
    ('amount_total', '>', 1000),
    ('date_order', '>=', '2026-01-01'),
    ('state', 'in', ['sale', 'done']),
]

# OR condition: email contains 'gmail' OR 'yahoo'
domain = [
    '|',
    ('email', 'ilike', 'gmail.com'),
    ('email', 'ilike', 'yahoo.com'),
]

# Complex: (state=sale AND amount>1000) OR (state=done AND amount>5000)
domain = [
    '|',
    '&', ('state', '=', 'sale'), ('amount_total', '>', 1000),
    '&', ('state', '=', 'done'), ('amount_total', '>', 5000),
]

# Negation: NOT archived
domain = [('active', '!=', False)]

# NULL check: has no email
domain = [('email', '=', False)]

# Hierarchical: all child categories of 'Electronics'
domain = [('categ_id', 'child_of', electronics_id)]

# Date ranges
from datetime import datetime, timedelta
domain = [
    ('create_date', '>=', (datetime.now() - timedelta(days=30)).strftime('%Y-%m-%d')),
    ('create_date', '<', datetime.now().strftime('%Y-%m-%d')),
]

Référence de l'opérateur

4. Opérations par lots

Les opérations par lots sont essentielles à la performance. Ne créez jamais d'enregistrements un par un en boucle :

# BAD: 1000 API calls (slow, ~300 seconds)
for customer in customers:
    odoo.create('res.partner', customer)

# GOOD: 1 API call with batch (fast, ~3 seconds)
# Using JSON-RPC batch create
partner_ids = odoo._call('/web/dataset/call_kw', {
    'model': 'res.partner',
    'method': 'create',
    'args': [customers],  # Pass list of dicts
    'kwargs': {},
})

// Node.js batch pattern with chunking
async function batchCreate(odoo, model, records, chunkSize = 200) {
  const results = [];

  for (let i = 0; i < records.length; i += chunkSize) {
    const chunk = records.slice(i, i + chunkSize);
    console.log(`Creating ${model} batch ${i / chunkSize + 1}/${Math.ceil(records.length / chunkSize)}`);

    const ids = await odoo.post(model, chunk);
    results.push(...(Array.isArray(ids) ? ids : [ids]));

    // Respect rate limits
    if (i + chunkSize < records.length) {
      await new Promise(resolve => setTimeout(resolve, 500));
    }
  }

  return results;
}

// Usage
const customers = generateCustomerData(); // Array of 5000 objects
const ids = await batchCreate(odoo, 'res.partner', customers);
console.log(`Created ${ids.length} partners`);

5. Gestion des erreurs

Les intégrations de production doivent gérer les erreurs avec élégance :

import requests
import logging
import time

logger = logging.getLogger(__name__)

class OdooAPIClient:
    MAX_RETRIES = 3
    RETRY_DELAY = 2  # seconds

    def __init__(self, url, api_key):
        self.url = url.rstrip('/')
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
        })

    def _request(self, method, endpoint, **kwargs):
        last_error = None

        for attempt in range(self.MAX_RETRIES):
            try:
                response = self.session.request(
                    method,
                    f'{self.url}{endpoint}',
                    timeout=30,
                    **kwargs
                )

                if response.status_code == 429:
                    retry_after = int(response.headers.get('Retry-After', 60))
                    logger.warning(f"Rate limited. Retrying after {retry_after}s")
                    time.sleep(retry_after)
                    continue

                if response.status_code == 401:
                    raise AuthenticationError("Invalid API key or session expired")

                if response.status_code == 403:
                    raise PermissionError(f"Access denied: {response.text}")

                if response.status_code == 404:
                    raise RecordNotFoundError(f"Record not found: {endpoint}")

                if response.status_code >= 500:
                    logger.error(f"Server error {response.status_code}: {response.text}")
                    if attempt < self.MAX_RETRIES - 1:
                        time.sleep(self.RETRY_DELAY * (attempt + 1))
                        continue
                    raise ServerError(f"Server error after {self.MAX_RETRIES} retries")

                response.raise_for_status()
                return response.json()

            except requests.exceptions.ConnectionError as e:
                last_error = e
                logger.warning(f"Connection error (attempt {attempt + 1}): {e}")
                if attempt < self.MAX_RETRIES - 1:
                    time.sleep(self.RETRY_DELAY * (attempt + 1))

            except requests.exceptions.Timeout as e:
                last_error = e
                logger.warning(f"Request timeout (attempt {attempt + 1}): {e}")
                if attempt < self.MAX_RETRIES - 1:
                    time.sleep(self.RETRY_DELAY * (attempt + 1))

        raise ConnectionError(f"Failed after {self.MAX_RETRIES} attempts: {last_error}")

class AuthenticationError(Exception): pass
class PermissionError(Exception): pass
class RecordNotFoundError(Exception): pass
class ServerError(Exception): pass

// Node.js error handling with axios interceptors
const axios = require('axios');

function createOdooClient(url, apiKey) {
  const client = axios.create({
    baseURL: `${url}/api`,
    headers: { Authorization: `Bearer ${apiKey}` },
    timeout: 30000,
  });

  // Response interceptor for error handling
  client.interceptors.response.use(
    (response) => response,
    async (error) => {
      const { config, response } = error;
      config.__retryCount = config.__retryCount || 0;

      // Rate limiting
      if (response?.status === 429) {
        const retryAfter = parseInt(response.headers['retry-after'] || '60', 10);
        console.warn(`Rate limited. Waiting ${retryAfter}s...`);
        await new Promise((r) => setTimeout(r, retryAfter * 1000));
        return client(config);
      }

      // Retry on server errors (max 3)
      if (response?.status >= 500 && config.__retryCount < 3) {
        config.__retryCount += 1;
        const delay = config.__retryCount * 2000;
        console.warn(`Server error ${response.status}. Retry ${config.__retryCount}/3 in ${delay}ms`);
        await new Promise((r) => setTimeout(r, delay));
        return client(config);
      }

      // Structured error response
      const errorMessage = response?.data?.error?.message
        || response?.data?.message
        || error.message;

      throw new Error(`Odoo API Error [${response?.status}]: ${errorMessage}`);
    }
  );

  return client;
}

6. Exemples d'intégration concrets

Shopify vers Odoo Synchronisation des commandes

class ShopifyOdooSync:
    def __init__(self, odoo_client, shopify_client):
        self.odoo = odoo_client
        self.shopify = shopify_client

    def sync_order(self, shopify_order):
        # 1. Find or create customer
        partner = self._get_or_create_partner(shopify_order['customer'])

        # 2. Map products
        order_lines = []
        for item in shopify_order['line_items']:
            product_id = self._find_product_by_sku(item['sku'])
            if not product_id:
                logger.warning(f"Product not found for SKU: {item['sku']}")
                continue
            order_lines.append((0, 0, {
                'product_id': product_id,
                'product_uom_qty': item['quantity'],
                'price_unit': float(item['price']),
                'discount': self._calc_discount(item),
            }))

        # 3. Create sale order
        order_id = self.odoo.create('sale.order', {
            'partner_id': partner['id'],
            'client_order_ref': shopify_order['name'],  # Shopify order #
            'order_line': order_lines,
            'note': f"Shopify Order: {shopify_order['id']}",
        })

        # 4. Auto-confirm if paid
        if shopify_order['financial_status'] == 'paid':
            self.odoo._call('/web/dataset/call_kw', {
                'model': 'sale.order',
                'method': 'action_confirm',
                'args': [[order_id]],
                'kwargs': {},
            })

        return order_id

    def _get_or_create_partner(self, customer):
        # Search by email first
        existing = self.odoo.search_read('res.partner',
            [('email', '=', customer['email'])],
            fields=['id', 'name'], limit=1)

        if existing:
            return existing[0]

        return {'id': self.odoo.create('res.partner', {
            'name': f"{customer['first_name']} {customer['last_name']}",
            'email': customer['email'],
            'phone': customer.get('phone'),
        })}

    def _find_product_by_sku(self, sku):
        products = self.odoo.search_read('product.product',
            [('default_code', '=', sku)],
            fields=['id'], limit=1)
        return products[0]['id'] if products else None

Récepteur Webhook (exemple de flacon)

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhook/odoo/order', methods=['POST'])
def handle_odoo_webhook():
    # Verify signature
    signature = request.headers.get('X-Odoo-Signature')
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({'error': 'Invalid signature'}), 401

    payload = request.json
    event_type = payload.get('event')

    if event_type == 'sale.order.confirmed':
        handle_order_confirmed(payload['data'])
    elif event_type == 'stock.picking.done':
        handle_shipment_complete(payload['data'])

    return jsonify({'status': 'ok'}), 200

7. Conseils de performances

Questions fréquemment posées

Quelle est la différence entre XML-RPC, JSON-RPC et l'API REST dans Odoo ?

XML-RPC est l'ancien protocole disponible dans toutes les versions d'Odoo : il est détaillé mais universellement pris en charge. JSON-RPC est le protocole utilisé par le client Web d'Odoo et fournit les mêmes fonctionnalités avec les charges utiles JSON. L'API REST a été introduite dans Odoo 17 et fournit des points de terminaison HTTP standard avec une authentification par clé API, ce qui en fait l'option la plus simple pour les intégrations modernes. Pour les nouveaux projets, utilisez l'API REST si vous êtes sur Odoo 17 ou version ultérieure.

Comment gérer les limites de débit de l'API Odoo ?

Odoo.sh applique des limites de débit en fonction du niveau de votre forfait. Lorsque vous recevez une réponse 429, lisez l'en-tête Retry-After et attendez avant de réessayer. Pour les intégrations à grand volume, implémentez une interruption exponentielle, regroupez vos opérations pour réduire le nombre d'appels d'API et envisagez d'utiliser les actions planifiées d'Odoo pour le traitement en masse au lieu des appels d'API en temps réel pour les synchronisations non critiques.

Puis-je appeler des méthodes Python personnalisées via l'API ?

Oui. Toute méthode publique sur un modèle Odoo peut être appelée via XML-RPC ou JSON-RPC à l'aide d'execute_kw. Pour l'API REST, vous devez créer un point de terminaison de contrôleur personnalisé avec @http.route. Les méthodes commençant par un trait de soulignement sont privées et ne peuvent pas être appelées en externe via XML-RPC. Validez toujours les entrées dans vos méthodes personnalisées pour éviter les attaques par injection.

Comment synchroniser efficacement des ensembles de données volumineux ?

Utilisez une combinaison de stratégies : synchronisation complète initiale avec opérations par lots et pagination (limite de 200 enregistrements par requête), puis synchronisations incrémentielles à l'aide du filtrage write_date pour récupérer uniquement les enregistrements modifiés depuis la dernière synchronisation. Stockez l'horodatage de la dernière synchronisation et utilisez-le comme filtre de domaine. Pour les ensembles de données très volumineux dépassant 100 000 enregistrements, envisagez la réplication directe de la base de données plutôt que la synchronisation API.

L'API Odoo REST est-elle disponible dans Odoo Community Edition ?

L'API REST native avec authentification par clé API a été introduite dans Odoo 17 Enterprise. Pour Odoo Community, vous pouvez utiliser XML-RPC ou JSON-RPC qui sont disponibles dans toutes les éditions, ou installer des modules communautaires comme le framework rest d'OCA qui ajoutent des points de terminaison RESTful. Les services d'intégration d'ECOSIRE prennent en charge toutes les éditions Odoo et les protocoles API.

Comment gérer les champs Many2many et One2many dans les appels d'API ?

Les champs relationnels utilisent des tuples de commandes spéciales : (0, 0, valeurs) pour créer et lier un nouvel enregistrement, (1, id, valeurs) pour mettre à jour un enregistrement lié, (2, id, 0) pour supprimer un enregistrement lié, (3, id, 0) pour dissocier sans supprimer, (4, id, 0) pour lier un enregistrement existant, (5, 0, 0) pour tout dissocier, et (6, 0, [ids]) pour remplacer tous les liens. Pour la lecture, ces champs renvoient des listes d'identifiants par défaut : utilisez search_read avec le nom du champ pour obtenir des données complètes.

Prochaines étapes

L'intégration des API est l'épine dorsale des systèmes d'entreprise modernes. Que vous construisiez une simple synchronisation de données ou une orchestration multiplateforme complexe, les modèles de ce guide vous seront très utiles.

Ressources connexes :

• Guide de développement Odoo Python — Plongez en profondeur dans le backend Python d'Odoo
• Guide de débogage des webhooks — Dépannage des intégrations de webhooks
• Connecteurs ECOSIRE Marketplace — Intégrations prédéfinies pour les principales plates-formes

Besoin d'aide pour l'intégration de l'API Odoo ? L'équipe d'intégration d'ECOSIRE a connecté Odoo à plus de 50 plateformes externes, dont Shopify, Amazon, Salesforce et des ERP personnalisés. De la simple synchronisation des données à l'orchestration bidirectionnelle en temps réel, nous construisons des intégrations évolutives. Planifiez une consultation technique gratuite.