1. 商品模块API

API URL

post {HTTP(S)地址}/api/{version}/sku

商品分类主数据（树查询/创建/更新/删除）见下文 商品分类，请求 URL 为 /api/{version}/sku_category。商品新增/编辑仍用 categoryName1 / categoryName2 / categoryName3 按名称挂分类。普通属性、SPU 属性见下文 普通属性、SPU属性。

1.1. 商品列表查询接口

1.1.1. SERVICE_TYPE

QUERY_SIMPLE_LIST_SKU

1.1.2. 请求参数

SkuCustomFieldValueSO(自定义栏位搜索)

1.1.3. 返回参数

Sku(商品)

SubSkuDTO(子品信息)

SkuCustomFieldValueVO(自定义栏位信息)

SkuSupplierDTO(供应商信息)

请求示例:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/sku' \
--form 'appId="TEST"' \
--form 'serviceType="QUERY_SIMPLE_LIST_SKU"' \
--form 'bizParam="{
    \"page\":1,
    \"pageSize\":1
}"' \
--form 'timestamp="1731742317"' \
--form 'sign="a9837b4485a8e427f584933267dc4ea4"'

返回示例:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"result\":[{\"cartonVolumeUnit\":\"cm3\",\"ccPriceUnit\":\"USD\",\"customsDeclarationPriceUnit\":\"USD\",\"dangerousTransportGoodsType\":\"NONE\",\"dimensionUnit\":\"cm\",\"enable\":1,\"exportTax\":0.0,\"height\":33.3,\"isDeleted\":0,\"length\":33.3,\"needQualityInspection\":false,\"netWeight\":33.0,\"picUrl\":\"https://test-logo.pomogo.co/STORE/1902244893482377216/default/ced190dda0e74aa0ba25879dffb8b9bc.png\",\"price\":0.0000,\"priceUnit\":\"USD\",\"sku\":\"3WkC2QzAnXPTsGO4vCNUgm\",\"skuCustomFieldValueVOList\":[{\"candidateValue\":[],\"columCode\":1,\"columName\":\"商品有效期\",\"columType\":\"DATE\",\"customFieldId\":17,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":17,\"isQuery\":0,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":2,\"columName\":\"商品产地\",\"columType\":\"STRING\",\"customFieldId\":16,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":16,\"isQuery\":1,\"isShow\":1,\"required\":0},{\"candidateValue\":[\"1\",\"2\",\"3\",\"123\"],\"columCode\":3,\"columName\":\"测试单选栏位\",\"columType\":\"SELECT\",\"customFieldId\":47,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":47,\"isQuery\":0,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":5,\"columName\":\"货值\",\"columType\":\"DATE\",\"customFieldId\":26,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"id\":26,\"isQuery\":0,\"isShow\":1,\"required\":0},{\"candidateValue\":[],\"columCode\":6,\"columName\":\"产品编码\",\"columType\":\"STRING\",\"customFieldId\":33,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":33,\"isQuery\":1,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":7,\"columName\":\"123\",\"columType\":\"STRING\",\"customFieldId\":40,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":40,\"isQuery\":1,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":10,\"columName\":\"地区账套\",\"columType\":\"STRING\",\"customFieldId\":27,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":27,\"isQuery\":0,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":11,\"columName\":\"单箱条码\",\"columType\":\"STRING\",\"customFieldId\":28,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":28,\"isQuery\":0,\"isShow\":0,\"required\":0},{\"candidateValue\":[],\"columCode\":12,\"columName\":\"规格型号\",\"columType\":\"STRING\",\"customFieldId\":29,\"customFieldValueVOList\":[],\"customerId\":3,\"customerIdForUser\":3,\"defaultValue\":\"\",\"id\":29,\"isQuery\":0,\"isShow\":0,\"required\":0}],\"title\":\"yhx母婴商品测试001自营 33\",\"type\":\"SINGLE\",\"weight\":33.0,\"weightUnit\":\"KG\",\"width\":33.3}],\"state\":\"success\",\"total\":3960}",
    "requestId": "afac1414-8397-4657-bd57-ed2c90bdc9b7"
}

1.2. 商品新增接口

1.2.1. SERVICE_TYPE

INSERT_SKU_INFO

1.2.2. 请求参数

SubSkuDTO(组合品子品信息)

SkuCustomFieldValueVO(自定义栏位)

SkuSupplierDTO(供应商信息)

1.2.3. 返回参数

请求示例:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/sku' \
--form 'appId="TEST"' \
--form 'serviceType="INSERT_SKU_INFO"' \
--form 'bizParam="{
\"sku\":\"ckfsku\",
\"title\":\"ckfsku\",
\"type\":\"SINGLE\",
\"weight\":1,
\"netWeight\":1,
\"weightUnit\":\"KG\",
\"length\":1,
\"width\":1,
\"height\":1,
\"dimensionUnit\":\"cm\",
\"enable\":1,
\"serialEnable\":1,
\"shelfLife\":90,

}"' \
--form 'timestamp="1731742317"' \
--form 'sign="bb8a4a78ebd8b43d6bc71f81e83ae900"'

