Tutoriel d'intégration des API Odoo REST et XML-RPC : connectez n'importe quel système

Odoo expose l'intégralité de son modèle de données via des API externes, ce qui permet de l'intégrer à pratiquement n'importe quel système : plateformes de commerce électronique, outils CRM, logiciels de business intelligence, applications mobiles et applications personnalisées. Ce didacticiel couvre les trois protocoles API (XML-RPC, JSON-RPC et REST), les méthodes d'authentification, les opérations CRUD et les modèles d'intégration réels avec des exemples de code et des bonnes pratiques.

Points clés à retenir

• Odoo fournit trois protocoles API : XML-RPC (le plus mature), JSON-RPC (convivial pour le navigateur) et REST (Odoo 19, compatible OpenAPI)
• Toutes les API nécessitent une authentification à l'aide du nom de la base de données, du nom d'utilisateur et du mot de passe ou de la clé API.
• Les opérations CRUD suivent un modèle cohérent sur tous les protocoles : rechercher, lire, créer, écrire, dissocier
• Les filtres de domaine utilisent une syntaxe de notation polonaise pour les requêtes complexes
• La pagination, la sélection de champs et les opérations par lots optimisent les performances pour les grands ensembles de données

Comparaison des protocoles API

Authentification

Authentification XML-RPC

L'authentification XML-RPC utilise un processus en deux étapes : s'authentifier pour obtenir un identifiant utilisateur (uid), puis utiliser cet identifiant pour les appels ultérieurs.

L'appel d'authentification atteint le point de terminaison /xmlrpc/2/common avec la méthode authenticate, en transmettant le nom de la base de données, le nom d'utilisateur, le mot de passe et un objet vide. La réponse est l'ID utilisateur numérique. Tous les appels de données ultérieurs utilisent /xmlrpc/2/object avec la méthode execute_kw, en transmettant la base de données, l'uid, le mot de passe, le nom du modèle, le nom de la méthode et les arguments.

Authentification JSON-RPC

JSON-RPC utilise l'authentification basée sur la session via le point de terminaison /web/session/authenticate. Le corps de la requête est un objet JSON avec jsonrpc: "2.0", une méthode de call et des paramètres contenant db, login et password. La réponse inclut un ID de session dans le cookie qui authentifie les demandes ultérieures.

Authentification API REST (Odoo 19)

L'API REST prend en charge les clés API générées dans le backend Odoo :

1. Accédez à Paramètres > Utilisateurs > Clés API.
2. Générez une nouvelle clé avec les autorisations spécifiées
3. Incluez la clé dans l'en-tête Authorization: Bearer

Les points de terminaison REST suivent le modèle /api/{model} pour les collections et /api/{model}/{id} pour les enregistrements individuels.

Opérations CRUD

Rechercher et lire

L'opération la plus courante consiste à rechercher des enregistrements avec des critères spécifiques et à lire leurs valeurs de champ.

Les filtres de domaine utilisent la notation polonaise (notation de préfixe) avec les opérateurs :

Conditions de combinaison : utilisez & (AND), | (OR) et ! (NOT) comme opérateurs de préfixe :

• ET : ['&', ['state', '=', 'sale'], ['amount_total', '>', 1000]] correspond aux commandes de vente supérieures à 1 000
• OU : ['|', ['state', '=', 'sale'], ['state', '=', 'done']] correspond à l'un ou l'autre des états
• Complexe : ['&', ['state', '=', 'sale'], '|', ['partner_id', '=', 5], ['partner_id', '=', 10]]

Sélection de champs : demandez uniquement les champs dont vous avez besoin pour réduire la taille de la charge utile et améliorer les performances. Transmettez un paramètre fields avec une liste de noms de champs. En cas d'omission, tous les champs sont renvoyés.

Pagination : utilisez les paramètres offset et limit pour paginer les résultats. Exemple : offset: 20, limit: 20 renvoie les enregistrements 21 à 40.

Créer des enregistrements

