快速开始

概述

本文通过演示底下几个常用能力对接步骤，让开发者快速了解发票云旗舰版的对接流程。

开票能力-单据开票
开票能力-直接开票(数电开票)
收票能力-嵌入发票采集页面

关于单据开票和直接开票的区别，可参考单据开票和直接开票两个文档的场景介绍一节。

环境申请

新用户可联系发票云售前(热线：400-968-8220)申请沙箱环境，申请成功后返回：环境地址、登录账号、appId、appSecret、accountId等对接API的必要参数用于接口测试。

本文所用的沙箱环境信息如下，读者可根据申请到的环境信息做替换：

baseUrl: https://cosmic-sandbox.piaozone.com/jdpjykjyxgs
登录账号: 15815530006 # web登录账号（非必须）
user: 15815530006
appId: FPY001
appSecret: FPY001fpy@2023*** # app密钥（已部分脱敏，有需要联系售前获取)
accountId: 1742050739649250304
businessSystemCode: BUSINESS_FPY # 业务系统编码
sellerTaxpayerId: 91440300MA5G9GK78Y, # 申请沙箱时填的税号
sellerName: 金蝶票据云科技(深圳)有限公司, # 申请沙箱时填的企业名称

沙箱环境我们会默认初始化好常用配置。如果是正式环境或想个性化配置沙箱环境，请参考：星瀚发票云API对接配置

开票对接-单据开票

整体流程

操作步骤

1.获取app_token

请求地址: baseUrl+/api/getAppToken.do
请求参数:

{
    "appId": "FPY001",
    "appSecret": "FPY001fpy@2023fpy",
    "accountId": "1742050739649250304"
}

注：请用申请到的用户信息替换上述参数，下同。

返回示例：

{
    "data": {
        "app_token": "e42bf075-695d-49f6-8040-7aeea3903027",
        "success": true,
        "error_desc": "",
        "expire_time": 1708414721911,
        "error_code": "0"
    },
    "state": "success",
    "status": true
}

2.根据apptoken，获取access_token

请求地址: baseUrl + /api/login.do
请求参数:

{
    "user": "15815530006",
    "apptoken": "e42bf075-695d-49f6-8040-7aeea3903027",
    "accountId": "1742050739649250304"
}

apptoken用上一个接口获取的值（有有效期）；其它直接用示列参数发起请求，获取access_token

返回示例：

{
    "data": {
        "access_token": "1742050739649250304_MBB21m4dd2w8RGbv7o1Mkypn7yBd1lBnN3ghr9ybEBJQAI3IVJRhWc9XTFrNOrN7BUghq4j4knv6b19zSW9uNK851RRvQima7x52",
        "success": true,
        "error_desc": "",
        "expire_time": 1708414785680,
        "error_code": "0"
    },
    "state": "success",
    "status": true
}

3. 调用单据开票接口下推开票申请单

用上一步获取的access_token调用单据开票接口，下推开票申请单。
请求地址: baseUrl + /kapi/app/sim/openApi?access_token={access_token}
请求参数:

{
"requestId":"1624601109096",
"businessSystemCode":"BUSINESS_FPY",
"interfaceCode":"BILL.PUSH",
"data":"W3siYmlsbE5vIjoiaWRzLXVhdC0zc3RkMS0yOSIsImJpbGxEYXRlIjoiMjAyMy0wNS0xNyIsInRvdGFsQW1vdW50IjoxMTMwMCwiYXV0b0ludm9pY2UiOiIxIiwiaW52b2ljZVR5cGUiOiIwOHhkcCIsImJ1eWVyTmFtZSI6Iua3seWcs+W4gumhuuS4sOW/q+i/kOaciemZkOWFrOWPuHRlc3QwMSIsImJ1eWVyUHJvcGVydHkiOiIwIiwic2VsbGVyVGF4cGF5ZXJJZCI6IjkxNDQwMzAwTUE1RzlHSzc4WSIsInNlbGxlck5hbWUiOiLph5Honbbnpajmja7kupHnp5HmioAo5rex5ZyzKeaciemZkOWFrOWPuCIsInNlbGxlckJhbmtBbmRBY2NvdW50IjoiMTM3MTA4ODQ3MDQiLCJzZWxsZXJBZGRyZXNzQW5kVGVsIjoi6auY5paw5oqA5pyv5Lqn5Lia5Zut5Y2X5Yy656eR5oqA5Y2X5Y2B5LqM6LevNTg5OTY5ODkiLCJkcmF3ZXIiOiLlvIDnpajkuroiLCJiaWxsRGV0YWlsIjpbeyJhbW91bnQiOjExMzAwLCJkZXRhaWxJZCI6IjExOTQxMjE2NjE5ODk3OTY2NjYiLCJnb29kc05hbWUiOiLonILog7blj6PohZTohpwiLCJsaW5lUHJvcGVydHkiOjIsInByaWNlIjoxMTMwMCwicXVhbnRpdHkiOjEsInJldmVudWVDb2RlIjoiMTA3MDMwNDk5MDAwMDAwMDAwMCIsInRheFJhdGUiOiIwLjEzIiwidW5pdHMiOiLkuKoifV19XQ=="
}