返回示例:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"state\":\"success\"}",
    "requestId": "223f998d-b0d6-43e4-95cb-5c691572417d"
}

1.3. 商品编辑接口

1.3.1. SERVICE_TYPE

UPDATE_SKU_INFO

1.3.2. 请求参数

SubSkuDTO(组合品子品信息)

SkuCustomFieldValueVO(自定义栏位)

SkuSupplierDTO(供应商信息)

1.3.3. 返回参数

请求示例:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/sku' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--form 'appId="TEST"' \
--form 'serviceType="UPDATE_SKU_INFO"' \
--form 'bizParam="{
\"sku\":\"ckfsku\",
\"title\":\"ckfsku\",
\"type\":\"SINGLE\",
\"weight\":1,
\"netWeight\":1,
\"weightUnit\":\"KG\",
\"length\":1,
\"width\":1,
\"height\":1,
\"dimensionUnit\":\"cm\",
\"enable\":1,
\"serialEnable\":1,
\"shelfLife\":90,

}"' \
--form 'timestamp="1731742317"' \
--form 'sign="f843a75cdb3cf14f403fa423108bc410"'

返回示例:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"state\":\"success\"}",
    "requestId": "223f998d-b0d6-43e4-95cb-5c691572417d"
}

1.4. 商品启用/停用接口

1.4.1. SERVICE_TYPE

UPDATE_SKU_STATUS

1.4.2. 请求参数

1.4.3. 返回参数

请求示例:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/sku' \
--form 'appId="TEST"' \
--form 'serviceType="UPDATE_SKU_STATUS"' \
--form 'bizParam="{
\"sku\":\"ckfsku\",
\"enable\":1

}"' \
--form 'timestamp="1731742317"' \
--form 'sign="b5400443bf960060453cacf9c351b6a4"'

返回示例:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"state\":\"success\"}",
    "requestId": "758f16da-dea5-4f1d-a36a-054bd581f0c8"
}

1.5. 查询系统商品

1.5.1. SERVICE_TYPE

QUERY_SYS_SKU_LIST_SKU

1.5.2. 请求参数

SkuExtDTO(SKU查询条件)

1.5.3. 返回参数

ReturnSkuExtDTO

SubSkuDTO

1.6. 商品分类

API URL

post {HTTP(S)地址}/api/{version}/sku_category

业务限制与报错与页面「商品 - 分类管理」/biz/sku_category/ 一致：最多三级；同父级下名称不可重复；更新不改上级；删除时若被系统商品或供应商占用则失败，并级联删除子分类。更新/删除必须传 id 与 version。

开放平台授权：四个接口均不自动授权。客户需在开放平台为应用勾选 QUERY_SKU_CATEGORY_LIST / CREATE_SKU_CATEGORY / UPDATE_SKU_CATEGORY / DELETE_SKU_CATEGORY 后才能调用，否则返回 SERVICE_TYPE_NOT_ALLOW。

1.6.1. 商品分类树查询接口

SERVICE_TYPE

QUERY_SKU_CATEGORY_LIST

请求参数

对齐页面 /biz/sku_category/get_all：返回当前客户下全部商品分类树（一级节点及其 childList），不是分页查询。无需 page / pageSize，无业务过滤参数，无条数上限。bizParam 可为空或 {}。

返回参数

SkuCategory

1.6.2. 商品分类创建接口

SERVICE_TYPE

CREATE_SKU_CATEGORY

请求参数

返回参数

成功时 result.id 为新建分类主键。失败错误码与页面一致，例如 SKU_CATEGORY_NAME_EXISTS、SKU_CATEGORY_PARENT_NOT_EXISTS、DATA_INPUT_ERROR（不可超过三级）。

1.6.3. 商品分类更新接口

SERVICE_TYPE

UPDATE_SKU_CATEGORY

请求参数

不可修改 parentId。version 不一致返回 VERSION_DIFF。

1.6.4. 商品分类删除接口

SERVICE_TYPE

DELETE_SKU_CATEGORY

请求参数

被 SKU 占用：CATEGORY_USED_BY_SKU。被供应商占用：CATEGORY_USED_BY_SUPPLIER。删除时会同时删除其子分类。

1.7. 普通属性

API URL

post {HTTP(S)地址}/api/{version}/skuProperty

普通属性包括单位、品牌、销售状态和自定义分类，不含 SPU 属性。name/nameEN 最长 50，remark 最长 128。

1.7.1. 创建普通属性

SERVICE_TYPE

