VTEX y ERP: cómo integrar catálogo, precios y pedidos

VTEX se conecta con un ERP a través de cuatro APIs: catálogo, logística, precios y pedidos. El ERP envía los SKU, el stock de cada almacén y los precios. VTEX devuelve los pedidos cuando están pagados y espera los datos de la factura para pasar al despacho. Esta guía explica cómo se modela cada dato, qué ofrece la API y dónde fallan las integraciones.

Qué datos van en cada sentido

Dato	Sentido	API de VTEX
Productos y SKU	ERP a VTEX	Catalog API
Stock por almacén	ERP a VTEX	Logistics API
Precio base y precios fijos	ERP a VTEX	Pricing API
Pedidos y clientes	VTEX a ERP	Orders API (feed o hook)
Factura y seguimiento	ERP a VTEX	Orders API

Fuente: Back office integration guide, VTEX Developers.

La guía oficial de VTEX para integrar un ERP propone ese mismo orden: primero precios, catálogo e inventario, después el flujo de pedidos. También indica que entre el ERP y VTEX va un middleware, que puede ser una plataforma de integración o un desarrollo propio. Si es propio, tiene que soportar los peaks de venta.

Cómo se autentica una integración

Cada llamada lleva dos encabezados: X-VTEX-API-AppKey y X-VTEX-API-AppToken. El par se crea en la configuración de la cuenta, en la sección de claves de aplicación, y el administrador puede crear varios, por ejemplo uno por integración.

Lo que cada clave puede hacer depende de los roles de License Manager que se le asignen. Una integración con el ERP necesita permisos sobre catálogo, precios, logística y pedidos, y nada más. VTEX advierte que estas claves no deben ir en código que corre en el navegador.

Producto, SKU y el código del ERP

VTEX separa dos niveles. El producto es la definición genérica de un artículo, por ejemplo una polera. El SKU es la unidad que se guarda en stock, por ejemplo la polera azul talla M. El comprador navega productos y compra SKU.

En la mayoría de los ERP cada talla o color es un código de producto distinto. El cruce queda así:

Cada código del ERP corresponde a un SKU de VTEX.
Los SKU de un mismo modelo se agrupan bajo un producto.
El código del ERP se guarda en el campo RefId del SKU. Es la llave entre los dos sistemas.

Para crear un SKU, VTEX exige al menos uno de dos identificadores alternativos: RefId o EAN. Con el RefId se puede buscar el SKU después, usando GET /api/catalog_system/pvt/sku/stockkeepingunitidbyrefid/{refId}. La guía de VTEX recomienda guardar en tu base el id que VTEX asigna a cada SKU junto a su código de referencia, porque el resto de las APIs trabaja con ese id.

Qué necesita un SKU para quedar activo

Un SKU recién creado no aparece en la tienda. Para activarse, la documentación pide:

Tener RefId o EAN.
Tener al menos una imagen.
Pertenecer a un producto activo, que a su vez tenga marca y categoría activas.
Tener completas sus especificaciones, si las tiene definidas.

El producto, además, debe estar asociado a una política comercial. La política comercial principal siempre tiene el ID 1.

Este punto explica una queja frecuente: “el ERP envió el producto y no aparece”. Casi siempre falta la imagen, la categoría o la política comercial. Por eso muchas empresas dejan que el ERP cree el SKU con su código, stock y precio, y que el equipo de ecommerce complete fotos y fichas en VTEX.

Stock por almacén

En VTEX el stock de un SKU se guarda a nivel de almacén (warehouse). La llamada que lo actualiza es:

PUT /api/logistics/pvt/inventory/skus/{skuId}/warehouses/{warehouseId}

Se envía la cantidad total del SKU en ese almacén, no la diferencia. Los almacenes se crean y se listan con /api/logistics/pvt/configuration/warehouses.

Con un ERP de varias bodegas hay que decidir tres cosas:

Qué bodegas cuentan. La bodega de tránsito, la de mermas o la del canal mayorista normalmente quedan fuera.
Cómo se agrupan. Una bodega del ERP por almacén de VTEX, o varias bodegas sumadas en un solo almacén.
Qué stock se publica. El disponible, descontando lo comprometido en notas de venta pendientes, no el stock físico.

Si vendes el mismo inventario en VTEX y en otros canales, el descuento tiene que ocurrir en el ERP. En sobreventa de stock multicanal explicamos por qué.

