电子发票开票平台接口文档（beta1 - QQ...电子发票开票平台接口文档（beta1.0） 2016/11/27 微信发票团队

电子发票开票平台接口文档（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、接入指引

目前发票平台角色较少，对于有资质的发票平台，请发送以下格式申请到官方指定邮箱

[email protected]

公司名称业务描述公司地址相关资质证

明

联系电

话

接口人开票平台

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







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






card_id String 是发票 id


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


reimburse_status String 是发票报销状态

返回参数

数据格式：POST




请求示例

请求：

{

"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




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 码

Documents

电子发票开票平台接口文档（beta1 - QQ...电子发票开票平台接口文档（beta1.0） 2016/11/27 微信发票团队