CREATE_SKU_PROPERTY

请求参数

返回参数

请求示例:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/skuProperty' \
--form 'appId="TEST"' \
--form 'serviceType="CREATE_SKU_PROPERTY"' \
--form 'bizParam="{\"type\":\"BRAND\",\"name\":\"耐克\",\"nameEN\":\"Nike\"}"' \
--form 'timestamp="1756865700001"' \
--form 'sign="sign"'

返回示例:

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"result\":{\"id\":88,\"name\":\"耐克\",\"nameEN\":\"Nike\",\"sequence\":0,\"type\":\"BRAND\"},\"state\":\"success\"}"
}

1.7.2. 修改普通属性

SERVICE_TYPE

UPDATE_SKU_PROPERTY

请求参数

成功时 bizContent 解码后为：

{"notSuccess":false,"state":"success"}

1.7.3. 删除普通属性

SERVICE_TYPE

DELETE_SKU_PROPERTY

请求参数

成功响应与修改接口相同；目标不存在或类型不匹配时返回业务错误。

1.7.4. 普通属性分页查询

SERVICE_TYPE

QUERY_SKU_PROPERTY_LIST

请求参数

返回参数

SkuProperty

空结果返回 result=[] 且 total=0。

分页返回示例：

{
  "state":"success",
  "errorCode":"",
  "errorMsg":"",
  "bizContent":"{\"notSuccess\":false,\"result\":[{\"id\":88,\"type\":\"BRAND\",\"name\":\"耐克\",\"nameEN\":\"Nike\",\"sequence\":0}],\"state\":\"success\",\"total\":1}"
}

1.7.5. 失败响应

参数校验、重名、目标不存在和类型不匹配等错误位于 bizContent。完整错误码见错误码。

{
  "state":"success",
  "errorCode":"",
  "errorMsg":"",
  "bizContent":"{\"errorCode\":\"sku.property.type.invalid\",\"errorMsg\":\"属性类型无效\",\"notSuccess\":true,\"state\":\"failure\"}"
}

1.8. SPU属性

API URL

post {HTTP(S)地址}/api/{version}/spuAttribute

管理 SPU 属性名和属性值。名称和值会去除首尾空格，最长 50；属性值最多 300 个。已被 SPU 引用的属性不可删除，已引用的属性名和属性值不可改掉。

1.8.1. 创建SPU属性

SERVICE_TYPE

CREATE_SPU_ATTRIBUTE

请求参数

返回参数

请求示例:

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/spuAttribute' \
--form 'appId="TEST"' \
--form 'serviceType="CREATE_SPU_ATTRIBUTE"' \
--form 'bizParam="{\"name\":\"颜色\",\"values\":[\"红\",\"蓝\"]}"' \
--form 'timestamp="1756865700001"' \
--form 'sign="sign"'

返回示例：

{
  "state":"success",
  "errorCode":"",
  "errorMsg":"",
  "bizContent":"{\"notSuccess\":false,\"result\":{\"id\":88,\"name\":\"颜色\",\"values\":[\"红\",\"蓝\"]},\"state\":\"success\"}"
}

1.8.2. 修改SPU属性

SERVICE_TYPE

UPDATE_SPU_ATTRIBUTE

请求参数

成功时 bizContent 解码后为 {"notSuccess":false,"state":"success"}。

1.8.3. 删除SPU属性

SERVICE_TYPE

DELETE_SPU_ATTRIBUTE

请求参数

成功响应与修改接口相同；属性被引用时返回业务错误且不会删除。

1.8.4. 查询SPU属性详情

SERVICE_TYPE

GET_SPU_ATTRIBUTE

请求参数

返回参数

attributeValues 每项包含 name、value 和 related；related=true 表示该属性值已被 SPU 引用。

1.8.5. SPU属性分页查询

SERVICE_TYPE

QUERY_SPU_ATTRIBUTE_LIST

请求参数

空结果返回 result=[] 且 total=0。列表不逐条返回引用标记，引用信息见详情。

列表成功响应的 bizContent 包含 result 和 total，result 每项包含 id、name、values；失败格式与普通属性接口一致。

1.9. SPU模块API

API URL

post {HTTP(S)地址}/api/{version}/spu

当前版本为 v1，请求地址为 /api/v1/spu。

1.9.1. 创建系统SPU接口

SERVICE_TYPE

CREATE_SPU

一次请求创建一个系统 SPU，支持在同一请求中新建 SKU 和关联已有 SKU。支持单规格、多规格商品。

应用须单独取得 CREATE_SPU 接口授权；已有 SKU 创建或 SPU 属性接口权限不能替代该授权。默认限流为每 60 秒 50 次，实际额度以应用配置为准。

请求参数

以下参数均位于 bizParam 中。