上面报文的data字段的值，为底下请求数据做base64后的值：

[{
  "billNo": "ids-uat-3std1-29",
  "billDate": "2023-05-17",
  "totalAmount": 11300,
  "autoInvoice": "0",
  "invoiceType": "08xdp",
  "buyerName": "深圳市顺丰快运有限公司test01",
  "buyerProperty": "0",
  "sellerTaxpayerId": "91440300MA5G9GK78Y",
  "sellerName": "金蝶票据云科技(深圳)有限公司",
  "sellerBankAndAccount": "13710884704",
  "sellerAddressAndTel": "高新技术产业园南区科技南十二路58996989",
  "drawer": "开票人",
  "billDetail": [{
     "amount": 11300,
     "detailId": "1194121661989796666",
     "goodsName": "蜂胶口腔膜",
     "lineProperty": 2,
     "price": 11300,
     "quantity": 1,
     "revenueCode": "1070304990000000000",
     "taxRate": "0.13",
     "units": "个"
   }]
}]

返回示例：

{
    "message": "开票申请单推送成功",
    "errorCode": "0",
    "status": true,
    "success": true
}

4. 登录系统查看推单【可选】

登录地址: baseUrl/login.html
账号: （你申请的账号）
密码: （你的密码）

如果没看到，可以尝试去掉过滤条件

附:postman文件

我们针对以上步骤，制作了一个postman的collection示例文件作参考。

*注：该文件包含了第3步提及的base64编码的postman前置脚本（Pre-request Script）；如你的版本不支持此类脚本，也可到这网站手工将data字段转Base64。

开票对接-直接开票(数电开票)

本章介绍如何通过接口，直接开出一张数电发票（虚拟票）。

整体流程

操作步骤

1. 获取app_token和access_token

参照上文的：获取app_token和获取access_token

2. 上传开票数据

接口定义: 2.1.01 数电票蓝字开票接口
请求地址: baseUrl + /kapi/app/sim/openApi?access_token={access_token}
请求参数：

{
  "requestId": "1624601109096",
  "businessSystemCode": "BUSINESS_FPY",
  "interfaceCode": "ALLE.INVOICE.OPEN",
  "data": {
    "serialNo": "202403011709193622529", // 开票流水号
    "invoiceType": "02",
    "sellerName": "金蝶票据云科技(深圳)有限公司",
    "sellerTaxpayerId": "91440300MA5G9GK78Y",
    "sellerBank": "中国银行深圳皇岗支行1111111111",
    "sellerBankAccount": "4000027219200486412",
    "sellerAddress": "高新技术产业园南区科技南十二路11111111111111",
    "buyerName": "深圳金蝶账无忧网络科技有限公司",
    "buyerTaxpayerId": "91440300358768292H1",
    "drawer": "张三",
    "invoiceDetail": [
      {
        "lineProperty": "0",
        "goodsName": "纸电一体开收票",
        "amount": 2000,
        "taxRate": "0.01",
        "revenueCode": "3040201010000000000"
      }
    ]
  }
}

返回示例

{
  "data": "MjAyNDAzMDExNzA5MTkzNjIyNTIx", //用Base64解密后，为请求参数中的开票流水号：serialNo
  "errorCode": "0",
  "status": true,
  "success": true
}

