Integrar Odoo 19 con otros sistemas: API, webhooks, conectores y middleware

Muy pocas empresas operan con un solo sistema. Incluso cuando Odoo es el ERP central, normalmente debe comunicarse con una pasarela de pago, un transportista, un banco, una tienda en línea, un dispositivo de asistencia o una aplicación heredada. La calidad de esas conexiones decide si sus datos son confiables o si su equipo pasa cada mes conciliando diferencias a mano.

Odoo 19 Enterprise ofrece un conjunto de herramientas por capas: conectores integrados que se configuran desde las aplicaciones, una API externa para desarrolladores, reglas de automatización que pueden recibir y enviar webhooks, e importación de archivos para los casos en que no es posible una conexión en tiempo real. Las herramientas de middleware se colocan encima de todo esto cuando se necesita orquestar muchos sistemas.

Una nota sobre las fuentes: este artículo se basa en la documentación oficial de Odoo para la versión 19.0 (el repositorio odoo/documentation). Los menús, las opciones y las condiciones de los planes pueden cambiar entre versiones y tipos de alojamiento, así que confirme siempre cada paso en una base de datos de prueba o duplicada antes de aplicarlo en producción.

Elija el patrón de integración adecuado

Parta de la necesidad del negocio, no de la tecnología. Pregúntese qué datos deben moverse, en qué dirección, con qué rapidez y quién es dueño del registro maestro. Luego elija la opción más ligera que cubra la necesidad.

• Use un conector integrado cuando Odoo ya admite al proveedor, como un proveedor de pago, un transportista o un proveedor de sincronización bancaria de la lista, o el conector de Amazon.
• Use la API externa cuando otra aplicación necesite leer o escribir registros de Odoo según su propio calendario.
• Use un webhook entrante cuando un sistema externo deba enviar un evento a Odoo en el momento en que ocurre.
• Use un webhook saliente cuando Odoo deba notificar a otro sistema después de un cambio, por ejemplo al crear un registro o al actualizar un campo.
• Use middleware cuando intervengan varios sistemas, cuando los datos requieran una transformación importante o cuando necesite reintentos y monitoreo centralizados.
• Use la importación de archivos cuando la otra parte solo proporcione archivos, como extractos bancarios en formato CAMT.053, OFX, QIF, CSV o XLSX.

La API externa en Odoo 19: JSON-2 y claves API

Odoo 19 introduce la API JSON-2, que expone parte del ORM a través de HTTP. Cada llamada es una solicitud POST a un endpoint con la forma /json/2/ seguida del nombre del modelo y del nombre del método, por ejemplo el método search_read del modelo res.partner. El cuerpo de la solicitud lleva los argumentos del método en JSON.

La autenticación usa una clave API enviada en el encabezado Authorization como token de portador (bearer). No hay un paso de inicio de sesión aparte con ID de usuario y contraseña, por lo que la clave identifica al usuario y la integración actúa con los permisos de acceso de ese usuario.

Para crear una clave manualmente, abra sus Preferencias de usuario, vaya a Seguridad de la cuenta y elija Nueva clave API. Se requieren una descripción y una duración, y el valor de la clave se muestra una sola vez, así que guárdelo de inmediato en un almacén de secretos seguro. La documentación indica que no se pueden crear claves por más de tres meses, así que planifique una rutina de rotación de claves desde el inicio.

Cuando un servidor aloja varias bases de datos, el encabezado opcional X-Odoo-Database indica a Odoo a qué base de datos va dirigida la llamada. Detrás de un proxy inverso, asegúrese de que el encabezado Host llegue correctamente a Odoo.

Cada llamada JSON-2 se ejecuta en su propia transacción de base de datos: se confirma si tiene éxito y se revierte si hay un error. No es posible encadenar varias llamadas en una sola transacción, así que prefiera un único método que haga el trabajo relacionado, como un search_read o un método de negocio, en lugar de muchas llamadas pequeñas que pueden dejar los datos a medio actualizar.

Los errores se devuelven con un estado HTTP 4xx o 5xx y un cuerpo JSON que incluye un nombre y un mensaje. Su código cliente debe leer ambos y registrarlos.

