Marketplace Catalog Sync

• Construir un conector de vendedor que necesita enviar nuevos SKUs a un marketplace de VTEX y gestionar el ciclo de vida de la sugerencia (enviar → pendiente → aprobado/rechazado).
• Implementar el flujo de Change Notification para detectar si un SKU ya existe en el marketplace (200 OK) o si necesita una nueva sugerencia (404 Not Found).
• Sincronizar cambios de precio e inventario a través de los endpoints /notificator/{sellerId}/changenotification/{sellerSkuId}/price e /inventory.
• Implementar el endpoint de Fulfillment Simulation del lado del vendedor (POST /pvt/orderForms/simulation) que debe responder en un plazo de 2,5 segundos.

• Estás realizando operaciones de catálogo del lado del marketplace, como escrituras directas de POST /api/catalog/pvt/product o POST /api/catalog/pvt/stockkeepingunit — esos no son flujos de conector de vendedor.
• Necesitas lógica de cumplimiento de pedidos o manejo de facturas (consulta el skill marketplace-fulfillment en su lugar).
• Necesitas patrones de limitación de velocidad de forma aislada, desacoplados de los flujos de notificación de catálogo (consulta el skill marketplace-rate-limiting en su lugar).

Los conectores de vendedor deben usar POST .../changenotification/{sellerId}/{sellerSkuId} — no la ruta de un solo segmento changenotification/{skuId}, que espera un ID de SKU de VTEX del marketplace. Esta habilidad documenta la distinción, explica por qué la documentación oficial a veces confunde ambas rutas y proporciona ejemplos concretos en TypeScript para las rutas de respuesta 200 (actualización) y 404 (nueva sugerencia).

Los nuevos SKUs deben pasar por el flujo de trabajo de sugerencia/aprobación mediante PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} — las escrituras directas a la API de Catálogo están prohibidas para los vendedores externos y devolverán el error 403 Forbidden. La habilidad aplica una verificación de estado antes de cualquier actualización de sugerencia, ya que las sugerencias solo pueden modificarse mientras se encuentren en estado Pending; las sugerencias aprobadas o rechazadas no pueden modificarse.

Las actualizaciones de precio e inventario se envían a través de endpoints separados POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price y .../inventory, donde el segmento de ruta es el ID de SKU del vendedor (no el ID de SKU VTEX del marketplace). Tras estas notificaciones, el marketplace llama al endpoint de Simulación de Fulfillment del vendedor para recuperar los datos actuales.

El marketplace llama al endpoint POST /pvt/orderForms/simulation del vendedor después de cada notificación de precio o inventario. VTEX espera un máximo de 2,5 segundos para recibir una respuesta; superar este límite marca el producto como no disponible en la tienda. Esta habilidad proporciona un patrón de implementación que prioriza el caché (en memoria o Redis) para que el endpoint responda en menos de 50 ms.

Enviar solicitudes masivas de notificaciones de cambios sin control de velocidad genera respuestas 429 que bloquean todo el acceso a la API del vendedor. Esta habilidad proporciona un bucle de notificaciones por lotes con control de concurrencia, retrasos por lote, análisis del encabezado retry-after y retroceso exponencial ante errores 429.

Las rutas del sistema de catálogo (p. ej., changenotification) utilizan el hostname de la tienda ({account}.vtexcommercestable.com.br), mientras que las rutas de sugerencia de SKU usan https://api.vtex.com/{accountName}. Ambas superficies se autentican con los mismos encabezados X-VTEX-API-AppKey y X-VTEX-API-AppToken. La skill proporciona un SellerConnectorConfig tipado y una fábrica de clientes Axios que cubre ambas URL base.

Un vendedor se conecta por primera vez a un marketplace de VTEX y necesita registrar todo su catálogo de SKU. La integración llama a changenotification/{sellerId}/{sellerSkuId} para cada SKU; cada respuesta 404 activa un PUT SKU Suggestion, colocando cada SKU en la cola de revisión pendiente del marketplace para su aprobación por parte del operador.

El sistema de almacén de un vendedor emite eventos de cambio de precio o stock. El conector envía notificaciones de precios e inventario en lotes a través de los endpoints /notificator/, y el endpoint de Simulación de Fulfillment del vendedor —respaldado por una caché precalentada— responde a las solicitudes de sondeo del marketplace dentro del plazo de 2,5 segundos.

Un operador necesita actualizar los datos del producto en una sugerencia que fue enviada pero aún no revisada. La integración primero llama a GET /suggestions/{sellerId}/{sellerSkuId} para confirmar que la sugerencia sigue en estado Pending, luego emite un PUT con los datos corregidos. Las sugerencias ya aprobadas o rechazadas se omiten con una advertencia.

Después de una migración de datos de productos, cientos de SKUs necesitan una nueva notificación. La integración utiliza el patrón de notificación por lotes de Marketplace Catalog Sync — procesando SKUs en grupos de cinco con retrasos de 200 ms entre lotes y lógica de reintento con detección de errores 429 — para volver a notificar al marketplace sin activar bloqueos por límite de velocidad.