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；失败格式与普通属性接口一致。