Skip to main content

​
Integracion con VTEX

Conecta tu tienda VTEX con ZenFlow para importar pedidos automaticamente, sincronizar inventario y optimizar tus operaciones de fulfillment a escala empresarial.
Esta integracion soporta VTEX Commerce en cualquier pais. Compatible con el OMS (Order Management System) de VTEX.

​
Caracteristicas

Importar Pedidos

Importa pedidos en estado “ready-for-handling”

Feed en Tiempo Real

Recibe cambios de estado via Feed o Webhooks

Sync Inventario

Sincronizacion de stock por almacen hacia VTEX

Multi-almacen

Soporte para multiples almacenes VTEX

​
Guia de Configuracion

​
Paso 1: Obtener Credenciales de API en VTEX

  1. En tu admin de VTEX, ve a Configuracion de la cuenta > Claves de aplicacion
  2. Haz clic en Generar nueva clave
  3. Asigna los siguientes permisos:
    • OMS - Full access
    • Logistics - Full access
  4. Copia el App Key y App Token
El App Token solo se muestra una vez. Guardalo de forma segura.

​
Paso 2: Conectar en ZenFlow

  1. Ve a Configuracion > Integraciones en ZenFlow
  2. Haz clic en Conectar VTEX
  3. Ingresa:
    • Account Name: El nombre de tu cuenta VTEX (ej: mitienda)
    • App Key: La clave de aplicacion
    • App Token: El token de aplicacion
  4. Haz clic en Conectar

​
Paso 3: Seleccionar Almacen VTEX

Despues de conectar, selecciona el almacen de VTEX que quieres sincronizar:
  1. Ve a Integraciones > VTEX > Configuracion
  2. Selecciona el almacen VTEX de la lista
  3. Habilita la sincronizacion de pedidos y/o inventario

​
Paso 4: Configurar Notificaciones (Opcional)

Elige como recibir notificaciones de nuevos pedidos:

Feed (Recomendado)

ZenFlow consulta VTEX cada 30 segundos. Mas confiable.

Webhooks

VTEX notifica a ZenFlow en tiempo real. Mas rapido pero puede perder eventos.

​
Flujo de Pedidos

​
Referencia API

​
Conectar Cuenta

POST /api/v1/integrations/vtex/connect
Request: 
{
  "account_name": "mitienda",
  "app_key": "vtexappkey-mitienda-XXXXXX",
  "app_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "environment": "vtexcommercestable"
}
Respuesta: 
{
  "success": true,
  "data": {
    "id": "cred_abc123",
    "account_name": "mitienda",
    "status": "active",
    "connected_at": "2024-01-15T10:30:00Z"
  }
}

​
Obtener Estado de Conexion

GET /api/v1/integrations/vtex/status
Respuesta: 
{
  "success": true,
  "data": {
    "connected": true,
    "account_name": "mitienda",
    "status": "active",
    "vtex_warehouse_id": "warehouse_1",
    "feed_configured": true,
    "hook_configured": false,
    "sync_orders": true,
    "sync_stock": true,
    "last_sync_at": "2024-01-20T15:45:00Z"
  }
}

​
Actualizar Configuracion

PUT /api/v1/integrations/vtex/config
Request: 
{
  "sync_orders": true,
  "sync_stock": true
}

​
Listar Almacenes VTEX

GET /api/v1/integrations/vtex/warehouses
Respuesta: 
{
  "success": true,
  "data": {
    "warehouses": [
      {
        "id": "warehouse_1",
        "name": "Deposito Central",
        "is_active": true
      },
      {
        "id": "warehouse_2",
        "name": "Sucursal Norte",
        "is_active": true
      }
    ]
  }
}

​
Configurar Almacen

POST /api/v1/integrations/vtex/warehouses/set
Request: 
{
  "vtex_warehouse_id": "warehouse_1"
}

​
Configurar Feed

POST /api/v1/integrations/vtex/feed/configure
Configura el feed de polling para recibir cambios de pedidos.

​
Configurar Webhooks

POST /api/v1/integrations/vtex/hook/configure
Registra webhooks en VTEX para notificaciones en tiempo real.

​
Sincronizar Pedidos Manualmente

POST /api/v1/integrations/vtex/sync/orders
Request: 
{
  "date_from": "2024-01-01",
  "date_to": "2024-01-31"
}

​
Sincronizar Stock a VTEX

