开票平台接口列表


上一篇 : 商户接口列表 下一篇: 报销方接口列表



1 获取自身的开票平台识别码

2 创建发票卡券模板

3 上传PDF

4 查询已上传的PDF文件

5 将电子发票卡券插入用户卡包

6 更新发票卡券状态

7 发票状态更新事件推送

8 解码code接口

9 错误码

10 发票报销状态一览表


1 获取自身的开票平台识别码

接口说明

开票平台可以通过此接口获得本开票平台的预开票url,进而获取s_pappid。开票平台将该s_pappid并透传给商户,商户可以通过该s_pappid参数在微信电子发票方案中标识出为自身提供开票服务的开票平台。

请求方式

请求URL:https://api.weixin.qq.com/card/invoice/seturl?access_token={access_token}

请求方法:POST

请求参数

请求参数使用JSON格式,传入空值{}

返回结果

返回结果为JSON格式,字段如下:

参数 类型 是否必填 描述
errcode string 错误码
errmsg string 错误信息
invoice_url string 该开票平台专用的授权链接。开票平台须将 invoice_url 内的 s_pappid 给到服务的商户,商户在请求授权链接时会向微信传入该参数,标识所使用的开票平台是哪家

示例代码

请求
{}
返回
{
   "errcode": 0,
   "errmsg": "ok",
   "invoice_url": "https://mp.weixin.qq.com/bizmall/authinvoice?action=list&s_pappid=d3xxxxxxxxxxxxxGLSS0wrL14No8c1"
}

2 创建发票卡券模板

接口说明

通过本接口可以为创建一个商户的发票卡券模板,为该商户配置发票卡券模板上的自定义栏位。创建发票卡券模板生成的card_id将在创建发票卡券时被引用,故创建发票卡券模板是创建发票卡券的基础。

请求方式

请求URL:https://api.weixin.qq.com/card/invoice/platform/createcard?access_token={access_token}

请求方法:POST

请求参数

请求参数使用JSON格式,字段如下:

参数 类型 是否必填 描述
invoice_info Object 发票模板对象

invoice_info为Object,里面包括以下字段:

参数 类型 是否必填 描述
base_info object 发票卡券模板基础信息
payee string 收款方(开票方)全称,显示在发票详情内。故建议一个收款方对应一个发票卡券模板
type string 发票类型

base_info为Object,里面包括以下字段:

参数 类型 是否必填 描述
logo_url string 发票商家 LOGO ,请参考 上传图片接口
title string 收款方(显示在列表),上限为 9 个汉字,建议填入商户简称
custom_url_name string 开票平台自定义入口名称,与 custom_url 字段共同使用,长度限制在 5 个汉字内
custom_url string 开票平台自定义入口跳转外链的地址链接 , 发票外跳的链接会带有发票参数,用于标识是从哪张发票跳出的链接
custom_url_sub_title string 显示在入口右侧的 tips ,长度限制在 6 个汉字内
promotion_url_name string 营销场景的自定义入口
promotion_url string 入口跳转外链的地址链接,发票外跳的链接会带有发票参数,用于标识是从那张发票跳出的链接
promotion_url_sub_title string 显示在入口右侧的 tips ,长度限制在 6 个汉字内

返回结果

返回结果为JSON格式,字段如下:

参数 类型 是否必填 描述
errcode string 错误码
errmsg string 错误信息
card_id string 当错误码为 0 时,返回发票卡券模板的编号,用于后续该商户发票生成后,作为必填参数在调用插卡接口时传入

示例代码

