Facturar ventas de VTEX con ARCA en n8n

Guía para integrar órdenes de VTEX con Afip SDK en n8n y emitir factura electrónica de ARCA con control de OMS, items e impuestos.

Ivan Muñoz jun 15, 2026

n8n

Abrir en ChatGTP

Descargá el workflow vtex-arca-invoice.json para importarlo en n8n y adaptarlo a tu cuenta de VTEX.

VTEX tiene un OMS robusto. Para integrarlo con ARCA no conviene hacer polling ciego de órdenes: VTEX ofrece Feed y Hook para cambios de estado, y la Orders API para consultar el detalle real del pedido.

Documentación útil:

• Orders API: https://developers.vtex.com/docs/api-reference/orders-api
• Feed v3: https://developers.vtex.com/docs/guides/orders-feed
• Integración de órdenes con ERP: https://developers.vtex.com/docs/guides/erp-integration-set-up-order-integration
• Nodo Afip SDK para n8n: https://n8n.io/integrations/afip-sdk/

Cómo funciona la integración

1. VTEX publica un cambio de orden por Feed v3 o Hook.
2. n8n recibe el evento o lee el feed.
3. n8n consulta el pedido completo en OMS.
4. n8n espera un estado facturable, por ejemplo payment-approved o el estado operativo definido por tu negocio.
5. n8n mapea items, shipping, discounts y taxes.
6. Afip SDK autoriza la factura.
7. n8n confirma el ítem del feed o actualiza el sistema fiscal/ERP.

Feed o Hook

VTEX documenta dos opciones para seguir cambios de órdenes:

• Feed: n8n consulta un endpoint de cambios pendientes, procesa cada item y luego lo confirma.
• Hook: VTEX llama a un endpoint tuyo cuando una orden cambia.

Para n8n, Feed suele ser más controlable en alto volumen porque podés manejar concurrencia y reintentos. Hook es más inmediato, pero exige que tu endpoint responda bien y sea idempotente.

Paso 1: tomar eventos de VTEX

Si usás Hook:

• Nodo Webhook en n8n.
• VTEX envía order id y estado.
• Respondé 200 sólo cuando aceptaste el evento.

Si usás Feed:

• Nodo Schedule Trigger cada pocos minutos.
• Nodo HTTP Request para leer feed items.
• Procesás cada item.
• Confirmás el item del feed cuando termina bien.

Paso 2: consultar OMS

Con el order id:

GET https://{account}.vtexcommercestable.com.br/api/oms/pvt/orders/{{ $json.orderId }}
X-VTEX-API-AppKey: {{ $env.VTEX_APP_KEY }}
X-VTEX-API-AppToken: {{ $env.VTEX_APP_TOKEN }}

Revisá:

• orderId.
• status.
• clientProfileData.
• items.
• totals.
• shippingData.
• marketplace.
• sellers.

Paso 3: elegir el estado facturable

No todas las empresas facturan en el mismo momento. Opciones comunes:

• payment-approved: factura cuando el pago fue aprobado.
• ready-for-handling: factura cuando la orden entra a preparación.
• Estado custom del ERP: factura cuando logística confirma disponibilidad.

Definí una sola regla y documentala. Si facturás demasiado temprano, aumentan notas de crédito por cancelaciones.

Paso 4: mapear totales de VTEX

VTEX separa totales por tipos. En n8n consolidá:

• Items.
• Discounts.
• Shipping.
• Tax.
• Change data, si hubo modificaciones.

Ejemplo de estructura:

const order = $json;

const totalById = Object.fromEntries(
  (order.totals || []).map((total) => [total.id, total.value / 100])
);

return [{
  json: {
    externalId: `vtex:${order.orderId}`,
    status: order.status,
    customerDocument: order.clientProfileData?.document,
    customerName: `${order.clientProfileData?.firstName || ''} ${order.clientProfileData?.lastName || ''}`.trim(),
    itemsAmount: totalById.Items || 0,
    discountsAmount: Math.abs(totalById.Discounts || 0),
    shippingAmount: totalById.Shipping || 0,
    taxAmount: totalById.Tax || 0,
    totalAmount: order.value / 100,
  },
}];

Paso 5: sellers, marketplace y CUIT emisor

VTEX puede operar con múltiples sellers. Antes de llamar a ARCA, decidí:

• Qué seller emite la factura.
• Qué CUIT corresponde.
• Qué punto de venta usar.
• Si el marketplace factura o si factura el seller.

No uses un único CUIT para todo si la cuenta opera marketplace o multi-seller.

Paso 6: emitir con Afip SDK

El tramo fiscal:

1. Obtener autorización wsfe.
2. FECompUltimoAutorizado.
3. FECAESolicitar.
4. Generar el PDF con el template de Afip SDK.

Clave de idempotencia: vtex:{orderId}:{sellerId} si hay sellers, o vtex:{orderId} si emite una sola razón social.

Paso 7: cerrar el circuito

Después de autorizar:

• Guardá CAE, número y PDF en el ERP o middleware.
• Marcá la orden como facturada en tu sistema.
• Si usás Feed, confirmá el item procesado para que VTEX no lo entregue de nuevo.

Errores comunes

• No confirmar items del Feed y reprocesar órdenes.
• Facturar todos los sellers con el mismo CUIT.
• Ignorar descuentos negativos en totals.
• No contemplar cambios de orden antes del estado final.
• Procesar un Hook duplicado como si fuera una orden nueva.

Cierre

VTEX necesita un flujo más transaccional que una tienda simple. El diseño correcto en n8n es: evento o feed, consulta OMS, validación de estado, mapeo por seller y recién después Afip SDK.