电子发票开票平台接口文档(beta1 -...
TRANSCRIPT
-
电子发票开票平台接口文档(beta1.0)
2016/11/27
微信发票团队
-
更新日志
更新日期 说明
2016/11/15 1. 支持发票平台为商户创建发票
2. 支持发票平台对授权成功的订单进行插卡
3. 支持发票平台接收发票状态变更、支持发票平台主
动将发票状态同步至微信侧
2016/11/27 1. 优化了一些描述
2. 修复了一些描述错误
[注意事项]
开发者在接入前须先阅读【微信公众平台开发文档:mp.weixin.qq.com/wiki】,
以熟悉基本的技术术语和开发规范。
-
目录
电子发票开票平台接口文档(beta1.0) .............................................................................. 1
1、 接入指引 ....................................................................................................................... 4
2、电子发票流程图 .............................................................................................................. 5
3、创建发票接口 .................................................................................................................. 6
4、获取授权链接接口 ........................................................................................................ 11
5、将发票插入用户卡包 ..................................................................................................... 13
6、检查 wx_invoice_token ................................................................................................. 18
7、状态更新事件推送 ........................................................................................................ 22
8、主动更新发票状态接口 ................................................................................................. 23
9、备注 .............................................................................................................................. 25
9.1、错误码 ................................................................................................................ 28
9.2、发票报销状态 ..................................................................................................... 29
9.3、发票跳转链接协议 .............................................................................................. 29
9.4、解码 code 接口 ................................................................................................... 29
-
1、 接入指引
目前发票平台角色较少,对于有资质的发票平台,请发送以下格式申请到官方指定邮箱
公司名称 业务描述 公司地址 相关资质证
明
联 系 电
话
接口人 开票平台
appid
若没有则填
无
填入测试
appid 和正
式 appid
-
2、电子发票流程图
电子发票流程涉及用户、商户、报销方、发票平台和公众平台五个角色。
其中发票平台承担着为商户制作发票、将发票插入用户卡包以及报销状态更新的关键作用。
发票平台报销方商户 公众平台用户
用户到商户开发票
获取授权链接
返回授权链接
返回授权页面
用户打开授权页,点击授权
推送用户授权消息
商户到开票平台开票
开票平台将用户发票插入到卡包
将发票插入到用户的卡包,并且推送服务通知
用户到报销方报销
报销方调用发票jsapi
返回发票列表
用户选择发票
返回发票cardid和encrypted_code
报销方获取发票信息
返回发票信息
报销方去开票平台获取发票pdf
开票平台去公众平台验token
返回验token结果
返回发票pdf
报销方去公众平台锁定或核销发票
核销用户发票
推送发票状态更新消息
如果开票平台发票状态有更新,
需要在公众平台同步发票状态
用户授权开发票
商户开发票
用户报销
-
3、创建发票接口
接口说明
发票平台可以通过这个接口可以帮助商户创建一张发票模板
请求方式
url:
https://api.weixin.qq.com/card/invoice/platform/createcard?access_token={access_token}
method:post
数据格式:post
发票示例
-
请求参数
发票 invoice_info 字段
参数 类型 是否必填 描述
base_info Object 是 发票信息
payee string 是 收款方(开票方)全称,显示在发票详情内
detail String 是 发票详情字段,预留字段,建议填入发票使用说明
type String 是 发票类型
base_info 字段
参数 类型 是 否 必
填
描述
-
logo_url String 是 发票商家 LOGO,请参考上传图片接口
brand_name string 是 发票类型,填写广东增值税普通发票等,上限为
12 个汉字
title String 是 收款方(显示在列表),上限为 9 个汉字,建
议填入商户简称
description String 是 发票使用说明。可以介绍电子发票的背景、报
销使用流程等
custom_url_name String 否 发票平台自定义入口名称,与 custom_url 字段
共同使用,长度限制在 5 个汉字内
custom_url String 否 发票平台自定义入口跳转外链的地址链接, 发
票外跳的链接会带有发票参数,用于标识是从
那张发票跳出的链接,详情请见备注 9.3。
custom_url_sub_title String 否 显示在入口右侧的 tips,长度限制在 6 个汉字
内
promotion_url_name String 否 营销场景的自定义入口
promotion_url String 否 入口跳转外链的地址链接,发票外跳的链接会
带有发票参数,用于标识是从那张发票跳出的
链接,详情请见备注 9.3。
promotion_url_sub_title String 否 显示在入口右侧的 tips,长度限制在 6 个汉字
内
http://mp.weixin.qq.com/wiki/8/b7e310e7943f7763450eced91fa793b0.html#.E6.AD.A5.E9.AA.A4.E4.B8.80.EF.BC.9A.E4.B8.8A.E4.BC.A0.E5.8D.A1.E5.88.B8LOGO
-
返回参数
参数 类型 描述
errcode Int 错误码
errmsg String 错误信息
当错误码为 0 是,有以下信息:
参数 类型 描述
card_id String 发票 card_id
请求示例
请求:
{
"invoice_info": {
"base_info": {
"logo_url":
"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxib
MLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
"brand_name": "测试-发票",
"title": "测试-发票",
"description": "des",
"custom_url_name": "xyz",
-
"custom_url": "xyz",
"custom_url_sub_title": "xyz",
"promotion_url_name": "puname",
"promotion_url": "purl",
"promotion_url_sub_title": "ptitle",
},
"type": "广东省增值税普通发票",
"payee": "测试-收款方",
"detail": "测试-detail"
}
}
返回:
{
"errcode": 0,
"errmsg": "ok",
"card_id": "pjZ8Yt9WoOePThU0NfUKz5-tBEWU"
}
-
4、获取发票平台授权链接接口
接口说明
发票平台可以通过此接口获得本发票平台的预开票 url,获取 s_appid,并透传给商户,
商户可以通过该 s_appid 参数指定提供开票服务的开票平台。
请求方式
Url https://api.weixin.qq.com/card/invoice/seturl?access_token=
请求方法:POST
协议:HTTPS
请求参数
{}
注意:此处请求时须传入{},不可传空
返回参数
参数 类型 是否必填 描述
errcode Int 是 错误码
errmsg String 是 错误信息
invoice_url String 是 该发票专用的授权链接,开票平台须将 url 内的
s_appid 给到服务的商户,商户在请求授权链接
-
时会向微信传入该参数,标识服务的发票平台是
哪家
请求示例
请求
{}
返回
{
"errcode": 0,
"errmsg": "ok",
"invoice_url":
"https://mp.weixin.qq.com/bizmall/authinvoice?action=list&s_pappid=d3xxxxxxxxxxxxxGLSS0wrL14No8
c1"
}
注意事项
1.仅限发票平台有该接口的权限;
2.发票平台获取 s_appid 后,须透传给商户,不可改动其中的内容;
3.开票平台须使用制券用的 appid 请求该接口,否则报错;
-
5、将发票插入用户卡包
接口说明
商户侧完成用户插卡授权后,向发票平台请求给某一个订单号进行开具发票动作并标识该订
单需要进行插卡,发票平台须调用该接口对用户进行开具发票动作。
建议开票平台在开放给商户的接口中加入“是否开票”字段选项,并传入商户的“appid”、“授权
订单号”
请求方式
URL: https://api.weixin.qq.com/card/invoice/insert?access_token={access_token}
请求方法:POST
协议:HTTPS
请求参数
数据格式:POST
参数 类型 是否必填 描述
order_id string 是 发票 order_id
card_id String 是 发票 card_id
appid String 是 该订单号授权时使用的 appid,一般为商户 appid
card_ext Object 是 发票具体内容
card_ext 包含以下内容:
参数 类型 是否必填 描述
-
outer_str string 是 自定义渠道参数,会通过用户领取发票的事件推
送给开发者
code String 是 发票 code
nonce_str String 是 随机字符串,防止重入
user_card Object 是 用户信息结构体
user_card 中包含一个 invoice_user_data 对象,invoice_user_data 包含以下字段:
参数 类型 是否必填 描述
fee Int 是 发票的金额,以分为单位
title String 是 发票的抬头
billing_time Int 是 发票的开票时间,为 10 位时间戳(utc+8)
billing_no String 是 发票的发票代码
billing_code String 是 发票的发票号码
info List 否 商品详情结构,见下方
fee_without_tax Int 是 不含税金额,以分为单位
tax Int 是 税额,以分为单位
detail String 是 发票的详情
pdf_url String 否 发票 pdf 的 url,当报销方请求时,微信会在该
url 上附带报销方的身份 token,开票平台可以针
对微信的 token 进行校验,保证该次请求的合法
性,pdf_url 和 pdf_media_id 两个必须填一个
pdf_media_id Int 否 发票 pdf 文件上传到微信发票平台后,会生成一
个发票 media_id,该 media_id 可以直接用于开
-
发票,pdf_url和 pdf_media_id两个必须填一个,
发票上传参考“10、上传 pdf”
reimburse_status String 是 发票报销状态,见备注 1
info 为 Object 列表,每个 Object 包含以下信息:
参数 类型 是否必填 描述
name String 是 项目的名称
num Int 是 项目的数量
unit String 是 项目的单位,如个
price Int 是 项目的单价
返回参数
数据格式:POST
参数 类型 是否必填 描述
errcode Int 是 错误码
errmsg String 是 错误信息
当错误码为 0 是,有以下信息:
参数 类型 是否必填 描述
code String 是 发票 code
openid String 是 用户标识,即领取到发票的 openid
-
请求示例
请求:
{
"order_id": "111163",
"card_ext": {
"outer_str": "xxxxxxx",
"code": "00000",
"nonce_str": "j!Re1WxaHv",
"user_card": {
"invoice_user_data": {
"info": [
{
"price": 10000,
"num": 3,
"name": "牙膏",
"unit": "个"
}
],
"billing_no": "4545145712",
"billing_code": "4541212454512",
"billing_time": "1468306058",
-
"tax": 123,
"detail": "项目",
"pdf_url": "pdf_url",
"fee": 123,
"title": "灌哥发票",
"fee_without_tax": 2345
}
}
},
"card_id": "pjZ8Yt9WoOePThU0NfUKz5-tBEWU",
"appid": "wxc0b84a53ed8e8d29"
}
返回:
{
"errcode": 0,
"errmsg": "ok",
"code": "682xxxx661927",
"openid": "ojZ8Ytz4lESxxxx_R1TvB2Kds"
}
-
6、检查 wx_invoice_token
接口说明
当报销方获取到下载发票 PDF 的 URL 并访问时,开票平台可以在 URL 后面获取到一串
token,用于校验 url 时效性以及报销主体身份,并决定是否为该报销方提供 PDF 文件。
请求方式
URL:
https://api.weixin.qq.com/card/invoice/platform/checktoken?access_token={access_token
}
请求方法:POST
请求参数
数据格式:POST
参数 类型 是否必填 描述
wx_invoice_token String 是 Token
返回参数
数据格式:POST
参数 类型 是否必填 描述
errcode Int 是 错误码
-
errmsg String 是 错误信息
当错误码为 0 是,有以下信息:
参数 类型 是否必填 描述
card_id String 是 发票 id
code String 是 发票 code
reimburse_biz String 是 报销方 appid
user_info Object 是 用户发票信息
user_info 包含以下信息:
参数 类型 是否必填 描述
fee Int 是 发票价税合计金额
title String 是 发票抬头
billing_time Int 是 发票开票时间,为十位时间戳(utc+8)
billing_no String 是 发票代码
billing_code String 是 发票号码
info List 否 商品详情结构体名称
fee_without_tax Int 是 不含税金额,以分为单位
tax Int 是 税额,以分为单位
detail String 是 发票详情
pdf_url String 是 发票的 url
reimburse_status String 是 发票报销状态,见备注 1
order_id String 是 发票 order_id
info 为 Object 列表,每个 Object 包含以下信息:
-
参数 类型 是否必填 描述
name String 否 发票项目名称
num Int 否 项目数量
unit String 否 单位
price Int 否 单价
请求示例
请求:
{
"wx_invoice_token":
"UgFHAfHougrFFyaoSfI1Deui7QQ0uKQq_vvXFzfZzwj8ubj8PYtAEhZrBdBHl0kNKIFs7so-8em6PRk1jIM
zNQ.="
}
返回:
{
"errcode": 0,
"errmsg": "ok",
"card_id": "pjZ8Yt7Um2jYxzneP8GomnxoVFWo",
"code": "186921658591",
"reimburse_biz": "wxc0b84a53ed8e8d29",
"user_info": {
-
"fee": 123,
"title": "灌哥发票",
"billing_time": 1468306058,
"billing_no": "4545145712",
"billing_code": "4541212454512",
"info": [
{
"name": "牙膏",
"num": 3,
"unit": "个",
"price": 10000
}
],
"accept": true,
"fee_without_tax": 2345,
"tax": 123,
"detail": "项目",
"pdf_url": "pdf_url",
"reimburse_status": "INVOICE_REIMBURSE_INIT",
"order_id": "111168"
}
}
-
7、状态更新事件推送
接口描述
当报销方更新发票状态的时候,公众平台会推送一条消息公众号消息通知开票平台设置的接
收事件回调的 url,关于事件推送请参考:。
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025274&token=&lang=zh_
CN
请求参数
数据格式:xml
参数 类型 是否必填 描述
ToUserName String 是 公众号标识
FromUserName String 是 用户 openid
CreateTime Int 是 事件时间
MsgType String 是 固定为 event
Event String 是 固定为 update_invoice_status
Status String 是 发票报销状态
CardId String 是 发票 id
Code String 是 发票 code
http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025274&token=&lang=zh_CNhttp://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025274&token=&lang=zh_CN
-
请求示例
1478068440
8、主动更新发票状态接口
接口说明
如果开票平台的发票状态发生改变,需要调用该接口,将状态同步给公众平台,确保双方发
票的状态一致。
请求方式
URL:https://api.weixin.qq.com/card/invoice/platform/updatestatus?access_token={access
_token}
-
请求方法:POST
请求参数
数据格式:post
参数 类型 是否必填 描述
card_id String 是 发票 id
code String 是 发票 code
reimburse_status String 是 发票报销状态
返回参数
数据格式:POST
参数 类型 是否必填 描述
errcode Int 是 错误码
errmsg String 是 错误信息
请求示例
请求:
{
"card_id": "pjZ8Yt7Um2jYxzneP8GomnxoVFWo",
"code": "186921658591",
-
"reimburse_status": "INVOICE_REIMBURSE_INIT"
}
返回:
{
"errcode": 0,
"errmsg": "ok"
}
9、上传 pdf
接口说明
开票平台可以将发票 pdf 上传到微信电子发票平台,用于开票使用。
请求方式
URL:https://api.weixin.qq.com/card/invoice/platform/setpdf?access_token={access_token
}
请求方法:POST
请求参数
数据格式:multipart/form-data
参数 是否必填 描述
-
pdf 是 form-data 中媒体文件标识,有 filename、
filelength、content-type 等信息
返回参数
数据格式:json
参数 类型 是否必填 描述
errcode Int 是 错误码
errmsg String 是 错误信息
media_id Int 是 64 位整数,用户获取发票 pdf 和插卡使用
请求示例
请求:
------WebKitFormBoundary2exwM16BY25kVBgf
Content-Disposition: form-data; name="pdf"; filename="1133090578170938.pdf"
Content-Type: application/pdf
Pdf content
------WebKitFormBoundary2exwM16BY25kVBgf--
返回:
{
"errcode": 0,
-
"errmsg": "ok",
"media_id": 3015806758683707
}
10、获取 pdf
接口说明
获取发票 pdf 文件
请求方式
URL:https://api.weixin.qq.com/card/invoice/platform/getpdf?access_token={access_token
}
请求方法:POST
请求参数
数据格式:json
参数 类型 是否必填 描述
media_id Int 是 发票 media_id
-
返回参数
pdf 文件二进制信息,可以直接保存到文件。
请求示例
请求:
{
"media_id": 1247031632790573
}
11、备注
9.1、错误码
错误码 备注
0 成功
72015 没有操作发票的权限
72017 发票抬头不一致
72023 发票已被其他公众号锁定
72024 发票状态错误
-
9.2、发票报销状态
状态 描述
INVOICE_REIMBURSE_INIT 发票初始状态,未锁定
INVOICE_REIMBURSE_LOCK 发票已锁定
INVOICE_REIMBURSE_CLOSURE 发票已核销
9.3、发票跳转链接协议
为了满足商户基于发票本身的扩展诉求,允许发票内页添加 url 跳转外链(创建发票字段中的
promotion_url 和 custom_url)。带有的的字段有 encrypt_code、card_id。
注意事项:
encrypt_code 为加密码码,需调用解码接口获取真实 code 码。 假如指定的 url 为
http://www.qq.com,用户点击时,跳转的 url 则为:
http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID
9.4、解码 code 接口
上一步中拿到的 encrypt_code 要经过 urldecode 后调用解码 code 接口解码方可得到真
实的 code。
接口调用请求说明
http://mp.weixin.qq.com/wiki/index.php?title=%E6%A0%B8%E9%94%80%E5%8D%A1%E5%88%B8#Code.E8.A7.A3.E7.A0.81.E6.8E.A5.E5.8F.A3http://www.qq.com/?encrypt_code=ENCRYPT_CODE&card_id=CARDID
-
http 请求方式: POST
https://api.weixin.qq.com/card/code/decrypt?access_token=TOKEN
参数说明
参数 是否必须 说明
POST 数据 是 Json 数据
access_token 是 调用接口凭证
POST 数据
注意,在调用前请确认该参数是否经过 urldecode
{
"encrypt_code":"XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE"
}
参数名 必填 类型 示例值 描述
encrypt_c
ode
是 string(128)
XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4
GWA60Fzpc8ksZ/5ZZ0DVkXdE
经 过 加 密 的
Code 码。
返回数据
https://api.weixin.qq.com/card/code/decrypt?access_token=TOKEN
-
数据示例:
{
"errcode":0,
"errmsg":"ok",
"code":"751234212312"
}
参数名 描述
errcode 错误码
errmsg 错误信息
code 解密后获取的真实 Code 码