Webhook de errores de publicación de stock en VTEX

Cuando Janis publica stock hacia una cuenta de VTEX, puede ocurrir que la publicación no se complete: el SKU o el warehouse todavía no existen en VTEX, VTEX rechaza la request o la plataforma no responde después de varios reintentos. Este webhook notifica cada uno de esos casos a un sistema externo (ERP, middleware o herramienta de monitoreo), para que el equipo de integración pueda detectarlos y darles tratamiento sin tener que revisar la publicación de forma manual.

📘

Antes de empezar

• La cuenta VTEX debe estar configurada en Janis. Ver Cuentas VTEX.
• El stock se publica por warehouse: el warehouse debe estar asociado a un canal de venta de la cuenta VTEX. Ver Integrar catálogo con VTEX.
• Se necesita un endpoint propio que reciba las notificaciones. Ver Webhooks: Buenas prácticas.

Configuración de la suscripción

La notificación solo se envía si existe una suscripción activa con el evento correspondiente. Aunque Janis detecte el error, sin suscripción no se notifica nada.

1. Ingresar a Webhooks y crear una suscripción nueva.
2. Completar el Nombre, la URL del endpoint y, si el endpoint lo requiere, el esquema de autenticación.
3. En el campo de eventos, seleccionar el trigger Vtex Wms - Stock - Stock Publish Error.
4. Opcional: configurar un Filtro para recibir solo algunos tipos de error (por ejemplo, filtrando por errorType).
5. Guardar la suscripción.

Para el detalle general de suscripciones y filtros, ver Suscripción de Webhook para notificar Eventos.

Estructura de la notificación

Cada error genera un evento stockPublishError del servicio vtex-wms, con la siguiente información en metadata:

El campo eventDate indica la fecha del evento en UTC.

🚧

errorType puede llegar vacío

Cuando el error ocurre antes de que la request llegue a VTEX y no corresponde a ninguno de los tipos de la tabla, la notificación viaja sin errorType y solo con errorMessage. Conviene contemplar este caso al procesar el evento.

Tipos de error

Errores previos a la publicación

Janis detecta el problema antes de enviar la request a VTEX:

🚧

Solo en la primera publicación de stock

Estos tres errores se evalúan únicamente cuando la combinación de SKU y warehouse publica stock por primera vez en esa cuenta VTEX. Si el SKU ya venía publicando stock y luego falla, el error se informa con el tipo que devuelva VTEX (por ejemplo, vtexClientError).

Consideraciones sobre warehouseNotFound:

• Si el warehouse no está asociado a un canal de venta de la cuenta VTEX, su stock no se envía a publicar, por lo que no se genera ningún error ni notificación.
• Si la cuenta está configurada para publicar warehouses hacia VTEX (en lugar de importarlos), el warehouse se crea en VTEX automáticamente al poco tiempo y el error deja de notificarse.

Errores al publicar en VTEX

La request llega a VTEX y la respuesta no es exitosa:

👍

Revisar credenciales ante vtexClientError

Un vtexClientError con 401 o 403 suele indicar un problema con las credenciales de la cuenta VTEX configurada en Janis. Ver Cuentas VTEX.

Ejemplos

SKU que todavía no existe en VTEX:

{
  "service": "vtex-wms",
  "entity": "stock",
  "eventName": "stockPublishError",
  "metadata": {
    "skuVtexId": null,
    "skuReferenceId": "<YOUR_SKU_REFERENCE_ID>",
    "warehouseVtexId": "<YOUR_WAREHOUSE_VTEX_ID>",
    "warehouseReferenceId": "<YOUR_WAREHOUSE_REFERENCE_ID>",
    "accountVtexName": "<YOUR_VTEX_ACCOUNT>",
    "stock": 80,
    "availableStock": 23,
    "errorType": "skuNotFound"
  },
  "eventDate": "2026-03-19T11:20:42.348Z"
}

Reintentos agotados por límite de requests de VTEX:

{
  "service": "vtex-wms",
  "entity": "stock",
  "eventName": "stockPublishError",
  "metadata": {
    "skuVtexId": 12345,
    "skuReferenceId": "<YOUR_SKU_REFERENCE_ID>",
    "warehouseVtexId": "<YOUR_WAREHOUSE_VTEX_ID>",
    "warehouseReferenceId": "<YOUR_WAREHOUSE_REFERENCE_ID>",
    "accountVtexName": "<YOUR_VTEX_ACCOUNT>",
    "stock": 105,
    "availableStock": 105,
    "errorType": "vtexTooManyRequests",
    "errorMessage": "429 - Too Many Requests",
    "vtexResponse": {
      "status": 429,
      "statusText": "Too Many Requests"
    }
  },
  "eventDate": "2026-03-19T11:55:10.768Z"
}

📘

Volumen de notificaciones

Ante un incidente de publicación (por ejemplo, una caída de VTEX), se puede recibir un volumen alto de notificaciones en pocos minutos, una por cada registro de stock afectado. El endpoint debe estar preparado para responder rápido y procesar los eventos de forma asíncrona. Ver Webhooks: Buenas prácticas.