Marketplace Catalog Sync

• Créer un connecteur vendeur permettant d'envoyer de nouveaux SKU vers un marketplace VTEX et de gérer le cycle de vie des suggestions (envoi → en attente → approuvé/refusé).
• Mettre en œuvre le flux de notification de changement (Change Notification) pour détecter si un SKU existe déjà dans le marketplace (200 OK) ou nécessite une nouvelle suggestion (404 Not Found).
• Synchroniser les modifications de prix et de stock via les endpoints /notificator/{sellerId}/changenotification/{sellerSkuId}/price et /inventory.
• Mettre en œuvre l'endpoint de simulation de commande (Fulfillment Simulation) côté vendeur (POST /pvt/orderForms/simulation), qui doit répondre en moins de 2,5 secondes.

• Vous effectuez des opérations de catalogue côté marketplace telles que des écritures directes POST /api/catalog/pvt/product ou POST /api/catalog/pvt/stockkeepingunit — celles-ci ne relèvent pas des flux seller-connector.
• Vous avez besoin d'une logique de traitement des commandes ou de gestion des factures (consultez plutôt le skill marketplace-fulfillment).
• Vous avez besoin de patterns de limitation de débit de manière isolée, découplés des flux de notification de catalogue (consultez plutôt le skill marketplace-rate-limiting).

Les connecteurs vendeurs doivent utiliser POST .../changenotification/{sellerId}/{sellerSkuId} — et non la route à segment unique changenotification/{skuId}, qui attend un identifiant SKU VTEX de la marketplace. Cette compétence documente la distinction, explique pourquoi la documentation officielle confond parfois les deux routes, et fournit des exemples TypeScript concrets pour les deux chemins de réponse : 200 (mise à jour) et 404 (nouvelle suggestion).

Les nouveaux SKU doivent passer par le workflow de suggestion/approbation via PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} — les écritures directes dans l'API Catalog sont interdites pour les vendeurs externes et renverront une erreur 403 Forbidden. La compétence applique une vérification du statut avant toute mise à jour de suggestion, car les suggestions ne peuvent être modifiées que lorsqu'elles sont à l'état Pending ; les suggestions approuvées ou refusées ne peuvent pas être modifiées.

Les mises à jour de prix et d'inventaire sont envoyées via des points de terminaison distincts POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price et .../inventory, où le segment de chemin correspond à l'ID SKU du vendeur (et non à l'ID SKU VTEX de la place de marché). Après ces notifications, la place de marché appelle le point de terminaison de simulation de traitement des commandes du vendeur afin de récupérer les données actuelles.

La marketplace appelle l'endpoint POST /pvt/orderForms/simulation du vendeur après chaque notification de prix ou de stock. VTEX attend un maximum de 2,5 secondes pour une réponse ; dépasser cette limite marque le produit comme indisponible sur la vitrine. Cette compétence fournit un modèle d'implémentation orienté cache (en mémoire ou Redis) afin que l'endpoint réponde en moins de 50 ms.

L'envoi de requêtes de notification de changement en masse sans limitation de débit déclenche des réponses 429 qui bloquent l'accès complet du vendeur à l'API. Cette compétence fournit une boucle de notification par lots avec contrôle de la simultanéité, des délais par lot, l'analyse de l'en-tête retry-after et un recul exponentiel en cas d'erreurs 429.

Les routes du système de catalogue (par ex., changenotification) utilisent le nom d'hôte de la boutique ({account}.vtexcommercestable.com.br), tandis que les routes de suggestion de SKU utilisent https://api.vtex.com/{accountName}. Les deux surfaces s'authentifient avec les mêmes en-têtes X-VTEX-API-AppKey et X-VTEX-API-AppToken. La compétence fournit un SellerConnectorConfig typé et une fabrique de clients Axios couvrant les deux URL de base.

Un vendeur se connecte pour la première fois à une marketplace VTEX et doit enregistrer l'intégralité de son catalogue de SKU. L'intégration appelle changenotification/{sellerId}/{sellerSkuId} pour chaque SKU ; chaque réponse 404 déclenche un PUT SKU Suggestion, plaçant chaque SKU dans la file d'attente de révision en attente de la marketplace pour approbation par l'opérateur.

Le système d'entrepôt d'un vendeur émet des événements de modification de prix ou de stock. Le connecteur envoie des notifications groupées de prix et d'inventaire via les endpoints /notificator/, et l'endpoint de Simulation de Fulfillment du vendeur — soutenu par un cache préchauffé — répond aux requêtes d'interrogation de la marketplace dans le délai imparti de 2,5 secondes.

Un opérateur doit mettre à jour les données produit d'une suggestion qui a été envoyée mais pas encore examinée. L'intégration appelle d'abord GET /suggestions/{sellerId}/{sellerSkuId} pour confirmer que la suggestion est toujours à l'état Pending, puis émet un PUT avec les données corrigées. Les suggestions déjà approuvées ou refusées sont ignorées avec un avertissement.

Après une migration de données produit, des centaines de SKU nécessitent une nouvelle notification. L'intégration utilise le modèle de notification par lots — traitant les SKU en groupes de cinq avec des délais de 200 ms entre chaque lot et une logique de nouvelle tentative tenant compte des erreurs 429 — pour notifier à nouveau la marketplace sans déclencher de blocages liés aux limites de débit.