Odoo expose ses modèles par des appels distants : pratique pour un script interne, inadapté pour une application mobile ou un partenaire externe, qui attendent une interface documentée, versionnée et authentifiée autrement qu'avec un compte utilisateur.
Dix-neuf modules communautaires permettent d'exposer une vraie interface depuis Odoo — en deux générations, là encore. Ils terminent le dépôt rest-framework.
Résumé
Trois modules forment le socle de la génération actuelle : l'intégration de FastAPI, la bibliothèque d'extensibilité qui permet d'en dériver les classes, et la colle entre les deux.
Cinq modules traitent l'authentification et la protection : par clé d'API, par jeton JWT, par partenaire — un mécanisme d'annuaires authentifiant des contacts hors du système d'utilisateurs —, et un captcha avec son serveur auto-hébergé.
Quatre modules traitent la journalisation : un journal d'appels d'interface en base, son activation endpoint par endpoint pour FastAPI, et deux modules transformant une exception en activité ou en courriel.
Trois modules traitent la validation et le contexte : la bibliothèque de validation Pydantic et son utilitaire de conversion depuis les enregistrements Odoo, et un contexte de requête surchargeable.
Quatre modules enfin forment la génération précédente : le cadre REST historique, son raccordement aux clés d'API, son pont vers Pydantic, et son journal d'appels.
L'essentiel
- FastAPI intégré dans Odoo : routes, dépendances, intercepteurs.
- Un journal des appels en base : requête, réponse, durée, statut.
- Une exception transformée en activité ou en courriel.
- L'authentification par clé d'API ou par jeton JWT.
- L'authentification de partenaires hors du système d'utilisateurs.
- Un captcha avec serveur auto-hébergé sur les routes sensibles.
- La validation Pydantic des entrées et des sorties.
- Deux générations coexistent : FastAPI (actuelle) et REST (précédente).
Ce que ces modules ajoutent à l'instance
| Famille | Modules | Nombre |
|---|---|---|
| Socle FastAPI | fastapi, extendable, extendable_fastapi | 3 |
| Authentification | fastapi_auth_api_key, fastapi_auth_jwt, fastapi_auth_partner, auth_partner | 4 |
| Captcha | fastapi_captcha, fastapi_captcha_altcha_backend | 2 |
| Journalisation | api_log, api_log_mail, fastapi_log, fastapi_log_mail | 4 |
| Validation et contexte | pydantic, fastapi_endpoint_context | 2 |
| Génération précédente | base_rest, base_rest_auth_api_key, base_rest_pydantic, rest_log | 4 |
Les menus : FastAPI ▸ Endpoint FastAPI et Fastapi Logs, REST API ▸ Docs et Logs, Paramètres ▸ Technique ▸ Structure de la base de données ▸ API Log, Paramètres ▸ Technique ▸ Partner Authentication ▸ Directory.
Pourquoi une interface, et non les appels distants
Les appels distants d'Odoo exposent le modèle de données : l'appelant doit connaître les noms de champs, les noms de modèles et les règles métier. Toute évolution du modèle casse l'intégration — et il n'y a aucun endroit où écrire le contrat.
fastapi (version 18.0.1.3.4, la plus avancée du dépôt) intègre le cadre FastAPI dans Odoo : définir des applications complètes avec leurs routes, leurs dépendances, leurs intercepteurs et leur authentification. Les endpoints se configurent sous FastAPI ▸ Endpoint FastAPI.
L'intérêt par rapport aux appels distants : une interface documentée automatiquement, un contrat explicite, et des entrées validées avant d'atteindre le modèle.
extendable(LGPL-3, sans aucune dépendance Odoo) intègre une bibliothèque Python d'extensibilité : elle permet à un module tiers de dériver les classes d'une interface sans la réécrire.extendable_fastapiest la colle entre les deux, et permet d'utiliser des modèles Pydantic extensibles.
Le couple extensibilité et validation est ce qui rend l'approche viable sur le long terme : une interface qu'un module tiers peut étendre sans la forker.
Qui a le droit d'appeler
Trois mécanismes d'authentification, selon l'appelant :
| Module | Mécanisme | Pour qui |
|---|---|---|
fastapi_auth_api_key | Clé d'API en en-tête | Un système interne de confiance |
fastapi_auth_jwt | Jeton JWT, par dépendances FastAPI (LGPL-3) | Une application mobile, un service dont l'accès expire |
fastapi_auth_partner + auth_partner | Authentification de partenaires par annuaires | Des clients ou fournisseurs sans compte Odoo |
Le troisième mécanisme est le plus intéressant et le moins connu : authentifier des contacts en dehors du système d'utilisateurs Odoo. Un portail client à dix mille comptes n'a pas à créer dix mille utilisateurs — avec les droits, les sessions et les coûts d'administration que cela implique.
auth_partner apporte les annuaires sous Paramètres ▸ Technique ▸ Partner Authentication ▸ Directory, et dépend du module d'environnement serveur — donc des identifiants hors base.
Le captcha
fastapi_captcha protège des routes par un captcha, pour limiter les abus sur les endpoints sensibles — inscription, connexion.
fastapi_captcha_altcha_backend implémente un serveur de captcha auto-hébergé directement dans Odoo, au lieu de dépendre d'un service en ligne.
Comme pour le site web, l'auto-hébergement n'est pas une préférence technique : un captcha fourni par un service tiers appelle ce service depuis le navigateur de l'appelant, avec ce que cela implique de transfert de données.
Les clés d'API et les jetons eux-mêmes sont traités dans identité fédérée, clés d'API et jetons.
Le journal des appels
api_log enregistre en base chaque requête et chaque réponse : adresse, méthode, en-têtes, corps, code de statut, durée. Menu sous Paramètres ▸ Technique ▸ Structure de la base de données ▸ API Log.
Sans journal d'appels, un partenaire qui affirme avoir envoyé une commande et un Odoo qui ne l'a pas reçue ne peuvent pas être départagés. Avec le corps de la requête en base, la discussion dure trente secondes.
fastapi_log active cette journalisation endpoint par endpoint pour FastAPI, avec son menu FastAPI ▸ Fastapi Logs — ce qui permet de tout tracer sur un endpoint sensible et rien sur un endpoint à fort volume.
api_log_mail et fastapi_log_mail transforment une exception journalisée en notification active : création d'une activité Odoo, envoi d'un courriel.
C'est le module qui ferme la boucle d'exploitation : une interface qui échoue en silence échoue pendant des jours. Une exception qui crée une activité est une exception que quelqu'un voit.
fastapi_endpoint_context fournit un contexte de requête surchargeable, permettant d'adapter le comportement du code Odoo — règles métier, société, langue — selon l'appelant.
pydantic fournit un utilitaire de conversion d'enregistrements Odoo vers des modèles Pydantic, pour sérialiser les réponses sans écrire la correspondance à la main.
La génération précédente
Quatre modules forment le cadre REST historique, antérieur à FastAPI :
base_rest(version 18.0.1.2.0, LGPL-3) est le cadre de développement d'interfaces REST au-dessus d'Odoo, fondé sur le cadre de composants communautaire. Il apporte ses propres menus REST API ▸ Docs.base_rest_auth_api_key(LGPL-3) fait apparaître l'authentification par clé dans la documentation générée.base_rest_pydantic(LGPL-3) relie la validation Pydantic à ce cadre.rest_log(LGPL-3) journalise les appels, sous REST API ▸ Logs.
Comme pour l'EDI, le dépôt contient deux générations. Le README de
base_restle dit lui-même : c'est la base historique. Pour un nouveau projet, FastAPI est la direction prise par le projet communautaire — et la seule qui bénéficie encore de développements.
Limites connues
- Deux générations coexistent : FastAPI (actuelle, activement développée) et
base_rest(historique). Ne pas démarrer un projet sur la seconde. - La plupart de ces modules sont des socles pour développeurs : installés seuls, ils n'exposent aucune interface métier.
- Le journal des appels stocke les corps de requête en base : ils peuvent contenir des données personnelles. Prévoir une durée de conservation et des règles de purge.
- Un journal activé sur un endpoint à fort volume fait grossir la base rapidement : c'est précisément pourquoi l'activation est par endpoint.
auth_partnerauthentifie des contacts, pas des utilisateurs : les règles d'accès d'Odoo ne s'appliquent pas de la même façon. À instruire avant d'exposer des données.- Le captcha auto-hébergé consomme des ressources du serveur Odoo : à dimensionner.
fastapidépend d'un module de gestion de routes (endpoint_route_handler) etextendabled'une bibliothèque Python externe : vérifier la chaîne avant d'installer.- Exposer une interface élargit la surface d'attaque : authentification, limitation de débit et journalisation se posent ensemble, pas l'une après l'autre.
Identité technique
Les dix-neuf modules viennent du dépôt OCA rest-framework, branche 18.0 — dont tous les modules sont désormais documentés ici. Dix sont en AGPL-3, neuf en LGPL-3. Les dépendances externes : endpoint_route_handler pour FastAPI, component pour le cadre REST historique, auth_api_key, auth_api_key_group, auth_jwt et auth_signup pour l'authentification, queue_job et server_environment pour l'authentification de partenaires, mail pour les notifications.
Voir aussi identité fédérée, clés d'API et jetons et le cadre EDI de l'OCA.
Questions fréquentes
Pourquoi exposer une API plutôt qu'utiliser les appels distants d'Odoo ?
Parce que les appels distants exposent le modèle de données : l'appelant doit connaître les noms de champs et de modèles, toute évolution casse l'intégration, et il n'y a aucun endroit où écrire le contrat. fastapi permet une interface documentée, avec un contrat explicite et des entrées validées avant d'atteindre le modèle.
Faut-il créer un utilisateur Odoo par client d'un portail ?
Non, et c'est le mécanisme le moins connu du dépôt : auth_partner et fastapi_auth_partner authentifient des partenaires par annuaires, hors du système d'utilisateurs. Un portail à dix mille comptes n'a pas à créer dix mille utilisateurs. Attention : les règles d'accès d'Odoo ne s'appliquent pas de la même façon.
Peut-on savoir ce qu'un partenaire a réellement envoyé à notre API ?
Oui : api_log enregistre en base chaque requête et réponse — adresse, méthode, en-têtes, corps, statut, durée. Sans ce journal, un partenaire qui affirme avoir envoyé une commande et un Odoo qui ne l'a pas reçue ne peuvent pas être départagés. Prévoyez une durée de conservation : les corps peuvent contenir des données personnelles.
Comment être averti qu'une API échoue ?
api_log_mail et fastapi_log_mail transforment une exception journalisée en activité Odoo ou en courriel. C'est le module qui ferme la boucle : une interface qui échoue en silence échoue pendant des jours ; une exception qui crée une activité est une exception que quelqu'un voit.
Faut-il partir sur base_rest ou sur fastapi ?
Sur FastAPI pour tout nouveau projet. Le README de base_rest indique lui-même qu'il est la base historique ; FastAPI est la direction prise par le projet communautaire et la seule qui bénéficie encore de développements.
Se faire accompagner
Exposer une interface depuis un ERP est le projet où l'on sous-estime le plus l'exploitation : l'authentification se pose vite, la journalisation jamais, et l'alerte sur exception encore moins. Résultat, une intégration qui tombe un vendredi se découvre le mardi, par le partenaire.
Nous posons donc les trois ensemble — authentification, journal par endpoint, alerte sur exception — avant la première route en production, et nous fixons une durée de conservation des corps de requête, qui contiennent des données personnelles. Voir les prestations d'Atalios Consulting ou demander un rappel.
Pour aller plus loin
En résumé
Les appels distants d'Odoo conviennent à un script interne, pas à une application mobile ni à un partenaire externe. Dix-neuf modules permettent d'exposer une vraie interface — authentification, captcha, validation, et un journal des appels qui départage les litiges. Parlons de vos intégrations.
