Construyendo integraciones REST sobre Odoo

Integrar Odoo con sistemas externos no es un ejercicio de configuración: es una disciplina de ingeniería. Las decisiones que tomes durante la primera semana — qué protocolo usar, cómo manejar fallos, qué datos fluyen y hacia dónde — definirán cuánto dolor absorberás en producción durante los próximos tres años.

Elegir el protocolo correcto

Odoo incluye JSON-RPC como interfaz externa principal. Cubre la superficie CRUD completa de cada modelo instalado, no requiere personalización en el servidor y respeta la capa de control de acceso de Odoo sin trabajo adicional. Para la mayoría de las integraciones de lectura intensiva es la opción predeterminada correcta.

El caso para un controlador REST personalizado surge cuando necesitas un endpoint específico del dominio que agrega lógica de varios modelos o cuando debes dar soporte a un sistema que no habla JSON-RPC. Compiten por el mismo grupo de workers que los usuarios interactivos — mantenlos ligeros.

Las colas de mensajes pertenecen a una tercera categoría. Cuando integras con un 3PL que procesa eventos de cumplimiento de forma asíncrona o una plataforma de comercio electrónico que lanza webhooks a ritmos impredecibles, un broker desacopla los sistemas, absorbe picos de carga, sobrevive a los reinicios de Odoo y permite reproducir eventos fallidos sin tocar datos de producción.

Autenticación y gestión de sesiones

La autenticación JSON-RPC en Odoo está basada en sesiones. La sesión expira, y si tu integración corre como un demonio, en algún momento encontrará un fallo de autenticación. Si no has diseñado para ello, ese fallo será silencioso y la pérdida de datos se descubrirá días después.

El patrón fiable es la re-autenticación automática ante un fallo y una cuenta de servicio dedicada con los derechos mínimos necesarios. Para endpoints REST personalizados, la autenticación por clave de API es más limpia que las cookies de sesión. El soporte nativo de claves de API de Odoo, disponible desde la versión 14, ofrece una credencial sin estado que no caduca al reiniciar el servidor.

Diseñar para fallos y reinicios de Odoo

Odoo se reinicia. Los despliegues ocurren, los workers se caen y la base de datos entra en modo de mantenimiento durante las migraciones. Cualquier integración que asuma disponibilidad continua fallará en producción.

Los patrones que funcionan son:

• Tablas de outbox dentro de Odoo — escribe en un área de staging local antes de intentar la entrega externa; un trabajo en segundo plano vacía el outbox y reintenta ante fallos.
• Consumidores idempotentes — cada registro enviado a un sistema externo lleva un identificador estable de Odoo para que las entregas duplicadas sean detectadas y descartadas.
• Backoff exponencial con destino de mensajes fallidos — los eventos que fallan más allá de un umbral van a una cola de mensajes muertos para revisión humana, no a un descarte silencioso.

Definir el contrato de integración

Antes de escribir código, responde por escrito cuatro preguntas: qué datos fluyen, en qué dirección, ante qué disparador y qué ocurre ante un error. Un buen contrato cubre el mapeo canónico a nivel de campo entre el modelo de Odoo y el esquema externo, el modelo de disparo (orientado a eventos, programado o por demanda), la propiedad de los errores y la política de compatibilidad hacia atrás.

Para la sincronización de comercio electrónico, el contrato debe abordar los conflictos de reserva de inventario y las cancelaciones de pedidos en vuelo. Para las exportaciones contables, debe definir el corte de periodos y el procedimiento de conciliación cuando un registro es rechazado por el sistema externo.

Patrones de integración en el mundo real

Los escenarios más comunes tienen sus propios modos de fallo:

• Sincronización de comercio electrónico — actualizaciones de stock concurrentes desde múltiples canales y cancelaciones que llegan después de que el cumplimiento haya comenzado en el almacén.
• Conexiones con almacenes 3PL — las confirmaciones de cumplimiento son casi siempre asíncronas; no cierres un albarán hasta recibir confirmación explícita del 3PL.
• Exportaciones contables — la mayoría de los sistemas rechazan registros con campos faltantes de forma silenciosa; valida antes del envío en lugar de depurar rechazos.
• Integraciones con TPV — los eventos de alta frecuencia y baja latencia requieren procesamiento en lotes; nunca bloquees la transacción del TPV esperando confirmación de Odoo.

Construir integraciones sobre Odoo es, en última instancia, respetar los límites entre sistemas — dar a cada sistema la propiedad de su propio estado, comunicarse a través de contratos bien definidos y tratar cada llamada de red como un fallo potencial. Los ingenieros que hacen esto bien no son los que conocen más endpoints de la API de Odoo. Son los que han pensado qué ocurre cuando las cosas salen mal y lo han diseñado desde el principio.