开发 行业对接说明 本地生活业务对接 对接说明 服务商对接 商品对接
# 商品对接
更新时间: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 长度不正确",
}]
}