商品对接

接口说明

获取挂载权限后，申请商品对接 ，商品需要经过审核。审核结果的通知机制为：通过回调地址回调结果，也可支持通过审核状态查询接口主动查询 。

对于审核通过的商品可通过商品编辑接口进行商品信息的编辑，需要注意，商品信息包含分销字段时（ 为分销商品 、包含佣金字段） ，对于分销佣金/比例的变更需要当日24点生效，其余字段实时生效 。

对于商品的上下线可调用商品状态变更接口，无需经过审核。

商品对接流程

过程如下图所示：

注意点

1、商品审核通过后，仍有可能在运营过程中再次改为审核不通过，此时会发送审核不通过的回调通知，开发者需注意处理这种case

2、商品信息编辑不会影响商品的上线/下线状态

3、商品审核未通过时，需重新调用“商品对接接口”同步商品信息

4、商品状态变更无需审核，开发者可自行控制商品的上线/下线状态

商品编辑流程细节

过程如下图所示：

注意点

1、商品编辑如果修改了需审字段，会生成审核单，此时线上的商品信息暂时不会变化。若审核通过，则覆盖线上的商品信息。若审核不通过，则保留原有的线上商品信息不变

2、商品信息编辑不会影响商品的上线/下线状态

1、 商品对接接口

项目	值
域名	https://open.kuaishou.com (opens new window)
接口说明	小程序申请挂载商品接口调用条件：商品首次上传/审核未通过重新上传
Path	/openapi/mp/developer/poi/service/product/mount
Method	POST

Request Param

参数名	类型	位置	是否必填	备注
component_app_id	string	request param	是	第三方应用id
authorizer_access_token	string	request paaram	是	小程序授权token

以下参数作为body发送

{
  "poi_id": "6724909500032869006", // 想要挂载的POI的id
  "product_id": "t12343", // 商品id
  "name": "盘古七星自助餐", // 商品名称
  "product_specific_category": 10101, // 商品类目代码
  "cover": "http://www.xxx.com/picture1.jpg", // 商品封面
  "path": "xxxxxx", // 卡片跳转路径
  "sell_expire_start_time": 240, // 商品售卖有效期，起止时间
  "sell_expire_end_time": 250, // 商品售卖有效期，截止时间
  "full_price": 25000, // 商品原价，单位分
  "discount_price": 20000, // 团购折扣价，单位分
  "refund_limit": 1, // 退款限制条件
  "reserve_limit": 1, // 预约限制条件
  "use_limit": 1, // 使用限制条件
  "sold_count": 200, // 销量
  "quality_labels" : [1,2],  //商品品质标签
  "marketing_labels" : ["国庆热销", "春节热卖"],  //商品营销活动标签
  "enable_promotion" : true,  //是否分销推广
  "promotion_commission_rate" : 500, //分销佣金比例，万分数，必须为整数
  "attach" : "type:MT",  //附加信息，由开发者自定义
  "notify_url": "http://www.open.kuaishou.com" // 回调地址，必选参数
}

body参数说明

参数名	类型	是否必填	备注
poi_id	string	是	要挂载的poiId
product_id	string	是	商品id 注意：app_id + poi_id + product_id 需要保证唯一
name	string	是	商品名称; 注意：不允许超过200个字符，一个汉字等于2个字符
product_specific_category	number	是	商品类目代码，参考商品类目对应表
cover	string	是	商品封面 注意：图片比例1:1
path	string	是	卡片跳转路径 注意：长度不超过1000
sell_expire_start_time	number	是	商品售卖有效起止时间戳，单位毫秒；0；表示永久有效eg：2021年10月18日0点0分0秒过期，则sell_expire_start_time=1634486400000 注意：起止日期 <= 截止日期
sell_expire_end_time	number	是	商品售卖有效截止时间戳，单位毫秒；0；表示永久有效eg：2021年10月20日0点0分0秒过期，则sell_expire_start_time=1634659200000 注意：起止日期 <= 截止日期
full_price	number	是	商品原价，单位：分
discount_price	number	是	商品团购折扣价，单位：分 注意：团购价 <= 原价，且团购价需大于0
refund_limit	number	是	退款限制条件；1：过期退-随时退，2：有条件退
reserve_limit	number	是	预约限制条件；1：免预约，2：需预约
use_limit	number	否	使用限制条件；1：周末节假日通用，2：周一至周五
sold_count	number	是	销量
quality_labels	number数组	否	商品品质标签，支持多选
marketing_labels	string数组	否	商品营销活动标签。 注意： 标签文案由开发者自定义，最大字数为7个字，仅支持中文字符，不支持特殊符号支持一个商品同时打多个标签，最多30个
enable_promotion	bool	否	是否分销推广，默认：不分销
promotion_commission_rate	number	否	分销佣金比例，万分数，必须为整数。如100表示佣金为万分之一百，即1% 。 注意：佣金比例＜2800，即佣金比例小于28%
attach	string	否	附加信息，会在回调通知时原样回传，详见小程序审核结果发送协议  注意：不允许超过200个字符
notify_url	string	是	审核结果推送地址，长度不允许超过200 详情见小程序审核结果发送协议

