Marketplace Catalog Sync

• 构建一个卖家连接器，需要将新 SKU 推送到 VTEX marketplace，并处理建议（发送 → 待处理 → 已批准/已拒绝）的生命周期。
• 实现变更通知流程，以检测 SKU 是否已存在于 marketplace 中（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} — 对于外部卖家而言，直接写入目录API的操作是被禁止的，并将返回403 Forbidden错误。该功能在任何建议更新之前强制执行状态检查，因为建议只能在 Pending（待处理）状态下进行修改；已批准或已拒绝的建议无法更改。

价格和库存更新分别通过 POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price 和 .../inventory 端点发送，其中路径段为卖家的 SKU ID（而非市场 VTEX SKU ID）。在收到这些通知后，市场将调用卖家的履单模拟端点以获取最新数据。

每当价格或库存通知触发后，Marketplace Catalog Sync 会调用卖家的 POST /pvt/orderForms/simulation 接口。VTEX 最多等待 2.5秒 以获取响应；超出此时限将导致商品在店面中被标记为不可购买。本技能提供以缓存优先的实现模式（内存缓存或 Redis），使接口响应时间控制在50毫秒以内。

在未进行限流控制的情况下批量发送变更通知请求，会触发429响应，从而阻断卖家的整个API访问权限。本技能提供了一个批量化、并发受控的通知循环，支持批次间延迟、retry-after响应头解析，以及针对429错误的指数退避重试机制。

目录系统路由（例如 changenotification）使用商店主机名（{account}.vtexcommercestable.com.br），而 SKU 建议路由则使用 https://api.vtex.com/{accountName}。两个接口均通过相同的 X-VTEX-API-AppKey 和 X-VTEX-API-AppToken 请求头进行身份验证。该技能提供了一个类型化的 SellerConnectorConfig 以及涵盖两个基础 URL 的 Axios 客户端工厂。

卖家首次接入 VTEX marketplace，需要注册其全部 SKU 目录。集成为每个 SKU 调用 changenotification/{sellerId}/{sellerSkuId}；每次收到 404 响应时，触发一次 PUT SKU 建议请求，将该 SKU 放入 marketplace 的待审核队列，等待运营人员审批。

卖家的仓库系统发出价格或库存变更事件。连接器通过 /notificator/ 端点发送批量价格和库存通知，卖家的履单模拟端点——由预热缓存提供支持——在 2.5 秒的截止时限内响应市场的轮询请求。

操作员需要更新已发送但尚未审核的建议中的产品数据。集成首先调用 GET /suggestions/{sellerId}/{sellerSkuId} 以确认建议仍处于 Pending（待处理）状态，然后发出包含更正数据的 PUT 请求。已批准或已拒绝的建议将被跳过，并显示警告信息。

在完成产品数据迁移后，需要对数百个 SKU 重新发送通知。该集成采用批量通知模式——每批处理五个 SKU，批次间延迟 200 毫秒，并内置针对 429 错误的重试逻辑——从而在不触发速率限制拦截的情况下，向市场重新发送通知。