POST /api/v1/integrations/vtex/sync/stock

​
Listar Mapeos de Productos

GET /api/v1/integrations/vtex/mappings
Respuesta: 
{
  "success": true,
  "data": {
    "mappings": [
      {
        "id": "map_abc123",
        "product_id": 100,
        "product_sku": "PROD-001",
        "vtex_sku_id": "123456",
        "vtex_product_id": "789",
        "sync_stock": true,
        "last_stock_sync": "2024-01-20T15:45:00Z"
      }
    ]
  }
}

​
Crear Mapeo de Producto

POST /api/v1/integrations/vtex/mappings
Request: 
{
  "product_id": 100,
  "vtex_sku_id": "123456",
  "vtex_product_id": "789",
  "sync_stock": true
}

​
Eliminar Mapeo

DELETE /api/v1/integrations/vtex/mappings/:id

​
Desconectar Cuenta

POST /api/v1/integrations/vtex/disconnect

​
Notificaciones de Pedidos

​
Feed (Polling)

El feed es el metodo recomendado para recibir notificaciones:
  • ZenFlow consulta VTEX cada 30 segundos
  • Procesa cambios de estado en lote
  • Confirma items procesados para evitar duplicados
  • Mas confiable que webhooks (no pierde eventos)

​
Webhooks

Los webhooks proporcionan notificaciones en tiempo real:
EventoDescripcionAccion en ZenFlow
Estado cambia a ready-for-handlingPedido listoImporta y inicia handling
Estado cambia a handlingEn preparacionActualiza estado
Estado cambia a invoicedEnviadoMarca como completado
Estado cambia a canceledCanceladoCancela pedido

​
Mapeo de Productos

​
Coincidencia Automatica

Cuando se importa un pedido, ZenFlow intenta coincidir productos automaticamente:
  1. Busca mapeo existente por vtex_sku_id
  2. Si no existe, busca por SKU o codigo de barras en ZenFlow
  3. Si encuentra, crea el mapeo automaticamente

​
Mapeo Manual

Para productos que no coinciden automaticamente:
  1. Ve a Integraciones > VTEX > Mapeo de Productos
  2. Filtra por “Sin mapear”
  3. Selecciona el producto ZenFlow correspondiente

​
Mapeo de Estados

Estado VTEXEstado ZenFlow
order-createdPendiente
payment-approvedListo para preparar
ready-for-handlingListo para preparar
start-handlingEn progreso
handlingEn progreso
invoiceListo para despacho
invoicedEnviado
canceledCancelado

​
Sincronizacion de Inventario

La sincronizacion de stock funciona de la siguiente manera:
  1. ZenFlow calcula el stock disponible (total - reservado)
  2. Actualiza el inventario en VTEX para el almacen configurado
  3. Solo sincroniza productos con mapeo activo y sync_stock: true
// Ejemplo de actualizacion
PUT /api/logistics/pvt/inventory/skus/{sku}/warehouses/{warehouse}
{
  "quantity": 50,
  "unlimitedQuantity": false
}

​
Solucion de Problemas

​
No Puedo Conectar

Asegurate de que el App Key y App Token sean correctos. Genera nuevas credenciales si es necesario.
Las credenciales necesitan acceso completo a OMS y Logistics. Verifica los permisos en VTEX Admin.
El account_name debe ser exactamente el nombre de tu cuenta VTEX (sin “.vtexcommercestable.com.br”).

​
Pedidos No Se Importan

Solo se importan pedidos en estado “ready-for-handling”. Verifica el flujo de pedidos en VTEX.
Asegurate de haber seleccionado el almacen VTEX correcto en la configuracion.
Verifica que el feed este configurado (recomendado) o que los webhooks esten activos.

​
Stock No Se Sincroniza

El producto debe estar mapeado y tener sync_stock habilitado.
El almacen VTEX debe estar configurado en la integracion.
Las credenciales necesitan permisos de Logistics para actualizar inventario.

​
Limites de Tasa

OperacionLimite
Llamadas API100 requests/segundo
Maximo por minuto6000 requests
ZenFlow maneja los limites de tasa automaticamente con espera y reintentos.

​
Requisitos

  • Cuenta VTEX activa
  • App Key y App Token con permisos:
    • OMS - Full access
    • Logistics - Full access
  • Al menos un almacen configurado en VTEX

​
Soporte