商品品质标签

值	含义
1	热卖/爆品
2	粉丝福利
3	超值
4	高佣商品

Response

{
    "result": 1, // 非1视为错误码，详见附录错误码
    "error_msg": "success", // 错误提示信息
    "data": {
        "auditId": "54edf507-1671-4fef-b8e8-de68a5e06413"
    }
}

2、 商品编辑接口

项目	值
域名	线上环境：https://open.kuaishou.com (opens new window)
接口说明	小程序商品编辑接口调用条件：商品处于上线/下线状态注：1、若上一次编辑仍处于审核中，则将覆盖上一次进审信息2、商品信息编辑不会影响当前商品的状态（上线/下线），编辑审核未通过时也不会影响商品本身状态
Path	/openapi/mp/developer/poi/service/product/update
Method	POST

Request Param

参数名	类型	位置	是否必填	备注
component_app_id	string	request param	是	第三方应用id
authorizer_access_token	string	request paaram	是	小程序授权token

以下参数作为body发送

推荐仅传需要更新的字段。

（即使传了需要进审的字段，若字段前后无变化，也不会触发审核。注：系统无法识别cover是否有变化，故只要传了cover字段就会触发进审。）

{
  "poi_id": "6724909500032869006", // 挂载的POI的id
  "product_id": "t12343", // 商品id
  "name": "盘古七星自助餐", // 商品名称
  "product_specific_category": 10101, // 商品类目代码
  "cover": "http://www.xxx.com/picture1.jpg", // 商品封面
  "path": "xxxxxx", // 卡片跳转路径
  "sell_expire_start_time": 240, // 商品售卖有效期，起止时间
  "sell_expire_end_time": 250, // 商品售卖有效期，截止时间
  "full_price": 25000, // 商品原价，单位分
  "discount_price": 20000, // 团购折扣价，单位分
  "refund_limit": 1, // 退款限制条件
  "reserve_limit": 1, // 预约限制条件
  "use_limit": 1, // 使用限制条件
  "sold_count": 200, // 已售数量
  "quality_labels" : [1,2],  //商品品质标签
  "marketing_labels" : ["国庆热销", "春节热卖"],  //商品营销活动标签
  "enable_promotion" : true,  //是否分销推广
  "promotion_commission_rate" : 500, //分销佣金比例，万分数，必须为整数
  "attach" : "type:MT",  //附加信息，由开发者自定义
  "notify_url": "http://www.open.kuaishou.com" // 回调地址
}

body参数说明

参数名	类型	是否必填	是否需要审核	备注
poi_id	string	是	非修改字段	挂载的poiId
product_id	string	是	非修改字段	商品id 注意：app_id + poi_id + product_id 需要保证唯一
name	string	否	是	商品名称; 注意：不允许超过200个字符，一个汉字等于2个字符
product_specific_category	number	否	是	商品类目代码，参考商品类目对应表
cover	string	否	是	商品封面 注意：图片比例1:1
path	string	否	是	卡片跳转路径
sell_expire_start_time	number	否	否	商品售卖有效起止时间戳，单位毫秒；0：表示永久有效eg：2021年10月18日0点0分0秒过期，则sell_expire_start_time=1634486400000 注意：起止日期 <= 截止日期
sell_expire_end_time	number	否	否	商品售卖有效截止时间戳，单位毫秒；0：表示永久有效eg：2021年10月20日0点0分0秒过期，则sell_expire_start_time=1634659200000 注意：起止日期 <= 截止日期
full_price	number	否	否	商品原价，单位：分
discount_price	number	否	否	商品团购折扣价，单位：分
refund_limit	number	否	否	退款限制条件；1：过期退-随时退，2：有条件退
reserve_limit	number	否	否	预约限制条件；1：免预约，2：需预约
use_limit	number	否	否	使用限制条件；1：周末节假日通用，2：周一至周五
sold_count	number	否	否	已售数量
quality_labels	number数组	否	否	商品品质标签，支持多选 注：若传了 quality_labels:[] 则代表将标签更新为空数组。
marketing_labels	string数组	否	否	商品营销活动标签。 注意： 标签文案由开发者自定义，最大字数为7个字，仅支持中文字符，不支持特殊符号 支持一个商品同时打多个标签，最多30个 若传了 marketing_labels:[] 则代表将标签更新为空数组。
enable_promotion	bool	否	否	是否分销推广
promotion_commission_rate	number	否	否	分销佣金比例，万分数，必须为整数。如100表示佣金为万分之一百，即1% 。 注意：佣金比例＜2800，即佣金比例小于28%
attach	string	否	否	附加信息，会在回调通知时原样回传，详见小程序审核结果发送协议。不传则默认附加原attach信息，若修改成功，则作为之后的默认attach信息注意：不允许超过200个字符
notify_url	string	否	否	审核结果推送地址，长度不允许超过200。不传则默认按原回调地址回调，若修改成功，则作为之后的默认回调地址详情见小程序审核结果发送协议