3.查询开票结果

接口定义: 4.1.04.数电票发票单张查询
请求地址: baseUrl + /kapi/app/sim/openApi?access_token={access_token}
请求参数：

{
    "requestId": "string",
    "businessSystemCode": "BUSINESS_FPY",
    "interfaceCode": "ALLE.INVOICE.QUERY",
    "data": {
        "serialNo": "202403011709193622529", //与上面请求的流水号参数一致
        "invoiceNum": "",
        "sellerTaxpayerId": "91440300MA5G9GK78Y" //与上面请求的销方税号参数一致
    }
}

返回示例

{
  "data": {
    "batch": "BUSINESS_FPY202403021304386175029",
    "billDate": "2024-03-02 13:04:38",
    "orderNo": "3Z04T3JTCPXUGKISUPQT",
    "buyerType": 3,
    "systemSource": "BUSINESS_FPY",
    "serialNo": "202403011709193622519",
    "invoiceType": "02",
    "sellerTaxpayerId": "91440300MA5G9GK78Y",
    "sellerName": "金蝶票据云科技(深圳)有限公司",
    "sellerAddress": "高新技术产业园南区科技南十二路11111111111111",
    "sellerBank": "中国银行深圳皇岗支行1111111111",
    "sellerBankAccount": "4000027219200486412",
    "buyerTaxpayerId": "91440300358768292H1",
    "buyerName": "深圳金蝶账无忧网络科技有限公司",
    "drawer": "张三",
    "includeTaxAmount": 2020,
    "totalAmount": 2000,
    "totalTaxAmount": 20,
    "invoiceDate": "2024-03-02 13:04:38",
    "invoiceNum": "18971330115230924800",
    ... //为便于展示，省略部分内容
    "invoiceFileUrl": "https://api-dev.piaozone.com/test/base/download/pdf/invoice-pdf-storage/ASYNC/simeinvtest/3Z04T3JTCPXUGKISUPQT.pdf",
    "ofdFileUrl": "https://api-dev.piaozone.com/test/base/download/ofd/invoice-ofd-storage-test/ASYNC/simeinvtest/3Z04T3JTCPXUGKISUPQT.ofd",
    "xmlFileUrl": "https://api-dev.piaozone.com/test/base/download/files/invoice-zip-storage-test/ASYNC/simeinvtest/3Z04T3JTCPXUGKISUPQT.zip",
    "invoiceDetail": [
        {
            "seq": 0,
            "revenueCode": "3040201010000000000",
            "goodsName": "*信息技术服务*纸电一体开收票",
            "quantity": "0E-13",
            "price": "0E-13",
            "taxUnitPrice": 0,
            "amount": 2000,
            "includeTaxAmount": 2020,
            "taxRate": "0.01",
            "taxAmount": 20,
            ... //为便于展示，省略部分内容
        }
    ],
  },
  "errorCode": "0",
  "status": true,
  "success": true
}

该报文是将真实返回报文的data字段的值做Base64解密后的结果。

4.验证开票结果

将上述返回报文的invoiceFileUrl下载并打开，验证该已开发票的板式和内容。

附.Postman文件

我们针对以上步骤，制作了一个postman的collection示例文件作参考。

注：该文件包含了base64编码的postman前置脚本（Pre-request Script）；如你的版本不支持此类脚本，也可到这网站手工将data字段转Base64。

收票对接

本章介绍如何通过嵌入旗舰版发票采集页面，实现第三方系统快速集成发票云收票能力。

整体流程

获取apptoken和access_token（和上文的开票对接一样）
获取evenCode，用于嵌入页面前，将组织和单据信息缓存到服务端：3.01 打开发票采集页面获取eventCode
建立websocket链接
打开【发票采集页面】：PC端打开选择发票页面
用户点击【导入单据】，发票云旗舰版会用长连接推送发票数据到三方系统

操作步骤

1. 获取app_token和access_token

参照上文的：获取app_token和获取access_token

2.获取eventCode

请求地址: baseUrl + /kapi/app/rim/message?access_token={access_token}
请求参数：

