Tutorial de integración de API REST y XML-RPC de Odoo: conecte cualquier sistema

Odoo expone todo su modelo de datos a través de API externas, lo que permite la integración con prácticamente cualquier sistema: plataformas de comercio electrónico, herramientas CRM, software de inteligencia empresarial, aplicaciones móviles y aplicaciones personalizadas. Este tutorial cubre los tres protocolos API (XML-RPC, JSON-RPC y REST), métodos de autenticación, operaciones CRUD y patrones de integración del mundo real con ejemplos de código y mejores prácticas.

Conclusiones clave

• Odoo proporciona tres protocolos API: XML-RPC (el más maduro), JSON-RPC (compatible con el navegador) y REST (Odoo 19, compatible con OpenAPI)
• Todas las API requieren autenticación mediante el nombre de la base de datos, el nombre de usuario y la contraseña o clave API
• Las operaciones CRUD siguen un patrón consistente en todos los protocolos: buscar, leer, crear, escribir, desvincular
• Los filtros de dominio utilizan una sintaxis de notación polaca para consultas complejas.
• La paginación, la selección de campos y las operaciones por lotes optimizan el rendimiento para grandes conjuntos de datos.

Comparación de protocolos API

Autenticación

Autenticación XML-RPC

La autenticación XML-RPC utiliza un proceso de dos pasos: autenticarse para obtener un ID de usuario (uid) y luego usar ese uid para llamadas posteriores.

La llamada de autenticación llega al punto final /xmlrpc/2/common con el método authenticate, pasando el nombre de la base de datos, el nombre de usuario, la contraseña y un objeto vacío. La respuesta es el ID de usuario numérico. Todas las llamadas de datos posteriores utilizan /xmlrpc/2/object con el método execute_kw, pasando la base de datos, el uid, la contraseña, el nombre del modelo, el nombre del método y los argumentos.

Autenticación JSON-RPC

JSON-RPC utiliza autenticación basada en sesiones a través del punto final /web/session/authenticate. El cuerpo de la solicitud es un objeto JSON con jsonrpc: "2.0", un método de call y parámetros que contienen db, login y password. La respuesta incluye un ID de sesión en la cookie que autentica las solicitudes posteriores.

Autenticación de API REST (Odoo 19)

La API REST admite claves API generadas en el backend de Odoo:

1. Vaya a Configuración > Usuarios > Claves API
2. Genere una nueva clave con permisos específicos.
3. Incluya la clave en el encabezado Authorization: Bearer

Los puntos finales REST siguen el patrón /api/{model} para colecciones y /api/{model}/{id} para registros individuales.

Operaciones CRUD

Buscar y leer

La operación más común es buscar registros con criterios específicos y leer los valores de sus campos.

Los filtros de dominio utilizan notación polaca (notación de prefijo) con operadores:

Condiciones combinadas: utilice & (AND), | (OR) y ! (NOT) como operadores de prefijo:

• AND: ['&', ['state', '=', 'sale'], ['amount_total', '>', 1000]] coincide con pedidos de venta superiores a 1000
• O: ['|', ['state', '=', 'sale'], ['state', '=', 'done']] coincide con cualquiera de los estados
• Complejo: ['&', ['state', '=', 'sale'], '|', ['partner_id', '=', 5], ['partner_id', '=', 10]]

Selección de campos: solicite solo los campos que necesita para reducir el tamaño de la carga útil y mejorar el rendimiento. Pase un parámetro fields con una lista de nombres de campos. Si se omite, se devuelven todos los campos.

Paginación: utilice los parámetros offset y limit para paginar los resultados. Ejemplo: offset: 20, limit: 20 devuelve los registros 21-40.

Crear registros

Cree registros llamando al método create con un diccionario de valores de campo. Se deben incluir los campos obligatorios. La respuesta devuelve el ID del registro recién creado (o una serie de ID para la creación por lotes).

Ejemplo: crear un contacto requiere como mínimo el campo name. Los campos opcionales incluyen email, phone, company_id, street, city, state_id, country_id y campos personalizados.

Para registros relacionados (uno2many o many2many), utilice tuplas de comandos especiales:

Actualizar registros

Actualice los registros llamando al método write con los ID de registro y un diccionario de campos modificados. Incluya únicamente los campos que deban cambiarse; los campos omitidos conservan sus valores actuales.

Se admiten actualizaciones por lotes: pase una lista de ID para actualizar varios registros con los mismos valores en una sola llamada.

Eliminar registros

Elimine registros llamando al método unlink con los ID de registro. El método devuelve True en caso de éxito.

Tenga cuidado con la eliminación: muchos registros de Odoo están protegidos por reglas comerciales. Intentar eliminar una factura publicada, por ejemplo, generará un error. Utilice en su lugar el método comercial adecuado (por ejemplo, button_cancel antes de la eliminación).

Patrones de integración del mundo real

Sincronización de pedidos de comercio electrónico

Sincronice pedidos desde una plataforma de comercio electrónico externa a Odoo:

