cmautobuy/docs/admin/10-商品目录接入接口.md

10 商品目录批量接入接口

第三方脚本先把不同 Excel 归一化，再用本接口一次提交蝦皮商品、蝦皮 SKU、PDD 商品及商品关联。接口只做 upsert，本批次没出现的数据不会被删除。

1. 地址与鉴权

• POST /api/v1/integrations/catalog/batches
• 请求头：Authorization: Bearer <专用 Token>
• 请求体上限 5 MB；每批商品总数最多 500，蝦皮 SKU 最多 5000。

Token 通过 CMAUTOBUY_CATALOG_TOKEN 或未提交的 config.yaml 配置。未配置时接口 返回 503；凭据错误返回 401。不要把 Token 放进 URL、日志或导入文件。

2. 请求示例

{
  "schema_version": 1,
  "batch_id": "source-file-20260811-001",
  "observed_at": "2026-08-11T10:00:00+08:00",
  "shopee_products": [
    {"goods_id": "S-1", "title": "蝦皮上衣", "status": "NORMAL", "main_sku_code": "A01"}
  ],
  "shopee_skus": [
    {"sku_id": "SKU-1", "goods_id": "S-1", "spec_raw": "黑色,M", "color": "黑色", "size": "M", "parse_ok": true, "sku_code": "A01-B-M"}
  ],
  "pdd_products": [
    {
      "goods_id": "P-1",
      "url": "https://mobile.yangkeduo.com/goods.html?goods_id=P-1",
      "title": "PDD 上衣",
      "shop_name": "示例店铺",
      "dimensions": [{"key": "color", "name": "颜色"}, {"key": "size", "name": "尺码"}],
      "skus": [{"options": {"color": "黑色", "size": "M"}, "price_cent": 1299, "list_price_cent": 1599, "available": true}]
    }
  ],
  "associations": [{"shopee_goods_id": "S-1", "pdd_goods_id": "P-1"}]
}

金额单位固定为人民币分，不接受小数金额。spec_raw 必须原样提交。PDD 规格必须用 结构化 dimensions 和 skus，第三方不能提交数据库内部的 skus_json。

3. 写入与幂等规则

• 整个批次在一个事务中写入：实体、SKU、关联任一步失败就全部回滚。
• (source, batch_id) 是幂等键。请求字节相同则重放首次结果；同键不同内容返回 409。
• 较旧的 observed_at 不覆盖较新的接口数据。
• 蝦皮 upsert 不覆盖采购员维护的 PDD 链接；SKU 的 is_manual 不被接口改写。
• 空关联可以建立、相同关联不重复写；已有不同 PDD 关联返回 409，绝不静默替换。
• 批次缺少某条记录不表示删除，接口没有“全量覆盖”语义。

成功响应包含批次状态和各类新增、更新、关联计数。相同请求重放时 replayed=true。

4. 错误格式

{
  "error": {
    "code": "ASSOCIATION_CONFLICT",
    "message": "蝦皮商品已经关联其他 PDD 商品",
    "retryable": false,
    "request_id": "调用方可选请求号",
    "details": {}
  }
}

调用方应按 code 处理，不要解析中文 message。校验错误通常是 400/422，业务冲突 是 409，临时服务错误是 500/503。响应和导入记录都不会回显 Token 或完整请求体。