# 商品对接

更新时间:2024-05-21 17:48:36

# 接口说明

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

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

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

# 商品对接流程

过程如下图所示:

img

# 注意点

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

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

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

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

# 商品编辑流程细节

过程如下图所示:

img

# 注意点

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_idstring要挂载的poiId
product_idstring

商品id

注意:app_id + poi_id + product_id 需要保证唯一

namestring

商品名称;

注意:不允许超过200个字符,一个汉字等于2个字符

product_specific_categorynumber商品类目代码,参考商品类目对应表
coverstring

商品封面

注意:图片比例1:1

pathstring

卡片跳转路径

注意:长度不超过1000

sell_expire_start_timenumber

商品售卖有效起止时间戳,单位毫秒;0;表示永久有效eg:2021年10月18日0点0分0秒过期,则sell_expire_start_time=1634486400000

注意:起止日期 <= 截止日期

sell_expire_end_timenumber

商品售卖有效截止时间戳,单位毫秒;0;表示永久有效eg:2021年10月20日0点0分0秒过期,则sell_expire_start_time=1634659200000

注意:起止日期 <= 截止日期

full_pricenumber商品原价,单位:分
discount_pricenumber

商品团购折扣价,单位:分

注意:团购价 <= 原价,且团购价需大于0

refund_limitnumber退款限制条件;1:过期退-随时退,2:有条件退
reserve_limitnumber预约限制条件;1:免预约,2:需预约
use_limitnumber使用限制条件;1:周末节假日通用,2:周一至周五
sold_countnumber销量
quality_labelsnumber数组商品品质标签,支持多选
marketing_labelsstring数组

商品营销活动标签。

注意:

标签文案由开发者自定义,最大字数为7个字,仅支持中文字符,不支持特殊符号支持一个商品同时打多个标签,最多30个

enable_promotionbool是否分销推广,默认:不分销
promotion_commission_ratenumber

分销佣金比例,万分数,必须为整数。如100表示佣金为万分之一百,即1% 。

注意:佣金比例<2800,即佣金比例小于28%

attachstring

附加信息,会在回调通知时原样回传,详见小程序审核结果发送协议 

注意:不允许超过200个字符

notify_urlstring

审核结果推送地址,长度不允许超过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_idstring非修改字段挂载的poiId
product_idstring非修改字段

商品id

注意:app_id + poi_id + product_id 需要保证唯一

namestring

商品名称;

注意:不允许超过200个字符,一个汉字等于2个字符

product_specific_categorynumber商品类目代码,参考商品类目对应表
coverstring

商品封面

注意:图片比例1:1

pathstring卡片跳转路径
sell_expire_start_timenumber

商品售卖有效起止时间戳,单位毫秒;0:表示永久有效eg:2021年10月18日0点0分0秒过期,则sell_expire_start_time=1634486400000

注意:起止日期 <= 截止日期

sell_expire_end_timenumber

商品售卖有效截止时间戳,单位毫秒;0:表示永久有效eg:2021年10月20日0点0分0秒过期,则sell_expire_start_time=1634659200000

注意:起止日期 <= 截止日期

full_pricenumber商品原价,单位:分
discount_pricenumber商品团购折扣价,单位:分
refund_limitnumber退款限制条件;1:过期退-随时退,2:有条件退
reserve_limitnumber预约限制条件;1:免预约,2:需预约
use_limitnumber使用限制条件;1:周末节假日通用,2:周一至周五
sold_countnumber已售数量
quality_labelsnumber数组

商品品质标签,支持多选

注:若传了 quality_labels:[] 则代表将标签更新为空数组。

marketing_labelsstring数组

商品营销活动标签。

注意:

  1. 标签文案由开发者自定义,最大字数为7个字,仅支持中文字符,不支持特殊符号
  2. 支持一个商品同时打多个标签,最多30个
  3. 若传了 marketing_labels:[] 则代表将标签更新为空数组。
enable_promotionbool是否分销推广
promotion_commission_ratenumber

分销佣金比例,万分数,必须为整数。如100表示佣金为万分之一百,即1% 。

注意:佣金比例<2800,即佣金比例小于28%

attachstring附加信息,会在回调通知时原样回传,详见小程序审核结果发送协议。不传则默认附加原attach信息,若修改成功,则作为之后的默认attach信息注意:不允许超过200个字符
notify_urlstring审核结果推送地址,长度不允许超过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_idstring要挂载的poiId
product_idstring商品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 长度不正确",
    }]
}
Copyright ©2024, All Rights Reserved