1. Encuesta para nuevos pedidos: consulte la API de comercio electrónico para conocer los pedidos desde la última marca de tiempo de sincronización.
2. Emparejar clientes: busque contactos de Odoo por correo electrónico; crear si no se encuentra
3. Crear pedido de ventas: cree el pedido con información del cliente, líneas, envío y pago.
4. Confirmar pedido: llame a action_confirm para procesar el pedido a través del flujo de trabajo.
5. Actualizar comercio electrónico: enviar la referencia del pedido de Odoo nuevamente a la plataforma de comercio electrónico

Sincronización de inventario

Mantenga los niveles de inventario sincronizados entre Odoo y un canal externo:

1. Leer niveles de existencias: llame a search_read al stock.quant con filtros de ubicación
2. Push updates: Send quantity changes to the external channel
3. Manejar reservas: Cuenta de stock reservado (comprometido con pedidos pendientes)
4. Programar sincronización: ejecutar cada 15 a 30 minutos para mantener la precisión

Importación de clientes potenciales de CRM

Importe clientes potenciales desde plataformas de marketing a Odoo CRM:

1. Obtener clientes potenciales: obtenga nuevos clientes potenciales de la API de la plataforma de marketing.
2. Deduplicar: busque en Odoo contactos existentes por correo electrónico o por teléfono
3. Crear clientes potenciales: cree registros en crm.lead con seguimiento de origen
4. Asignar: use las reglas de asignación de clientes potenciales de Odoo o asigne según la lógica personalizada

Exportación de datos financieros

Exportar datos financieros a una plataforma de inteligencia empresarial:

1. Exportar plan de cuentas: Lea account.account para conocer la estructura de cuentas
2. Exportar asientos de diario: leer account.move.line con filtros de fecha
3. Exportar saldos: utilice read_group para agregar saldos por cuenta y período.
4. Programación: se ejecuta diariamente después del período de cierre de contabilidad.

Manejo de errores

Errores comunes de API

Limitación de velocidad

Odoo no aplica límites de velocidad de API de forma predeterminada, pero las implementaciones de producción deben implementar límites de velocidad en el nivel de proxy inverso. Para Odoo.sh, se aplican límites predeterminados para evitar abusos. Diseñe integraciones con intervalos de sondeo razonables y operaciones por lotes.

Estrategia de reintento

Implemente un retroceso exponencial para errores transitorios:

1. Primer reintento después de 1 segundo
2. Segundo reintento después de 4 segundos
3. Tercer intento después de 16 segundos.
4. Registrar y alertar después del máximo de reintentos

Optimización del rendimiento

Operaciones por lotes

Prefiera operaciones por lotes al procesamiento de registros individuales:

• create acepta una lista de diccionarios de valores para la creación por lotes
• write acepta una lista de ID para actualizaciones por lotes
• search_read con paginación es más eficiente que las llamadas read individuales

Selección de campo

Especifique siempre el parámetro fields para evitar cargar datos innecesarios. Cargar todos los campos en un modelo con más de 50 columnas genera una sobrecarga significativa, especialmente para modelos como sale.order o account.move.line.

Almacenamiento en caché

Caché que cambia lentamente los datos localmente:

• Catálogo de productos (actualizado cada hora)
• Lista de clientes (actualizar al recibir notificación de cambio)
• Tasas impositivas y posiciones fiscales (actualización diaria)

Servicios de integración de ECOSIRE

Construir integraciones confiables requiere comprender tanto el sistema externo como el modelo de datos de Odoo. Los [servicios de integración de Odoo] (/services/odoo/integration) de ECOSIRE cubren el diseño de API, el desarrollo de conectores, el mapeo de datos y el monitoreo continuo. Para las organizaciones que conectan plataformas de comercio electrónico, nuestra integración Shopify-Odoo y conectores de mercado especializados manejan los escenarios más comunes.

Lectura relacionada

• Guía de integración de API de Odoo
• Tuberías ETL para datos ERP: Odoo y Shopify
• Guía de implementación de Docker Odoo
• Guía de desarrollo de módulos personalizados de Odoo
• Seguridad API: autenticación y autorización

¿Qué protocolo API debo elegir para una nueva integración?

Para nuevos proyectos en Odoo 19, utilice la API REST. Sigue los estándares HTTP, tiene documentación generada automáticamente y admite claves API para autenticación. Para Odoo 17 o 18, XML-RPC es la opción más confiable y mejor documentada. JSON-RPC es mejor para integraciones basadas en navegador o aplicaciones JavaScript.

¿Existe un límite de velocidad en la API externa de Odoo?

Odoo en sí no impone límites de tarifas. Sin embargo, las implementaciones de Odoo.sh tienen límites a nivel de infraestructura y las implementaciones autohospedadas deben implementar limitaciones de velocidad en el nivel de proxy inverso (Nginx). Diseñe integraciones para utilizar operaciones por lotes e intervalos de sondeo razonables independientemente de los límites.

¿Puedo activar flujos de trabajo (confirmar pedido, registrar factura) a través de la API?

Sí. Utilice el método execute_kw con el nombre del método de flujo de trabajo. Por ejemplo, llame a action_confirm en una venta.orden para confirmarlo, o action_post en una cuenta.move para registrar un asiento de diario. Los métodos de flujo de trabajo aplican las mismas reglas comerciales que la interfaz de usuario.