# 商品对接
更新时间：2024-05-21 17:48:36
# 接口说明
获取挂载权限后，申请商品对接 ，商品需要经过审核。审核结果的通知机制为：通过回调地址回调结果，也可支持通过审核状态查询接口主动查询 。
对于审核通过的商品可通过商品编辑接口进行商品信息的编辑，需要注意，商品信息包含分销字段时（ 为分销商品 、包含佣金字段） ，对于分销佣金/比例的变更需要当日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.kuaishou.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.kuaishou.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数组 | 否 | 否 | 商品营销活动标签。 注意：
|
| 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 长度不正确",
}]
}