品牌和分类须已存在于当前应用所属客户下。分类名称为空白时按未传处理，指定分类后必须匹配层级和完整父子路径，不会自动创建分类。

priceUnit、purchaseCostUnit、dimensionUnit、weightUnit 不传或为 null 时按系统创建规则处理；空字符串属于非法枚举值。SPU 售价币种缺省为 USD；新建 SKU 的售价、采购成本币种缺省使用客户有效币种。关联已有 SKU 时也会应用顶层共享字段及默认规则，详见下文。

Video（商品视频）

Attribute（SPU可选属性）

公共属性和属性值会按系统创建规则自动创建或补充，无需传入内部属性 ID。同一属性内的值不可重复。公共属性可能在 SPU 创建失败后仍保留。

AttributeValue（属性值）

SpuSku（新建或关联SKU）

新建 SKU 时，长、宽、高、重量未传均按 1 补齐。新增 SKU 类型为单品（SINGLE）。

规格及关联规则：

• 单规格：isMultiAttribute=false，最多一行 SKU；不传 SKU 时仅创建 SPU，不自动创建 SKU。单规格不保存规格属性关系。
• 多规格：isMultiAttribute=true 或不传，至少一行 SKU，每行必须具有规格信息；不同 SKU 的规格组合不可重复，同一行内属性名不可重复。
• SKU 使用了已在 SPU 中定义可选值的属性时，其取值必须位于该属性的可选值范围内。
• 每个 SKU 行必须明确指定 skuBindMode；LINK 查询不到时失败，不会转为新建。同一已有 SKU 不可重复关联。
• LINK 目标必须有效、未关联其他 SPU，类型须为单品（SINGLE）或组装品（ASSEMBLY）；关联单品采购成本的组装品不能绑定 SPU。
• LINK 行的名称、图片、售价、采购成本、长宽高、重量，未传或 null 时补齐原值，非 null 值参与更新；0 和空字符串也会进入业务处理。
• 品牌、分类、售价币种、采购成本币种、尺寸及重量单位统一取顶层参数并应用系统规则；即使省略，也不能据此认定已有 SKU 对应字段保持不变。关联时省略售价币种按 USD 处理，省略尺寸和重量单位按 cm、KG 处理。需要保留共享字段时请显式传入目标值。
• 规格取值、排序来自本次请求，不从已有 SKU 的旧规格关系补齐。

仅上述业务字段参与创建。内部主键、租户、登录身份、校验开关等字段不能由调用方指定；品牌、分类按名称传入，已有 SKU 按编码传入。

PriceControl（SKU控价配置）

RuleConfig（控价规则）

CountryRuleSet（国家规则集合）

CountryRule（国家规则）

DefaultCountryRule（其他国家默认规则）

控价按规则对象处理，不作为任意深层字段的部分更新接口。无需传入 skuId。

返回参数

接口采用两层响应，bizContent 为 JSON 字符串，需再次解析。外层成功仅表示协议处理成功；判断创建是否成功还需检查 bizContent.state。

外层响应

业务响应（解析 bizContent 后）

成功时不返回 result、SPU ID 或 SKU 列表。重复调用相同 SPU 编码不会更新原商品，也不保证幂等成功。

请求示例

多规格：新建SKU并关联已有SKU

以下 bizParam 示例中，品牌、分类和须预先存在，已有 SKU 须满足上述关联条件：

{
    "spu": "YF_20261026_01",
    "title": "YF_20261026_01",
    "picUrls":
    [
        "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png",
        "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/MjU5YjMyODMxNTE1MjJmNDUwOTc5YzkxZmI1ZmU4MWI.jpg"
    ],
    "video":
    {
        "videoUrl": "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/video/ZjMyNWMxZmRhNmYwZmI0NDg5ZmYwODk4Y2Q2Y2RmM2M.mp4",
        "videoName": "NzVkMTE0NDNhYzc5YTQ2OTY1NTMxODlmMmZhMzc4MWU=.mp4"
    },
    "priceUnit": "BZD",
    "purchaseCostUnit": "BZD",
    "weightUnit": "KG",
    "dimensionUnit": "cm",
    "details": "%3Cp%3E%E5%9B%BE%E6%96%87%E8%AF%A6%E6%83%85%3C%2Fp%3E",
    "description": "",
    "isMultiAttribute": true,
    "brandName": "brand",
    "categoryName1": "111",
    "categoryName2": "222",
    "categoryName3": "333",
    "spuAttributes":
    [
        {
            "name": "YF_TEST",
            "attributeValues":
            [
                {
                    "value": "测试1",
                    "name": "YF_TEST",
                    "sort": 1
                },
                {
                    "value": "测试2",
                    "name": "YF_TEST",
                    "picUrl": null,
                    "sort": 2
                }
            ]
        },
        {
            "name": "口味",
            "attributeValues":
            [
                {
                    "value": "柠檬味",
                    "sort": 1
                },
                {
                    "value": "蓝莓味",
                    "picUrl": null,
                    "sort": 2
                }
            ]
        }
    ],
    "skus":
    [
        {
            "skuBindMode": "LINK",
            "attributeValueList":
            [
                "测试1",
                "柠檬味"
            ],
            "sku": "YF_20261026_02",
            "title": "YF_20261026_02",
            "sort": 1,
            "priceControlConfig":
            {
                "selfConfig":
                {
                    "enabled": true,
                    "priceMode": "BY_COUNTRY",
                    "countryRules":
                    {
                        "countries":
                        [
                            {
                                "countryCode": "US",
                                "currency": "USD",
                                "minPrice": 100
                            }
                        ],
                        "defaultCountryRule":
                        {
                            "enabled": true,
                            "minPrice": 11,
                            "currency": "BZD"
                        }
                    }
                },
                "distributionConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 200,
                    "defaultCurrency": "BZD"
                }
            }
        },
        {
            "skuBindMode": "LINK",
            "picUrl": null,
            "attributeValueList":
            [
                "测试2",
                "蓝莓味"
            ],
            "sku": "YF_20261026_04",
            "purchaseCost": 2,
            "price": 3,
            "weight": 4,
            "length": 3,
            "width": 4,
            "height": 100,
            "title": "YF_20261026_04",
            "sort": 2
        }
    ]
}

