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

En tu admin de VTEX, ve a Configuracion de la cuenta > Claves de aplicacion
Haz clic en Generar nueva clave
Asigna los siguientes permisos:
- OMS - Full access
- Logistics - Full access
Copia el App Key y App Token

El App Token solo se muestra una vez. Guardalo de forma segura.

Paso 2: Conectar en ZenFlow

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

Paso 3: Seleccionar Almacen VTEX

Despues de conectar, selecciona el almacen de VTEX que quieres sincronizar:

Ve a Integraciones > VTEX > Configuracion
Selecciona el almacen VTEX de la lista
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:

Evento	Descripcion	Accion en ZenFlow
Estado cambia a `ready-for-handling`	Pedido listo	Importa y inicia handling
Estado cambia a `handling`	En preparacion	Actualiza estado
Estado cambia a `invoiced`	Enviado	Marca como completado
Estado cambia a `canceled`	Cancelado	Cancela pedido

Mapeo de Productos

Coincidencia Automatica

Cuando se importa un pedido, ZenFlow intenta coincidir productos automaticamente:

Busca mapeo existente por vtex_sku_id
Si no existe, busca por SKU o codigo de barras en ZenFlow
Si encuentra, crea el mapeo automaticamente

Mapeo Manual

Para productos que no coinciden automaticamente:

Ve a Integraciones > VTEX > Mapeo de Productos
Filtra por “Sin mapear”
Selecciona el producto ZenFlow correspondiente

Mapeo de Estados

Estado VTEX	Estado ZenFlow
`order-created`	Pendiente
`payment-approved`	Listo para preparar
`ready-for-handling`	Listo para preparar
`start-handling`	En progreso
`handling`	En progreso
`invoice`	Listo para despacho
`invoiced`	Enviado
`canceled`	Cancelado

Sincronizacion de Inventario

La sincronizacion de stock funciona de la siguiente manera:

ZenFlow calcula el stock disponible (total - reservado)
Actualiza el inventario en VTEX para el almacen configurado
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

Verificar credenciales

Asegurate de que el App Key y App Token sean correctos. Genera nuevas credenciales si es necesario.

Verificar permisos

Las credenciales necesitan acceso completo a OMS y Logistics. Verifica los permisos en VTEX Admin.

Verificar nombre de cuenta

El account_name debe ser exactamente el nombre de tu cuenta VTEX (sin “.vtexcommercestable.com.br”).

Pedidos No Se Importan

Verificar estado del pedido

Solo se importan pedidos en estado “ready-for-handling”. Verifica el flujo de pedidos en VTEX.

Verificar almacen configurado

Asegurate de haber seleccionado el almacen VTEX correcto en la configuracion.

Verificar feed o webhooks

Verifica que el feed este configurado (recomendado) o que los webhooks esten activos.

Stock No Se Sincroniza

Verificar mapeo de producto

El producto debe estar mapeado y tener sync_stock habilitado.

Verificar almacen VTEX

El almacen VTEX debe estar configurado en la integracion.

Verificar permisos de Logistics

Las credenciales necesitan permisos de Logistics para actualizar inventario.

Limites de Tasa

Operacion	Limite
Llamadas API	100 requests/segundo
Maximo por minuto	6000 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

Documentacion de VTEX APIs
VTEX Help Center
Contacta a [email protected] para ayuda con la integracion

​Integracion con VTEX

​Caracteristicas

Importar Pedidos

Feed en Tiempo Real

Sync Inventario

Multi-almacen

​Guia de Configuracion

​Paso 1: Obtener Credenciales de API en VTEX

​Paso 2: Conectar en ZenFlow

​Paso 3: Seleccionar Almacen VTEX

​Paso 4: Configurar Notificaciones (Opcional)

Feed (Recomendado)

Webhooks

​Flujo de Pedidos

​Referencia API

​Conectar Cuenta

​Obtener Estado de Conexion

​Actualizar Configuracion

​Listar Almacenes VTEX

​Configurar Almacen

​Configurar Feed

​Configurar Webhooks

​Sincronizar Pedidos Manualmente

​Sincronizar Stock a VTEX

​Listar Mapeos de Productos

​Crear Mapeo de Producto

​Eliminar Mapeo

​Desconectar Cuenta

​Notificaciones de Pedidos

​Feed (Polling)

​Webhooks

​Mapeo de Productos

​Coincidencia Automatica

​Mapeo Manual

​Mapeo de Estados

​Sincronizacion de Inventario

​Solucion de Problemas

​No Puedo Conectar

​Pedidos No Se Importan

​Stock No Se Sincroniza

​Limites de Tasa

​Requisitos

​Soporte

Integracion con VTEX

Caracteristicas

Guia de Configuracion

Paso 1: Obtener Credenciales de API en VTEX

Paso 2: Conectar en ZenFlow

Paso 3: Seleccionar Almacen VTEX

Paso 4: Configurar Notificaciones (Opcional)

Flujo de Pedidos

Referencia API

Conectar Cuenta

Obtener Estado de Conexion

Actualizar Configuracion

Listar Almacenes VTEX

Configurar Almacen

Configurar Feed

Configurar Webhooks

Sincronizar Pedidos Manualmente

Sincronizar Stock a VTEX

Listar Mapeos de Productos

Crear Mapeo de Producto

Eliminar Mapeo

Desconectar Cuenta

Notificaciones de Pedidos

Feed (Polling)

Webhooks

Mapeo de Productos

Coincidencia Automatica

Mapeo Manual

Mapeo de Estados

Sincronizacion de Inventario

Solucion de Problemas

No Puedo Conectar

Pedidos No Se Importan

Stock No Se Sincroniza

Limites de Tasa

Requisitos

Soporte