Smart.cr: Conector Shopify → Odoo 19 bidireccional

La situación inicial

Smart Technology CR opera smart.cr, una tienda en línea de electrónica y tecnología con más de 2,050 productos activos en Shopify. Su operación interna corre sobre Odoo 19 Enterprise: compras, inventario, contabilidad y facturación electrónica.

Antes de este proyecto, cada pedido que llegaba por Shopify pasaba por un proceso manual: un miembro del equipo revisaba el pedido en Shopify, creaba la orden en Odoo, buscaba o creaba el cliente, generaba la factura electrónica, la enviaba al Ministerio de Hacienda y actualizaba el estado en Shopify. Este proceso tomaba entre 15-20 minutos por pedido y era propenso a errores de transcripción.

Con 40-60 pedidos diarios, el equipo invertía entre 10-20 horas diarias solo en data entry. Y el inventario se desincronizaba constantemente: productos que se vendían en tienda física aparecían como disponibles en Shopify, generando cancelaciones y clientes insatisfechos.

Decisiones técnicas clave

GraphQL sobre REST

Shopify ofrece dos APIs: REST Admin API y GraphQL Admin API. Elegimos GraphQL por tres razones específicas:

Eficiencia en queries complejas. Para sincronizar un producto necesitamos: datos del producto, variantes, imágenes, inventario por ubicación y metafields. En REST, esto requiere 4-5 llamadas encadenadas. En GraphQL, es una sola query que trae exactamente los campos que necesitamos.

Paginación estable con cursores. El catálogo de Smart tiene 2,050 productos con variantes. La paginación por cursor de GraphQL garantiza que no se saltan ni duplican registros durante la sincronización, algo que la paginación por offset de REST no puede garantizar si hay cambios concurrentes.

Rate limit más generoso. GraphQL usa un sistema de "puntos de costo" que permite hacer más trabajo por ventana de tiempo comparado con el límite de 4 requests/segundo de REST.

Webhooks como backbone de eventos

En lugar de polling constante para detectar cambios, el conector registra webhooks en Shopify para los eventos críticos:

• ORDERS_CREATE: nuevo pedido completado
• ORDERS_PAID: pago confirmado por el gateway
• ORDERS_CANCELLED: cancelación de pedido
• ORDERS_FULFILLED: pedido despachado (para confirmación bidireccional)
• PRODUCTS_UPDATE: cambios a productos hechos directamente en Shopify

Cada webhook se verifica con HMAC-SHA256 antes de procesarse, se registra en un log de auditoría y se procesa de forma asíncrona mediante la cola de trabajos de Odoo.

Arquitectura del conector

Modelos Odoo

El módulo smart_shopify_connector agrega los siguientes modelos a Odoo 19:

shopify.backend: configuración de la conexión con la tienda Shopify. Almacena API key, secret, URL de la tienda y configuraciones de sincronización (intervalos, umbrales, mapeos de impuestos).

shopify.product.binding: vincula un product.template de Odoo con su equivalente en Shopify. Almacena el Shopify Product ID, GIDs de GraphQL, estado de sincronización y timestamps de última actualización en ambos sistemas.

shopify.order.queue: cola de procesamiento de pedidos entrantes. Cada registro contiene el payload del webhook, estado de procesamiento (pendiente, procesado, error), número de intentos y mensaje de error si aplica.

shopify.sync.log: registro detallado de cada operación de sincronización para auditoría y debugging.

Flujo de un pedido (Shopify → Odoo → Factura)

1. El cliente completa su compra en smart.cr y el pago se procesa.
2. Shopify dispara el webhook ORDERS_CREATE al endpoint del conector.
3. El conector verifica la firma HMAC y encola el pedido.
4. El procesador asíncrono toma el pedido de la cola y:
   • Busca al cliente en Odoo por email (match principal) o por cédula (match secundario vía metafield)
   • Si no existe, lo crea con los datos del pedido
   • Crea la orden de venta con las líneas correspondientes, mapeando productos por SKU
   • Aplica descuentos, impuestos y costos de envío según la configuración
5. La orden se confirma automáticamente (el pago ya fue procesado en Shopify).
6. Se genera la factura electrónica con los datos fiscales del cliente.
7. El módulo TRIBU-CR envía el XML firmado al Ministerio de Hacienda.
8. La factura PDF se envía al cliente por email.
9. Un metafield en la orden de Shopify se actualiza con el número de factura electrónica.

Todo el proceso desde webhook hasta factura enviada toma menos de 30 segundos.

Sincronización de inventario

El inventario es donde la sincronización bidireccional se vuelve crítica. El enfoque:

Odoo como fuente de verdad. Cada 15 minutos, un cron job calcula el stock disponible para Shopify: stock_quant.quantity - reservas_pendientes - umbral_seguridad (2 unidades).

Reserva inmediata en Odoo. Cuando llega un pedido de Shopify, antes de crear la orden de venta se reserva el inventario en Odoo. Esto evita que dos canales de venta (Shopify + tienda física) vendan el mismo producto.

Reconciliación diaria. A las 2:00 AM, un proceso compara el inventario publicado en Shopify con el stock real en Odoo y corrige discrepancias. Esto actúa como red de seguridad para cualquier evento que el sistema de tiempo real no haya capturado.

Sincronización de productos (Odoo → Shopify)

Los productos se mantienen en Odoo y se publican a Shopify:

• Datos maestros: nombre, descripción HTML, precio, peso
• Variantes: talla, color u otros atributos configurados en Odoo
• Imágenes: se suben a Shopify vía la mutation stagedUploadsCreate de GraphQL
• Inventario: stock disponible por ubicación
• Metafields: datos adicionales como garantía, especificaciones técnicas

Solo los productos marcados como "publicar en Shopify" en Odoo se sincronizan. Los cambios se detectan por timestamp de escritura (write_date) y solo se envían los campos modificados.

Resultados medibles

Después de 3 meses en producción (diciembre 2025 - febrero 2026):

• 2,050 productos sincronizados con variantes, imágenes y stock
• Facturación electrónica automática en menos de 30 segundos post-compra
• 4 horas diarias de data entry eliminadas por completo
• 0 errores de sobreventa (antes: 3-5 por semana)
• 100% de facturas enviadas a Hacienda dentro del plazo legal
• Reconciliación diaria automática como red de seguridad

El equipo de Smart reasignó a las 2 personas que hacían data entry a funciones de atención al cliente y gestión de marketplace, donde generan más valor para el negocio.

Escalabilidad demostrada

Este mismo conector sirvió como base para la integración con VTEX/Walmart CR que se implementó posteriormente. La arquitectura de modelos de binding, cola de procesamiento y sincronización programada se replicó con adaptaciones específicas para la API de VTEX, reduciendo el tiempo de desarrollo del segundo conector en un 40%.