Precio base, precios fijos y tablas de precios

La Pricing API maneja dos tipos de precio por SKU:

Precio base. Es el precio de referencia del SKU en todas las tablas de precios. Se carga con la operación Create/Edit Price (PUT /prices/{itemId}). En la misma llamada puede ir el precio de lista y el costo o el markup. Si envías costo y markup, VTEX calcula el precio base como costo por uno más markup.
Precio fijo. Es un valor que reemplaza al precio calculado de un SKU en una tabla de precios específica. Se carga con POST /prices/{itemId}/fixed/{priceTableId}.

Una tabla de precios es un conjunto de precios que se aplica en un contexto. Si una tabla no tiene precio para un SKU, se usa el precio base. Los precios fijos también se pueden cargar por política comercial.

El cruce con el ERP es directo: la lista de precios principal alimenta el precio base, y cada lista adicional (mayorista, convenio, canal) alimenta los precios fijos de una tabla o de una política comercial. Así los precios se siguen administrando en el ERP. Si vendes a empresas con condiciones distintas, revisa precios por cliente en un ecommerce B2B.

Antes de cargar precios, confirma con tu equipo si la tienda muestra valores con IVA incluido y qué lista del ERP corresponde a eso. Es la causa más común de precios que aparecen un 19 % más altos o más bajos.

Pedidos: feed o hook

VTEX ofrece dos mecanismos independientes para avisar los cambios de un pedido. Los dos usan el mismo filtro.

	Feed	Hook
Modelo	La integración consulta una cola de eventos	VTEX envía cada evento a una URL tuya
Configuración	`POST /api/orders/feed/config`	`POST /api/orders/hook/config`
Lectura	`GET /api/orders/feed` y confirmación con `POST /api/orders/feed`	Tu endpoint debe responder 200 en menos de 5.000 ms
Si tu sistema se cae	Los eventos esperan en la cola durante el período de retención	VTEX reintenta con intervalos crecientes
Cuándo lo recomienda VTEX	Cuando quieres controlar cuánto recibes a la vez	Operaciones grandes con un middleware que escala

Fuente: Feed v3, VTEX Developers.

Detalles que conviene conocer antes de programar:

El feed es una cola de eventos, no una lista de pedidos. Cada evento leído hay que confirmarlo para que salga de la cola. Los que no se confirman vuelven a aparecer.
La retención de los eventos del feed se configura entre 345.600 y 1.209.600 segundos, es decir, entre 4 y 14 días.
Pueden llegar eventos duplicados. La integración tiene que revisar si el pedido ya existe en el ERP antes de crearlo.
La configuración de un hook se elimina si pasa tres días sin notificaciones.
VTEX recomienda una configuración de feed o hook por app key, porque los usuarios que comparten una clave comparten la misma cola.
Ante una respuesta 429 hay que detener las llamadas y esperar. VTEX sugiere un minuto.

El filtro más simple es por estado (FromWorkflow). Para un ERP, el estado que importa es ready-for-handling: indica que el pedido está pagado y que terminó el plazo en que el cliente puede cancelarlo. Es la señal para preparar el despacho.

El ciclo completo de un pedido

Llega el evento ready-for-handling por el feed o el hook.
La integración pide el detalle con GET /api/oms/pvt/orders/{orderId}. La respuesta trae productos, pagos, entrega y cliente.
Se crea el documento en el ERP: nota de venta, boleta o factura, según tus reglas.
Si el ERP lo aceptó, se llama a Start handling (/api/oms/pvt/orders/{orderId}/start-handling), una sola vez. El pedido pasa a preparación.
Cuando el ERP emite el documento, se informa con POST /api/oms/pvt/orders/{orderId}/invoice. El pedido pasa a facturado.
El número y la URL de seguimiento pueden ir en esa misma llamada o agregarse después.

Para cancelar existe POST /api/oms/pvt/orders/{orderId}/cancel. En el flujo de VTEX un pedido no se puede cancelar una vez facturado, y una cancelación no se revierte. Una devolución se informa con otra notificación de factura, con el tipo Input en lugar de Output.

Boleta, factura y RUT

La documentación de la API de VTEX que revisamos no incluye la emisión de documentos tributarios electrónicos ante el SII. VTEX registra los datos de la factura que le informas. El DTE lo emite tu ERP o tu proveedor de facturación.

