Marketplace Catalog Sync

• 建立賣家連接器，需將新 SKU 推送至 VTEX 商城，並處理建議流程（傳送 → 待審 → 核准/拒絕）的生命週期。
• 實作變更通知流程，以偵測 SKU 是否已存在於商城中（200 OK），或需要提交新建議（404 Not Found）。
• 透過 /notificator/{sellerId}/changenotification/{sellerSkuId}/price 與 /inventory 端點同步價格與庫存變更。
• 實作賣家端的履行模擬端點（POST /pvt/orderForms/simulation），該端點必須在 2.5 秒內回應。

• 您正在執行市集端的目錄操作，例如直接寫入 POST /api/catalog/pvt/product 或 POST /api/catalog/pvt/stockkeepingunit——這些不屬於賣家連接器流程。
• 您需要訂單履行或發票處理邏輯（請改參閱 marketplace-fulfillment 技能）。
• 您需要獨立的速率限制模式，與目錄通知流程解耦（請改參閱 marketplace-rate-limiting 技能）。

賣家連接器必須使用 POST .../changenotification/{sellerId}/{sellerSkuId}，而非單段式的 changenotification/{skuId} 路由（該路由預期接收的是 marketplace 的 VTEX SKU ID）。本技能說明兩者之間的差異，解釋為何官方文件有時會將這兩條路由混為一談，並針對 200（更新）與 404（新建議）兩種回應路徑提供具體的 TypeScript 範例。

新的 SKU 必須透過建議/審核工作流程進行處理，使用 PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} — 外部賣家禁止直接寫入 Catalog API，否則將回傳 403 Forbidden 錯誤。此功能在任何建議更新之前會強制執行狀態檢查，因為建議僅能在 Pending（待審核）狀態下進行修改；已核准或已拒絕的建議將無法變更。

價格與庫存更新分別透過 POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price 和 .../inventory 端點傳送，其中路徑區段為賣家的 SKU ID（而非市集的 VTEX SKU ID）。收到這些通知後，市集會呼叫賣家的履單模擬端點以擷取最新資料。

市集在每次價格或庫存通知後，都會呼叫賣家的 POST /pvt/orderForms/simulation 端點。VTEX 最多等待 2.5 秒以獲得回應；超過此限制將導致商品在店面標記為無法購買。此技能提供以快取優先的實作模式（記憶體內或 Redis），使端點能在 50 毫秒內回應。

在未進行流量控制的情況下，大量發送變更通知請求會觸發 429 回應，進而封鎖賣家的整個 API 存取權限。此技能提供一個具備批次處理與並發控制的通知迴圈，包含每批次延遲、retry-after 標頭解析，以及針對 429 錯誤的指數退避機制。

Catalog System 路由（例如 changenotification）使用商店主機名稱（{account}.vtexcommercestable.com.br），而 SKU Suggestion 路由則使用 https://api.vtex.com/{accountName}。兩個介面均使用相同的 X-VTEX-API-AppKey 與 X-VTEX-API-AppToken 標頭進行驗證。此技能提供具有型別定義的 SellerConnectorConfig 以及涵蓋兩種基礎 URL 的 Axios 客戶端工廠。

一位賣家首次連接至 VTEX 商城，需要註冊其完整的 SKU 目錄。整合流程會針對每個 SKU 呼叫 changenotification/{sellerId}/{sellerSkuId}；每當收到 404 回應時，即觸發一次 PUT SKU 建議，將每個 SKU 放入商城的待審核佇列，等候操作人員審核核准。

賣家的倉儲系統會發出價格或庫存變動事件。連接器透過 /notificator/ 端點批次傳送價格與庫存通知，而賣家的履行模擬端點——以預先暖機的快取為後盾——能在 2.5 秒的期限內回應市場的輪詢請求。

操作人員需要更新一筆已送出但尚未審核的建議商品資料。整合流程會先呼叫 GET /suggestions/{sellerId}/{sellerSkuId} 確認該建議仍處於「待審核 (Pending)」狀態，接著使用 PUT 提交修正後的資料。已核准或已拒絕的建議將會略過，並顯示警告訊息。

在產品資料遷移完成後，數百個 SKU 需要重新通知。此整合採用批次通知模式——以每組五個 SKU 為單位進行處理，批次間延遲 200 毫秒，並具備感知 429 錯誤的重試邏輯——以便在不觸發速率限制封鎖的情況下，重新通知 Marketplace Catalog Sync。