发票云(标准版)API文档

发票助手移动端-h5对接

收票对接流程图

对接约定

测试环境:

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）进行授权，每个环境的授权不同，获取方式可以找实施人员协助提供

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

{
    "errcode": "0000", ///成功时为0000, 失败时为非0000
    "description": "操作成功", //描述，失败时可以根据这个字段进行提示
    "data": "" //请求的返回实际数据
}

引入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	是	String	通过 userkey 接口获取
socketName	是	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	否		报销单类型说明如下 1.0.2 表格
branch_id	否	最长 50	报销单分录 ID
bxd_key	是	最长 50	报销单 ID
ghf_mc	是		购货方名称（校验发票抬头是否一致时使用）
timestamp	是		时间戳：用于签名验证
client_id	是	发票云授权标识（创建当前报销单的发票云授权标识，与查询单据发票时保持一致）
tin	是		企业税号（校验发票税号是否一致时使用）
eid	是	支持最大长度 80 位，建议使用 32 位 uuid	接入企业用户 ID，
sign	是	64 位	签名, 签名规则见对接约定, clientSecret 和 clientId 由发票云分配
encType	否	2 位	签名加密类型 0：MD5、1：SHA256、2：HMAC SHA256，不传默认MD5加密
random	否	支持最大长度 35 位	随机码
ticketParam	是	固定长度 4 位	过滤规则，格式如：1101
salerName	否	单据限制销方名称
salerTaxNo	否	单据限制销方税号
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	智能对公报销单
""	费用报销单传空字符串

请求参数示例

{
    "billNumber": "报销单号-可自定义",
    "billType": "",
    "branch_id": "",
    "ghf_mc": "公司税号",
    "bxd_key": "报销单ID-可自定义",
    "client_id": "i2ntHzlEsFKBcZCgfYVL",
    "eid": "60319137",
    "random": "0.007343462480909446",
    "sign": "eaff5dbd52a7ef4e3548f707d44d9ec5",
    "encType": 0,
    "ticketParam": "1111",
    "timestamp": "1577324258055",
    "tin": "91440300358768292H"
}

获取 linkkey 接口

请求方式：post

参数：无

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

返回描述：

{
    "errcode": "0000",
    "description": "操作成功",
    "data": "d9d302f207c247d7bce4eb3197b7cc36"
}