Response

{
    "result": 1, // 非1视为错误码，详见附录错误码
    "error_msg": "success", // 错误提示信息
      "data" : {
          "needAudit" : true,  //是否需要审核，如果为true，则审核结果会推送到notify_url
          "auditId": "727c68b2-6ada-4358-8379-0a67a81085ba"
    }
}

3、 商品状态变更接口

项目	值
域名	线上环境：https://open.kuaishou.com (opens new window)
接口说明	商品上线/下线接口调用条件：商品是上线/下线状态注：接口是幂等的，即多次调用下线接口，最终仍为下线状态
Path	/openapi/mp/developer/poi/service/product/status/update
Method	POST

Request Param

参数名	类型	是否必填	备注
component_app_id	string	是	第三方应用id
authorizer_access_token	string	是	小程序授权token

以下参数作为body发送

{
  "poi_id": "6724909500032869006", // 想要挂载的POI的id
  "product_id": "t12343", // 商品id
  "status": 1  //更新的状态，1：上线，0：下线
}

body参数说明

参数名	类型	是否必填	备注
poi_id	string	是	要挂载的poiId
product_id	string	是	商品id
status	number	是	更新的状态，1：上线，0：下线

Response

{
    "result": 1, // 非1视为错误码，详见错误码说明
    "error_msg": "success", // 错误提示信息
}

4、 商品审核状态查询接口

项目	值
域名	线上环境：https://open.kuaishou.com (opens new window)
接口说明	小程序商品挂载状态查询接口
Path	/openapi/mp/developer/poi/product/service/status
Method	POST

Request Param

参数名	类型	位置	是否必填	备注
component_app_id	string	request param	是	服务商id
authorizer_access_token	string	request param	是	小程序授权token

以下参数作为body发送

{
  "param": [{
      "poi_id":"6724909438339477816",
      "product_id":"product77"
  },{
      "poi_id":"6724909430998709296",
      "product_id":"product78"
  }]
}

body参数说明

参数名	类型	是否必填	备注
poi_id	string	是	要挂载的poiId
product_id	string	是	商品id 注：一次查询不可超过20个

Response

正常情况

{
    "result": 1, // 非1视为错误码，详见附录错误码
    "error_msg": "success", // 错误提示信息
      "data": [{
        "appId": "ks682576822728817112",
        "poiId": "6724909438339477816",
        "productId": "product77",
        "status": "REJECT",  // DEFAULT:待审核 PASSED:通过(上线) REJECT:拒绝 OFFLINE:下线
        "latestEditStatus": "PASSED",
        "latestEditAuditId": "33e1ed0a-2a0c-4a7b-94e0-eb488d87caa6",
        "reason": "",
        "code": 1,  //code为1代表正常返回
        "message": ""
    },{
        "appId": "ks682576822728817112",
        "poiId": "6724909430998709296",
        "status": "PASSED",  // DEFAULT:待审核 PASSED:通过(上线) REJECT:拒绝 OFFLINE:下线
        "latestEditStatus": "PASSED",
        "latestEditAuditId": "33e1ed0a-2a0c-4a7b-94e0-eb488d87caa6",
        "reason": "",
        "code": 1,  //code为1代表正常返回
        "message": "",
        "productId": "product78"
    }]
}

部分数据异常情况

{
    "result": 1, // 非1视为错误码，详见错误码说明
    "error_msg": "success", // 错误提示信息
      "data": [{
        "appId": "ks682576822728817112",
        "poiId": "6724909430998709296",
        "productId": "product79",
        "status": "",
        "reason": "",
        "code": 10002005,  //code非1表示异常，详见错误码说明
        "message": "poi_id不存在,请确认请求的poi_id是否挂载过",
    },{
        "appId": "ks682576822728817112",
        "poiId": "300218552458160511",
        "productId": "product80",
        "status": "",
        "reason": "",
        "code": 10000200,  //code非1表示异常，详见错误码说明
        "message": "poiId 长度不正确",
    }]
}