Integración con Servicios Externos: APIs y Webhooks en Odoo
Odoo no vive aislado. Las empresas necesitan conectar su ERP con sistemas externos: pasarelas de pago, plataformas de e-commerce, servicios de mensajería, sistemas de inventario y más. Este artículo explora los métodos de integración disponibles en Odoo 18, desde las APIs nativas hasta la configuración de webhooks, incluyendo ejemplos reales de conectores con servicios populares.
1. API JSON-RPC de Odoo
JSON-RPC es el protocolo nativo de Odoo para comunicación externa. Es el mismo que usa la interfaz web internamente. Para conectarte desde Python, usa xmlrpc.client para autenticarte con el método authenticate y luego ejecuta operaciones del ORM con execute_kw.
Ejemplo completo de conexión con autenticación, búsqueda y creación de registros usando el protocolo JSON-RPC nativo de Odoo.
2. API REST de Odoo (JSON)
Odoo 18 soporta JSON-RPC sobre HTTP con endpoints REST-like. Puedes usar curl, fetch de JavaScript o cualquier cliente HTTP para interactuar con Odoo. Los endpoints principales son /web/session/authenticate para autenticación, /web/dataset/call_kw para operaciones del ORM, y /web/dataset/call para métodos específicos.
3. Desarrollo de un Conector REST Reutilizable
Crea una clase base reutilizable que maneje la autenticación, sesiones HTTP, y operaciones CRUD. La clase encapsula la lógica de conexión y proporciona métodos simples para search_read, create, write y unlink. Usa requests.Session para mantener las cookies de autenticación entre llamadas.
import requests
import json
class OdooConnector:
def __init__(self, url, db, user, password):
self.url = url.rstrip('/')
self.db = db
self.user = user
self.password = password
self.session = requests.Session()
self.uid = None
self._authenticate()
def _authenticate(self):
resp = self.session.post(
f'{self.url}/web/session/authenticate',
json={
'jsonrpc': '2.0', 'method': 'call',
'params': {
'db': self.db, 'login': self.user,
'password': self.password,
}
}
)
data = resp.json()
if data.get('result'):
self.uid = data['result']['uid']
else:
raise Exception('Autenticación fallida')
def search_read(self, model, domain, fields=None, limit=100):
resp = self.session.post(
f'{self.url}/web/dataset/call_kw',
json={
'jsonrpc': '2.0', 'method': 'call',
'params': {
'model': model, 'method': 'search_read',
'args': [domain],
'kwargs': {'fields': fields or [], 'limit': limit}
}
}
)
return resp.json().get('result', [])
def create(self, model, vals):
resp = self.session.post(
f'{self.url}/web/dataset/call_kw',
json={
'jsonrpc': '2.0', 'method': 'call',
'params': {'model': model, 'method': 'create', 'args': [vals]}
}
)
return resp.json().get('result')4. Configuración de Webhooks Entrantes
Los webhooks permiten que servicios externos notifiquen a Odoo cuando ocurre un evento. Crea un controller HTTP en Odoo con el decorador route, verifica la firma del webhook usando HMAC-SHA256 para garantizar la autenticidad, y procesa la información recibida creando o actualizando registros en la base de datos.
5. Webhooks Salientes desde Odoo
Para enviar notificaciones a servicios externos cuando ocurren eventos en Odoo, sobrescribe los métodos de los modelos relevantes. Por ejemplo, al confirmar un pedido de venta, envía un POST con el payload del pedido a la URL del webhook configurada en los parámetros del sistema.
6. Integración con Pasarelas de Pago
Los módulos de pago en Odoo usan una arquitectura de provider que facilita la integración con múltiples pasarelas. Crea una clase que maneje la creación de pagos, la verificación de webhooks entrantes, y la reconciliación automática de transacciones con los pedidos correspondientes.
7. Integración con E-commerce
Los conectores de e-commerce sincronizan productos, pedidos y clientes entre Odoo y plataformas como Shopify o WooCommerce. Implementa la lógica de búsqueda o creación de clientes por email, la conversión de líneas de pedido, y el manejo de estados de envío.
8. Seguridad en Integraciones
Usa usuarios dedicados con permisos mínimos en Odoo. Almacena credenciales en variables de entorno nunca en código fuente. Usa HTTPS siempre para transmitir datos sensibles. Implementa rate limiting para evitar abusos. Valida y sanitiza todos los datos entrantes para prevenir inyección de código.
9. Monitoring de Integraciones
Crea un modelo de logs de integraciones que registre cada llamada API con su dirección (entrante o saliente), endpoint, código de estado HTTP, payload, respuesta, errores y duración en milisegundos. Esto te permite diagnosticar problemas rápidamente y mantener un historial de todas las comunicaciones con servicios externos.
10. Tareas Asíncronas para Integraciones
Para integraciones que no pueden bloquear el hilo principal de Odoo, usa cron jobs personalizados o el módulo job_queue de OCA. Programa el envío de webhooks de forma asíncrona para evitar timeouts y mejorar la experiencia del usuario.
11. Pruebas de Integración
Escribe pruebas unitarias que simulen las llamadas a APIs externas usando unittest.mock. Verifica que los webhooks se envíen correctamente al ejecutar acciones en Odoo, que las firmas se validen adecuadamente, y que los errores se manejen de forma graceful.
12. Documentación y Mantenimiento
Mantén documentadas todas las integraciones con información sobre el servicio externo, tipo de integración, endpoint, método de autenticación, frecuencia de sincronización, modelos de Odoo involucrados, errores comunes y sus soluciones, y contacto de soporte del servicio.
Conclusión
Las integraciones convierten a Odoo en el centro neurálgico de la infraestructura tecnológica. La clave es implementar integraciones robustas con manejo de errores, logging exhaustivo y mecanismos de reintento. Empieza con las APIs nativas de Odoo y evoluciona hacia webhooks y conectores personalizados según las necesidades del negocio.
13. Seguridad en Integraciones API
La seguridad es critica en todas las integraciones. Usa usuarios API dedicados en Odoo con permisos minimos necesarios para cada integracion. Nunca uses el usuario admin o un usuario con permisos de administrador para integraciones automatizadas.
Almacena todas las credenciales en variables de entorno o en un gestor de secretos como HashiCorp Vault. Nunca hardcodes credenciales en el codigo fuente o en archivos de configuracion que se suben a repositorios de control de versiones.
Implementa rate limiting en todos los endpoints de integracion para prevenir abusos. Un rate limit de 100 peticiones por minuto por IP es razonable para la mayoria de las integraciones. Los clientes que excedan el limite deben recibir un error 429 (Too Many Requests).
Valida y sanitiza todos los datos entrantes antes de procesarlos. Los payloads de webhooks pueden contener datos maliciosos que intentan inyectar codigo SQL, XSS, o CSRF. Usa las funciones de sanitizacion de Odoo para limpiar los datos antes de usarlos.
Registra todas las operaciones de integracion en un log de auditoria que incluya la IP del cliente, los datos enviados y recibidos, y el resultado de la operacion. Este log es invaluable para diagnosticar problemas y cumplir con requisitos de auditoria.
14. Testing de Integraciones
Las pruebas de integracion deben cubrir tanto el exito como el fallo de las comunicaciones. Usa unittest.mock para simular respuestas de APIs externas y verifica que tu codigo maneja correctamente los diferentes escenarios: respuesta exitosa, error de conexion, timeout, respuesta con datos invalidos, y errores HTTP 4xx y 5xx.
Para webhooks, prueba que la verificacion de firmas funciona correctamente con firmas validas e invalidas. Verifica que los payloads malformados se rechazan sin causar errores en la base de datos.
Implementa tests de integracion en un pipeline de CI/CD que se ejecuten automaticamente cada vez que se modifique el codigo de integracion. Los tests que dependen de servicios externos deben usar mocks para evitar dependencias de servicios que puedan no estar disponibles durante las pruebas.
Monitorea las metricas de integracion en produccion: tiempo promedio de respuesta, tasa de exito, y numero de errores. Estas metricas te ayudan a detectar problemas de rendimiento o disponibilidad en los servicios externos antes de que afecten a los usuarios.
15. Integracion con Servicios de Email Marketing
Los servicios de email marketing como Mailchimp, Sendinblue o SendGrid se pueden integrar con Odoo para sincronizar listas de contacto, automatizar envios, y rastrear metricas de entrega y apertura. La sincronizacion bidireccional garantiza que los contactos se mantengan actualizados en ambas plataformas.
Para sincronizar contactos, exporta los contactos de Odoo con sus campos personalizados y importa la plataforma de email marketing. Mapea los campos de Odoo con los campos de la plataforma para que la informacion se transfiera correctamente.
Las campanas de email marketing pueden activarse automaticamente desde Odoo usando webhooks. Cuando se crea un nuevo lead o se confirma un pedido, Odoo envia un webhook al servicio de email marketing que inicia la campana correspondiente.
Las metricas de email marketing (tasa de apertura, tasa de clics, tasa de rebote) se sincronizan de regreso a Odoo para enriquecer los perfiles de contacto. Los contactos que no abren emails pueden marcarse como inactivos o moverse a una lista de re-engagement.
16. Integracion con Herramientas de BI
Las herramientas de Business Intelligence como Metabase, Grafana o Power BI se pueden conectar directamente a la base de datos de Odoo para crear dashboards y reportes avanzados. La conexion directa a PostgreSQL permite crear visualizaciones en tiempo real sin necesidad de exportar datos.
Para proteger la base de datos, crea un usuario de solo lectura dedicado para la herramienta de BI con acceso solo a las vistas de reporte en lugar de las tablas originales. Esto evita que la herramienta de BI ejecute consultas costosas que afecten el rendimiento de Odoo.
Las vistas SQL personalizadas (CREATE VIEW) son ideales para la integracion con herramientas de BI. Crea vistas que combinen datos de multiples tablas y calculen metricas de negocio, y conecta la herramienta de BI a estas vistas en lugar de a las tablas base.
Para dashboards en tiempo real, usa las vistas materializadas de PostgreSQL que almacenan pre-calculos que se actualizan periodicamente. Esto reduce la carga en la base de datos y mejora el rendimiento de las consultas de BI.
17. Integracion con Herramientas de Soporte
Las herramientas de soporte como Zendesk, Freshdesk o Jira Service Desk se pueden integrar con Odoo para sincronizar tickets de soporte con oportunidades de CRM. Cuando un cliente envia un ticket de soporte, se crea automaticamente un registro en Odoo con los datos del cliente y la descripcion del problema.
La sincronizacion bidireccional permite que los agentes de soporte vean el historial de pedidos y facturas del cliente directamente desde la herramienta de soporte. Cuando se resuelve un ticket, el estado se actualiza en ambas plataformas.
Para integraciones con herramientas de chat en vivo como Intercom o Drift, crea webhooks que notifiquen a Odoo cuando un cliente inicia una conversacion. Esto permite que los vendedores respondan rapidamente a clientes potenciales con contexto completo de su historial.
Los SLAs (Service Level Agreements) se pueden configurar en Odoo para dar seguimiento automatico a los tiempos de respuesta de soporte. Configura alertas que notifiquen a los supervisores cuando un ticket esta proximo a vencer su SLA.
18. Integracion con Herramientas de Proyecto
Las herramientas de gestion de proyectos como Jira, Asana o Monday se pueden sincronizar con Odoo Project para mantener las tareas actualizadas en ambas plataformas. La sincronizacion permite que los equipos de desarrollo usen su herramienta preferida mientras los managers ven el progreso en Odoo.
Para sincronizar tareas, crea un mapeo entre los campos de la herramienta externa y los campos de Odoo. Los campos como prioridad, fecha de vencimiento, y responsable se sincronizan automaticamente cuando cambian en cualquiera de las dos plataformes.
Los reportes de tiempo (timesheets) se pueden sincronizar entre Odoo y la herramienta de proyecto para mantener un registro unificado del tiempo dedicado a cada tarea. Esto es especialmente util para empresas que facturan por horas.
Para integraciones con repositorios de codigo como GitHub o GitLab, configura webhooks que creen commits automaticamente en Odoo cuando se hace push al repositorio. Esto permite rastrear que cambios de codigo corresponden a que tareas de Odoo.
19. Integracion con Herramientas de Monitoreo
Las herramientas de monitoreo de aplicaciones como New Relic, Datadog o Dynatrace proporcionan visibilidad completa del rendimiento de Odoo incluyendo tiempos de respuesta de la aplicacion, consumo de base de datos, y errores de la interfaz de usuario.
Para integrar Odoo con herramientas de monitoreo, instala el agente correspondiente en el servidor y configuralo para que monitoree los procesos de Python que ejecutan Odoo. El agente recopila metricas automaticamente y las envia al servicio de monitoreo.
Las metricas de monitoreo mas importantes incluyen: tiempo promedio de respuesta por tipo de peticion, numero de errores por tipo, consumo de memoria por worker, numero de consultas SQL por peticion, y tasa de cache hits de Redis.
Los dashboards de monitoreo deben configurarse para mostrar tanto metricas en tiempo real como historicas. Las metricas en tiempo real permiten detectar problemas inmediatos, mientras que las historicas permiten identificar tendencias y patrones de uso.
20. Integracion con Herramientas de BPM
Las herramientas de Business Process Management como Camunda o Activiti se pueden integrar con Odoo para automatizar flujos de trabajo complejos que involucran multiples departamentos y aprobaciones. La integracion permite que Odoo dispare procesos de BPM y que BPM actualice registros en Odoo.
Para integrar Odoo con BPM, crea webhooks que envien eventos a la herramienta de BPM cuando se crean o modifican registros en Odoo. La herramienta de BPM ejecuta el flujo de trabajo definido y envia notificaciones a Odoo para que actualice los registros correspondientes.
Los flujos de trabajo de BPM son ideales para procesos que requieren multiples aprobaciones como compras que superan un umbral de monto, solicitudes de permisos que pasan por varios niveles de gestion, y contratos que necesitan revision legal antes de ser firmados.
La integracion con BPM separa la logica de negocio (definida en la herramienta de BPM) de la logica de datos (definida en Odoo). Esto facilita la modificacion de flujos de trabajo sin tocar el codigo de Odoo y permite que los usuarios de negocio diseñen procesos sin conocimiento tecnico.
21. Integracion con Herramientas de Automatizacion de Marketing
Las herramientas de automatizacion de marketing como HubSpot, Marketo o ActiveCampaign se pueden integrar con Odoo para sincronizar leads, automatizar campañas de nurturing, y rastrear el engagement de clientes potenciales. La sincronizacion bidireccional garantiza que los leads de Odoo se enriquecen con datos de comportamiento de la plataforma de marketing.
Los triggers de automatizacion se configuran en la herramienta de marketing y se activan cuando los leads de Odoo alcanzan ciertos criterios como score de lead, interacciones con emails, o visitas al sitio web. Cuando se activa un trigger, la herramienta ejecuta la accion configurada como enviar un email personalizado, crear una tarea para el vendedor, o actualizar el score del lead en Odoo.
Para medir el ROI de las campañas de marketing, sinciliza los datos de conversion de Odoo (pedidos cerrados, facturas generadas) con las metricas de la herramienta de marketing. Esto permite atribuir ingresos a campañas especificas y optimizar la inversion en marketing basandose en datos reales de negocio.
22. Manejo de Rate Limiting y Cuotas de API
Cuando interactuas con APIs externas como Shopify, Stripe o servicios de email, debes respetar los limites de velocidad (rate limits) que cada servicio impone. El rate limiting controla cuantas peticiones puedes hacer por minuto, hora o dia. Exceder los limites resulta en errores 429 (Too Many Requests) y puede causar la suspension temporal de tu cuenta de API.
Implementa un sistema de rate limiting en tus conectores que respete los limites del servicio externo. Usa colas de mensajes como Redis Queue o Celery para gestionar la velocidad de envio de peticiones. Si el servicio externo retorna un error 429, espera el tiempo indicado en el header Retry-After antes de reintentar.
Las cuotas de API varian segun el plan contratado del servicio externo. Documenta las cuotas de cada servicio y monitorea el uso para evitar exceder los limites. Algunos servicios ofrecen dashboards de uso que muestran cuantas peticiones te quedan en el periodo actual.
Para servicios criticos, implementa un sistema de alertas que te notifique cuando estes cerca del limite de cuota. Esto te da tiempo para optimizar las peticiones o solicitar un aumento de cuota antes de que el servicio se suspenda.
