Popecho Third 商户商品接口文档

1. 接口说明

本接口供合作商户向 Popecho 提交或更新商品。商品数据结构与平台内部商品结构保持一致，支持：

商品名称、副标题、简介和详情

商品主图、分类、基础价格

SKU、库存和 SKU 图片

销售属性

SPU 阶梯价

可选的编辑器模板 JSON

商户提交的商品不会直接上架。每次新建或修改后，商品都会进入“待审核”并保持下架；平台审核通过后才会上架。

商户商品属于成品商品。消费者选定 SKU 和数量后直接进入普通购物车及支付流程，不进入定制编辑器，也不需要上传设计图或参考图。

2. 环境信息

环境	Base URL
测试环境	由 Popecho 提供，例如 `https://opentest.popecho.art/`
正式环境	由 Popecho 提供，例如 `https://open.popecho.art/`

服务内部默认端口为 7010。第三方只能调用平台提供的 HTTPS 网关地址，不应直接访问内部服务端口。

3. 身份认证

Popecho 为每个商户分配一组 ApiKey 和 ApiSecret。调用接口时放入请求头：

注意：

不要把 ApiSecret 写入前端代码或公开仓库。

不要在日志中打印完整请求头。

商户身份由服务端根据 ApiKey 确定，请求体中不允许传入 merchantId。

商户被禁用或凭证错误时，请求会被拒绝。

商户开户、启停和 API 凭证生成或重置由 Popecho 平台负责，不属于第三方开放接口。

后续提供商户资料自助维护接口时，商户也只能修改当前凭证对应的自身资料，不能修改状态或 API 凭证。

4. 上传商品图片

第三方不需要预先拥有 Popecho 域名下的图片。先通过本接口上传本地图片，再把返回的 url 填入商品主图、SKU 图片或编辑器模板。

请求

表单字段 files 可重复传入以批量上传图片。每次最多上传 20 张，只接受图片，单个文件最大 10MB。

成功响应

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "bucketName": "popecho",
      "fileName": "c18f4f8f.jpg",
      "url": "https://popecho.art/api/file/openFile/popecho/309f17d92e86450998bed1a49e382ba1.jpg",
      "coverUrl": "https://popecho.art/api/file/openFile/popecho-cover/309f17d92e86450998bed1a49e382ba1.webp"
    }
  ]
}

商品数据使用原图时取 url；列表缩略图等场景可以使用 coverUrl。第三方自己的公网图片 URL 不会自动转存，正式提交商品前应先调用本接口上传。

商户 Logo/头像也使用本接口上传。平台将返回的原图 url 配置到商户资料的 logoUrl，商城商户聚合页会展示该图片。

5. 提交或更新商品

请求

相同商户第一次提交 externalProductId 时创建商品；再次提交相同 externalProductId 时更新原商品。该字段应使用商户系统内稳定且唯一的商品编号。

请求体结构

字段	类型	必填	说明
`externalProductId`	string	是	商户侧商品唯一编号，最长 128 字符
`product`	object	是	商品主体，结构与 Madbuz 商品保存结构一致
`product.spu`	object	是	SPU 基础信息
`product.skus`	array	是	SKU 列表，至少一项
`product.skuAttributeValues`	array	否	SKU 与销售属性值的关联
`product.spuLadderPrices`	array	否	SPU 阶梯价
`product.attributeJson`	array	否	商品销售属性定义
`editorTemplateJson`	string	否	编辑器导出的原始 JSON 字符串

第三方传入的 spu.id、spu.spuCode、spu.saleable、spu.verifyStatus、spu.custom、sku.id、sku.spuId 等平台字段不会用于绕过平台规则。新商品的内部编号由平台生成；spu.custom 由平台强制设置为 2，表示商户成品商品。

完整示例

{
  "externalProductId": "IP-PRODUCT-10001",
  "product": {
    "spu": {
      "spuName": "IP 联名定制帆布袋",
      "slug": "ip-custom-canvas-bag",
      "subTitle": "上传图片，定制专属帆布袋",
      "categoryId": 1001,
      "brandId": 2001,
      "mainImage": [
        "https://popecho.art/api/file/openFile/popecho/309f17d92e86450998bed1a49e382ba1.jpg",
        "https://popecho.art/api/file/openFile/popecho-cover/309f17d92e86450998bed1a49e382ba1.webp"
      ],
      "price": 19.90,
      "discount": 1.00,
      "description": "商品简介",
      "detailHtml": "<p>商品详情</p>",
      "weight": 0.25,
      "volume": 0.001,
      "minOrderQty": 1,
      "ladderPriceSupport": 1
    },
    "skus": [
      {
        "skuName": "白色 / 标准款",
        "price": 19.90,
        "costPrice": 10.00,
        "marketPrice": 29.90,
        "stock": 9999,
        "lowStock": 10,
        "mainImage": "https://cdn.example.com/products/10001/white.jpg",
        "enabled": 1,
        "weight": "0.25"
      }
    ],
    "attributeJson": [
      {
        "attributeId": 10,
        "attributeName": "颜色",
        "attributeValueId": "101",
        "attributeValueName": "白色",
        "valueText": "白色"
      }
    ],
    "skuAttributeValues": [
      {
        "attributeId": 10,
        "attributeValueId": 101,
        "valueText": "白色"
      }
    ],
    "spuLadderPrices": [
      {
        "minQuantity": 1,
        "maxQuantity": 9,
        "price": 19.90,
        "discount": 1.00
      },
      {
        "minQuantity": 10,
        "maxQuantity": 49,
        "price": 17.90,
        "discount": 0.90
      },
      {
        "minQuantity": 50,
        "maxQuantity": null,
        "price": 15.90,
        "discount": 0.80
      }
    ]
  },
  "editorTemplateJson": "{\"schemaVersion\":\"1.0\",\"surfaces\":[],\"slots\":[]}"
}