Créez des enregistrements en appelant la méthode create avec un dictionnaire de valeurs de champ. Les champs obligatoires doivent être inclus. La réponse renvoie l'ID de l'enregistrement nouvellement créé (ou un tableau d'ID pour la création par lots).

Exemple : La création d'un contact nécessite au minimum le champ name. Les champs facultatifs incluent email, phone, company_id, street, city, state_id, country_id et les champs personnalisés.

Pour les enregistrements associés (one2many ou many2many), utilisez des tuples de commandes spéciaux :

Mettre à jour les enregistrements

Mettez à jour les enregistrements en appelant la méthode write avec le(s) ID d'enregistrement et un dictionnaire des champs modifiés. Incluez uniquement les champs qui doivent être modifiés : les champs omis conservent leurs valeurs actuelles.

Les mises à jour par lots sont prises en charge : transmettez une liste d'ID pour mettre à jour plusieurs enregistrements avec les mêmes valeurs en un seul appel.

Supprimer les enregistrements

Supprimez les enregistrements en appelant la méthode unlink avec le(s) ID d'enregistrement. La méthode renvoie True en cas de succès.

Soyez prudent lors de la suppression : de nombreux enregistrements Odoo sont protégés par des règles métier. Tenter de supprimer une facture publiée, par exemple, générera une erreur. Utilisez plutôt la méthode commerciale appropriée (par exemple, button_cancel avant la suppression).

Modèles d'intégration du monde réel

Synchronisation des commandes de commerce électronique

Synchronisez les commandes d'une plateforme de commerce électronique externe avec Odoo :

1. Sondage pour les nouvelles commandes : interrogez l'API de commerce électronique pour les commandes depuis le dernier horodatage de synchronisation
2. Match clients : recherchez des contacts Odoo par e-mail ; créer si introuvable
3. Créer une commande client : créez la commande avec les informations sur le client, les lignes, l'expédition et le paiement.
4. Confirmer la commande : Appelez action_confirm pour traiter la commande via le workflow
5. Mettre à jour le commerce électronique : renvoyer la référence de commande Odoo à la plateforme de commerce électronique

Synchronisation des stocks

Gardez les niveaux d'inventaire synchronisés entre Odoo et un canal externe :

1. Lire les niveaux de stock : Appelez search_read sur stock.quant avec des filtres de localisation
2. Mises à jour push : envoyez les modifications de quantité au canal externe
3. Gérer les réservations : compte du stock réservé (engagé sur les commandes en attente)
4. Synchronisation programmée : exécutez toutes les 15 à 30 minutes pour maintenir la précision.

Importation de prospects CRM

Importez des leads depuis des plateformes marketing dans Odoo CRM :

1. Récupérer des prospects : extrayez de nouveaux prospects de l'API de la plateforme marketing
2. Dédupliquer : recherchez Odoo pour les contacts existants par e-mail ou par téléphone
3. Créer des prospects : créez des enregistrements dans crm.lead avec suivi des sources
4. Attribuer : utilisez les règles d'attribution des leads d'Odoo ou attribuez-les en fonction d'une logique personnalisée.

Exportation de données financières

Exportez des données financières vers une plateforme de business intelligence :

1. Exporter le plan comptable : Lisez account.account pour la structure du compte
2. Exporter les écritures de journal : lisez account.move.line avec des filtres de date
3. Exporter les soldes : utilisez read_group pour agréger les soldes par compte et par période.
4. Calendrier : Exécuté quotidiennement après la fenêtre de clôture comptable

Gestion des erreurs

Erreurs API courantes

Limitation du débit

Odoo n'applique pas de limites de débit d'API par défaut, mais les déploiements de production doivent implémenter une limitation de débit au niveau du proxy inverse. Pour Odoo.sh, des limites par défaut s'appliquent pour éviter les abus. Concevez des intégrations avec des intervalles d'interrogation raisonnables et des opérations par lots.

Stratégie de nouvelle tentative

Implémentez un recul exponentiel pour les erreurs transitoires :

1. Réessayez d'abord après 1 seconde
2. Deuxième tentative après 4 secondes
3. Troisième tentative après 16 secondes
4. Enregistrez et alertez après le nombre maximum de tentatives

Optimisation des performances

Opérations par lots

Préférez les opérations par lots au traitement des enregistrements individuels :

• create accepte une liste de dictionnaires de valeurs pour la création par lots
• write accepte une liste d'identifiants pour les mises à jour par lots
• search_read avec pagination est plus efficace que les appels individuels read

Sélection de champ

Spécifiez toujours le paramètre fields pour éviter de charger des données inutiles. Le chargement de tous les champs sur un modèle comportant plus de 50 colonnes crée une surcharge importante, en particulier pour les modèles comme sale.order ou account.move.line.

Mise en cache

Mettre en cache localement les données qui changent lentement :

• Catalogue de produits (actualisation horaire)
• Liste des clients (actualisation sur notification de changement)
• Taux d'imposition et positions fiscales (actualisation quotidienne)

Services d'intégration ECOSIRE

Construire des intégrations fiables nécessite de comprendre à la fois le système externe et le modèle de données d'Odoo. Les services d'intégration Odoo d'ECOSIRE couvrent la conception d'API, le développement de connecteurs, le mappage de données et la surveillance continue. Pour les organisations connectant des plateformes de commerce électronique, nos intégration Shopify-Odoo et connecteurs de place de marché spécialisés gèrent les scénarios les plus courants.

Lecture connexe

• Guide d'intégration de l'API Odoo
• Pipelines ETL pour les données ERP : Odoo et Shopify
• Guide de déploiement de Docker Odoo
• Guide de développement de modules personnalisés Odoo
• Sécurité API : Authentification et autorisation

Quel protocole API dois-je choisir pour une nouvelle intégration ?

Pour les nouveaux projets sur Odoo 19, utilisez l'API REST. Il suit les normes HTTP, dispose d'une documentation générée automatiquement et prend en charge les clés API pour l'authentification. Pour Odoo 17 ou 18, XML-RPC est l'option la plus fiable et la mieux documentée. JSON-RPC est idéal pour les intégrations basées sur un navigateur ou les applications JavaScript.

Y a-t-il une limite de débit sur l'API externe d'Odoo ?

Odoo lui-même n'applique pas de limites de débit. Cependant, les déploiements Odoo.sh ont des limites au niveau de l'infrastructure, et les déploiements auto-hébergés doivent implémenter une limitation de débit au niveau du proxy inverse (Nginx). Concevez des intégrations pour utiliser des opérations par lots et des intervalles d'interrogation raisonnables, quelles que soient les limites.

Puis-je déclencher des workflows (confirmation de commande, publication de facture) via l'API ?

Oui. Utilisez la méthode execute_kw avec le nom de la méthode de workflow. Par exemple, appelez action_confirm sur une vente.commande pour la confirmer, ou action_post sur un compte.move pour publier une écriture de journal. Les méthodes de workflow appliquent les mêmes règles métier que l'interface utilisateur.