# 开票平台的接口调用说明

# 接口列表

接口名称	英文名	请求路径
创建发票卡券模板	invoiceplatformcreatecard	/card/invoice/platform/createcard
上传发票PDF	invoiceplatformsetpdf	/card/invoice/platform/setpdf
获取开票平台识别码	setinvoiceurl	/card/invoice/seturl
查询已上传的PDF文件	invoiceplatformgetpdf	/card/invoice/platform/getpdf
将电子发票卡券插入用户卡包	insertinvoice	/card/invoice/insert
更新发票卡券状态	invoicekpupdatainvoicestatus	/card/invoice/platform/updatestatus

# 接口调用顺序

开发者可参考下方接口调用顺序完成开发。

# 1 获取开票平台识别码

接口说明

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

# 2 创建发票卡券模板

接口说明

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

# 3 上传发票PDF

接口说明

商户或开票平台可以通过该接口上传PDF。PDF上传成功后将获得发票文件的标识，后续可以通过插卡接口将PDF关联到用户的发票卡券上，一并插入到收票用户的卡包中。

注意：若上传成功的PDF在三天内没有被关联到发票卡券发送到用户卡包上，将会被清理。若商户或开票平台需要在三天后再关联发票卡券的话，需要重新上传。

# 4 查询已上传的PDF文件

接口说明

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

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

接口说明

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

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

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

# 6 更新发票卡券状态

接口说明

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

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

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

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

# 7 发票状态更新事件推送

接口说明

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

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

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

返回结果

返回结果为xml格式，字段如下：

示例代码

<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格式，参数清单如下：

返回结果

返回结果为JSON格式，字段如下：

示例代码

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

# 错误码