钉钉：打开发票云界面

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

  var pwyWebsocket = new PwyWebSocket({ //参数说明同文档1.0表格，
        env: "test",    //正式环境: prod,     测试环境: test
        tin: "91440300358768292H", //${tin}为获取userKey时的税号
        eid: "60319137", //eid为获取${userKey}时的用户${eid}
        client_id: "i2ntHzlEsFKBcZCgfYVL", // 发票云授权标识
        sign: "1f399f3e48d1d0e556671ddbe60247f7", // ${sign}签名规则：MD5(client_id + client_secret + timestamp)
        timestamp: "1577324259001", // 签名时的时间戳${timestamp}
        name: "841c078bdcba4f60854f5c8728fa0b9e", // 连接名称，选择发票前获取的${linkKey}    1.7接口
        onOpen: function () { // 连接成功的回调
            var socketName = this.name;
            if(socketName != ''){
                dd.ready(function(){
                       dd.biz.util.openLink({
                            url: ${baseUrl} + /m4-web/dd/wap/index?userKey=${userkey} + &socketName='+ socketName + '&app=dingding' + '&model=yes',
                            enableShare:true
                         })
                    })
            }else{
                 console.log('未获取到连接名');
            }
        },
        onMessage: function (msg) { //从发票云采集完发票点击首页推送返回到当前页面时，此处会接收发票数据
            alert('获取到'+ msg.data.length +'条数据');
        },
        onError: function (errText, errCode) { //失败时的回调
            console.log("与发票云建立连接失败!");
            console.log("errText>>>" + errText);
        }
    })

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

  var isOpenSocket=false; //防止socket突然重连导致闪退重复打开iframe
  var iframe=document.createElement('iframe');
  iframe.width = '100%';
  iframe.height =  '100%';
  iframe.style.border = 0;
  iframe.style = "border:0;position:absolute;top:0;z-index:2"
  var pwyWebsocket = new PwyWebSocket({ //参数说明同文档1.0表格，
        env: "test",    //正式环境: prod,     测试环境: test
        tin: "91440300358768292H", //${tin}为获取userKey时的税号
        eid: "60319137", //eid为获取userKey时的用户${eid}
        client_id: "i2ntHzlEsFKBcZCgfYVL", // 发票云授权标识
        sign: "1f399f3e48d1d0e556671ddbe60247f7", // ${sign}签名规则：MD5(client_id + client_secret + timestamp)
        timestamp: "1577324259001", // 签名时的时间戳${timestamp}
        name: "841c078bdcba4f60854f5c8728fa0b9e", // 连接名称，选择发票前获取的${linkKey} ，接口1.7
        onOpen: function () { // 连接成功的回调
            var socketName = this.name;
            if(socketName != ''){
                window.onhashchange = function () {// 该代码非必要，视情况而定；如果碰到页面头部返回,iframe无法关闭，可以在打开的时候给当前地址加上hash,然后通过监听hash的方式关闭iframe。
                     if (this.location.hash.indexOf('pwy') < 0) {
                         var fwy = document.getElementById('fwy');
                         if (fwy) {
                            fwy.parentNode.removeChild(fwy);
                         }
                     }
                }
                if (!isOpenSocket) {
                    window.location.hash = 'pwy' + new Date().getTime();
                    iframe.src = ${baseUrl} + /m4-web/dd/wap/index?userKey=${userkey} + '&socketName='+socketName + '&app=qywx' + '&model=no' + '&wechatCard=false'；
                    document.body.appendChild(iframe);
                }
                isOpenSocket = true;
            }else{
                console.log('未获取到连接名');
            }
        },
        onMessage: function (msg) { //从发票云采集完发票点击首页推送返回到当前页面时，此处会接收发票数据
            alert('获取到'+ msg.data.length +'条数据');
            if(iframe){// 关闭新增的地址
                window.history.go(-1);
                iframe.parentNode.removeChild(iframe);
                isOpenSocket = false;
             }
        },
        onError: function (errText, errCode) { //失败时的回调
            console.log("与发票云建立连接失败!");
            console.log("errText>>>" + errText);
            isOpenSocket = false;
        }
    })

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

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

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

  var isOpenSocket=false; //防止socket突然重连导致闪退重复打开iframe
  var iframe=document.createElement('iframe');
  iframe.width = '100%';
  iframe.height =  '100%';
  iframe.style.border = 0;
  iframe.style = "border:0;position:absolute;top:0;z-index:2"
  var pwyWebsocket = new PwyWebSocket({ //参数说明同文档1.0表格，
        env: "test",    //正式环境: prod,     测试环境: test
        tin: "91440300358768292H", //${tin}为获取userKey时的税号
        eid: "60319137", //eid为获取userKey时的用户${eid}
        client_id: "i2ntHzlEsFKBcZCgfYVL", // 发票云授权标识
        sign: "1f399f3e48d1d0e556671ddbe60247f7", // ${sign}签名规则：MD5(client_id + client_secret + timestamp)
        timestamp: "1577324259001", // 签名时的时间戳${timestamp}
        name: "841c078bdcba4f60854f5c8728fa0b9e", // 连接名称，选择发票前获取的${linkKey} ，接口1.7
        onOpen: function () { // 连接成功的回调
            var socketName = this.name;
            if(socketName != ''){
                window.onhashchange = function () {// 如果碰到页面头部返回,iframe无法关闭，可以在打开的时候给当前地址加上hash,然后通过监听hash的方式关闭iframe
                     if (this.location.hash.indexOf('pwy') < 0) {
                         var fwy = document.getElementById('fwy');
                         if (fwy) {
                            fwy.parentNode.removeChild(fwy);
                         }
                     }
                }
                if (!isOpenSocket) {
                    window.location.hash = 'pwy' + new Date().getTime();
                    iframe.src = ${baseUrl} + /m4-web/dd/wap/index?userKey=${userkey} + '&socketName='+socketName + '&app=other' + '&model=no' + '&wechatCard=false'；
                    document.body.appendChild(iframe);
                }
                isOpenSocket = true;
            }else{
                console.log('未获取到连接名');
            }
        },
        onMessage: function (msg) { //从发票云采集完发票点击首页推送返回到当前页面时，此处会接收发票数据
            alert('获取到'+ msg.data.length +'条数据');
            if(iframe){// 关闭新增的地址
                window.history.go(-1);
                iframe.parentNode.removeChild(iframe);
                isOpenSocket = false;
             }
        },
        onError: function (errText, errCode) { //失败时的回调
            console.log("与发票云建立连接失败!");
            console.log("errText>>>" + errText);
            isOpenSocket = false;
        }
    })

msg消息返回格式

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

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

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

