创建自定义入口

更新时间：2024.09.20

接口介绍：该接口为电子小票自定义入口创建接口，商家可以通过该接口为品牌创建自定义入口展示内容。

接口说明

支持商户：【普通商户】

请求方式：【POST】/v3/marketing/shopping-receipt/customentrances

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引点击查看

请求参数

Header HTTP头参数

Authorization 　必填　string

请参考签名认证生成认证信息

Accept 　必填　string

请设置为application/json

Content-Type 　必填　string

请设置为application/json

body 包体参数

custom_entrance_type 　必填 string

【自定义入口种类】自定义入口种类。种类为商家小程序，主标题展示的字为“商家小程序”，种类为商家活动，主标题展示的字为“商家活动”。

可选取值：

MERCHANT_ACTIVITY: 自定义入口为商家活动

MERCHANT_MINI_PROGRAM: 自定义入口为商家小程序

subtitle 　必填 string(10)

【副标题】副标题，辅助描述商家活动或商家小程序信息。

goods_thumbnail_url 　选填 string(256)

【商品缩略图URL】展示商品信息，当自定义入口种类为商家活动时，该字段必填，种类为商家小程序该字段不填。仅支持通过《图片上传API》接口获取的图片URL地址。大小需要满足42*42px，格式仅支持png、jpg。

start_time 　必填 string(32)

【入口展示开始时间】自定义入口的开始时间。需要大于当前时间，且小于结束时间。遵循rfc3339标准格式，格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE，YYYY-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日13点29分35秒。

end_time 　必填 string(32)

【入口展示结束时间】自定义入口的结束时间。需要大于开始时间，最长可以配置180天内的活动。遵循rfc3339标准格式，格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE，YYYY-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日13点29分35秒。

custom_entrance_state 　必填 string

【自定义入口状态】设置自定义入口的状态，在线对用户展示，下线对用户不展示

可选取值：

ONLINE: 当前自定义入口对用户展示

OFFLINE: 当前自定义入口对用户不展示

brand_id 　必填 string(16)

【品牌ID】自定义入口的归属品牌ID。创建者需要是该品牌的品牌服务商或品牌主。

out_request_no 　必填 string(128)

【请求业务单据号】商户创建自定义入口的凭据号（格式：商户ID+日期+流水号），商家侧需要保持唯一且递增

jump_link 　必填 object

【跳转信息】自定义入口跳转信息

属性

请求示例

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/marketing/shopping-receipt/customentrances \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "custom_entrance_type" : "MERCHANT_ACTIVITY",
8    "subtitle" : "双十一8折活动",
9    "goods_thumbnail_url" : "https://qpic.cn/xxx",
10    "start_time" : "2015-05-20T13:29:35+08:00",
11    "end_time" : "2015-05-20T13:29:35+08:00",
12    "custom_entrance_state" : "ONLINE",
13    "brand_id" : "1014",
14    "out_request_no" : "6122352020010133287985742",
15    "jump_link" : {
16      "mini_programs_appid" : "wxea9c30a90fs8d3fe",
17      "mini_programs_path" : "/pages/bonus/bonus"
18    }
19  }'
20

应答参数

200 OK

custom_entrance_type 　必填 string

【自定义入口种类】自定义入口种类。种类为商家小程序，主标题展示的字为“商家小程序”，种类为商家活动，主标题展示的字为“商家活动”。

可选取值：

MERCHANT_ACTIVITY: 自定义入口为商家活动

MERCHANT_MINI_PROGRAM: 自定义入口为商家小程序

subtitle 　必填 string(10)

【副标题】副标题，辅助描述商家活动或商家小程序信息。

goods_thumbnail_url 　选填 string(256)

custom_entrance_state 　必填 string

【自定义入口状态】设置自定义入口的状态，在线对用户展示，下线对用户不展示

可选取值：

ONLINE: 当前自定义入口对用户展示

OFFLINE: 当前自定义入口对用户不展示

start_time 　必填 string(32)

end_time 　必填 string(32)

brand_id 　必填 string(16)

【品牌ID】自定义入口的归属品牌ID。

create_time 　必填 string(128)

【创建时间】自定义入口创建的时间，遵循rfc3339标准格式，格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE，YYYY-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日13点29分35秒。

modify_time 　必填 string(128)

【修改时间】自定义入口修改的时间，遵循rfc3339标准格式，格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE，YYYY-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35+08:00表示，北京时间2015年5月20日13点29分35秒。

out_request_no 　必填 string(128)

【请求业务单据号】商户创建自定义入口的凭据号（格式：商户ID+日期+流水号），商家侧需要保持唯一且递增

jump_link 　必填 object

【跳转信息】自定义入口跳转信息

属性

应答示例

200 OK

1{
2  "custom_entrance_type" : "MERCHANT_ACTIVITY",
3  "subtitle" : "双十一8折活动",
4  "goods_thumbnail_url" : "https://qpic.cn/xxx",
5  "custom_entrance_state" : "ONLINE",
6  "start_time" : "2015-05-20T13:29:35+08:00",
7  "end_time" : "2019-12-31T13:29:35.120+08:00",
8  "brand_id" : "1014",
9  "create_time" : "2015-05-20T13:29:35+08:00",
10  "modify_time" : "2015-05-20T13:29:35+08:00",
11  "out_request_no" : "100002322019090134234sfdf",
12  "jump_link" : {
13    "mini_programs_appid" : "wxea9c30a90fs8d3fe",
14    "mini_programs_path" : "/pages/bonus/bonus"
15  }
16}
17

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
400	INVALID_REQUEST	无效请求	请根据接口返回的详细信息检查
500	SYSTEM_ERROR	系统错误	请使用相同参数稍后重新调用

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服