单规格：新建SPU和一个SKU

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/spu' \
--form-string 'appId=TEST' \
--form-string 'serviceType=CREATE_SPU' \
--form-string 'bizParam={"spu":"OPEN-SPU-002","title":"基础款水杯","isMultiAttribute":false,"priceUnit":"USD","purchaseCostUnit":"CNY","dimensionUnit":"cm","weightUnit":"KG","skus":[{"skuBindMode":"CREATE","sku":"OPEN-SKU-CUP","title":"基础款水杯","price":19.90,"purchaseCost":10.00,"length":10,"width":10,"height":20,"weight":0.3}]}' \
--form-string 'timestamp=1793059200000' \
--form-string 'sign=替换为按本次完整参数计算的签名'

示例时间戳和签名须替换为实际值。--form-string 的值就是服务端收到的表单字符串，不要额外给 JSON 增加包裹双引号。

单规格：仅创建SPU

bizParam：

{
  "spu": "OPEN-SPU-003",
  "title": "待关联商品",
  "isMultiAttribute": false
}

返回示例

成功：

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"notSuccess\":false,\"state\":\"success\"}"
}

业务失败（SPU编码重复）：

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"errorCode\":\"spu.number.repeat\",\"errorMsg\":\"SPU编码重复\",\"notSuccess\":true,\"state\":\"failure\"}"
}

协议失败（签名错误）：

{
  "state": "failure",
  "errorCode": "SIGNATURE_ERROR",
  "errorMsg": "签名错误"
}

以上示例省略可选的排障字段，错误文案仅作示意。

常见错误码

业务错误码区分大小写，以下列出实际返回的错误码值。

签名、应用授权、IP 白名单及限流失败通常位于外层响应：

应用所属客户的主账号不存在或无效时，业务响应返回 user.not.exist。其他商品、图片和控价错误沿用系统现有错误码；完整错误定义参见错误码。

1.9.2. 修改系统SPU接口

SERVICE_TYPE

UPDATE_SPU

一次请求编辑一个系统 SPU，支持在同一请求中新建 SKU 和关联已有 SKU。支持单规格、多规格商品。

应用须单独取得 UPDATE_SPU 接口授权；已有 SKU 创建或 SPU 属性接口权限不能替代该授权。默认限流为每 60 秒 50 次，实际额度以应用配置为准。

请求参数

以下参数均位于 bizParam 中。

品牌和分类须已存在于当前应用所属客户下。分类名称为空白时按未传处理，指定分类后必须匹配层级和完整父子路径，不会自动创建分类。

priceUnit、purchaseCostUnit、dimensionUnit、weightUnit 不传或为 null 时按系统创建规则处理；空字符串属于非法枚举值。SPU 售价币种缺省为 USD；新建 SKU 的售价、采购成本币种缺省使用客户有效币种。关联已有 SKU 时也会应用顶层共享字段及默认规则，详见下文。

Video（商品视频）

Attribute（SPU可选属性）

公共属性和属性值会按系统创建规则自动创建或补充，无需传入内部属性 ID。同一属性内的值不可重复。公共属性可能在 SPU 创建失败后仍保留。

AttributeValue（属性值）

SpuSku（新建或关联SKU）

新建 SKU 时，长、宽、高、重量未传均按 1 补齐。新增 SKU 类型为单品（SINGLE）。

规格及关联规则：

