开发指南

适用范围

本文档适用阅读人员包括：发票云的设计、开发人员，合作伙伴。
适用于航天信息金税盘或百望税控盘设备, 或已经对接本接口但想开数电票的客户。
适用发票云组件版本： 1.2.4或更新

环境地址

针对非托管的税控和数电开票的地址如下，托管的请参考：托管开票开发指南

• 测试环境：https://api-sit.piaozone.com/test/bill-websocket/invoicewebsocket/push
• 生产环境：https://api.piaozone.com/bill-websocket/invoicewebsocket/push

注意：如果用本api平台做测试，请选择用“wss测试环境”或“wss生产环境”

版本说明（重要）📌

目前单机组件开票有多个版本。

• v1和v3覆盖单机版组件能力的所有接口，唯一区别是v3比v1在环境地址上多了一个/v3
• v4只针对数电异步开票目录下的接口

版本	说明	生产环境地址	测试环境地址
v1	早期版本，只适用于组件开票（税控）	https://api.piaozone.com/bill-websocket/invoicewebsocket/push	https://api-sit.piaozone.com/test/bill-websocket/invoicewebsocket/push
v3	支持数电票同步开票（推荐）	https://api.piaozone.com/bill-websocket/v3/invoicewebsocket/push	https://api-sit.piaozone.com/test/v3/invoicewebsocket/push
v4	支持数电票异步开票（维护开发中）	https://api.piaozone.com/bill-websocket/v4/invoicewebsocket/push	https://api-sit.piaozone.com/test/v4/invoicewebsocket/push

连接方式（只适合税盘）

接口均为 POST 方式，只支持 Content-Length 报文编码，不支持 Chunk 编码
所有接口均使用 UTF-8 编码请求与返回

有两种连接方式：

1. IP直连方式
   适用于局域网内的HTTP调用方式，默认端口为 61624

2. 通过接口长连接方式调用
   这种方式下，税盘开票需要增加name参数，参数值=client_secret+盘号。
   例子：

• 接口地址：https://api.piaozone.com/bill-websocket/invoicewebsocket/push
• client_secret（发票云授权信息） ：3de1f420ed08409bbc3d4b9a156b4945
• 盘号为：3312345667
  则链接地址为https://api.piaozone.com/bill-websocket/invoicewebsocket/push?name=3de1f420ed08409bbc3d4b9a156b49453312345667

请求参数

字段	类型	是否必须	描述
messageId	string	是	本次请求的编号，用于后端区分（可以使用时间戳作为编号）
request_path	string	是	请求的组件接口资源路径 （默认为 / ）
...	...	...	其他接口参数