# 查询与设置授权页与商户信息
接口应在服务器端调用,不可在前端(小程序、网页、APP等)直接调用,具体可参考接口调用指南
接口英文名:invoicebizsetattr
本接口提供了一系列用于管理授权页和商户信息的功能:
授权页字段管理:
- set_auth_field:用于设置type=1类型授权页上用户需要填写的信息,设置为一次性,除非需要调整字段。
- get_auth_field:用于查询授权页的字段设置情况。
商户与开票平台关联管理:
- set_pay_mch:用于将商户号与开票平台的识别号进行关联,设置为一次性,除非识别号变更或更换开票平台。
- get_pay_mch:用于查询商户与开票平台的绑定情况。 商户联系方式管理:
- set_contact:用于在获取授权链接之前设置商户的联系方式。
- get_contact:用于获取商户的联系方式。
这些接口通过get参数来决定具体的用法,适用于不同的场景和需求,具体参数和适用场景如下
Action | 描述 | 备注 |
---|---|---|
set_auth_field | 设置授权页上需要用户填写的信息。仅适用于type=1的授权页(若使用type=0或type=2类型的授权页,无需调用本接口)。此设置为一次性,除非需要调整页面字段。 | 当使用type=1类型的授权页时,设置为显示状态的字段均为必填字段,若不填写将无法进入后续流程。 |
get_auth_field | 查询授权页的字段设置情况。 | 商户需要了解当前授权页的字段设置情况时使用。 |
set_pay_mch | 商户使用支付后开票,需要先将自身的商户号和开票平台的识别号进行关联,开票平台识别号由开票平台根据微信规则生成后告知商户。本接口为一次性设置,后续一般在遇到开票平台识别号变更,或者商户更换开票平台时才需要调用本接口重设对应关系。 | 若商户已经实现电子发票的微信卡包送达方案,调用本接口前,建议在微信支付商户平台中确认商户号所绑定的公众号和拉起授权页的公众号是同一个。若不是同一个,仍需重新使用商户号所绑定公众号去调通拉取授权页的接口。 |
get_pay_mch | 查询商户与开票平台的绑定情况。 | 商户需要了解当前与开票平台的绑定情况时使用。 |
set_contact | 设置商户的联系方式。 | 商户在获取授权链接之前,需先设置联系方式。 |
get_contact | 获取商户的联系方式。 | 商户需要了解当前设置的联系方式时使用。 |
# 1. 调用方式
# HTTPS 调用
POST https://api.weixin.qq.com/card/invoice/setbizattr?access_token=ACCESS_TOKEN&action=ACTION
# 云调用
- 本接口不支持云调用
# 第三方调用
本接口支持第三方平台代商家调用。
该接口所属的权限集 id 为:26
服务商获得其中之一权限集授权后,可通过使用 authorizer_access_token 代商家进行调用,具体可查看 第三方调用 说明文档。
# 2. 请求参数
# 查询参数 Query String parameters
参数名 | 类型 | 必填 | 示例 | 说明 |
---|---|---|---|---|
access_token | string | 是 | ACCESS_TOKEN | 接口调用凭证,可使用 access_token、authorizer_access_token |
action | string | 是 | set_auth_field | 接口功能类型,需填写允许的 action,当为 get_auth_field、get_pay_mch 时,请求体为空(传JSON格式{}) |
# 请求体 Request Payload
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
auth_field | object | 是 | 授权页字段(set_auth_field使用) |
paymch_info | object | 是 | 微信商户号与开票平台关系信息(set_pay_mch使用) |
contact | object | 是 | 联系方式信息(set_contact使用) |
# Body.auth_field Object Payload
授权页字段(set_auth_field使用)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
user_field | object | 是 | 授权页个人发票字段 |
biz_field | object | 是 | 授权页单位发票字段 |
# Body.paymch_info Object Payload
微信商户号与开票平台关系信息(set_pay_mch使用)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
mchid | string | 是 | 微信支付商户号 |
s_pappid | string | 是 | 为该商户提供开票服务的开票平台 id ,由开票平台提供给商户 |
# Body.contact Object Payload
联系方式信息(set_contact使用)
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
time_out | number | 是 | 开票超时时间 |
phone | string | 是 | 联系电话 |
# Body.auth_field.user_field Object Payload
授权页个人发票字段
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
show_title | number | 否 | 是否填写抬头,0为否,1为是 |
show_phone | number | 否 | 是否填写电话号码,0为否,1为是 |
show_email | number | 否 | 是否填写邮箱,0为否,1为是 |
require_phone | number | 否 | 电话号码是否必填,0为否,1为是 |
require_email | number | 否 | 邮箱是否必填,0位否,1为是 |
custom_field | objarray | 否 | 自定义字段 |
# Body.auth_field.user_field.custom_field(Array) Object Payload
自定义字段
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
key | string | 是 | 字段名 |
is_require | number | 否 | 0:否,1:是, 默认为0 |
notice | string | 否 | 提示文案 |
# Body.auth_field.biz_field Object Payload
授权页单位发票字段
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
show_title | number | 否 | 是否填写抬头,0为否,1为是 |
show_tax_no | number | 否 | 是否填写税号,0为否,1为是 |
show_addr | number | 否 | 是否填写单位地址,0为否,1为是 |
show_phone | number | 否 | 是否填写电话号码,0为否,1为是 |
show_bank_type | number | 否 | 是否填写开户银行,0为否,1为是 |
show_bank_no | number | 否 | 是否填写银行账号,0为否,1为是 |
require_tax_no | number | 否 | 税号是否必填,0为否,1为是 |
require_addr | number | 否 | 单位地址是否必填,0为否,1为是 |
require_phone | number | 否 | 电话号码是否必填,0为否,1为是 |
require_bank_type | number | 否 | 开户行是否必填,0为否,1为是 |
require_bank_no | number | 否 | 银行账号是否必填,0为否,1为是 |
require_tax_no | number | 否 | 税号是否必填,0为否,1为是 |
custom_field | objarray | 否 | 自定义字段 |
# Body.auth_field.biz_field.custom_field(Array) Object Payload
自定义字段
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
key | string | 是 | 字段名 |
is_require | number | 否 | 0:否,1:是, 默认为0 |
notice | string | 否 | 提示文案 |
# 3. 返回参数
# 返回体 Response Payload
参数名 | 类型 | 说明 |
---|---|---|
errcode | number | 错误码 |
errmsg | string | 错误描述 |
auth_field | object | 授权页字段(set_auth_field、get_auth_field返回) |
paymch_info | object | 微信商户号与开票平台关系信息(get_pay_mch返回) |
contact | object | 联系方式信息(get_contact返回) |
# Res.auth_field Object Payload
授权页字段(set_auth_field、get_auth_field返回)
参数名 | 类型 | 说明 |
---|---|---|
user_field | object | 授权页个人发票字段 |
biz_field | object | 授权页单位发票字段 |
# Res.paymch_info Object Payload
微信商户号与开票平台关系信息(get_pay_mch返回)
参数名 | 类型 | 说明 |
---|---|---|
mchid | string | 微信支付商户号 |
s_pappid | string | 为该商户提供开票服务的开票平台 id ,由开票平台提供给商户 |
# Res.contact Object Payload
联系方式信息(get_contact返回)
参数名 | 类型 | 说明 |
---|---|---|
time_out | number | 开票超时时间 |
phone | string | 联系电话 |
# Res.auth_field.user_field Object Payload
授权页个人发票字段
参数名 | 类型 | 说明 |
---|---|---|
show_title | number | 是否填写抬头,0为否,1为是 |
show_phone | number | 是否填写电话号码,0为否,1为是 |
show_email | number | 是否填写邮箱,0为否,1为是 |
require_phone | number | 电话号码是否必填,0为否,1为是(仅 get_auth_field返回) |
require_email | number | 邮箱是否必填,0位否,1为是(仅 get_auth_field返回) |
custom_field | objarray | 自定义字段 |
# Res.auth_field.user_field.custom_field(Array) Object Payload
自定义字段
参数名 | 类型 | 说明 |
---|---|---|
key | string | 字段名 |
is_require | number | 0:否,1:是, 默认为0 |
notice | string | 提示文案 |
# Res.auth_field.biz_field Object Payload
授权页单位发票字段
参数名 | 类型 | 说明 |
---|---|---|
show_title | number | 是否填写抬头,0为否,1为是 |
show_tax_no | number | 是否填写税号,0为否,1为是 |
show_addr | number | 是否填写单位地址,0为否,1为是 |
show_phone | number | 是否填写电话号码,0为否,1为是 |
show_bank_type | number | 是否填写开户银行,0为否,1为是 |
show_bank_no | number | 是否填写银行账号,0为否,1为是 |
require_tax_no | number | 税号是否必填,0为否,1为是(仅 get_auth_field返回) |
require_addr | number | 单位地址是否必填,0为否,1为是(仅 get_auth_field返回) |
require_phone | number | 电话号码是否必填,0为否,1为是(仅 get_auth_field返回) |
require_bank_type | number | 开户行是否必填,0为否,1为是(仅 get_auth_field返回) |
require_bank_no | number | 银行账号是否必填,0为否,1为是(仅 get_auth_field返回) |
require_tax_no | number | 税号是否必填,0为否,1为是(仅 get_auth_field返回) |
custom_field | objarray | 自定义字段 |
# Res.auth_field.biz_field.custom_field(Array) Object Payload
自定义字段
参数名 | 类型 | 说明 |
---|---|---|
key | string | 字段名 |
is_require | number | 0:否,1:是, 默认为0 |
notice | string | 提示文案 |
# 4. 注意事项
本接口无特殊注意事项
# 5. 代码示例
# 5.1 设置授权页字段信息
请求示例
https://api.weixin.qq.com/card/invoice/setbizattr?action=set_pay_mch&access_token={access_token}
{
"auth_field" : {
"user_field" : {
"require_phone" : 1,
"custom_field" : [
{
"is_require" : 1,
"key" : "field1"
}
],
"show_email" : 1,
"show_title" : 1,
"show_phone" : 1,
"require_email" : 1
},
"biz_field" : {
"require_phone" : 0,
"custom_field" : [
{
"is_require" : 0,
"key" : "field2"
}
],
"require_bank_type" : 0,
"require_tax_no" : 0,
"show_addr" : 1,
"require_addr" : 0,
"show_title" : 1,
"show_tax_no" : 1,
"show_phone" : 1,
"show_bank_type" : 1,
"show_bank_no" : 1,
"require_bank_no" : 0
}
}
}
返回示例
{
"errcode": 0,
"errmsg": "ok"
}
# 5.2 查询授权页字段信息
请求示例
https://api.weixin.qq.com/card/invoice/setbizattr?action=get_pay_mch&access_token={access_token}
{}
返回示例
{
"errcode": 0,
"errmsg": "ok",
"auth_field": {
"user_field": {
"show_title": 1,
"show_phone": 1,
"show_email": 1,
"custom_field": [{"key": "field1"}]
},
"biz_field": {
"show_title": 1,
"show_tax_no": 1,
"show_addr": 1,
"show_phone": 1,
"show_bank_type": 1,
"show_bank_no": 1,
"custom_field": [{"key": "field2"}]
}
}
}
# 5.3 关联商户号与开票平台
请求示例
https://api.weixin.qq.com/card/invoice/setbizattr?action=set_pay_mch&access_token={access_token}
{
"paymch_info": {
"mchid": "1234",
"s_pappid": "wxabcd"
}
}
返回示例
{
"errcode": 0,
"errmsg": "ok"
}
# 5.4 查询商户号与开票平台关联情况
请求示例
https://api.weixin.qq.com/card/invoice/setbizattr?action=get_pay_mch&access_token={access_token}
{}
返回示例
{
"errcode": 0,
"errmsg": "ok",
"paymch_info":
{
"mchid": "1234",
"s_pappid": "wxabcd"
}
}
# 5.5 设置商户联系方式
请求示例
https://api.weixin.qq.com/card/invoice/setbizattr?action=set_contact&access_token={access_token}
{
"contact" :
{
"phone" : "88888888",
"time_out" : 12345
}
}
返回示例
{
"errcode": 0,
"errmsg": "ok"
}
# 5.6 查询商户联系方式
请求示例
https://api.weixin.qq.com/card/invoice/setbizattr?action=get_contact&access_token={access_token}
{}
返回示例
{
"contact" : {
"phone" : "88888888",
"time_out" : 12345
},
"errcode" : 0,
"errmsg" : "ok"
}
# 6. 错误码
以下是本接口的错误码列表,其他错误码可参考 通用错误码
错误码 | 错误描述 | 解决方案 |
---|---|---|
40078 | invalid card status | card_id 未授权。 若开发者使用沙箱环境报此错误,主要因为未将调用接口的微信添加到测试把名单; 若开发者使用正式环境报此错误,主要原因可能为:调用接口公众号未开通卡券权限,或创建 card_id 与插卡时间间隔过短。 |
40097 | invalid args | type参数值不符预期 |
72015 | unauthorized create invoice | 没有操作权限,请检查是否已开通相应权限。 |
72017 | invalid invoice title | 发票抬头不一致 |
72023 | invoice has been lock by others | 发票已被其他公众号锁定。一般为发票已进入后续报销流程,报销企业公众号/企业号/App锁定了发票。 |
72024 | invoice status error | 发票状态错误 |
72025 | invoice token error | wx_invoice_token 无效 |
72028 | invoice never set pay mch info | 未设置微信支付商户信息 |
72029 | invoice never set auth field | 未设置授权字段 |
72030 | invalid mchid | mchid 无效 |
72031 | invalid params | 参数错误。可能为请求中包括无效的参数名称或包含不通过后台校验的参数值 |
72035 | biz reject insert | 财政电子票据已经被拒绝领取。若 order_id 被用作参数调用过拒绝领取接口,再使用此 order_id 插卡机会报此错误 |
72036 | invoice is busy | 财政电子票据正在被修改状态,请稍后再试 |
72038 | invoice order never auth | 订单没有授权,可能是财政局的s_pappid 、执收单位 appid 、订单 order_id 不匹配 |
72039 | invoice must be lock first | 订单未被锁定 |
72040 | invoice pdf error | Pdf 无效,请提供真实有效的 pdf |
72042 | billing_code and billing_no repeated | 票据号码和票据代码重复 |
72043 | billing_code or billing_no size error | 票据号码和票据代码错误 |
72044 | scan text out of time | 发票抬头二维码超时 |
72063 | biz contact is empty | 商户联系方式未空,请先调用接口设置商户联系方式 |
73000 | sys error make out invoice failed | 开票平台逻辑错误 |
73001 | wxopenid error | OpenId错误 |
73002 | ddh orderid empty | 订单号为空 |
73003 | fpqqlsh empty | 发票流水号为空 |
73004 | kplx empty | 发票流水号为空 |
73007 | nsrmc empty | 纳税人名称为空 |
73008 | nsrdz empty | 纳税人地址为空 |
73009 | nsrdh empty | 纳税人电话为空 |
73010 | ghfmc empty | 购货方名称为空 |
73011 | kpr empty | 开票人为空 |
73012 | jshj empty | 计税合计为空 |
73013 | hjje empty | 合计金额为空 |
73014 | hjse empty | 合计税额为空 |
73015 | hylx empty | 行业类型为空 |
73016 | nsrsbh empty | 纳税人识别号为空 |
73100 | ka plat error | 开票平台错误 |
73101 | nsrsbh not cmp | 纳税人识别号不匹配,请求中的纳税人识别号和创建工单填写的纳税人识别号不一致 |
73102 | sys error | 微信开票平台系统错误 |
73105 | Kp plat make invoice timeout, please try again with the same fpqqlsh | 开票平台开票中,请使用相同的发票请求流水号重试开票 |
73106 | Fpqqlsh exist with different ddh | 发票请求流水号已存在,并被其他订单号占用 |
73107 | Fpqqlsh is processing, please wait and query later | 发票请求流水正在被处理,请通过查询接口获取结果 |
73108 | This ddh with other fpqqlsh already exist | 该订单已被其他发票请求流水处理 |
73110 | fpqqlsh first 6 byte not cmp | 发票请求流水号前6位不正确 |
# 7. 适用范围
本接口在不同账号类型下的可调用情况:
公众号 | 服务号 |
---|---|
✔ | ✔ |
- ✔:该账号可调用此接口
- 其他未明确声明的账号类型,如无特殊说明,均不可调用此接口;