• 单规格：isMultiAttribute=false，最多一行 SKU；不传 SKU 时仅创建 SPU，不自动创建 SKU。单规格不保存规格属性关系。
• 多规格：isMultiAttribute=true 或不传，至少一行 SKU，每行必须具有规格信息；不同 SKU 的规格组合不可重复，同一行内属性名不可重复。
• SKU 使用了已在 SPU 中定义可选值的属性时，其取值必须位于该属性的可选值范围内。
• 每个 SKU 行必须明确指定 skuBindMode；LINK 查询不到时失败，不会转为新建。同一已有 SKU 不可重复关联。
• LINK 目标必须有效、未关联其他 SPU，类型须为单品（SINGLE）或组装品（ASSEMBLY）；关联单品采购成本的组装品不能绑定 SPU。
• 品牌、分类、售价币种、采购成本币种、尺寸及重量单位统一取顶层参数并应用系统规则；即使省略，也不能据此认定已有 SKU 对应字段保持不变。关联时省略售价币种按 USD 处理，省略尺寸和重量单位按 cm、KG 处理。需要保留共享字段时请显式传入目标值。
• 规格取值、排序来自本次请求，不从已有 SKU 的旧规格关系补齐。

仅上述业务字段参与创建。内部主键、租户、登录身份、校验开关等字段不能由调用方指定；品牌、分类按名称传入，已有 SKU 按编码传入。

PriceControl（SKU控价配置）

RuleConfig（控价规则）

CountryRuleSet（国家规则集合）

CountryRule（国家规则）

DefaultCountryRule（其他国家默认规则）

控价按规则对象处理，不作为任意深层字段的部分更新接口。无需传入 skuId。

返回参数

接口采用两层响应，bizContent 为 JSON 字符串，需再次解析。外层成功仅表示协议处理成功；判断创建是否成功还需检查 bizContent.state。

外层响应

业务响应（解析 bizContent 后）

成功时不返回 result、SPU ID 或 SKU 列表。重复调用相同 SPU 编码不会更新原商品，也不保证幂等成功。

请求示例

多规格：新建SKU并关联已有SKU

以下 bizParam 示例中，品牌、分类须预先存在，已有 SKU 须满足上述关联条件：

{
    "spu": "YF_20261026_01",
    "title": "YF_20261026_011",
    "picUrls":
    [
        "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png"
    ],
    "video":
    {
        "videoUrl": "https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/video/ZjMyNWMxZmRhNmYwZmI0NDg5ZmYwODk4Y2Q2Y2RmM2M.mp4",
        "videoName": "NzVkMTE0NDNhYzc5YTQ2OTY1NTMxODlmMmZhMzc4MWU=.mp4"
    },
    "priceUnit": "BZD",
    "purchaseCostUnit": "BZD",
    "weightUnit": "KG",
    "dimensionUnit": "cm",
    "details": "%3Cp%3E%E5%9B%BE%E6%96%87%E8%AF%A6%E6%83%85%3C%2Fp%3E",
    "isMultiAttribute": true,
    "brandName": "南极人",
    "categoryName1": "2",
    "spuAttributes":
    [
        {
            "name": "YF_TEST",
            "attributeValues":
            [
                {
                    "value": "测试1",
                    "name": "YF_TEST",
                    "sort": 1
                },
                {
                    "value": "测试3",
                    "sort": 2
                }
            ]
        },
        {
            "name": "口味",
            "attributeValues":
            [
                {
                    "value": "柠檬味",
                    "sort": 1
                },
                {
                    "value": "蓝莓味",
                    "picUrl": null,
                    "sort": 2
                }
            ]
        }
    ],
    "skus":
    [
        {
            "skuBindMode": "CREATE",
            "attributeValueList":
            [
                "测试1",
                "柠檬味"
            ],
            "sku": "YF_20261029_02",
            "title": "YF_20261029_02",
            "sort": 1,
            "priceControlConfig":
            {
                "selfConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 100,
                    "defaultCurrency": "USD",
                    "countryRules":
                    {
                        "countries":
                        [
                            {
                                "countryCode": "US",
                                "currency": "USD",
                                "minPrice": 100
                            }
                        ],
                        "defaultCountryRule":
                        {
                            "enabled": true,
                            "minPrice": 11,
                            "currency": "BZD"
                        }
                    }
                },
                "distributionConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 200,
                    "defaultCurrency": "BZD"
                }
            }
        },
        {
            "skuBindMode": "LINK",
            "picUrl": null,
            "attributeValueList":
            [
                "测试3",
                "蓝莓味"
            ],
            "sku": "YF_20261026_04",
            "purchaseCost": 2,
            "price": 3,
            "weight": 4,
            "length": 3,
            "width": 4,
            "height": 100,
            "title": "YF_20261026_04",
            "sort": 2,
            "priceControlConfig":
            {
                "selfConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 200,
                    "defaultCurrency": "USD",
                    "countryRules":
                    {
                        "countries":
                        [
                            {
                                "countryCode": "US",
                                "currency": "USD",
                                "minPrice": 100
                            }
                        ],
                        "defaultCountryRule":
                        {
                            "enabled": true,
                            "minPrice": 11,
                            "currency": "BZD"
                        }
                    }
                },
                "distributionConfig":
                {
                    "enabled": true,
                    "priceMode": "UNIFIED",
                    "defaultMinPrice": 200,
                    "defaultCurrency": "BZD"
                }
            }
        }
    ]
}

