收票对接流程图

对接约定

测试环境:

var baseUrl = https://api-dev.piaozone.com/test

var STATIC_URL = https://imgshow-master.piaozone.com

正式环境:

var baseUrl = https://api.piaozone.com

var STATIC_URL = https://img-expense.piaozone.com

对接过程中需要： 发票云授权标识（client_id）、授权密钥（client_secret）、加密密钥（encrypt_key）进行授权，每个环境的授权不同，获取方式可以找实施人员协助提供

接口返回约定：若无特别说明，接口返回如下

引入socket库

STATIC_URL + /static/gallery/socket.io.js

STATIC_URL + /static/public/js/pwy-socketio-v2.js

打开发票云H5

注：单据界面点击 “导入发票” 跳转到发票界面时，单据界面不能关闭，否者发票数据无法推送到单据界面, （推送、接收数据参考下方‘企业微信嵌入发票云界面 Demo’）

地址

baseUrl + /m4-web/dd/wap/index

参数说明

参数名	是否必须	长度	类型	备注
userKey	是	32	String	通过 userkey 接口获取
socketName	是	32	String	socket 建立时的名字（linkkey 接口获取）
app	是	-	String	钉钉: dingding 企业微信: qywx 其他: other
wechatCard	否	-	String	发票云界面卡包功能标志，默认 flase; 显示 true
model	是	-	String	发票云界面扫码功能标志默认 yes，隐藏 no (仅支持了钉钉，其他app不支持)
attach	否	-	String	发票云界面附件功能标志，默认 yes，隐藏 no （像星空云有自己的附件系统，不使用发票云的）
title	否	-	String	设置需要通过encodeUrl()进行编码；默认显示“金蝶发票云”，通过iframe打开设置title无效

注：以上功能（wechatCard：卡包，attach：附件， model：扫码）配置，也可以通过商家平台（进项发票管理/发票助手配置）进行配置

打开发票云界面接口调用

获取userkey

接口地址: baseUrl + /m4/fpzs/getUserKey

请求方式： POST

请求 content-type 格式： application/json

请求的全部参数：

参数名	是否必须	长度	备注
billNumber	是	最大长度 55	企业单据编号，可以为空，已经保存的单据传入可以方便查询出已经存在的票据
billType	否	最大长度 16 位	报销单类型说明如下 1.0.2 表格
branch_id	否	最大长度 50	报销单分录 ID
bxd_key	是	最大长度 50	报销单 ID
ghf_mc	是	最大长度100	购货方名称（校验发票抬头是否一致时使用）
timestamp	是	固定长度13	时间戳：用于签名验证
client_id	是	发票云授权标识（创建当前报销单的发票云授权标识，与查询单据发票时保持一致）
tin	是	最大长度20	企业税号（校验发票税号是否一致时使用）
eid	是	最大长度 80 位，建议使用 32 位 uuid	接入企业用户 ID，
sign	是	64	签名, 签名规则见对接约定, clientSecret 和 clientId 由发票云分配
encType	否	1	签名加密类型 0：MD5、1：SHA256、2：HMAC SHA256，不传默认MD5加密
random	否	最大长度 35	随机码
ticketParam	是	固定长度 4	过滤规则，格式如：1101
salerName	否	最大长度 100	单据限制销方名称
salerTaxNo	否	最大长度 20	单据限制销方税号
assembleByBillType	否	--	是否按单据类型(billType)组装推送给APP的数据。 1：组装；其他不组装
resource	否	--	产品线来源：1发票云、2EAS、3Cloud、4苍穹、5星空、6k3w、7SAP、11泛微
phone	否	11	手机号码，企业用户ID存在时，绑定到用户信息上
参数说明

1、ticketParam

参数规则顺序： 0 不允许 1 允许

第 1 位：已报销过的发票是否允许导入

第 2 位：发票抬头与企业名称不一致的发票是否允许导入

第 3 位：发票抬头与税号不一致发票是否允许导入

第 4 位：发票查验不通过的发票是否允许导入

2、billType

参数值	备注
Tra	智能差旅行程单
Pur	智能物品采购报销单
BizOut	智能对公报销单
""	费用报销单传空字符串

请求参数示例

获取 linkkey 接口

请求方式：post

参数：无

接口地址：baseUrl + /m4/fpzs/getLinkKey

返回描述：

钉钉：打开发票云界面

需引入钉钉 jsSDK： https://g.alicdn.com/dingding/dingtalk-jsapi/2.0.57/dingtalk.open.js

企业微信：嵌入发票云界面

企业微信嵌入发票云界面 Demo