{
    "data":[
        {
            "canBeDeduction":1,
            "invoiceAmount":566.04, //不含税金额
            "localTempUrl":"blob:https://api-dev.piaozone.com/b3026f54-2c21-4721-8e6b-b565ba27549a",
            "invoiceType":4, //发票种类
            "attachSerialNoList":[//发票关联附件

            ],
            "invoiceNo":"01378561",
            "batchNo":"61d58d51971e4f1493f04e8949af0085",
            "buyerTaxNo":"91350200751602758A",
            "companySeal":"1",
            "invoiceCode":"3500203130",
            "checkCode":"",
            "serialNo":"83b8f2031daa4e5ebac09a53633793800", //发票流水号
            "totalAmount":600,
            "taxRate":"0.00",

            "recognitionSerialNo":"wcyba10fddda7ac4bb8bdeb476233c204fb0",
            "invoiceCodeConfirm":"3500203130",
            "totalTaxAmount":33.96,
            "taxAmount":"33.96",
            "region":"[0,0,553,356]",
            "items":[ //发票明细
                {
                    "unitPrice":"",
                    "taxRate":"6%",
                    "unit":"",
                    "num":"",
                    "detailAmount":"566.04",
                    "taxAmount":"33.96",
                    "goodsName":"*住宿服务*住宿费"
                }
            ],
        }
    ],
    "attachData":[

    ],
    "type":"updateInvoice",
    "certificateList":[

    ]
}

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

{
    "type": "updateInvoice",
    "data": {
        "billnumber": "2018-11-28-00001898", //单据编号
        "bxd_key": "Ik2TrOC5RSCOND0pE9J8=", //单据全球唯一key
        "data": [{
            "invoiceData": [{
                "salerAccount": "中国银行5218666111888",  //销方银行名称和账号
                "stationGeton": "",  //
                "classify": "other", //分类
                "amount": 50.91,  //不含税金额，飞机票则采用票价
                "salerName": "航信培训企业", //销方名称
                "invoiceDate": "2018-09-29", //开票日期
                "invoiceCode": "", //发票代码
                "serialNo": "", //发票流水号
                "totalAmount": 56, //价税合计
                "taxRate": "0.099980", //税率
                "seatGrade": "",
                "salerAddressPhone": "广东省深圳市南山区 xxxx", //销方地址电话
                "stationGetoff": "",
                "salerTaxNo": "", //销方税号
                "invoiceType": "1", //发票种类，1.普通电子发票2.电子发票专票3.普通纸质发票4.专用纸质发票5.普通纸质卷票7.通用机打8.的士票9.火车票10.飞机票11.其他 12.机动车 13.二手车14.定额发票15.通行费16.客运票17.过路过桥发票19.完税证明20.轮船票23通用机打电子发票
                "goodsCode": "3079900000000000000", //商品编码
                "taxAmount": 5.09, //总税额
                "invoiceNo": "", //发票号码
                "airItemsArr": [],  //如果是机票，可能有多条行程
                "goodsName": "*水果*苹果",  //商品名称
                "classifyName": "其他费用" //分类中文名
            }],
            "totalAmount": 60.3,
            "amount": 54.97,
            "costName": "其他费用",
            "size": 2,
            "costType": "other",
            "taxAmount": 6.33,
            "invoiceDate": "2018-09-29"
        }],
        "invoicesTotalAmount": 76.98,//发票金额总和
        "invoicesTaxAmount": 5.82,//发票税额总和
        "allSize": 3,//导入该单据的发票总数量
        "invoiceSerialNos":"e7601aa2a677467bbf0271fbde682d910,e7fde3adddbe46328aa3405085854c250",//当前单据导入的发票流水号集合
        "isElectronicInvoice": false,//当前单据导入的发票是否全是电票，true为是，false为否
        "userid": "eid-1544420896749"//对应用户的eid
    }
}

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

{
    "type": "updateInvoice",
    "data": {
        "billnumber":"", //对应传入的billnumber
        "bxd_key":"", //对应传入的bxd_key
        "type":"", //前端约定交互方式识别
        "userid":"", //对应传入的eid
        "isElectronicInvoice": false,//当前单据导入的发票是否全是电票，true为是，false为否
        "invoiceSerialNos":"e7601aa2a677467bbf0271fbde682d910,e7fde3adddbe46328aa3405085854c250",//当前单据导入的发票流水号集合
        "data":
            {
                //收款方信息集合
                "buyerInfo":[
                    {
                        "buyerName":"", //收款方企业名称
                        "buyerTaxNo":"", //收款方企业税号
                        "buyerAddressPhone":"", //收款方地址电话
                        "buyerAccount":"", //收款方银行帐号
                    }
                ],

                //采购列表信息,按供应商、品名划分
                "purchaseInfo":[
                    {
                        "salerName":"", //销方名称,即供应商名称
                        "salerTaxNo":"", //销方税号,即供应商税号
                        "goodsName":"", //品名
                        "goodsCode":"", //品名对应的商品编码
                        "invoiceDate":"", //日期,默认取第一个
                        "unit":"", //单位,默认取第一个
                        "num":"", //数量,数量总和
                        "unitPrice":"", //单价,平均单价
                        "detailAmount":"", //金额
                        "taxAmount":"", //合计税额
                        "size":"", //品名条数
                        "invoiceData":[] //发票流水号集合
                    }
                ]
            }
        }
    }

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