返回示例

成功：

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"notSuccess\":false,\"state\":\"success\"}"
}

业务失败（SPU编码必填）：

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"errorCode\":\"spu.number.repeat\",\"errorMsg\":\"SPU编码必填\",\"notSuccess\":true,\"state\":\"failure\"}"
}

协议失败（签名错误）：

{
  "state": "failure",
  "errorCode": "SIGNATURE_ERROR",
  "errorMsg": "签名错误"
}

以上示例省略可选的排障字段，错误文案仅作示意。

1.9.3. 查询系统SPU编码接口

SERVICE_TYPE

QUERY_SPU_CODE

根据查询查询条件查询SPU编码列表，如需要SPU详情，则需调用SPU详情接口查询

请求参数

以下参数均位于 bizParam 中。

返回参数

接口采用两层响应，bizContent 为 JSON 字符串，需再次解析。外层成功仅表示协议处理成功；判断创建是否成功还需检查 bizContent.state。

外层响应

业务响应（解析 bizContent 后）

成功时不返回 result、SPU ID 或 SKU 列表。重复调用相同 SPU 编码不会更新原商品，也不保证幂等成功。

请求示例

以下 bizParam 示例中，品牌、分类须预先存在，已有 SKU 须满足上述关联条件：

{"page":1,"pageSize":10,"updateTimeFrom":"2026-10-29 00:00:00","updateTimeTo":"2026-10-30 23:59:00","titleList":["YF_20261026_011"]}

返回示例

成功：

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"result\":[{\"spu\":\"YF_20261026_01\"}],\"state\":\"success\",\"total\":1,\"traceId\":\"a92f7e5ef3a142af946ac72ae6dca7cc\"}",
    "requestId": "f1c3fcd9-9dce-4e5e-a46b-856c55fe6152"
}

1.9.4. 查询系统SPU详情接口

SERVICE_TYPE

QUERY_SPU_INFO

请求方式为 POST，请求地址为 /api/v1/spu。按 SPU 编码批量查询应用所属客户的 SPU 详情，同时返回品牌、分类、规格属性、关联 SKU 及 SKU 控价配置。

请求参数

以下参数位于 bizParam 中；公共表单参数沿用 appId、serviceType、bizParam、timestamp、sign。

• 本接口不分页，无需传入 page、pageSize；超过 200 项时请分批调用。
• 仅返回当前应用所属客户下查询到的 SPU，不存在或不属于当前客户的编码不返回占位数据；全部未命中时成功返回空列表。
• 返回顺序不保证与传入编码顺序一致，请通过 spu 字段匹配结果。

返回参数

接口采用两层响应，bizContent 为 JSON 字符串，需再次解析。外层成功表示协议处理成功；查询是否成功还需检查 bizContent.state。

外层响应

业务响应（解析 bizContent 后）

本接口不返回分页总数 total 或 hasMore。以下可选字段未设置时可能不返回。

SpuInfo（SPU详情）

VideoInfo（商品视频）

AttributeInfo（SPU属性）

AttributeValueInfo（SPU属性值）

SkuInfo（关联SKU信息）

SkuAttributeInfo（SKU规格属性）

PriceControlInfo（SKU控价配置）

RuleConfig、CountryRuleSet、CountryRule、DefaultCountryRule 的字段结构与本章“创建系统SPU接口”中的同名结构一致。查询返回已保存的配置：enabled 表示是否启用，priceMode 为 UNIFIED（统一控价）或 BY_COUNTRY（分国家控价），defaultMinPrice / defaultCurrency 为统一最低限价及币种，countryRules 为国家规则及其他国家的默认规则；未设置的字段可能不返回。

请求示例

bizParam：

{
  "spuList": ["OPEN-SPU-001", "OPEN-SPU-002"]
}

完整表单请求：

curl --location --request POST 'https://gerp-test1.800best.com/api/v1/spu' \
--form-string 'appId=TEST' \
--form-string 'serviceType=QUERY_SPU_INFO' \
--form-string 'bizParam={"spuList":["OPEN-SPU-001","OPEN-SPU-002"]}' \
--form-string 'timestamp=1793059200000' \
--form-string 'sign=替换为按本次完整参数计算的签名'

