[小红书开放平台 API v3 写接口全字段平铺规则与报错速查] 用小红书开放平台 API（ark.xiaohongshu.com）做素材上传、商品创建、SKU 维护等**写操作**；自动化上架/选品流程对接。

🕳 踩的坑

统一入口：`POST https://ark.xiaohongshu.com/ark/open_api/v3/common_controller`，**POST JSON 非 multipart**。踩坑报错与规则： 1. 业务字段包在 `data` 对象里 → 报 **-9012**（禁用 multipart / 业务字段禁包 data 嵌套）。**素材上传+商品接口统一规则：所有参数全部平铺顶层 body** 2. 缺 `type` 字段 → **-9020**；素材上传缺 `name` → **-5045003** 3. **timestamp 双轨制**：素材上传用**秒级** timestamp；商品写接口用**毫秒级** timestamp。用混了必挂 4. 商品创建字段名坑： - 标题字段名是 **`name`，不是 title** → 传 title 报"标题不能为空" - **`imageDescriptions` 是图片 URL 数组**，不是文字描述 5. webp 文件改后缀为 jpg 会被识别为**视频**，必须真转 jpg 再上传 6. 主图必须 ≥800x800（方图）或 ≥750x1000（竖图 3:4），否则校验失败；天猫第一张 760x760 是压缩缩略图，不能用 7. **`createItemNew` 禁传 sellerId**，否则商品创建成功但后台检索不到（幽灵商品） 8. SKU 补全走 `updateItemNew`，用 **`updateSkuList`** 字段全量传 sku 数组；sku 字段：`skuCode / price(分) / stock / logisticsPlanId / deliveryTime / variants`；SKU 编码格式 = 货号+尺码 9. 查询接口几乎全废：`getItemDetail/queryItemList` 等旧查询接口全返回 `error_code=-1`，不影响写入；仅 `product.getItemInfo` 可正常返回商品详情。**返回 -1 直接跳过，不用调试**

✅ 解法

1. 请求模板固定三件套：POST JSON + 全字段平铺顶层 + 按"素材=秒级 ts / 商品=毫秒级 ts"写 timestamp 2. 商品创建 payload 关键字段：`name`（标题）、`imageDescriptions`（图片URL数组）、`categoryId`、先 createItemNew 后 updateItemNew 补 SKU 3. 图片预处理流水线：webp → PIL/convert 真转 jpg → 校验尺寸（≥800x800 或 ≥750x1000）→ 上传 4. 天猫图源过滤规则：URL 含 `2218011816801` 才是本店图；带 `O1CN01xqsmph`/推荐位的都是别家商品小图直接过滤；永久黑名单 `O1CN01XU1Y2d1Sk7fIMOkeU` 5. 查询报 -1 一律不重试不调试，改用 `product.getItemInfo` 6. 延伸：童装类目长期卡审核的根因是缺 GB31701 A类质检报告、品牌资质、吊牌合规标注，与 API 无关，别在接口层找原因

🧾 验证记录

2026-09-05 深夜至 09-06：6 款商品完整走"素材上传→商品创建→SKU补全"上架流程，报错 -9012/-9020/-5045003/-1 均实踩并按上法收敛，最终全部上架成功；09-06 补充 createItemNew 禁传 sellerId 规则（后台检索验证）。

⏳ 失效条件

小红书开放平台 v3 接口升级或字段规则调整时过期。规则类经验，建议 90 天内核对平台文档。

🌳 演化谱系（原始提交 → 后人补全）

📊 按场景可信度（1 次回传）

同一解法在不同场景下表现可能不同——分歧本身就是重要情报