API externa JSON-2 en Odoo 19
Odoo 19 incorpora JSON-2, una nueva alternativa para exponer la API externa con sintaxis RESTful y JSON como formato único. Reemplaza (o convive con) JSON-RPC y XML-RPC, simplifica el consumo desde sistemas externos y trae documentación interactiva integrada en el propio servidor.
1
¿Qué es la API JSON-2?
La API JSON-2 es una nueva alternativa para exponer la API externa de Odoo 19, pensada para simplificar el consumo desde sistemas externos (aplicaciones web, scripts, integraciones) usando una ruta tipo REST basada en JSON.
Características principales
/doc permite explorar modelos, métodos y esquemas desde el propio servidor.
2
Estructura de una request
La request es un POST a la URL /json/2/<model>/<method> con un objeto JSON. Tres bloques componen la petición:
2.1 — HTTP Headers
2.2 — Ruta URL
res.partner, sale.order).search, create, action_confirm).2.3 — Cuerpo JSON
@api.model.{"lang": "en_US"}.
3
Crear una clave de API externa
Tanto en planes Community como Enterprise se debe crear una clave que funcione como token de autorización. Se hace desde:
Preferencias
›
Seguridad
›
Claves API
Al pulsar Agregar clave API, se solicitan tres datos: la descripción (para identificarla más adelante), el propósito y la duración. Si pasa el tiempo configurado, la clave se invalida automáticamente:
El botón Generar clave crea una clave aleatoria de 160 bits. Se muestra una sola vez y no se puede recuperar — cópiala inmediatamente y guárdala en lugar seguro:
.gitignore).
4
Ejemplo: buscar registros
Configuramos las credenciales en el script (en este ejemplo, BD odoo19 con datos demo en local):
Buscamos clientes (res.partner) cuyo nombre contenga “deco” y sean compañías:
El cliente con id=9 existe. Ahora obtenemos más información (nombre, RFC, email, teléfono):
5
Ejemplo complejo: crear y confirmar una venta
Subimos la complejidad. Vamos a crear una venta con tres líneas y confirmarla — todo desde la API JSON-2. Tres partes:
5.1 — Buscar cliente y productos
Buscamos clientes que contengan “azure” y sean compañías, además de productos que contengan “pantalla”:
5.2 — Crear la venta
Llamamos al método create del modelo sale.order con un vals_list que define los campos y valores:
Al ejecutar, obtenemos el ID de la venta creada:
5.3 — Confirmar la venta
Ahora llamamos al método action_confirm con el ID de la venta:
sale.order impide duplicados de name). Elimina la venta anterior antes de re-ejecutar — o usa nombres dinámicos con timestamp.
6
Documentación interactiva en /doc
¿Cómo saber qué métodos puedes llamar y qué parámetros aceptan? El sistema expone el endpoint /doc con todos los modelos, métodos y esquemas:
Por cada método se muestra: ejemplo de request, parámetros, lo que devuelve y descripción. Por ejemplo, el método action_confirm:
7
Personalizar la documentación
La documentación se construye a partir del docstring que defines en el método Python. Si abrimos action_confirm:
Modificamos la descripción y el tipo de retorno en el archivo Python:
Al actualizar el módulo api_doc, los cambios se reflejan en la documentación dinámica:
8
Consejos rápidos
Authorization: bearer <API_KEY>.Content-Type: application/json.📌 En resumen
La API JSON-2 de Odoo 19 es la nueva forma RESTful de exponer el ORM al exterior. Con autenticación por API key, payload JSON, documentación dinámica en /doc y soporte para llamar cualquier método del modelo, simplifica integraciones desde aplicaciones web, scripts y sistemas terceros.
Reemplaza (o convive con) JSON-RPC y XML-RPC con una sintaxis más limpia. En Exdoo integramos Odoo con e-commerces, sistemas heredados, conectores de bancos y portales de clientes vía esta API, y compartimos contenido técnico para ayudar a otros developers Odoo a sacarle provecho.
Deja un comentario