示例时间戳和签名须替换为实际值。bizParam 是 JSON 字符串，不要额外增加包裹双引号。

返回示例

成功（示例中仅命中一个SPU）：

{
    "state": "success",
    "errorCode": "",
    "errorMsg": "",
    "bizContent": "{\"notSuccess\":false,\"result\":[{\"brandName\":\"JJ专属品牌\",\"categoryName1\":\"111\",\"categoryName2\":\"222\",\"categoryName3\":\"333\",\"details\":\"%3Cp%3E%E5%9B%BE%E6%96%87%E8%AF%A6%E6%83%85%3C/p%3E%20%0A%3Cfigure%20class=%22image%22%3E%20%0A%20%3Cimg%20src=%22https://qianyierp-test.oss.aliyuncs.com/attachment/20261103/image/NjU4ZjU5MzFhN2NmYmM5ZTE4OGQ0YTdiZjZjYjI5MmU.jpg%22%20width=%22432%22%20height=%22268%22%3E%20%0A%3C/figure%3E\",\"dimensionUnit\":\"cm\",\"isMultiAttribute\":true,\"picUrls\":[\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png\"],\"priceUnit\":\"BZD\",\"purchaseCostUnit\":\"BZD\",\"skus\":[{\"attributeValues\":[{\"name\":\"YF_TEST\",\"value\":\"测试3\"},{\"name\":\"口味\",\"value\":\"蓝莓味\"}],\"categoryName1\":\"111\",\"categoryName2\":\"222\",\"categoryName3\":\"333\",\"dimensionUnit\":\"cm\",\"height\":100.0,\"length\":3.0,\"picUrl\":\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png\",\"price\":3.0000,\"priceControlConfig\":{\"distributionConfig\":{\"countryRules\":{\"countries\":[],\"defaultCountryRule\":{\"enabled\":false}},\"defaultCurrency\":\"BZD\",\"defaultMinPrice\":200.0000,\"enabled\":true,\"priceMode\":\"UNIFIED\"},\"selfConfig\":{\"countryRules\":{\"countries\":[],\"defaultCountryRule\":{\"enabled\":false}},\"defaultCurrency\":\"USD\",\"defaultMinPrice\":200.0000,\"enabled\":true,\"priceMode\":\"UNIFIED\"}},\"priceUnit\":\"BZD\",\"purchaseCost\":2.0000,\"purchaseCostUnit\":\"BZD\",\"sku\":\"YF_20261026_04\",\"title\":\"YF_20261026_04\",\"weight\":4.0,\"weightUnit\":\"KG\",\"width\":4.0}],\"spu\":\"YF_20261026_01\",\"spuAttributes\":[{\"attributeValues\":[{\"name\":\"YF_TEST\",\"picUrl\":\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png\",\"sort\":1,\"value\":\"测试1\"},{\"name\":\"YF_TEST\",\"picUrl\":\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/image/NmJiYmY2MGIxNTAyZWE2YjRhODk5YTYwNzE4MzY0NDU.png\",\"sort\":2,\"value\":\"测试3\"}],\"name\":\"YF_TEST\",\"values\":[\"测试1\",\"测试3\"]},{\"attributeValues\":[{\"name\":\"口味\",\"sort\":1,\"value\":\"柠檬味\"},{\"name\":\"口味\",\"sort\":2,\"value\":\"蓝莓味\"}],\"name\":\"口味\",\"values\":[\"柠檬味\",\"蓝莓味\"]}],\"title\":\"YF_20261026_011\",\"video\":{\"videoName\":\"NzVkMTE0NDNhYzc5YTQ2OTY1NTMxODlmMmZhMzc4MWU=.mp4\",\"videoUrl\":\"https://qianyierp-test.oss.aliyuncs.com/attachment/20261026/video/ZjMyNWMxZmRhNmYwZmI0NDg5ZmYwODk4Y2Q2Y2RmM2M.mp4\"},\"weightUnit\":\"KG\"}],\"state\":\"success\",\"traceId\":\"c920de9db71e42adb0f3950b58b9eb7c\"}",
    "requestId": "edc11513-1f1c-462c-8844-2eaab89e8a07"
}

全部未命中：

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"notSuccess\":false,\"state\":\"success\",\"result\":[]}"
}

业务失败（编码列表为空或超过200项）：

{
  "state": "success",
  "errorCode": "",
  "errorMsg": "",
  "bizContent": "{\"errorCode\":\"data.input.error.msg\",\"errorMsg\":\"输入参数不正确：spuList.size: 1-200\",\"notSuccess\":true,\"state\":\"failure\"}"
}

以上示例省略可选排障字段，错误文案仅作示意。签名、授权及限流等协议失败沿用本章“创建系统SPU接口”的错误码说明。