XML-RPC y JSON-RPC heredados: planifique su migración

Muchas integraciones existentes usan los antiguos endpoints XML-RPC o el endpoint JSON-RPC. En Odoo 19 están obsoletos, y la documentación oficial indica que está previsto eliminarlos en Odoo 22. Todavía funcionan, pero los proyectos nuevos deben construirse sobre JSON-2 y los existentes deben inventariarse y migrarse como parte de su hoja de ruta de actualización.

• Haga un inventario de todos los scripts, conectores y herramientas de terceros que llaman a los endpoints antiguos.
• Reemplace la autenticación con usuario y contraseña por claves API dedicadas para cada integración.
• Reescriba las secuencias de varios pasos como llamadas únicas cuando sea posible, debido al comportamiento de una transacción por llamada.
• Pruebe la versión migrada contra una base de datos duplicada antes de cambiar el tráfico de producción.

La disponibilidad según el plan también importa. La documentación indica que el acceso a los datos mediante la API externa solo está disponible en los planes de precios Personalizado de Odoo, no en One App Free ni en Estándar. Verifique su suscripción antes de diseñar una integración basada en la API en Odoo Online.

Webhooks y reglas de automatización

Las reglas de automatización permiten que Odoo reaccione a eventos sin módulos personalizados. En Odoo 19 Enterprise se gestionan desde Studio, en el menú Automatizaciones, y los webhooks entrantes también tienen su propia entrada Webhooks en Studio. El modo de desarrollador ofrece más control, incluida la elección del modelo de destino.

Para un webhook entrante, cree una regla con el disparador Al recibir un webhook. Odoo genera la URL automáticamente; el sistema externo envía una solicitud POST con una carga JSON a esa URL. El código del registro de destino indica a Odoo a qué registro se refiere la carga, y la pestaña Acciones a realizar define qué sucede después, normalmente una acción Ejecutar código cuando necesita crear registros en lugar de actualizar uno.

Active Registrar llamadas mientras construye y depura. Guarda el historial de solicitudes a la URL, que puede abrir desde el botón inteligente Registros de la regla.

Trate la URL del webhook como un secreto. La documentación advierte que compartirla puede dar acceso no deseado a la base de datos. Si queda expuesta, use Rotar secreto para generar una nueva URL y actualice el sistema externo.

Para las notificaciones salientes, agregue la acción Enviar notificación de webhook a una regla. Envía una solicitud POST con los valores de los campos que seleccione a la URL que indique, y una carga de ejemplo le ayuda a verificar la estructura antes de salir en vivo.

Al escribir acciones Ejecutar código, use la función log para escribir mensajes en la tabla de registros de la base de datos, de modo que los fallos sean visibles para los usuarios funcionales y no solo en los registros del servidor.

Studio forma parte de Odoo Enterprise. En Community no existe la interfaz de Studio, por lo que estas mismas necesidades suelen cubrirse con configuración en modo de desarrollador o con pequeños módulos personalizados que mantiene un desarrollador.

Conectores integrados para las integraciones más comunes

Antes de escribir código, verifique si Odoo ya cubre al proveedor. Los conectores integrados se mantienen con cada versión y suelen ser la opción más segura.

