Integracion VTEX con ERP: SAP, TOTVS, y APIs personalizadas
La integracion entre VTEX y ERP es una de las etapas mas criticas de una implementacion de e-commerce. Cuando esta bien hecha, la operacion fluye automaticamente: pedidos caen en el ERP, facturas se emiten, stock se actualiza en tiempo real y el catalogo se mantiene sincronizado. Cuando esta mal hecha, genera retrabajo manual, ventas de productos sin stock, divergencia de precios y atrasos en la facturacion. Esta guia cubre la arquitectura de integracion, los principales ERPs y las buenas practicas para una integracion robusta.
Arquitectura de integracion
VTEX expone APIs REST documentadas para todas las entidades del sistema: catalogo (productos, SKUs, categorias, marcas), precios (tablas de precio, precios fijos, promociones), stock (warehouses, inventory), pedidos (orders, feed, hook) y logistica (SLAs, docks, carriers). La integracion con ERP puede hacerse de tres formas. Directa: el ERP llama las APIs de VTEX y viceversa. Via middleware: un servicio intermediario (Node.js, Python o plataforma iPaaS) orquesta la comunicacion. Via conector listo: soluciones como Eccosys, Celigo y conectores especificos que abstraen la complejidad. Para operaciones grandes, el middleware dedicado es la aproximacion recomendada.
Integracion con SAP
SAP es el ERP mas comun en operaciones enterprise que corren VTEX. La integracion tipica cubre: catalogo (SAP envia materiales, VTEX recibe como productos/SKUs), precios (SAP envia tablas de precio por condicion comercial), stock (SAP actualiza disponibilidad via API de inventory), pedidos (VTEX envia pedidos facturados a SAP para generar factura) y devoluciones (SAP notifica VTEX sobre estado de reversa). El conector mas utilizado es via SAP Commerce Cloud Integration o un middleware Node.js dedicado que traduce IDocs/BAPIs a llamadas REST en VTEX. Puntos de atencion: mapeo de campos entre SAP y VTEX, tratamiento de divergencia de stock en alta concurrencia y cola de retry para llamadas que fallan.
Integracion con TOTVS y ERPs regionales
TOTVS Protheus es ampliamente usado en operaciones medianas en Brasil y LATAM. La integracion con VTEX sigue patrones similares a SAP pero con APIs diferentes. TOTVS disponibiliza web services SOAP y APIs REST. El flujo tipico: TOTVS publica productos via API de Catalog de VTEX, sincroniza stock via API de inventory, recibe pedidos via feed o webhook y retorna factura. Herramientas como Eccosys y Bridge Hub ofrecen conectores listos TOTVS-VTEX. Para ERPs regionales en otros paises de LATAM (como Siigo en Colombia, Contpaqi en Mexico), la aproximacion es similar: middleware Node.js que traduce entre formatos.
Integracion con ERPs livianos
ERPs enfocados en e-commerce (Bling, Tiny, Omie en Brasil; Bind en Mexico) son populares entre operaciones pequenas y medianas. Ofrecen APIs REST bien documentadas e integraciones nativas con VTEX via marketplace de apps. Sincronizan catalogo, precios, stock y pedidos a traves del app oficial o via API directa. El setup es mas simple: instala el app en el admin VTEX, configura credenciales del ERP y mapea campos. En pocos dias la integracion esta operacional. Punto de atencion: para operaciones con mas de 500 pedidos por dia, valida si el plan del ERP soporta el throughput necesario.
Middleware: cuando y como construir
Un middleware de integracion se recomienda cuando: los sistemas no se comunican directamente, la operacion necesita transformacion de datos compleja, existen reglas de negocio que no pertenecen ni al ERP ni a VTEX, o el volumen requiere colas y retry automatico. La stack recomendada: Node.js con Fastify para alta performance, colas con Redis o SQS para procesamiento asincrono, logs estructurados con Pino para debugging, health checks y alertas. El middleware debe ser idempotente: procesar el mismo mensaje dos veces no puede generar duplicidad. Usa IDs de correlacion para rastrear un pedido de inicio a fin. Monitorea latencia y tasa de error. Un middleware saludable procesa mensajes en menos de 2 segundos con tasa de error bajo 0.1%.
Sincronizacion de catalogo y precios
La sincronizacion de catalogo es la base de toda integracion. El ERP es el master de datos del producto: nombre, descripcion, atributos, peso, dimensiones. VTEX es el sistema de presentacion: imagenes, SEO, categorias visuales. El flujo tipico: ERP envia producto via API de Catalog de VTEX (POST /api/catalog/pvt/product), luego SKUs, luego precios (PUT /api/pricing/prices/sku-id), luego stock (PUT /api/logistics/pvt/inventory/skus/sku-id/warehouses/warehouse-id). La sincronizacion puede ser por polling (periodica) o por evento (webhook del ERP). Para catalogo, polling cada 15-30 minutos es aceptable. Para stock en operaciones de alto volumen, sincronizacion por evento o polling cada 1-2 minutos es necesaria para evitar overselling.
Flujo de pedidos y facturacion
El flujo de pedidos integrados sigue: cliente compra en VTEX, pedido entra en el OMS con status payment-approved, VTEX notifica al ERP via feed o webhook, ERP procesa el pedido (reserva stock, genera factura), ERP retorna la factura a VTEX via API de invoice (POST /api/oms/pvt/orders/order-id/invoice), VTEX actualiza el status a invoiced y envia email de confirmacion al cliente. Para capturar pedidos, usa el Order Feed o el Order Hook de VTEX. El Feed es pull-based, el Hook es push-based. El Hook es mas eficiente pero requiere un endpoint siempre disponible. En ambos casos, procesa pedidos de forma asincrona con cola para no perder eventos en picos.
Buenas practicas y errores comunes
Siempre usa autenticacion via appKey y appToken de VTEX. Nunca expongas credenciales en el frontend. Implementa retry con backoff exponencial para llamadas que fallan por timeout o rate limit. VTEX tiene rate limits por endpoint; respeta los headers X-RateLimit. Valida datos antes de enviar: productos sin imagen, SKUs sin precio o stock negativo causan errores silenciosos. Monitorea la cola de integracion: pedidos parados mas de 30 minutos indican problema. Crea alertas para divergencia de stock. Documenta el mapeo de campos entre sistemas. Testa en ambiente de homologacion antes de produccion. Y lo mas importante: planea para la falla. Sistemas caen, APIs se ponen lentas, datos llegan incompletos. Una integracion robusta maneja todos esos escenarios sin intervencion manual.