请求:
{
   "invoice_info": {
       "base_info": {
           "logo_url": "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
           "title": "xx公司",
           "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": " 测试 - 收款方 ",
   }
}
返回:
{
   "errcode": 0,
   "errmsg": "ok",
   "card_id": "pjZ8Yt9WoOePThU0NfUKz5-tBEWU"
}

3 上传PDF

接口说明

商户或开票平台可以通过该接口上传PDF。PDF上传成功后将获得发票文件的标识,后续可以通过插卡接口将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 错误信息
s_media_id String 64位整数,在 将发票卡券插入用户卡包 时使用用于关联pdf和发票卡券,s_media_id有效期有3天,3天内若未将s_media_id关联到发票卡券,pdf将自动销毁

示例代码

请求:
------WebKitFormBoundary2exwM16BY25kVBgf Content-Disposition: form-data; name="pdf"; filename="1133090578170938.pdf" Content-Type: application/pdf Pdf content ------WebKitFormBoundary2exwM16BY25kVBgf—
返回:
{
   "errcode":0,
   "errmsg":"ok",
   "s_media_id":"3015806758683707"
}

4 查询已上传的PDF文件

接口说明

用于供发票PDF的上传方查询已经上传的发票或消费凭证PDF。

请求方式

请求URL:https://api.weixin.qq.com/card/invoice/platform/getpdf?action=get_url&access_token=access_token={access_token}

请求方法:POST

请求参数

请求参数使用JSON格式,字段如下:

参数 类型 是否必填 描述
action String 填“get_url”
s_media_id string 发票s_media_id

返回结果

返回结果为JSON格式,字段如下:

参数 类型 是否必填 描述
errcode Int 错误码
errmsg String 错误信息
pdf_url String pdf 的 url ,两个小时有效期
pdf_url_expire_time Int pdf_url 过期时间, 7200 秒

示例代码

请求:
{
   "action": "get_url",
   "s_media_id": "75195574948725301"
}
返回:
{
   "errcode": 0,
   "errmsg": "ok",
   "pdf_url": "https://mp.weixin.qq.com/intp/invoice/getpdf?action=media_pdf&media_key=dFRnTkV6WCswNjB1V1czZ0tVU3MhaX4yb2pxeEVSY0teSCtuflY6UXAifD5rL09kTjFpOFVWKyJGNCgxTCtkJER6VjFlRCtVU2JKcS5FZw",
   "pdf_url_expire_time": 7200
}

5 将电子发票卡券插入用户卡包

接口说明

本接口由开票平台或自建平台商户调用。对用户已经授权过的开票请求,开票平台可以使用本接口将发票制成发票卡券放入用户的微信卡包中。

值得关注的是,如果授权页由商户拉起,而插卡递送发票的动作由开票平台来完成的话,商户需要将需要存入微信卡包的标识和order_id在开票请求中发送给开票平台。

注意:需要使用之前调用获取s_pappid接口时的开票平台公众号appid调用本接口,否则会造成报错,插卡失败。

请求方式

请求URL:https://api.weixin.qq.com/card/invoice/insert?access_token={access_token}

请求方法:POST

请求参数

请求参数使用JSON格式,字段如下:

参数 类型 是否必填 描述
order_id string 发票order_id,既商户给用户授权开票的订单号
card_id String 发票card_id
appid String 该订单号授权时使用的appid,一般为商户appid
card_ext Object 发票具体内容

card_ext为Object,包括以下内容:

参数 类型 是否必填 描述
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 税额,以分为单位
s_pdf_media_id String 发票pdf文件上传到微信发票平台后,会生成一个发票s_media_id,该s_media_id可以直接用于关联发票PDF和发票卡券。发票上传参考“ 3 上传PDF ”一节
s_trip_pdf_media_id String 其它消费附件的PDF,如行程单、水单等,PDF上传方式参考“ 3 上传PDF ”一节
check_code String 校验码,发票pdf右上角,开票日期下的校验码
buyer_number String 购买方纳税人识别号
buyer_address_and_phone String 购买方地址、电话
buyer_bank_account String 购买方开户行及账号
seller_number String 销售方纳税人识别号
seller_address_and_phone String 销售方地址、电话
seller_bank_account String 销售方开户行及账号
remarks String 备注,发票右下角初
cashier String 收款人,发票左下角处
maker String 开票人,发票下方处

info为Object列表,列表中每个Object包含以下信息:

参数 类型 是否必填 描述
name String 项目的名称
num Int 项目的数量
unit String 项目的单位,如个
price Int 项目的单价

返回结果

返回结果为JSON格式,字段如下:

参数 类型 是否必填 描述
errcode Int 错误码
errmsg String 错误信息
code String 发票code
openid String 获得发票用户的openid
unionid String 只有在用户将公众号绑定到微信开放平台帐号后,才会出现该字段

示例代码

请求:
{
   "order_id": "111163",
   "card_ext": {
       "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,
               "s_pdf_media_id": "s_pdf_media_id_abc123",
               "fee": 123,
               "title": "灌哥发票",
               "fee_without_tax": 2345
               "buyer_number":"123456789012345678"
           }
       }
   },
   "card_id": "pjZ8Yt9WoOePThU0NfUKz5-tBEWU",
   "appid": "wxc0b84a53ed8e8d29"
}
返回:
{
   "errcode": 0,
   "errmsg": "ok",
   "code": "682xxxx661927",
   "openid": "ojZ8Ytz4lESxxxx_R1TvB2Kds"
}

6 更新发票卡券状态

接口说明

发票平台在获知发票状态变化(如被冲红、被报销)时,需更新在用户卡包中发票卡券的状态。确保发票卡券可用性,避免无效报销、重复报销。

本接口主要用于发票平台更新从其他渠道或者的发票报销状态变更,企业报销接口请见企业报销电子发票章节。

目前电子发票冲红在微信中表现为对应的发票卡券被核销,调用该接口并将发票卡券状态置为“INVOICE_REIMBURSE_CANCEL”即可

具体发票状态见发票状态一览表。

请求方式

