NFC-e 离线开票
NFC-e 离线开票入口:什么时候需要、内置 SDK 与发票助手怎么选、接入总流程、号码与补传规则、结果怎么收到。
这页是 NFC-e 离线开票的入口:说明什么时候需要它、两种接入方案怎么选、接入要走哪几步。读完你能选定方案,并知道每一步去哪一页做。前提是主体已按云端 NFC-e 的要求接入。
什么时候需要离线开票
门店断网、连不上平台时,收银机仍要当场开票交给消费者。离线开票让收银机在本机开出 离线应急票(断网时在本机签名开出、待补传授权的 NFC-e),当场打印小票;网络恢复后票据自动 补传(把离线票送平台、再送 SEFAZ 授权),结果照常推送给你。
网络正常时照常在线授权,结果与云端 NFC-e 相同。
选哪种方案
| 方案一:收银程序内置 SDK | 方案二:对接发票助手 | |
|---|---|---|
| 是什么 | 收银软件集成开发包,离线开票内核随收银软件运行 | 门店电脑安装 TF Fiscal 发票助手(Windows 程序),收银软件调用它的本机接口 |
| 适合谁 | 自研 Java 收银软件,希望门店不用多装程序 | 不想改动收银软件内部的集成商;没有收银系统、直接用助手自带简易开票的门店 |
| 要做什么 | 引入 SDK、随安装包分发运行时、调用开票方法、处理事件 | 门店安装助手;收银软件把开票地址换成本机,请求体与云端开票接口相同 |
| 工作量 | 中:要写初始化、配对、事件处理代码 | 小:只改调用地址与鉴权请求头 |
| 税种 | 支持,须联网;断网时改传 impostos | 支持,须联网;断网时改传 impostos |
选型建议:收银软件是自研的 Java 程序,选内置 SDK;否则选发票助手。内置 SDK 只提供 Java 版本。两种方案任选其一,同一主体下不同收银机也可以各用一种。
接入总流程
- 生成配对码:为每台收银机调用生成设备配对码,把返回的 配对码(让一台收银机绑定主体的一次性凭证)交给门店。首次调用即为该主体开通离线开票。
- 门店安装并配对:内置 SDK 见内置 SDK 教程的准备与配对两节;发票助手见发票助手教程的安装与配对一节。每台收银机配对一次即可。
- 开票:内置 SDK 调开票方法,见开第一张票;发票助手调本机开票接口,见开票、查询与补传。联网与断网用同一个调用。
- 收结果:收银软件在本机收,集成商服务端照常收 Webhook,见结果怎么收到。
配对码有效期与离线最长时长由平台控制。测试环境可以完整联调,测试环境开出的票没有税务效力;主体切换环境后,须在新环境重新生成配对码、配对收银机。
号码与系列
- 设备系列:每台收银机独占的一个 NFC-e 系列。联网开票和断网离线开票都用它,由收银机本机按同一顺序取号、签名:联网时把签好的票交平台转发 SEFAZ,断网时接着往下开离线票,所以同一台收银机的在线票与离线票号码连续。联网开票因此也要用到本机的证书与计税数据,配对后自动同步。
- 指定系列与起始号码:生成配对码时用
serie指定设备系列,用numeroInicial指定第一张票的号码;都不填时平台自动分配系列,从 1 开始。查询设备列表里的serieOffline就是设备系列。 - 与云端系列分开:云端开票接口开的 NFC-e 仍用主体档案里的系列,与设备系列互不重合。同一 CNPJ 在多个集成商处开票时,各集成商须使用不重叠的系列(含设备系列),否则 SEFAZ 会拒。
- 一店多台共用一个系列:多台收银台也可以共用一个设备系列,由一处统一取号、号码连续。发票助手打开局域网模式由全店共用,见一店多收银台部署;内置 SDK 用主从模式,见多收银台(主从模式)。
- 平台自动处理的号码:在线提交结果不明、在线票被拒、个别州不受理作废时,号码由平台自动收口,收银软件与集成商无需操作。细节见附录。
离线票与补传
- 断网时开出的票状态为
ContingenciaPendente,小票自带离线应急标识,照常交给消费者。 - 网络恢复后自动补传,无需任何操作;SEFAZ 授权后状态变为
Autorizada。 - SEFAZ 拒绝的离线票须用同一号码修正后重传,只能改不影响金额与税额的内容(例如 NCM、CFOP、消费者证件)。
- 离线票必须在州规定的时限内补传,时限以平台配置为准;接近时限时会提醒,超过后该收银机不能继续离线开票。
- 离线票授权前提交的取消由平台挂起,授权那一刻自动发起。
- 含燃料的票不能离线开。
- 商品行引用税种(
classeImposto)时必须联网,断网时改传impostos,见税种与联网。
税种与联网
商品行可以像云端开票一样用 classeImposto 引用税种,cfop 与 impostos 可不传。税种只保存在平台:发票助手与内置 SDK 开票时先把请求交平台展开为完整的 impostos,再在本机算税、签名、开票,展开结果与云端开票相同。
- 必须联网:断网或连不上平台时,引用了税种的请求被拒绝,返回
10029780,提示改传impostos。被拒的请求不占用票号,下一张票号码照常连续。 - 断网兜底由收银程序负责:发票助手与内置 SDK 不缓存税种。要在断网时也能开票,收银程序须自己保存展开后的
impostos,断网时在商品行改传impostos。用内置 SDK 时,联网开出的票用Consultar取回的Pedido就是展开后的请求。 - 税种被拒:税种不存在、与主体当前税制不符(
IncompativelComRegime)等情形,返回与云端开票相同的错误码与说明,例如10005202、10005220;说明的语言随发票助手的界面语言或内置 SDK 的idioma。 - 记录所用税种:每张票记录商品行所用的税种编号与版本,随票上报平台。
结果怎么收到
| 渠道 | 内容 |
|---|---|
| 收银软件 | 内置 SDK 用 SDK 事件,发票助手用助手的本地回调或查询 |
| 集成商服务端 | 照常收 NFC-e Webhook:补传受理 nfce.contingency_issued、授权 nfce.authorized、被拒 nfce.rejected、取消 nfce.canceled / nfce.cancel_rejected |
| 设备事件 | nfce.device.activated(配对)、nfce.device.deactivated(停用)、nfce.device.upload_overdue(补传即将逾期),data 为设备对象 |
- 经收银机开出的票:Webhook 载荷末尾多一个
dispositivoId;设备上报了收银台时,其后再多一个 收银台标识terminal,说明票是哪台收银台开的。发票助手为收银令牌名称,内置 SDK 主从模式为从机的终端名称。 - 没有收银台标识的票:设备没有上报收银台时,例如内置 SDK 主机自己开的票、独立模式开的票,查询与 Webhook 不输出
terminal这个键,不会输出null。 - 订阅:哪些事件会推送、怎么只订阅部分事件,见 Webhook 的订阅规则。
接口列表
附录:平台自动处理的号码情形
以下情形都由平台处理,收银软件与集成商无需操作。
| 情形 | 平台怎么处理 |
|---|---|
| 在线提交后结果不明,例如超时、断网或平台没有及时返回 | 这个号码不再使用,收银机用下一个号码开离线票交给消费者。平台随后核对原号码:已被 SEFAZ 授权的,由平台替代取消;没有授权的,由平台向 SEFAZ 申报作废 |
| 在线票被 SEFAZ 拒绝 | 号码由平台申报作废、不再使用 |
| 平台当场拒收、没有送出 | 号码留给下一张票 |
| AC、BA、SP 三州,或其他州的作废服务停用 | 上面需要作废的号码不申报,断号后直接往后编号。这些号码视为已用,不会再开出 |