Para decidir entre boleta y factura, el pedido trae los datos del comprador en clientProfileData. Los campos relevantes son:

Campo	Qué contiene
`document`	Número de documento que informó el cliente
`documentType`	Tipo de documento
`isCorporate`	Indica si el cliente es una persona jurídica
`corporateName`	Razón social, si es persona jurídica
`corporateDocument`	Documento de la empresa, si es persona jurídica

Fuente: orderForm fields reference, VTEX Developers.

La regla habitual en Chile: persona natural recibe boleta, empresa recibe factura con su RUT y razón social. Para que funcione, el checkout tiene que pedir el RUT y la integración tiene que validarlo antes de crear el cliente en el ERP. Si ya emites documentos desde otra tienda, las reglas son las mismas que describimos en facturación electrónica para tiendas online en Chile.

Errores típicos

SKU sin RefId. Sin el código del ERP en el SKU no hay cómo cruzar stock ni precios. Cargar el catálogo a mano y “después ver la integración” obliga a rehacer el mapeo.
SKU inactivos sin explicación. Falta imagen, categoría, marca activa o política comercial.
Stock total en vez de disponible. Se publica lo que hay en la bodega y no lo que se puede vender.
Leer el feed sin confirmar. Los mismos eventos vuelven una y otra vez y los nuevos se atrasan.
Pedidos duplicados en el ERP. La integración no revisa si el pedido ya entró antes de crearlo.
Facturar sin avisar a VTEX. El documento existe en el ERP, pero el pedido nunca pasa a facturado en VTEX.
Una sola clave para todo. Varias integraciones con la misma app key comparten la cola del feed y se quitan eventos entre sí.
Middleware que no aguanta un evento. Antes de un Cyber, prueba el volumen. En cómo preparar la operación para CyberDay hay una lista de revisión.

Qué definir antes de partir

Qué código del ERP va en el RefId de cada SKU.
Qué bodegas alimentan cada almacén de VTEX.
Qué lista de precios es el precio base y cuáles van como precio fijo.
En qué estado entra el pedido al ERP y con qué documento.
Quién emite el DTE y en qué momento se informa a VTEX.
Qué pasa con las cancelaciones y las devoluciones: nota de crédito automática o aviso a tu equipo.

ERPSync con VTEX

ERPSync conecta el ERP con VTEX usando estas mismas APIs. Nuestra especialidad es Softland: en la ficha de Softland con VTEX está el detalle de qué se sincroniza, el cruce de campos y los requisitos. El stock y los precios se actualizan cada 5 minutos desde las bodegas y listas que elijas, y cada pedido listo para preparar entra a Softland como nota de venta o factura, con el cliente identificado por RUT.

También trabajamos con otros ERP, previa revisión técnica de tu caso. La lista completa está en integraciones.

Cuesta 0,80 UF al mes por integración, sin límite de pedidos ni de productos. Puede haber un costo inicial, que cotizamos después de revisar tu caso. Hay prueba de 14 días. El detalle está en precios.

Preguntas frecuentes

¿VTEX tiene API para conectar un ERP?

Sí. Tiene APIs de catálogo, logística, precios y pedidos, además de una guía oficial para integrar sistemas de back office. Se usan con un par app key y app token.

¿Cómo se relaciona el código de mi ERP con VTEX?

Va en el campo RefId del SKU. Cada talla o color es un SKU distinto, agrupado bajo un producto.

¿Conviene usar feed o hook para los pedidos?

VTEX recomienda el feed si quieres controlar cuánto recibes a la vez, y el hook para operaciones grandes con un middleware que escala. También sugiere usar el hook como principal y el feed como respaldo.

¿En qué estado se lee un pedido de VTEX?

En ready-for-handling. Indica que el pedido está pagado y que ya pasó el plazo de cancelación del cliente.

¿VTEX emite boleta o factura electrónica en Chile?

En la documentación de su API no aparece la emisión de DTE ante el SII. El documento lo emite tu ERP o tu proveedor de facturación, y sus datos se informan al pedido de VTEX.

¿Puedo manejar varias bodegas?

Sí. VTEX guarda el stock de cada SKU por almacén. Cada bodega del ERP puede alimentar un almacén, o varias pueden sumarse en uno.

Fuentes

Consultadas el 10 de noviembre de 2026.

Escrito por el equipo de ERPSync, especialistas en integraciones con Softland. Quiénes somos