El contexto: Walmart llega a Costa Rica con VTEX
Cuando Walmart Costa Rica abrió su marketplace en línea a sellers externos a través de la plataforma VTEX, Smart Technology CR (smart.cr) vio una oportunidad inmediata: poner su catálogo de más de 2,000 productos de electrónica y tecnología frente a los millones de visitantes mensuales de Walmart.co.cr.
Pero la oportunidad venía con un desafío operativo significativo: VTEX requiere que los sellers mantengan su catálogo, precios e inventario actualizados en tiempo real. Un producto con stock 0 que sigue publicado genera una venta que no se puede cumplir. Un precio desactualizado puede significar vender a pérdida.
Smart ya operaba su e-commerce propio en Shopify y su ERP en Odoo 19. Agregar un tercer canal manualmente no era viable.
El desafío técnico
Modelo de datos VTEX
VTEX tiene un modelo de catálogo propio que no mapea 1:1 con Odoo ni con Shopify. Los conceptos clave son:
- Categorías con árbol jerárquico: VTEX requiere que cada producto esté en una categoría específica de su taxonomía, que no coincide con la categoría de Odoo.
- Especificaciones de producto: campos obligatorios que varían por categoría (marca, garantía, voltaje, etc.).
- SKUs con sellers: cada variante de producto es un SKU que se asocia al seller con precio y stock independientes.
- Política comercial: precios específicos para el canal Walmart que pueden diferir del precio en smart.cr.
APIs involucradas
VTEX expone varias REST APIs que el conector necesita orquestar:
- Catalog API: creación y actualización de productos, SKUs y especificaciones
- Pricing API: gestión de precios por política comercial
- Inventory API: actualización de stock disponible por SKU
- Orders API: recepción de pedidos del marketplace
- Feed API: cola de cambios de estado de órdenes
La solución: conector Odoo 19 → VTEX
Módulo smart_vtex_connector
Desarrollamos un módulo Odoo 19 que actúa como puente entre el ERP y el Seller Portal de VTEX. El módulo maneja todo el ciclo de vida:
Publicación inicial del catálogo. Se mapearon las categorías de Odoo a la taxonomía de VTEX mediante una tabla de correspondencia configurable. Cada producto en Odoo que tiene la marca "publicar en Walmart" activa se exporta con todas sus variantes, imágenes, especificaciones y precio de la política comercial Walmart.
Sincronización de precios. Un cron cada 30 minutos verifica si hay cambios de precio en Odoo para productos publicados en VTEX. Solo los productos con cambios se actualizan, minimizando las llamadas a la API y respetando los rate limits.
Sincronización de inventario. Cada 15 minutos, el conector calcula el stock disponible para Walmart (stock total menos reservas de Shopify menos umbral de seguridad) y lo publica a VTEX. Si el stock de un producto baja de 3 unidades, se reduce la prioridad de publicación para evitar sobreventa durante la ventana de latencia.
Importación de pedidos. El conector consulta el Feed API de VTEX cada 5 minutos buscando nuevos pedidos. Cada pedido se importa como una orden de venta en Odoo con:
- Cliente creado o actualizado con datos de facturación
- Líneas de pedido con productos mapeados a los SKUs de Odoo
- Precio de venta según la política comercial Walmart
- Datos de envío y dirección de entrega
- Referencia cruzada con el ID de orden VTEX para trazabilidad
Manejo de la taxonomía de categorías
Este fue uno de los puntos más laboriosos del proyecto. VTEX requiere que los productos estén en categorías específicas de su árbol, y Walmart tiene requisitos adicionales sobre especificaciones obligatorias por categoría.
Creamos un modelo vtex.category.mapping en Odoo que permite:
- Mapear cada categoría de Odoo a una categoría VTEX
- Definir las especificaciones obligatorias por categoría VTEX
- Auto-llenar especificaciones desde campos de Odoo cuando es posible
- Marcar productos como "incompletos" cuando falta información requerida
Esto le permite al equipo de Smart identificar rápidamente qué productos no pueden publicarse y qué información necesitan completar.
Flujo de fulfillment
Cuando un pedido de Walmart se procesa en Odoo:
- Se genera la orden de venta con la referencia VTEX
- Se confirma y se genera la orden de entrega
- Cuando el almacén despacha, el conector notifica a VTEX el tracking y carrier
- VTEX actualiza el estado en Walmart.co.cr para el comprador
- Se genera la factura electrónica en Odoo vía TRIBU-CR
- Se notifica a VTEX la factura emitida (requisito del marketplace)
Resultados
El conector entró en producción en febrero de 2026 con los siguientes resultados:
- 2,000+ productos publicados en Walmart.co.cr con sincronización automática
- Actualización de inventario cada 15 minutos sin intervención manual
- Importación automática de pedidos con creación de cliente y orden de venta en Odoo
- Facturación electrónica automática para cada venta del marketplace
- Panel de control en Odoo con estado de publicación, errores de sincronización y métricas de venta por canal
El equipo de Smart pasó de necesitar 2 personas dedicadas a gestionar el canal Walmart manualmente a operar el marketplace con supervisión mínima. Los errores de inventario por sobreventa, que eran frecuentes en las primeras semanas de operación manual, se eliminaron por completo.
Aprendizajes clave
VTEX tiene rate limits estrictos. Las APIs de catálogo permiten un máximo de 40 requests por minuto. Con 2,000 productos, la sincronización completa inicial tomó más de 8 horas. El conector implementa queuing con respeto a los rate limits y reintentos automáticos para errores 429.
La taxonomía es un problema de negocio, no técnico. Mapear categorías correctamente requiere conocimiento del catálogo del seller y de los requisitos de Walmart. Automatizamos lo que pudimos, pero la configuración inicial requirió trabajo conjunto con el equipo comercial de Smart.
Multi-canal requiere una fuente de verdad clara. Odoo 19 es la fuente de verdad para productos, precios e inventario. Shopify y VTEX son canales de venta. Esta decisión de arquitectura evitó conflictos de datos y simplificó significativamente la lógica del conector.