发票云(旗舰版)API文档
旗舰版标准版智能特性
旗舰版标准版智能特性
🤖 AI Support​​
    • 整体介绍
    • 快速开始
    • 加解密
    • 文件预览&文件上传&文件下载
    • 发票数据结构
    • 错误码
    • 常见接口错误
    • 场景指引
      • 概述
      • 直接开票
      • 单据开票
      • 扫码开票
    • 授权
      • 1.01.获取app_token
        POST
      • 1.02获取access_token
        POST
    • 开票
      • 单据开票接口（税控+数电）
        • 单据开票对接指引
        • 开票申请单错误码列表
        • 1.1.01 开票申请单生成及开票（支持拆分合并后，再开票）
        • 1.1.02 开票申请单撤回（对接方主动撤回）
        • 1.1.03 开票申请单发票查询
        • 1.1.04 开票申请单快速红冲（仅支持税控普票）
        • 1.1.05 开票申请单批量作废（作废单据的发票，仅支持税控纸票）
        • 1.1.06 开票申请单红冲单或作废单生成（星瀚发票云版本5.0.015支持，不支持数电票）
        • 1.1.07 开票申请单重开单生成（星瀚发票云版本5.0.015支持，不支持数电票）
        • 1.1.08 创建负数单匹配任务
        • 1.1.09 查询负数单匹配任务结果
        • 1.1.10 单据开票预览
      • 直接开票接口
        • 数电开票
          • 接入指引（必看）
          • 返回编码说明
          • FAQ
          • 电子税局操作
            • 2.1.30 电子税局登录检测
          • 2.1.01 数电票蓝字发票开具
          • 2.1.02 数电票回调
          • 2.1.03 红字确认单生成
          • 2.1.04 数电票红冲（直接红冲或通过红字确认单）
          • 2.1.05 授信额度查询
          • 2.1.08 红字确认单撤销
          • 2.1.09 红字确认单确认或拒绝
          • 2.1.12 红字确认单下载
          • 2.1.13 红字确认单编号查询
          • 2.1.14 发票用途状态查询（发票云版本6.0.11支持，暂只支持乐企）
        • 税控开票
          • 2.2.01税控开票（直接开票，不支持拆分合并）
          • 2.2.02税控发票快速红冲（仅支持全额红冲）
          • 2.2.03税控发票作废
          • 2.2.04税控红字信息表申请
          • 2.2.05税控红字信息表下载
          • 2.2.06税控发票库存查询
          • 2.2.07税控开票设备查询
          • 2.2.08税控发票打印发票打印（需安装套打打印组件，仅适用于局域网内的HTTP调用方式）
          • 2.2.09税控发票打印（仅适用于组件开票，托管无法使用）
          • 2.2.10邮件短信重发（数电票和税控发票都支持）
          • 2.2.11税控机动车发票开具
          • 2.2.12税控机动车发票作废
          • 2.2.13税控机动车发票红冲
          • 2.2.14税控机动车发票打印
          • 2.2.15机动车信息查询（数电专用）
      • 发票查询接口
        • 4.1.01已开发票查询
        • 4.1.02机动车发票查询（税控）
        • 4.1.03.数电票发票批量查询
        • 4.1.04.数电票发票单张查询
      • 回调接口（支持除数电票直接开票接口外的开票回调）
        • 5.1.01开票申请单回退接口（星瀚发起退回开票申请单）
        • 5.1.02回调接口-按票回调(一次回调一张发票信息)
        • 5.1.03回调接口-按单回调（单据对应的所有发票开票完毕后一起回调（包含开票成功和开票失败），不支持合并又拆分的场景）
      • 开票风控接口
        • 6.0.01 风控解除接口（星瀚发票云版本6.0.6支持）
      • 扫码开票接口（税控+数电）
        • 业务系统生成二维码链接模式
          • 3.1.01业务系统组装二维码链接格式
          • 3.1.02查询订单接口(由客户提供)
          • 3.1.03 扫码提交购方抬头规则
          • 3.1.04账单中心开票小程序短链接生成
        • 推单星瀚生成二维码链接模式
          • 3.2.01上传销售单获取二维码链接
    • 收票
      • 全票池引入
        • 5.01全票池导入
      • 收票报销
        • 发票助手对接流程
        • 3.01 打开发票采集页面获取eventCode
        • 3.02 查看发票获取eventCode
        • 3.03 保存单据
        • 3.04 删除单据
        • 3.05 保存凭证
        • 3.06 删除凭证
        • 3.07 长轮询获取发票信息
        • 3.08 发票验重
      • 查询全票池的发票
        • 1.01 发票查询
        • 1.02 发票查询（按流水号查询）
        • 1.03获取单据文件信息
        • 1.04 删除全票池发票
      • 税局下载发票和勾选认证
        • 4.01 税局登录
        • 4.02 进项发票表头归集
        • 4.03 进项发票表头归集结果查询
        • 4.04 获取税款所属期信息
        • 4.05 发票勾选&撤销勾选
        • 4.06 发票勾选结果查询
        • 4.07 当前统计查询
        • 4.08 生成&撤销统计表
        • 4.09 生成&撤销统计表结果查询
        • 4.10 确认统计表
        • 4.11 确认统计表结果查询
        • 4.12 变更税款所属期
        • 4.13 发票预勾选
        • 4.14 发票预勾选确认
        • 4.15 预勾选确认结果查询
        • 4.16 批量创建税局入账申请任务
        • 4.17 查询税局入账申请任务结果
      • 识别查验
        • 2.01 发票查验
        • 2.02 发票识别查验
        • 2.03 文件上传
        • 2.04 发票编辑
      • 微服务接口
    • 页面类
      • 基础设置页面
        • 基础设置相关页面
      • 开票页面
        • 开票相关页面
      • 收票页面
        • PC端打开选择发票页面
        • PC端打开查看发票页面
        • 移动端打开查看发票页面
        • 移动端打开选择发票页面
      • 数据统计页面
        • 销项发票统计页面
      • 2.1、退出登录API接口
    • 影像
      • 开发指南
      • 1.基础接口
        • 1.01获取eventCode
        • 1.02接收ERP单据推送接口
      • 2.影像页面
        • 2.01PC端影像调阅
        • 2.02移动端影像调阅
        • 2.03影像采集页面
        • 2.04影像匹配结果页面
      • 3.影像操作
        • 3.01影像退扫
        • 3.02影像取消退扫
        • 3.03影像删除
        • 3.04获取PC端影像调阅页面地址
        • 3.05获取移动端影像调阅页面地址
        • 3.06影像状态查询
      • 4.采集接口
        • 4.01影像文件采集
        • 4.02影像单据提交
    • 档案
      • 对接说明（电子档案云旗舰版）
      • 异构系统接口定义
    • 设置类
      • 3.1、切换组织
      • 3.2、新增组织（星空ERP专用）
      • 3.3、新增租户组织下的员工
      • 3.4、查询电子税局账号
    • 订单
      • 1.01 产品订阅（平台服务商专用）
      • 发票云创建组织

    快速开始

    概述#

    本文通过演示底下几个常用能力对接步骤，让开发者快速了解发票云旗舰版的对接流程。
    开票能力-单据开票
    开票能力-直接开票(数电开票)
    收票能力-嵌入发票采集页面
    关于单据开票和直接开票的区别，可参考单据开票和直接开票两个文档的场景介绍一节。

    环境申请#

    新用户可联系发票云售前(热线：400-968-8220)申请沙箱环境，申请成功后返回：环境地址、登录账号、appId、appSecret、accountId等对接API的必要参数用于接口测试。
    本文所用的沙箱环境信息如下，读者可根据申请到的环境信息做替换：
    沙箱环境我们会默认初始化好常用配置。如果是正式环境或想个性化配置沙箱环境，请参考：星瀚发票云API对接配置

    开票对接-单据开票#

    整体流程#

    image.png

    操作步骤#

    1.获取app_token#

    请求地址: baseUrl+/api/getAppToken.do
    请求参数:
    注：请用申请到的用户信息替换上述参数，下同。
    返回示例：

    2.根据apptoken，获取access_token#

    请求地址: baseUrl + /api/login.do
    请求参数:
    apptoken用上一个接口获取的值（有有效期）；其它直接用示列参数发起请求，获取access_token
    返回示例：

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

    用上一步获取的access_token调用单据开票接口，下推开票申请单。
    请求地址: baseUrl + /kapi/app/sim/openApi?access_token={access_token}
    请求参数:
    上面报文的data字段的值，为底下请求数据做base64后的值：
    返回示例：

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

    登录地址: baseUrl/login.html
    账号: （你申请的账号）
    密码: （你的密码）
    image.png
    image.png
    image.png
    如果没看到，可以尝试去掉过滤条件

    附:postman文件#

    我们针对以上步骤，制作了一个postman的collection示例文件作参考。
    *注：该文件包含了第3步提及的base64编码的postman前置脚本（Pre-request Script）；如你的版本不支持此类脚本，也可到这网站手工将data字段转Base64。

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

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

    整体流程#

    image.png

    操作步骤#

    1. 获取app_token和access_token#

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

    2. 上传开票数据#

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

    3.查询开票结果#

    接口定义: 4.1.04.数电票发票单张查询
    请求地址: baseUrl + /kapi/app/sim/openApi?access_token={access_token}
    请求参数：
    返回示例
    该报文是将真实返回报文的data字段的值做Base64解密后的结果。

    4.验证开票结果#

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

    附.Postman文件#

    我们针对以上步骤，制作了一个postman的collection示例文件作参考。
    注：该文件包含了base64编码的postman前置脚本（Pre-request Script）；如你的版本不支持此类脚本，也可到这网站手工将data字段转Base64。

    收票对接#

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

    整体流程#

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

    操作步骤#

    1. 获取app_token和access_token#

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

    2.获取eventCode#

    请求地址: baseUrl + /kapi/app/rim/message?access_token={access_token}
    请求参数：
    注意
    1.
    这里linkKey值，要和下面建立websocket链接的identifytype参数一致
    2.
    taxNo和name要用申请环境时的税号、企业名称
    返回示例

    3.建立websocket链接#

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

    4.打开发票采集页面#

    第三方系统页面嵌入发票采集页面。
    信息
    1.
    这里需要用iframe方式嵌入发票采集页面，否则认证会出问题
    2.
    移动端：安卓系统或小程序也可以这么嵌入
    3.
    移动端：IOS因安全问题，可能这么嵌入是打不开，方案【待补充】

    5.整合起来#

    为方便开发者测试，我们将上述步骤整合起来，做了一个postman的collection[下载]和html示例代码[下载]。
    用PC打开该页面，并填写
    image.png
    点击“打开页面”
    如果出现以下发票采集页面，则说明打开成功。
    image.png
    采集发票
    如果您按上述步骤的参数打开的页面，可以通过【电脑上传】上传发票
    image.png
    需上传申请eventCode时传入的税号和企业名称作为购方的发票，否则会提示不合规
    导入单据
    点击右下角的【导入单据】按钮，如果出现下图的弹框，说明PC页面已经收到服务端通过websocket推送的发票数据。
    image.png
    至此，对接完毕！

    下一步#

    经过上述步骤，开发者已完整打通发票云旗舰版的API，接下来你可以查看：
    场景指引
    加解密
    认证接口的更多描述
    修改于 2024-11-05 06:52:32
    上一页
    整体介绍
    下一页
    加解密
    Built with