http://imgdev-master.piaozone.com/static/fwh/html/socketDemo/index.html?userKey=${userKey}

其他第三方APP：嵌入发票云界面（如云之家，泛微等）

msg消息返回格式

消息格式： {"type":"updateInvoice", data: {}}

type为saveBill时为导入时的发票数据

费用单据的数据格式：billType为空字符串

智能差旅行程单的数据数据格式, billType为：Tra

智能物品采购单据-数据数据格式, billType为：Pur

智能对公单据-数据数据格式, billType为：BizOut

企业微信：调用卡包（电子发票）、扫码

注：该电子发票功能仅适用企业微信内部自建应用，第三方ISV不适合；仅认证的企业微信账号并且企业激活人数超过200的企业才有接口权限（2022年/6月），如果认证的企业激活人数不超过200人请联系企业微信客服咨询。

引入企业微信库jsSDK

http://res.wx.qq.com/open/js/jweixin-1.2.0.js

postMessage相关代码

getWechatCardPackSign接口

获取 wx.config 、wx.chooseInvoice 、wx.scanQRCode 方法所需参数

接口地址：baseUrl + /m10/thirdparty/wechat/getWechatCardPackSign

请求方式： POST

请求 content-type 格式： application/json

参数说明：

参数	类型	长度	描述
corpid	String	-	当前企业 ID ， "企业微信后台--我的企业" 如：wwf21c817a9653e942
corpsecret	String	-	当前自建应用的 Secret， "企业微信后台--应用管理"
url	String	-	当前主页的地址（用来生成签名 sign 所需，不明白的可以看 JsSDk 附录签名流程）

注：当前自建应用底部-“开发者接口”，需要设置当前页面的域名，否者调用卡包时会提示没有权限，新创建的自建应用还需要在“开发者接口”处设置“企业可信IP”

注：下方拉取电子发票列表可能会有些慢！自己看情况加进度框

拉取微信电子发票列表

拉取企业微信扫一扫

常见问题处理

1，可以在当前页面添加 vonsole 插件方便调试！调试完再去掉

2，提示签名不通过时，可以在下方地址进行验证签名是否正确

https://work.weixin.qq.com/api/jsapisign

其他APP调用卡包（电子发票）、扫码

注一：H5本身并不支持直接拉起微信电子票夹，需要APP支持拉取微信电子票夹的能力并封装给前端调用

1：首先处理微信对app的授权（已授权忽略），并封装js提供给前端调用

2：调用指令方式同上诉企业微信

3：其次改造上方“微信-电子发票”（搜关键字）处代码即可

注二：暂不支持除企业微信、钉钉App外的其他应用个性化扫码功能

报销单据与发票关系处理（重点）

请查看接口文档： 发票助手PC web端对接

报销单据上查看关联发票（重点）

通过报销单 ID 查询

接口地址：baseUrl + /m4/fpzs/bxdInvoices?bxd_key={报销单ID}&client_id={创建当前报销单的发票云授权标识}&timestamp={时间戳}&sign={签名}&ticketParam={发票校验过滤规则}

请求方式： GET

参数说明

参数	类型	长度	描述
bxd_key	String	最大长度50	报销单 ID
client_id	String	最大长度30	创建当前报销单的发票云授权标识
timestamp	String	13	时间戳
sign	String	32	签名规则见对接约定, clientSecret 和 clientId 由发票云分配
encType	Int	1	签名加密类型 0：MD5、1：SHA256、2：HMAC SHA256，不传默认MD5加密
ticketParam	String	5	发票校验过滤规则，格式如：11011

ticketParam 参数规则顺序： 0 不允许 1 允许

第1位：已被单据占用的发票是否允许导入

第2位：发票抬头与企业名称不一致的发票是否允许导入

第3位：发票抬头与税号不一致发票是否允许导入

第4位：发票查验不通过的发票是否允许导入

第5位: 个人发票是否允许导入

请求接口参数示例

单据分录上通过事件代码查询

接口地址：baseUrl + /m4/fpzs/expense/invoices/certifacate/query?event_code=${eventCode}

请求方式： GET

参数说明

参数	类型	长度	描述
envent_code	String	-	事件代码（如下接口获取）

获取事件代码 eventCode

接口地址： baseUrl + /base/oauth/eventCode

请求方式： POST

请求 content-type 格式： application/json

参数说明