• Pasarelas de pago: configúrelas desde Configuración, luego Proveedores de pago, en la aplicación Contabilidad, Sitio web o Ventas. Entre los proveedores de la lista están Stripe, Adyen, PayPal, Paymob, Mollie, Razorpay y otros. Ingrese las credenciales en la pestaña Credenciales y use primero el modo de prueba con credenciales de sandbox, idealmente en una base de datos duplicada para proteger la numeración de las facturas. El diario de pagos debe ser un diario de tipo Banco.
• Transportistas: actívelos desde los ajustes de Inventario, en la sección Conectores de envío. Los conectores disponibles incluyen DHL Express, FedEx, UPS, Sendcloud, EasyPost y otros. Cada método de envío empieza en un entorno de prueba; pasarlo a producción genera etiquetas reales que el transportista puede facturar, así que verifique antes las tarifas y las etiquetas. La opción Depurar solicitudes registra los mensajes intercambiados.
• Bancos: la sincronización bancaria importa las transacciones mediante proveedores externos como Plaid, Yodlee, Salt Edge, Ponto, Enable Banking y Basiq, y requiere una suscripción Enterprise vigente. Si su banco no está cubierto, importe los archivos de extractos desde el diario de banco en el tablero de Contabilidad.
• Comercio electrónico y marketplaces: la propia aplicación Comercio electrónico de Odoo comparte la misma base de datos, así que no necesita conector. Para Amazon, el conector de Amazon sincroniza los pedidos como órdenes de venta y relaciona los productos por su referencia interna.
• Dispositivos de asistencia: la aplicación Asistencias admite el modo quiosco en un dispositivo dedicado y el registro de entrada desde el backend. Los terminales biométricos de otros fabricantes no están cubiertos por la documentación oficial, por lo que suelen conectarse mediante un módulo personalizado o un middleware que envía los registros de entrada a Odoo.

Middleware como n8n

Las plataformas de middleware como n8n se sitúan entre Odoo y otros sistemas. Son herramientas de terceros, no forman parte de Odoo, y se comunican con Odoo mediante la misma API externa y los mismos webhooks descritos arriba.

Son útiles cuando un evento debe actualizar varios sistemas, cuando la correspondencia de campos es compleja o cuando se desea un flujo visual con manejo de errores y reintentos centralizados. La contrapartida es un componente más que alojar, proteger, monitorear y actualizar, y siguen aplicándose las mismas condiciones de plan para el acceso a la API.

Reglas de diseño: idempotencia, manejo de errores y registros

La mayoría de los problemas de integración provienen de mensajes repetidos, fallos parciales y errores silenciosos. Diseñe pensando en ellos desde el primer día.

• Haga que cada escritura sea idempotente: guarde la referencia externa en el registro de Odoo y verifíquela antes de crear, para que un webhook reenviado o una llamada reintentada no genere un pedido o un pago duplicado.
• Decida quién es dueño de cada campo y nunca permita que dos sistemas sobrescriban el mismo valor.
• Mantenga una operación de negocio en una sola llamada cuando sea posible, porque cada llamada JSON-2 es su propia transacción.
• Reintente solo ante fallos temporales, con intervalos crecientes, y envíe los fallos permanentes a una cola de revisión.
• Registre la solicitud, la respuesta y la referencia del registro de Odoo en cada intercambio, usando Registrar llamadas, Depurar solicitudes o el historial de su middleware.
• Monitoree volúmenes y fallos a diario durante las primeras semanas, y concilie entre sistemas totales como pagos, envíos y saldos bancarios.

Lista de verificación de seguridad

• Cree un usuario de integración dedicado con solo los permisos de acceso que la integración necesita, y genere su clave API desde ese usuario.
• Use una clave por integración, registre su propósito en la descripción, elija una duración corta y rótela antes de que caduque.
• Guarde las claves y las URL de webhooks en un gestor de secretos, nunca en hojas de cálculo, mensajes de chat ni código fuente.
• Revoque las claves y rote los secretos de los webhooks de inmediato cuando termine la relación con un proveedor o se sospeche una filtración.
• Use siempre HTTPS, y construya y pruebe cada integración en una base de datos duplicada antes de activarla en producción.

Cómo puede ayudarle 1CBMS

1CBMS diseña e implementa integraciones de Odoo 19 para empresas de Egipto e Irak, desde la configuración de proveedores de pago, transportistas y conexiones bancarias hasta la construcción de integraciones con la API JSON-2 y webhooks, la migración de scripts XML-RPC heredados y la conexión de dispositivos de asistencia y sistemas internos mediante módulos personalizados o middleware. Empezamos con un mapa de la propiedad y los flujos de datos, probamos todo en una base de datos duplicada y entregamos documentación clara y monitoreo para que su equipo pueda confiar en las cifras. Contáctenos en www.1cbms.com para revisar su panorama de integraciones.