{
    "type": "updateInvoice",
    "data": {
        "billnumber": "RH-365-20181117-1054", //单据编号
        "bxd_key": "iCFJ7WdQTrxjJTCkx2fAmKk7FTnPXj=", //单据ID
        "type": "savebill",
        "userid": "", //用户eid
        "invoicesTotalAmount": 1000, //总价税合计总额
        "invoicesTaxAmount": 200, //总税额
        "data": [  //按税号、银行帐号划分
        {
            "salerTaxNo":"", //开票方税号
            "salerName":"", //开票方名称
            "salerAddressPhone":"", //开票方地址、帐号
            "salerAccount":"", //开票方银行开户行、帐号
            "amount": 1000,  //总金额(不含税)
            "taxAmount": 200, //总税额
            "totalAmount":"", //价税合计总额
            "invoiceType":"", //发票类型
            "invoiceNo":"", //发票号码
            "invoiceCode":"",//发票代码
            "goodsCode":"", //税收分类编码,发票数据中取第一条信息为准
            "goodsName":"", //货物名称,发票数据中取第一条信息为准
            "taxRate":"", //税率    ,发票数据中取第一条信息为准
            "serialNo":"" //发票流水号
        }]
    }
}

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

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

引入企业微信库jsSDK

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

postMessage相关代码

var pwyPostmessage = {
    initEvent: function(handler){
        handler = (typeof handler === 'function' ? handler: function(){});
        if(window.addEventListener){
            window.addEventListener("message", handler, false);
        }else{
            window.attachEvent("onmessage", handler);
        }
    },
    sendMsg: function(opt, target){
        target = target || '*';
        var fwyIframe = parent.document.getElementById("fwy");
        fwyIframe.contentWindow.postMessage(opt, target);
    }
}

pwyPostmessage.initEvent(function(onMessage){
    var type = onMessage.data.type;
    if(type == "wechatCard") { //固定值，拉取微信卡包电子发票列表（微信-电子发票）
        var opt = {
            corpID : ${corpID},
            timestamp : ${timestamp},
            nonceStr : ${nonceStr},
            cardPocketSign : ${cardPocketSign},
            configSign : ${configSign},
            accessToken : ${accessToken}
        }
        openWxCard(opt);
    } else if(type == "scanCode") { //固定值，拉取企业微信扫一扫
        var opt = {
            corpID: ${corpID},
            timestamp: ${timestamp},
            nonceStr: ${nonceStr},
            configSign: ${configSign}
        }
        openScanQrCode(opt);
    }
});

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”


{
    "errcode": "0000",
    "description": "成功",
    "data": {
        "configSign": "******", //wx.config 配置中的 sign
        "ticket": "******",
        "accessToken": "******",
        "cardPocketSign": "******",  wx.invoke中的 cardSign
        "nonceStr": "******",
        "timestamp": "1629853754709"
    }
}

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

拉取微信电子发票列表

function openWxCard(opt){
    wx.config({
        beta: true, //必填
        appId: opt.corpID, //必填，
        timestamp: opt.timestamp, //必填
        nonceStr: opt.nonceStr, //必填
        signature: opt.configSign, //必填
        jsApiList: ['chooseInvoice']  //必填，
    });
    wx.error(function(res){
        console.log('config配置失败---', res);
    });
    wx.ready(function(){
        console.log('准备拉起', opt);
        wx.invoke('chooseInvoice', {
            'timestamp': opt.timestamp, // 卡券签名时间戳
            'nonceStr': opt.nonceStr, // 卡券签名随机串
            'signType': 'SHA1',
            'cardSign': opt.cardPocketSign, // 卡券签名
        }, function(res) {
            console.log('结构---', JSON.stringify(res)); // 返回的结果
            if(res.err_msg == 'ok') {
                var invoiceList = res.choose_invoice_info; //发票id
                pwyPostmessage.sendMsg({ //通知发票云界面解析发票
                    type: 'qywxCardBack',  //固定值
                    result: {
                        accessToken: opt.accessToken
                        itemList: invoiceList
                    } //发票数据
                }, '*');
            } else if(res.err_msg == 'fail') {
               alert(res.err_info);
            }
        });
    });
}