参数	类型	长度	描述
client_id	String	最大长度30	创建当前报销单的发票云授权标识
timestamp	String	13	时间戳
sign	String	32	签名规则见对接约定, clientSecret 和 clientId 由发票云分配
encType	Int	1	签名加密类型 0：MD5、1：SHA256、2：HMAC SHA256，不传默认MD5加密
type	String	22	EXPENSE_SERIALNO_QUERY //固定值
buyerName	String	最大长度100	购方抬头
buyerTaxNo	String	最大长度20	购方税号
ticketParam	String	5	发票校验过滤规则，格式如：1101
certifacateSerialNos	Array	最大长度35	附件流水号
invoiceSerialNos	Array	最大长度35	发票流水号
expenseId	String	最大长度30	报销单ID

请求接口参数示例

单张发票查看发票详情界面

页面路径：baseUrl + /m4-web/dd/wap/index?checkDetail=true&serialNo={userKey}

参数说明

参数	类型	长度	描述
checkDetail	String	-	固定值 true
serialNo	String	最大长度35	发票流水号
userKey	String	32	生成规则查看 userKey 接口

票夹流程

页面地址：baseUrl + /m4-web/ticket/wap/index?userKey={socketName}&app=qywx&model=yes

参数说明

参数	类型	长度	描述
socketName	String	32	socket 建立时的名字（linkkey 接口获取）
userKey	String	32	生成规则查看 userKey 接口

单据删除发票云关联附件流程

页面路径：baseUrl + /m4-web/fpzs/bill-attachments?bxd_key={client_id}&userKey=${userKey}
参数说明

参数	是否必须	类型	长度	描述
bxd_key	是	String	最大长度50	报销单 ID）
client_id	是	String	最大长度30	创建当前报销单的发票云授权标识
userKey	是	String	32	生成规则查看 userKey 接口

对接方式

参考文档4.打开发票云界面接口调用

点击“保存并返回”后msg消息返回格式

单据审核中只补附件流程

背景：客户通过发票云采集发票到单据上后，发现发票少了附件，只能通过删除发票，重新打开发票云上传发票再上传附件，希望能通过单据信息直接补附件

页面路径：baseUrl + /m4-web/fpzs/supplemental/ticket?userKey={socketName}&app=${app}

请求方式： GET

参数说明

参数	是否必须	类型	长度	描述
userKey	是	String	32	生成规则查看 userKey 接口
socketName	是	String	32	socket 建立时的名字（linkkey 接口获取）
app	是	String	-	钉钉: dingding 企业微信: qywx 其他: other

对接方式

参考文档1.收票对接流程图

企业微信单据补附件Demo

http://imgdev-master.piaozone.com/static/fwh/html/socketDemo/bfj.html?userKey=${userKey}

返回的结果

msg消息返回格式

参考文档8.msg消息返回格式跟首页采集后推送格式一致

保存推送过来的发票附件信息和单据的关系

请查看接口文档： 发票助手PC web端对接#10保存单据

发票助手移动端-h5对接

收票对接流程图#

对接约定#

引入socket库#

打开发票云H5#

地址#

参数说明#

打开发票云界面接口调用#

获取userkey#

获取 linkkey 接口#

钉钉：打开发票云界面#

企业微信：嵌入发票云界面#

企业微信嵌入发票云界面 Demo#

其他第三方APP：嵌入发票云界面（如云之家，泛微等）#

msg消息返回格式#

企业微信：调用卡包（电子发票）、扫码#

引入企业微信库jsSDK#

postMessage相关代码#

getWechatCardPackSign接口#

拉取微信电子发票列表#

拉取企业微信扫一扫#

其他APP调用卡包（电子发票）、扫码#

报销单据与发票关系处理（重点）#

报销单据上查看关联发票（重点）#

通过报销单 ID 查询#

单据分录上通过事件代码查询#

获取事件代码 eventCode#

单张发票查看发票详情界面#

票夹流程#

单据删除发票云关联附件流程#

单据审核中只补附件流程#

收票对接流程图

对接约定

引入socket库

打开发票云H5

地址

参数说明

打开发票云界面接口调用

获取userkey

获取 linkkey 接口

钉钉：打开发票云界面

企业微信：嵌入发票云界面

企业微信嵌入发票云界面 Demo

其他第三方APP：嵌入发票云界面（如云之家，泛微等）

msg消息返回格式

企业微信：调用卡包（电子发票）、扫码

引入企业微信库jsSDK

postMessage相关代码

getWechatCardPackSign接口

拉取微信电子发票列表

拉取企业微信扫一扫

其他APP调用卡包（电子发票）、扫码

报销单据与发票关系处理（重点）

报销单据上查看关联发票（重点）

通过报销单 ID 查询

单据分录上通过事件代码查询

获取事件代码 eventCode

单张发票查看发票详情界面

票夹流程

单据删除发票云关联附件流程

单据审核中只补附件流程