请求URL:https://api.weixin.qq.com/card/invoice/platform/updatestatus?access_token={access_token}

请求方法:POST

请求参数

请求参数使用JSON格式,字段如下:

参数 类型 是否必填 描述
card_id String 发票 id
code String 发票 code
reimburse_status String 发票报销状态

返回结果

返回结果为JSON格式,字段如下:

参数 类型 是否必填 描述
errcode Int 错误码
errmsg String 错误信息

示例代码

请求:
{
   "card_id": "pjZ8Yt7Um2jYxzneP8GomnxoVFWo",
   "code": "186921658591",
   "reimburse_status": "INVOICE_REIMBURSE_INIT"
}
返回:
{
   "errcode": 0,
   "errmsg": "ok"
}

7 发票状态更新事件推送

接口说明

微信在获知用户将发票提交企业报销后,会将发票状态的变更情况推送给发票平台及商户,以便确保各方的发票状态同步。发票平台或自建平台商户通过配置时间接收URL,解析推送事件类型,获得状态变更消息。

该事件将发送至开发者填写的URL(登录公众平台进入【开发者中心设置】,参考下图)。

Xw_fRw0B4PZAFlPBbEaqjXFhgcGEHNwIsmUD8iFdWtdG_oX9lmKu0FTUeYHVY6Qx.png

微信服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。关于重试的消息排重,推荐使用FromUserName + CreateTime 排重。假如服务器无法保证在五秒内处理并回复,可以直接回复空串,微信服务器不会对此作任何处理,并且不会发起重试。

返回结果

返回结果为xml格式,字段如下:

参数 类型 是否必填 描述
ToUserName String 公众号标识
FromUserName String 用户 openid
CreateTime Int 事件时间
MsgType String 固定为 event
Event String 固定为 update_invoice_status
Status String 发票报销状态
CardId String 发票 id
Code String 发票 code

示例代码

<xml>
   <ToUserName><![CDATA[gh_9e1765b5568e]]></ToUserName>
   <FromUserName><![CDATA[ojZ8Ytz4lESgdWZ34L_R1TvB2Kds]]></FromUserName>
   <CreateTime>1478068440</CreateTime> <MsgType><![CDATA[event]]></MsgType>
   <Event><![CDATA[update_invoice_status]]></Event>
   <Status><![CDATA[INVOICE_REIMBURSE_INIT]]></Status>
   <CardId><![CDATA[pjZ8Yt7Um2jYxzneP8GomnxoVFWo]]></CardId>
   <Code><![CDATA[186921658591]]></Code>
</xml>

8 解码code接口

接口说明

为了满足商户基于发票本身的扩展诉求,允许发票内页添加url跳转外链(创建发票字段中的promotion_url和custom_url)。带有的的字段有encrypt_code、card_id。

假如指定的url为:http://www.qq.com
用户点击时,跳转的url则为:http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID

encrypt_code为加密码,需调用接口解码方可得到真实的code。获取到的真实code和调用插卡接口返回的code相同。

请求方式

请求URL:https://api.weixin.qq.com/card/code/decrypt?access_token={access_token}

请求方法:POST

请求参数

请求参数使用JSON格式,参数清单如下:

参数 类型 是否必填 描述
encrypt_code String 在发票卡券发起访问外链的时候后缀的加密发票code,指向一张具体的发票卡券

返回结果

返回结果为JSON格式,字段如下:

参数 类型 是否必填 描述
errcode Int 错误码
errmsg String 错误信息
code String 解密后获取的真实发票卡券Code码

示例代码

请求:
{
   "encrypt_code":"XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE"
}
返回:
{
   "errcode":0,
   "errmsg":"ok",
   "code":"751234212312"
}

9 错误码

错误码 错误信息 备注
0 OK 成功
72015 unauthorized create invoice 没有操作发票的权限,请检查是否已开通相应权限。
72017 invalid invoice title 发票抬头不一致
72023 invoice has been lock 发票已被其他公众号锁定。一般为发票已进入后续报销流程,报销企业公众号/企业号/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 订单没有授权,可能是开票平台 appid 、商户 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 发票抬头二维码超时
40078 invalid card status card_id未授权。 若开发者使用沙箱环境报此错误,主要因为未将调用接口的微信添加到测试把名单; 若开发者使用正式环境报此错误,主要原因可能为:调用接口公众号未开通卡券权限,或创建card_id与插卡时间间隔过短。

10 发票报销状态一览表

状态 描述
INVOICE_REIMBURSE_INIT 发票初始状态,未锁定
INVOICE_REIMBURSE_LOCK 发票已锁定
INVOICE_REIMBURSE_CLOSURE 发票已核销
INVOICE_REIMBURSE_CANCEL 发票被冲红


上一篇 : 商户接口列表 下一篇: 报销方接口列表