拉取企业微信扫一扫

function openScanQrCode(opt){
    wx.config({
        beta: true, //必填
        appId: opt.corpID, //必填，
        timestamp: opt.timestamp, //必填
        nonceStr: opt.nonceStr, //必填
        signature: opt.configSign, //必填
        jsApiList: ['scanQRCode']  //必填
    });
    wx.ready(function(){
        wx.scanQRCode({
            desc: 'scanQRCode desc',
            needResult: 1, // 默认为0，扫描结果由企业微信处理，1则直接返回扫描结果，
            scanType: ["qrCode"], // 可以指定扫二维码还是条形码（一维码），默认二者都有
            success: function(res) {
                // 回调
                pwyPostmessage.sendMsg({ //通知发票云界面解析二维码内容
                    type: 'scanResult',  //固定值
                    result: res.resultStr //二维码内容
                }, '*');
            },
            error: function(res) {
                if (res.errMsg.indexOf('function_not_exist') > 0) {
                    alert('版本过低请升级')
                }
            }
        });
    });
}

常见问题处理

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

<script src="https://unpkg.com/vconsole/dist/vconsole.min.js"></script>;

var vConsole = new VConsole();

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	报销单 ID
client_id	String	创建当前报销单的发票云授权标识
timestamp	String	时间戳
sign	String	签名规则见对接约定, clientSecret 和 clientId 由发票云分配
encType	Int	签名加密类型 0：MD5、1：SHA256、2：HMAC SHA256，不传默认MD5加密
ticketParam	String	发票校验过滤规则，格式如：11011

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

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

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

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

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

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

请求接口参数示例

{
    "client_id": "创建当前报销单的发票云授权标识",
    "sign": "签名,签名规则见对接约定",
    "encType": 0,
    "timestamp": "时间戳",
    "bxd_key": "weqasdaqweqweqe"
}

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

接口地址：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	创建当前报销单的发票云授权标识
timestamp	String	时间戳
sign	String	签名规则见对接约定, clientSecret 和 clientId 由发票云分配
encType	Int	签名加密类型 0：MD5、1：SHA256、2：HMAC SHA256，不传默认MD5加密
type	String	EXPENSE_SERIALNO_QUERY //固定值
buyerName	String	购方抬头
buyerTaxNo	String	购方税号
ticketParam	String	发票校验过滤规则，格式如：1101
certifacateSerialNos	Array	附件流水号
invoiceSerialNos	Array	发票流水号
expenseId	String	报销单ID

请求接口参数示例

{
    "client_id": "创建当前报销单的发票云授权标识",
    "data": {
        "buyerName": "校验发票抬头企业名称不一致提示",
        "buyerTaxNo": "校验发票抬头税号不一致提示",
        "certifacateSerialNos": [
            "附件流水号1",
            "附件流水号1"
        ],
        "invoiceSerialNos": [
            "发票流水号1",
            "发票流水号2"
        ],
        "ticketParam": "校验报销拦截参数",
        "expenseId":"报销单ID"
    },
    "sign": "签名:MD5(client_id+client_secret+timestamp)",
    "encType": 0,
    "timestamp": "时间戳",
    "type": "EXPENSE_SERIALNO_QUERY"
}

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

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

参数说明

参数	类型	描述
checkDetail	String	固定值 true
serialNo	String	发票流水号
userKey	String	生成规则查看 userKey 接口

票夹流程

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

参数说明

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

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

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

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

对接方式

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

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

    {
        "type": "updateInvoice",
        "data": {
            "key" : "",
            "from":"",
            "clientId":"",
            "bxdKey":"",
            "data": [
                {
                    "serialNo": 影像附件流水号
                    "gatherTime": 采集时间
                    "attachmentName": 附件名称
                    "attachmentType": 附件类型:1、pdf,2、图片
                    "remark": 备注
                    "originalFileName": 原文件名
                    "fileHash":"", //文件hash
                    "localUrl":"", //源文件地址
                    "snapshotUrl":"", //快照地址
                    "rotationAngle":"", //源文件角度
                }
            ]
            
        }
    }

单据审核中只补附件流程

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

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

请求方式： GET

参数说明

参数	是否必须	类型	描述
userKey	是	String	生成规则查看 userKey 接口
socketName	String	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保存单据

最后修改时间： 5 个月前