{
    "messageType": "getEventCode",
    "messageId": "1",
    "data": {
        "billId": "1",
        "billNo": "1",
        "billType": "普通单",
        "resource ": "单据来源系统",
        "billTaxNo": "91440300MA5G9GK99K",
        "userId": "18126533510",
        "pushType": "socket",
        "linkKey": "socket123456789",
        "companyInfo": [
            {
                "taxNo": "91440300MA5G9GK78Y",
                "name": "金蝶票据云科技(深圳)有限公司"
            }
        ]
    }
}

:::caution

这里linkKey值，要和下面建立websocket链接的identifytype参数一致
taxNo和name要用申请环境时的税号、企业名称
:::

返回示例

{
  "data": {
    "eventCode": "ca05b4453ddc437bbcc1390ad9c075fa0"
  },
  "message": "成功",
  "errorCode": "0000",
  "status": true,
  "success": true
}

3.建立websocket链接

var httpUrl = "https://cosmic-sandbox.piaozone.com/jdpjykjyxgs/";
var wssUrl = "wss://cosmic-sandbox.piaozone.com/jdpjykjyxgs/" // 规律：将环境地址https改为wss（如果是http则改为ws）
var accessToken = "..."; // 上文第1步获取的access_token
var eventCode = "...";   // 上文第2步获取的eventCode
var identifytype = ".."  // 获取eventCode时，传入的linkKey参数

var socket = new WebSocket(wssUrl + "msgwatch/?identifytype=" + identifytype + "&token=" + accessToken);
//打开事件
socket.onopen = function () {
    alert("连接成功");
    setInterval(function () {
    socket.send("{\"handshake\":false}");
    }, 20000)
};
//获得消息事件
socket.onmessage = function (msg) {
    alert("接收消息:" + msg.data);
};
//关闭事件
socket.onclose = function () {
    alert("连接关闭");
};
//发生了错误事件
socket.onerror = function () {
    alert("连接失败");
}

:::caution
这里identifytype值，要调用获取eventCode接口传入的linkKey参数一致
:::

4.打开发票采集页面

第三方系统页面嵌入发票采集页面。

<iframe id="iframe" style="width: 1150px; height: 600px;padding:2px; border:1px solid #ccc;"></iframe>

<script>
// 上一步的变量...
var reqUrl = encodeURIComponent(httpUrl + 'index.html?formId=rim_fpzs_main&&eventCode=' + eventCode);
$("#iframe").attr("src", httpUrl + "accessTokenLogin.do?encode=true&access_token=" + accessToken + '&redirect=' + reqUrl);
</script>

:::info

这里需要用iframe方式嵌入发票采集页面，否则认证会出问题
移动端：安卓系统或小程序也可以这么嵌入
移动端：IOS因安全问题，可能这么嵌入是打不开，方案【待补充】
:::
5.整合起来
为方便开发者测试，我们将上述步骤整合起来，做了一个postman的collection[下载]和html示例代码[下载]。

用PC打开该页面，并填写
点击“打开页面”
如果出现以下发票采集页面，则说明打开成功。
采集发票
如果您按上述步骤的参数打开的页面，可以通过【电脑上传】上传发票

需上传申请eventCode时传入的税号和企业名称作为购方的发票，否则会提示不合规
导入单据
点击右下角的【导入单据】按钮，如果出现下图的弹框，说明PC页面已经收到服务端通过websocket推送的发票数据。

至此，对接完毕！

下一步

经过上述步骤，开发者已完整打通发票云旗舰版的API，接下来你可以查看：
场景指引
 加解密
 认证接口的更多描述

最后修改时间： 1 个月前

快速开始

概述

环境申请

开票对接-单据开票

整体流程

操作步骤

1.获取app_token

2.根据apptoken，获取access_token

3. 调用单据开票接口下推开票申请单

4. 登录系统查看推单【可选】

附:postman文件

开票对接-直接开票(数电开票)

整体流程

操作步骤

1. 获取app_token和access_token

2. 上传开票数据

3.查询开票结果

4.验证开票结果

附.Postman文件

收票对接

整体流程

操作步骤

1. 获取app_token和access_token

2.获取eventCode

3.建立websocket链接

4.打开发票采集页面

5.整合起来

下一步