Marketplace Catalog Sync

• VTEXマーケットプレイスに新しいSKUをプッシュし、サジェスチョン（送信 → 保留中 → 承認/拒否）のライフサイクルを処理するセラーコネクターの構築。
• SKUがすでにマーケットプレイスに存在するか（200 OK）、新しいサジェスチョンが必要か（404 Not Found）を検出するChange Notificationフローの実装。
• /notificator/{sellerId}/changenotification/{sellerSkuId}/price および /inventory エンドポイントを通じた価格・在庫変更の同期。
• 2.5秒以内に応答しなければならないセラー側のフルフィルメントシミュレーションエンドポイント（POST /pvt/orderForms/simulation）の実装。

• POST /api/catalog/pvt/product や POST /api/catalog/pvt/stockkeepingunit への直接書き込みなど、マーケットプレイス側のカタログ操作を実行している場合 — それらはセラーコネクターのフローではありません。
• 注文フルフィルメントや請求書処理のロジックが必要な場合（代わりに marketplace-fulfillment スキルを参照してください）。
• カタログ通知フローから切り離した、独立したレート制限パターンが必要な場合（代わりに marketplace-rate-limiting スキルを参照してください）。

セラーコネクターは POST .../changenotification/{sellerId}/{sellerSkuId} を使用する必要があります。マーケットプレイスのVTEX SKU IDを想定する単一セグメントの changenotification/{skuId} ルートではありません。このスキルでは、両者の違いを文書化し、公式ドキュメントが2つのルートを混同している場合がある理由を説明し、200（更新）と404（新規提案）の両レスポンスパスに対する具体的なTypeScriptの例を提供します。

新しいSKUは、PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} を介したサジェスト／承認ワークフローを経由する必要があります。外部セラーによるカタログAPIへの直接書き込みは禁止されており、403 Forbiddenが返されます。サジェストはPending（保留中）状態の場合にのみ変更可能であり、承認済みまたは却下済みのサジェストは変更できないため、このスキルはサジェストの更新前にステータスチェックを実施します。

価格と在庫の更新は、それぞれ別々の POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price および .../inventory エンドポイントを介して送信されます。パスセグメントはセラーのSKU ID（マーケットプレイスのVTEX SKU IDではありません）です。これらの通知の後、マーケットプレイスはセラーのフルフィルメントシミュレーションエンドポイントを呼び出して、最新データを取得します。

マーケットプレイスは、価格または在庫の通知があるたびに、販売者の POST /pvt/orderForms/simulation エンドポイントを呼び出します。VTEXはレスポンスを最大 2.5秒 待機し、この制限を超えるとストアフロントで商品が利用不可としてマークされます。このスキルは、エンドポイントが50ミリ秒以内に応答できるよう、キャッシュ優先の実装パターン（インメモリまたはRedis）を提供します。

スロットリングなしで大量の変更通知リクエストを送信すると、429レスポンスが発生し、販売者のAPIアクセス全体がブロックされます。このスキルは、バッチごとの遅延、retry-afterヘッダーの解析、および429エラーに対する指数バックオフを備えた、バッチ処理・同時実行制御された通知ループを提供します。

カタログシステムのルート（例：changenotification）はストアのホスト名（{account}.vtexcommercestable.com.br）を使用し、SKU提案ルートはhttps://api.vtex.com/{accountName}を使用します。両方のサーフェスは同じX-VTEX-API-AppKeyおよびX-VTEX-API-AppTokenヘッダーで認証されます。このスキルは、両方のベースURLをカバーする型付きのSellerConnectorConfigとAxiosクライアントファクトリーを提供します。

セラーが初めてVTEXマーケットプレイスに接続する際、すべてのSKUカタログを登録する必要があります。インテグレーションは各SKUに対してchangenotification/{sellerId}/{sellerSkuId}を呼び出し、404レスポンスが返されるたびにPUT SKU Suggestionをトリガーして、各SKUをオペレーターの承認待ちとなるマーケットプレイスのレビューキューに追加します。

販売者の倉庫システムが価格または在庫の変更イベントを発行します。コネクターは /notificator/ エンドポイントを通じて価格と在庫の通知をバッチ送信し、事前にウォームアップされたキャッシュを備えた販売者のフルフィルメントシミュレーションエンドポイントが、2.5秒の期限内にマーケットプレイスのポーリングリクエストに応答します。

オペレーターは、送信済みだがまだレビューされていない提案の商品データを更新する必要があります。インテグレーションはまず GET /suggestions/{sellerId}/{sellerSkuId} を呼び出して提案がまだ Pending（保留中）の状態であることを確認し、その後、修正されたデータで PUT リクエストを発行します。すでに承認または拒否された提案は、警告とともにスキップされます。

商品データの移行後、数百件のSKUに再通知が必要になります。このインテグレーションでは、バッチ通知パターンを使用して、5件ずつのグループでSKUを処理し、バッチ間に200ミリ秒の遅延を設けるとともに、429エラーに対応したリトライロジックを組み合わせることで、レート制限によるブロックを引き起こすことなくマーケットプレイスへの再通知を実現します。