向 VTEX 市场推送卖家 SKU 目录时…

为 VTEX 市场构建卖家连接器时，用变更通知 + SKU 建议流程注册/更新 SKU，并同步价格、库存与履约模拟。

适用场景

解决思路

1. 卖家侧目录集成必须使用双段路径 `POST /api/catalog_system/pvt/skuseller/changenotification/{sellerId}/{sellerSkuId}`（sellerId 为市场账号中的卖家，sellerSkuId 为卖家自己的 SKU 编码）；返回 200 表示 SKU 已存在（走更新路径），返回 404 表示不存在（发送 SKU 建议）。
2. 不要用单段路径 `POST .../changenotification/{skuId}` 传卖家的 SKU 编码——该路径期望的是 VTEX 市场侧的 SKU ID，仅在标识符确实是市场 SKU ID 时才使用。
3. 用 `PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId}` 注册或更新待处理建议；不要用 `{account}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/seller/...` 这类店铺主机名 + Catalog 路径。
4. 价格与库存使用独立通知端点：`POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price` 和 `POST /notificator/{sellerId}/changenotification/{sellerSkuId}/inventory`，路径中的段是卖家 SKU ID（与建议、卖家侧目录流程同一标识符），不是市场 VTEX SKU ID。
5. 价格/库存通知后，市场会调用卖家的履约模拟端点 `POST /pvt/orderForms/simulation`；该端点必须在 2.5 秒内响应，否则商品被视为不可用。
6. 建议只能在 Pending 状态更新；已批准或已拒绝后卖家无法修改，更新前先 `GET` 建议检查 Status，仅当为 Pending 时才 `PUT`。
7. 所有目录通知调用必须实现 429 处理与指数退避；批量通知必须限流（例如并发 5、批次间延迟 200ms），读取 `retry-after` 头等待后重试。
8. 不要直接写 Catalog API（如 `POST /api/catalog/pvt/product`、`POST /api/catalog/pvt/stockkeepingunit`）——卖家不拥有目录，会返回 403 或产生绕过审批的孤儿条目；必须走变更通知 + SKU 建议流程。
9. 创建带认证的 HTTP 客户端：baseURL 为 `https://{marketplaceAccount}.vtexcommercestable.com.br`，请求头带 `X-VTEX-API-AppKey`、`X-VTEX-API-AppToken`、`Content-Type: application/json`、`Accept: application/json`，超时 10 秒；建议调用使用同一套请求头但完整 URL 指向 `https://api.vtex.com/{account}`。
10. 实现 notifyAndSync：先 POST 卖家侧变更通知，捕获 404 后 `PUT` 建议；其他错误返回 error 结果，不要静默吞掉。
11. 实现履约模拟处理器：从本地目录/缓存读取价格与库存，返回 items（含 id、requestIndex、quantity、seller、price、listPrice、sellingPrice、priceValidUntil、availability、merchantName），并确保在 2.5 秒内响应。
12. 用缓存优先策略（内存或 Redis，事件驱动更新）预缓存价格与库存，使履约模拟在 50ms 内返回，避免超时导致商品下架。
13. 不要紧循环轮询建议状态；建议审批可能耗时数分钟到数天，应使用 cron 定时任务（如每 15-30 分钟）或 webhook 通知检查状态。
14. 批量同步时在 SKU 操作之间加节流（如 200ms），价格与库存通知也逐个发送并节流，避免触发限流。
15. 上线前替换所有占位值（账号名、卖家 ID、API Key/Token），并对照检查清单逐项核对路径、状态码处理、限流与超时。

适用边界 · 注意事项

• 市场侧的目录操作（直接写 Catalog API）不适用，应使用市场侧目录接口。
• 订单履约或发票处理不适用，参见 `marketplace-fulfillment`。
• 单独讨论限流模式不适用，参见 `marketplace-rate-limiting`。