票通电子发票平台对接指引 V1.0 北京票通信息技术有限公司 2024 年 10 月 16 日 修订文档历史记录 日期 版本 2024-10-16 <1.0> 说明 编写初稿，包括对接文档及 sdk 获取，企业注册开通说明， 开票场景，冲红场景，数电账号管理、补充场景说明等内容 作者 饶森林 本文档基于票通电子发票平台提供的接口能力进行说明，为合作伙伴对接票通系统时提 供简要指引和参考。 一、对接前事项 票通提供对接服务，随时可启动对接。对接前合作伙伴或客户需提供一些简单的信息。 接入方名称： 接入方联系人及电话： 接入方产品类型：企业定制开发产品、企业私有化部署系统、SaaS 产品 接入方产品所属行业：餐饮收银、物业收银、停车收费、供热收费等等 接入方需要的开票场景：扫码开票、订单开票、小程序开票、支付开票等 接入方预计服务的企业数量：用于评估需要接入的接口范围 该信息可发给票通商务人员，或直接发到对接沟通群。 二、如何启动对接 票通商务人员确认需要提供对接服务时，建立微信群，拉入相关的人员，票通侧需拉入 产品人员、对接人员、服务或运营人员。客户侧视客户情况拉入相关人员，一般建议有商务、 产品和研发人员。 在微信群，票通对接人员发送标准接口文档《票通数电发票接口文档 3.X.X.pdf》和 SDK 工具包，目前 SDK 工具包支持 Java 和 C#两种开发语言。 对接所需的测试环境及参数信息：如平台编码，RSA 签名验签的证书，3des 加密秘钥， 可用于测试开票的税号等由票通对接人员提供。接入方系统开发完成，正式上线前，联系票 通对接人员提供正式环境的参数信息。 正式对接前，可先参考该文档，如有疑问可在微信群组织会议沟通。 三、企业注册开通 要通过接口开具发票，需要开票的企业先在票通平台完成入驻流程，完成入驻有以下几 种方法。（联调测试阶段，可使用票通对接人员提供测试税号） （1）客户在票通平台直接注册 客户可以在票通企业版平台申请注册（注册地址：https://fpkj.vpiaotong.com/register） ， 也可以在票通集团版（票通集团版账号可联系票通商务人员获取）的机构管理功能中添加需 要入驻的企业。申请提交后，需要票通平台运营人员或有权限的代理商进行审核。该过程如 有问题可联系商务人员沟通。 （2）接口注册 针对企业数量较多的平台，可通过票通接口完成注册，使用上述接口文档中的“2.2.注 册企业”提交注册信息。接口注册的企业，无登录密码，用户如需使用票通平台，可在票通 平台，通过注册时预留的手机号，获取短信验证码完成密码设置，使用设置后的密码即可登 录票通平台。 基础文档仅提供了提交注册接口，如需获取票通的审核状态，可通过查询接口或推送接 口获取审核状态，如需接口可联系票通对接人员提供。 （3）可由票通代理商协助完成注册 联系票通代理商进行操作。 通过接口注册的企业，平台和企业的绑定关系自动生成，如果是使用票通产品功能完成 的注册或已经在票通完成入驻的企业，需要联系票通商务人员或运营人员完成接入方平台和 开票企业的绑定关系。 四、主要的开票场景 一般情况下，仅完成基础开票，对接少量的一至两个接口即可。根据开票场景不同，我 们分别介绍。 （1）扫码开票 扫码开票是票通提供的特色能力，针对一些当面交易场景，企业的顾客消费完成后，现 场获取交易小票，可在小票后追加打印开票二维码，顾客可自行扫码，填写完成开票。 顾客侧操作如下图示意： 该过程中，二维码信息生成，可调用票通接口文档中提供的“2.16.获取开票二维码” ， 接入方系统传入交易相关信息，如商品、单价、数量、税率等，票通为该笔交易生成对应的 开票链接和二维码并同步返回给接入方，接入方系统展示或打印二维码到小票上。 用户扫码后，看到的开票界面是由票通提供，该界面集成了发票抬头模糊检索，获取微 信或支付宝抬头，默认记录上次开票的发票抬头等功能，可方便顾客快速填充抬头信息，并 支持填写邮箱地址和手机号，票通会自动发送邮件，已开通短信服务的企业票通也会自动发 送短信推送发票。票通开票 H5 支持扫描多个二维码合并开票，或将一个二维码拆分开票， 商户自行设置即可。 提交发票后，还可授权将发票插入微信发票卡包或支付宝发票管家，发票开具成功后， 票通自动推到发票到顾客的微信发票卡包或支付宝发票管家。 平台发票开具成功，会调用“2.13.推送发票主要信息”接口推送开具成功的发票，接入 方也可调用“2.18.查询二维码开票信息”主动查询二维码开票状态。 如果用户侧产生退货，未开票情况下可调用“2.17.批量作废开票二维码”直接作废开票 二维码。如果二维码已开票，可调用“2.10.快捷冲红数电发票（全额冲红）”冲红已开具发 票。 注意：2.10、2.13、2.17、2.18 为可选接口，如不对接接口，相关操作也可以通过票通 产品功能完成。 （2）直接开票 直接开票接口是通用的开票能力，系统接入方组织好待开票信息后，直接调用“2.9.开 具蓝字数电发票”接口完成开票申请提交，票通服务会实时返回结果，并附带一个链接，通 过该链接可打开 H5 界面实时查看发票开具状态。 票通接收开票申请后，处理开票过程，开票成功或开票异常，都会通过“2.13.推送发票 主要信息”接口，推送相关的信息。 目前数电票开具，需要开票人保持电子税务局账号的登录状态，如果需要开票人员进行 登录认证或风险认证时，票通将会 2.13 接口返回 3999 的特定错误状态，该状态表明需要提 供开票人完成相关认证。数电账号的认证问题，会在后续第六章节详细说明。 注意：提交开票时，发票请求流水号字段，唯一代表一张发票，同一个发票请求流水号 不会重复开票，接入方系统遇到一些场景需重试开票时，如果为同一张发票，请不要变更发 票请求流水号，否则可能有导致重开发票的风险。 （3）单据开票 票通集团版提供的单据管理的能力，支持拆分开票、合并开票、支持直接传入订单信息 后续补充发票抬头等进行开票。该接口并非基础能力接口，如有需要财务人员介入进行审核 或拆分合并开票的场景，可使用该套接口能力，联系票通商务人员，安排提供相关的接口文 档，该功能的使用需依赖票通集团版系统。 五、冲红场景 当顾客产生退货或发票开具错误时，票通提供了多种冲红操作能力，票通企业版、集团 版均提供有手工冲红和一键冲红的能力，接口能力也提供了快捷冲红（1 个接口）和全场景 冲红（需 4-8 个接口组合使用） 。 数电票冲红需要发起红字确认单，确认单申请通过后才可发起真正的冲红操作，流程相 对较长，接口较多，一般建议接入方系统使用快捷冲红接口即可，快捷冲红接口服务对冲红 逻辑进行了封装，由票通整合红字信单申请管理和冲红功能，有效减轻接入方系统的开发工 作量。 （1）快捷冲红 快捷冲红时，如仅需全部冲红，可对接“2.10.快捷冲红数电发票（全额冲红）”，该接口 参数简单；如需支持部分冲红，可对接“2.37.快捷冲红数电发票（全额冲红、部分冲红）”， 该接口参数比较完整，支持场景更多，部分冲红和全额冲红都支持，如果需要进行部分冲红， 建议调用“2.36.初始化红字信息确认单”完成初始化，该初始化的目的是加载剩余可冲红的 发票信息，无需接入方系统自行管理剩余可冲红的商品信息。 （2）全场景冲红管理 全场景冲红需对接“2.28.红字发票确认单申请”、“2.29.查看红字发票确认单”、“2.30. 开具红字数电发票”、“2.31.红字发票确认单审核”、“2.32.红字发票确认单撤销”、“2.33.红 字发票确认单查询（下载）”、“2.34.获取红字发票确认单查询（下载）结果”、 “2.36.初始化 红字信息确认单”接口，用于精细化管理红字发票确认单及冲红。 销方申请冲红管理流程如下： 发票冲红流程及事项： 数电发票冲红，均需发起红字发票确认单申请， 普通发票申请，如果对方未进行入账操作，则申请后无需确认，调用红字信息表查询接 口获取到已确认（或无需确认）状态后，可进行冲红。 专用发票申请，如果对方未入账未勾选，则申请后无需确认，其他情况需对方确认，对 方确认通过后，调用红字信息表查询接口获取已确认（或无需确认）状态，接下来可进行冲 红。 对方企业发起的红字信息表，可通过红字信息表查询（下载）接口获取红字信息表，对 需要审核的红字信息表，可通过红字信息表审核接口，进行拒绝或者通过。 数电发票（普通发票）可冲红对应的增值税普通发票，包括普通电子发票。 数电发票（增值税专用发票），可冲红对应的增值税专用发票，包括专用电子发票。 接口同时支持购方申请红字确认单，冲红动作需销方执行。 注：冲红接口为非必须对接的接口，有些开发资源紧张或财务人员可人工处理冲红的情 况下，可以不对接冲红接口。或者将冲红功能放入后续的迭代开发。 六、数电账号管理 数电发票的开具，需要用户先在票通平台完成电子税务局账号的登录和风险认证。对于 接入方系统期望在系统内完成认证过程的，可使用票通提供的接口能力。如接入方系统仅需 完成开票，不关注认证过程，可使用票通成熟的认证方式。可通过票通企业版、集团版、微 票通 APP、票通云小程序、票通云服务公众号都可完成认证。推荐使用票通云公众号，该方 式认证无需登录票通账号，可直接在公众号进行数电账号的绑定、认证和对未认证导致开 票失败的发票进行重开。 （1）接口能力 票通提供了“2.3.数电账号登记”、“2.4.获取登录短信验证码”、“2.5.短信登录”、“2.6. 获取实名认证二维码”、 “2.7.查询实名认证二维码扫码状态” 、 “2.8.查询数电账号认证状态”、 “2.45.查询数电账号列表” 、“2.46.退出电子税局登录”等接口完成数电账号的认证。 这里支持几种场景。 1. 接入方系统仅需要数电账号信息，用于开票时指定开票人，可使用 2.45 接口获取 在票通维护好的数电账号及对应状态即可。在开票时传入开票人信息。 2. 接入方系统需进行是数电账号维护的，可调用 2.3 数电账号登记接口，该接口为实 时接口，可验证用户输入的账号密码是否正确。 3. 接入方系统如需完成认证，需首先通过 2.3 或 2.45 获取登录信息，然后调用 2.4 和 2.5 完成短信登录认证，使用 2.6、2.7 完成风险码扫码认证。如需查询各状态的登录或认证 状态，可通过 2.8 接口完成认证。 （2）票通云公众号 票通云服务公众号提供了您和您的数电账号关联的两种方式，一种是通过在企业版或集 团版对应数电账号后的关注二维码，扫码关注后，建立用户和数电账号的绑定关系。一种是 直接在票通云公众号-数电认证功能，通过输入手机号或电子税务局的登录账号密码完成验 证，获取属于用户的数电账号列表进行绑定。 “票通云服务”公众号提供的能力： 1. 用户绑定的账号未登录或未认证，导致发票开票失败时，票通将会通过消息通知进 行提醒，用户可直接点击通知，进入到认证界面，完成相应的认证，认证完成后可直接选择 是否重开发票及重开发票的范围（当前失败的发票或 30 天内因为该错误导致失败的发票） 。 2. 可通过票通云服务-数电认证功能，主动完成登录认证或风险认证，该场景适用于 一些企业为提高顾客体验，要求企业员工按时认证的情况，数电认证功能，无论当前账号处 于何种状态，都可以随时进行再次认证。 3.支持退出登录，目前通过短信方式完成登录，可保持很长的登录状态。 注意：由于目前短信登录方式保持登录的有效期很长，在 PC 端登录进行审核或其他操 作时，可能会被票通平台挤掉，可提醒用户先在票通平台退出登录，然后在电子税务局 PC 端进行操作。退出登录操作可使用票通产品或公众号，也可以通过接口 2.46 完成。 七、补充场景 （1）发票抬头获取接口 接入方系统如需自行开发 H5 或需要帮助用户补充抬头信息时，可使用发票抬头获取接 口，该接口非基础接口，请联系商务人员获取。 （2）开票项目智能赋码接口 接入方系统如需管理大量的商品品目时，可通过智能赋码接口完成对商品的税收分类编 码设置。该接口非基础接口，请联系商务人员获取。 （3）SaaS 平台类对接工单接口 接入方系统如果服务的企业较多，需要完善的线上原因流程支持，可联系票通商务人员 和对接人员，提供工单的接口支持，工单接口包括套餐（订单）创建、企业绑定、套餐续费 等能力。 八、更多支持 票通平台提供了多种场景组合的接口能力，如需交流沟通，可在微信群直接沟通或组织 会议进行沟通。