editorTemplateJson 当前按字符串原样保存。商户没有编辑器模板时，可以不传或传 null。模板的图片替换与渲染规则由后续编辑器协议约定。

成功响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "relationId": 123,
    "spuId": 456,
    "externalProductId": "IP-PRODUCT-10001",
    "auditStatus": 0
  }
}

字段说明：

字段	说明
`relationId`	商户商品关联记录 ID，可提供给平台排查问题
`spuId`	Popehco平台商品 ID
`externalProductId`	商户商品编号
`auditStatus`	`0` 待审核、`1` 审核通过、`2` 审核拒绝

6. 审核与上架流程

商户调用图片上传接口，取得平台图片 URL。

商户把平台图片 URL 写入商品数据并调用商品提交接口。

popehco 校验 ApiKey、ApiSecret 和商户状态。

popehco 根据凭证得到可信的 merchantId，调用 popehco-product 内部接口。

popehco 将请求转换为平台完整商品模型，通过统一完整保存流程一次性保存 SPU、SKU、销售属性、阶梯价和商户商品关联。

商品被强制设置为待审核和下架状态。

平台运营人员审核商品。

审核通过后，平台将商品设置为审核通过并上架；审核拒绝时保持下架并记录原因。

已通过商品再次提交修改后，会重新进入待审核并下架。

商品更新采用完整覆盖语义：请求中的 SKU 列表、销售属性和阶梯价会替换原有对应数据。因此更新时也应提交完整商品数据，而不是只提交发生变化的字段。

消费者下单模式

商品详情中的 spu.custom 用于区分消费者下单流程：

`spu.custom`	下单模式
`0`	编辑器定制商品，需要消费者完成设计
`1`	人工询价商品，可提交参考图和需求
`2`	商户成品商品，只选择 SKU 和数量，直接走普通购物车及支付

商户开放接口创建或更新的商品始终为 2。普通购物车接口中的 productInfo、originalPictureInfo 和 resourceInfo 对该模式均非必填。

商户成品商品的购物车和订单展示图由平台统一取 spu.mainImage 中第一张有效图片。请确保商品至少提供一张主图，并将希望展示给消费者的图片放在数组第一位。

7. 常见失败原因

场景	说明
缺少请求头	未传 `X-Api-Key` 或 `X-Api-Secret`
凭证错误	ApiKey 不存在、商户被禁用或 ApiSecret 不正确
缺少商品编号	`externalProductId` 为空
缺少 SPU	`product.spu` 为空
缺少 SKU	`product.skus` 为空，商品至少需要一个 SKU
字段不合法	分类、品牌、属性或图片等数据不符合平台规则
内部服务失败	商品服务不可用或商品数据保存失败

第三方应记录请求时间、externalProductId 和响应内容，但必须对 X-Api-Secret 脱敏。

7. cURL 示例

8. 版本约定

当前为第一版接口。新增非必填字段不会视为破坏性变更；字段删除、字段含义变化或必填规则变化时，应发布新版本接口并提前通知商户。

Cn Docs

Popecho Third 商户商品接口文档

1. 接口说明

2. 环境信息

3. 身份认证

4. 上传商品图片

请求

成功响应

5. 提交或更新商品

请求

请求体结构

完整示例

成功响应

6. 审核与上架流程

消费者下单模式

7. 常见失败原因

7. cURL 示例

8. 版本约定

请求参数

请求示例代码

返回响应

Cn Docs

Popecho Third 商户商品接口文档#

1. 接口说明#

2. 环境信息#

3. 身份认证#

4. 上传商品图片#

请求#

成功响应#

5. 提交或更新商品#

请求#

请求体结构#

完整示例#

成功响应#

6. 审核与上架流程#

消费者下单模式#

7. 常见失败原因#

7. cURL 示例#

8. 版本约定#

请求参数

请求示例代码

返回响应

Popecho Third 商户商品接口文档

1. 接口说明

2. 环境信息

3. 身份认证

4. 上传商品图片

请求

成功响应

5. 提交或更新商品

请求

请求体结构

完整示例

成功响应

6. 审核与上架流程

消费者下单模式

7. 常见失败原因

7. cURL 示例

8. 版本约定