TF Fiscal
开发文档

NFC-e 离线开票

内置 SDK 教程

内置 SDK 快速上手:生成配对码、引入 SDK、初始化与配对、开第一张票、打印小票、接收结果、断网时的行为与上线前检查,附 Java 完整示例。

这页带你在收银软件里接入内置 SDK:联网时 SDK 在本设备系列上取号、签名,经平台在线授权;断网时在本机签发离线应急票、当场打印,联网后自动补传。读完你能配对一台收银机、开出并打印第一张票、收到补传与取消结果。前置:能调用平台开放接口生成配对码,收银软件运行在 Windows 上;开票请求与云端开票接口相同;商品行引用税种须联网。

全程你只和 SDK 打交道,SDK 在后台运行离线开票内核。整个接入过程如下:

text
准备:生成配对码、引入 SDK、分发运行时
│
▼
初始化 ──► 未配对?──► 配对(只在首次,需联网)
│
▼
开票 ──► 按状态处理 ──► 打印小票
│
└─ 后台:断网时离线签发,联网后自动补传,结果以事件通知
日常:作废与查询、取授权 XML、替代取消、月度导出 XML、备份与坏机恢复

每一步都给 Java 写法。方法与类型的完整说明见 SDK 参考;设备系列、离线应急票、补传等术语见号码与系列。

1 准备

1.1 生成配对码

每台收银机配对一次,配对码由集成商调用平台接口生成。下面是生成配对码的接口:

http
POST /openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacao

请求体可以为空;给收银机起名、限定只能由 SDK 配对时这样传:

json
{ "nomeDispositivo": "Caixa 01", "formaPermitida": "Sdk" }

首次调用即为该主体开通离线开票,没有单独的开通步骤。字段与错误见生成设备配对码。响应里的 codigoAtivacao(TFA1. 开头)就是配对码:

  • 只在这次响应里返回全文,请立即交给实体店的收银负责人;72 小时内有效,只能用一次。
  • 可以作为文本交出,也可以存成 .tfa 文件(UTF-8、单行,内容就是配对码全文)。
  • 不传 ambiente 时取主体当前环境;设备配对后固定在这个环境开票。

收银软件不需要在平台预先登记:初始化时传收银软件名称与版本,平台自动识别。

1.2 引入 SDK

SDK 与运行时在控制台左侧菜单「离线开票 → 离线开票」页的「下载」标签获取:登录即可下载,表中列出各版本的文件大小与 SHA-256 校验值,下载后请先核对校验值。

SDK 以 Maven 构件 com.tffiscal:tffiscal-nfce-sdk-java 提供,支持 Java 8 及以上。下面是 pom.xml 里的依赖写法(version 填发布版本号):

xml
<dependency>
<groupId>com.tffiscal</groupId>
<artifactId>tffiscal-nfce-sdk-java</artifactId>
<version>VERSAO_PUBLICADA</version>
</dependency>

本页示例代码与 SDK 包里的 Java 示例工程(五个场景:快速上手、断网与补传、事件处理、作废查询与 XML、文件与打印)一致。

1.3 随安装包分发运行时

SDK 在后台启动一个运行时子进程运行离线开票内核。把整个 tffiscal-runtime 目录原样放进收银软件安装包(约 60 MB),目录结构如下:

text
tffiscal-runtime/
├── tffiscal-nfce.exe
├── app/
├── runtime/
└── VERSION

初始化时用运行时目录指向它;找不到返回 10029877。SDK 与运行时请用同一版本一起分发。Java 收银软件运行在 Java 21 及以上时,也可以用进程内模式不分发运行时,见 SDK 参考。

1.4 数据目录

每台收银机一个数据目录,例如 C:\ProgramData\MinhaLoja\TFFiscal:

  • 补传前,离线票的已签名文件只存在这里,是唯一的法律原件。 卸载、升级收银软件时不要删除。
  • 设备密钥按当前 Windows 用户加密:收银软件始终用同一个 Windows 用户运行;目录不能拷到别的电脑或别的用户下使用(10029827)。
  • 同一时刻只能有一个进程打开(10029828)。同一电脑装了两套收银软件,就用两个目录、配对为两台设备。
  • 一个目录可以配对多个主体(多个 CNPJ)。只配对一个时各方法的 empresaId 可省略,配对多个时必须传。
  • 授权 XML 与取消 XML 授权后自动下载到这里,保留天数由配置 RetencaoXmlDias 决定(见 2.2);过期自动清理,再取时自动联网回取。
  • 定期用 Backup 备份,电脑坏了来不及补传时用 ExportarPendentes 导出交给平台,见备份与坏机恢复。

2 初始化与配对

收银软件启动时初始化一次,整个运行期间共用这个实例;首次在这台电脑运行时还要配对一次。

2.1 初始化与配对

初始化必须传收银软件名称与版本:平台据此自动识别你的收银软件,并可按版本管控;缺少时返回 10029874。

首次在这台电脑运行时 Ativado 为 false,用配对码与主体的 A1 证书配对:

  • 配对码:收银员粘贴文本,或选择 .tfa 文件。先用 InspecionarCodigoAtivacao 在本机核验,显示环境与到期时间让收银员确认,不联网、不消耗配对码。
  • 证书:选 Windows 证书存储中已有的证书(按指纹),或导入 PFX 文件加密码。PFX 导入后私钥不可导出,密码不保存;证书留在「当前用户 > 个人」证书存储中长期使用,删除后设备无法签名,停用与清理步骤见证书来源。

下面的代码启动 SDK、挂上事件处理器,未配对时核验配对码后配对。实体店经代理上网、或要调整 XML 保留天数时,在同一份配置里加上 2.2 的配置项。

java
import com.tffiscal.nfce.sdk.Certificado;
import com.tffiscal.nfce.sdk.Configuracao;
import com.tffiscal.nfce.sdk.EventoNfce;
import com.tffiscal.nfce.sdk.Resultados;
import com.tffiscal.nfce.sdk.TfFiscalException;
import com.tffiscal.nfce.sdk.TfFiscalNfce;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.function.Consumer;
public final class NfceInicio {
private NfceInicio() {}
/** 初始化 SDK;监听器在启动时挂上,启动前积压的事件不会错过。 */
public static TfFiscalNfce iniciar(Consumer<EventoNfce> aoEvento) {
Configuracao configuracao = Configuracao.builder()
.diretorioDados(Paths.get("C:/ProgramData/MinhaLoja/TFFiscal"))
.diretorioRuntime(Paths.get("C:/Program Files/MinhaLoja/tffiscal-runtime"))
.nomeAplicativo("Caixa Exemplo")
.versaoAplicativo("1.0.0")
.idioma("pt-BR")
.aoReceberEvento(aoEvento)
.build();
return TfFiscalNfce.iniciar(configuracao);
}
/** 未配对时配对。codigoOuArquivo 可以是配对码文本,也可以是 .tfa 文件路径;senhaPfx 为 null 时按指纹取证书存储中的证书。 */
public static boolean ativarSeNecessario(TfFiscalNfce nfce, String codigoOuArquivo, String thumbprintOuPfx, String senhaPfx)
throws IOException {
if (nfce.isAtivado()) {
return true;
}
Path arquivo = Paths.get(codigoOuArquivo);
String codigo = Files.isRegularFile(arquivo)
? new String(Files.readAllBytes(arquivo), StandardCharsets.UTF_8)
: codigoOuArquivo;
codigo = codigo.replace("\uFEFF", "").trim();
Certificado certificado = senhaPfx == null
? Certificado.doRepositorio(thumbprintOuPfx, false)
: Certificado.deArquivoPfx(Files.readAllBytes(Paths.get(thumbprintOuPfx)), senhaPfx);
try {
Resultados.CodigoAtivacao info = nfce.inspecionarCodigoAtivacao(codigo);
System.out.println("Codigo de pareamento: ambiente " + info.getAmbiente() + ", expira em " + info.getExpiraEm());
Resultados.Ativacao a = nfce.ativar(codigo, certificado);
System.out.println("Pareado: empresa " + a.getEmpresaId() + ", CNPJ " + a.getCnpj() + ", serie do dispositivo " + a.getSerieOffline());
return true;
} catch (TfFiscalException e) {
int c = e.getCodigo();
if (c == 10029824 || c == 10029833 || c == 10029839) {
// 可重试:检查网络后用同一个配对码再试
System.out.println("Tente de novo: " + e.getMessage());
} else {
// 需要新配对码或换证书:getMessage() 已按 idioma 翻译,可直接展示
System.out.println("Erro " + c + " " + e.getTipo() + ": " + e.getMessage());
}
return false;
}
}
}

配对或启动失败时按错误码处理:

类别错误码处理
可重试10029824(连不上平台)、10029833(超时)提示检查网络后重试
可重试10029839(平台已配对但本机保存失败)用同一个配对码再配对一次
要换配对码10029825、10029205 到 10029209、10029219、10029221 到 10029225请集成商重新生成配对码
要换证书10029813、10029814、10029213、10029214换用主体的有效证书
启动即失败10029842(数据目录被更新版本的 SDK 用过,本地库比当前程序新,拒绝启动)把 SDK 与运行时升级到不低于上次使用的版本即可,绝不要删除数据目录

2.2 代理与 XML 保留天数

出站代理:实体店的网络要经代理才能上外网时设置;都不设即直连。三种方式:

方式怎么设说明
直连代理相关项都不设缺省方式
手工代理Proxy 填 host:porta,例如 10.0.0.1:3128格式不合法返回 10029874
系统代理UsarProxyDoSistema 设为 true读 Windows 的代理设置,先取机器级设置,再取当前 Windows 用户的浏览器代理设置;与 Proxy 同时设置时系统代理优先
  • 代理认证:用 proxyAutenticacao(usuario, senha) 设置,手工代理与系统代理都可以带。口令只在内存里随启动交给运行时,不落盘、不进日志;收银软件自己保存口令时请加密保存。只设了认证、却既没有代理地址也没开系统代理时返回 10029874。
  • 不支持自动代理脚本:Windows 里只配了 PAC 自动代理脚本时,SDK 按直连处理并在日志里记一条警告。这样的网络请改用手工代理,或在 Windows 里配固定代理。
  • Java 进程内模式要加启动参数:经 HTTPS 访问平台时,代理的 Basic 认证要求 JVM 允许在隧道上使用 Basic,而 JVM 只在首次使用自带 HTTP 客户端时读一次这项设置,之后再改无效。用 Java 进程内模式(EM_PROCESSO)且配了代理认证时,在收银软件的 JVM 启动参数里加上 -Djdk.http.auth.tunneling.disabledSchemes=(等号后留空)。内核加载时也会尽早把它置空,但收银软件若已先用过 JVM 自带的 HTTP 客户端,或自己把该项设成了禁用 Basic,置空就不生效,这时 Situacao 的 Avisos 会给出告警,代理认证可能失败。Java 子进程模式由运行时自己处理,不需要加参数。

XML 保留天数:RetencaoXmlDias 是授权 XML 与取消 XML 在本机保留的天数,取值 1 到 3650,不设时为 90 天,越界返回 10029874。超过保留期的自动清理,之后再取会自动联网回取(见取回 XML)。按月导出给会计时,导出区间最好落在保留期内,见按月导出 XML 给会计。

下面在 2.1 的配置上追加手工代理、代理认证与 180 天的 XML 保留期:

java
// 在 2.1 的 Configuracao.builder() 链上追加:经手工代理上网,代理要求认证
Configuracao configuracao = Configuracao.builder()
.diretorioDados(Paths.get("C:/ProgramData/MinhaLoja/TFFiscal"))
.diretorioRuntime(Paths.get("C:/Program Files/MinhaLoja/tffiscal-runtime"))
.nomeAplicativo("Caixa Exemplo")
.versaoAplicativo("1.0.0")
.proxy("10.0.0.1:3128")
.proxyAutenticacao("caixa01", senhaProxy)
// 或改用 Windows 系统代理(优先于 proxy):.usarProxyDoSistema(true)
// 授权与取消 XML 在本机保留 180 天
.retencaoXmlDias(180)
.aoReceberEvento(aoEvento)
.build();

3 开第一张票

3.1 开票请求

请求体就是开具 NFC-e 的请求体,字段说明、各州规则与更多场景都以那一页为准。SDK 中无需传 modoResposta。税种须联网:商品行可以用 classeImposto 引用税种,由平台展开后再在本机开票;断网或连不上平台时返回 10029780,提示改传 impostos,不占用票号,见税种与联网。税码必须与主体的税制一致:简易税制(Simples Nacional)用三位的 CSOSN,常规税制用两位的 CST。下面两份请求与 SDK 包里的 pedido-exemplo.json、pedido-exemplo-regime-normal.json 相同。

简易税制:门店现场销售、消费者不识别、现金付款。

json
{
"id": "EXEMPLO-0001",
"ambienteEmissao": "Homologacao",
"pedido": {
"presencaConsumidor": "OperacaoPresencial",
"pagamento": {
"formas": [
{ "tipo": "Dinheiro", "valor": 50.30 }
]
}
},
"itens": [
{
"cfop": "5102",
"codigo": "7891000100101",
"descricao": "ARROZ BRANCO TIPO 1 5KG",
"ncm": "10063021",
"quantidade": 2,
"unidadeMedida": "UN",
"valorUnitario": 25.15,
"impostos": {
"icms": { "situacaoTributaria": "102" },
"pis": { "situacaoTributaria": "49" },
"cofins": { "situacaoTributaria": "49" }
}
}
]
}

常规税制:同一笔销售,只是税码不同。

json
{
"id": "EXEMPLO-RN-0001",
"ambienteEmissao": "Homologacao",
"pedido": {
"presencaConsumidor": "OperacaoPresencial",
"pagamento": {
"formas": [
{ "tipo": "Dinheiro", "valor": 50.30 }
]
}
},
"itens": [
{
"cfop": "5102",
"codigo": "7891000100101",
"descricao": "ARROZ BRANCO TIPO 1 5KG",
"ncm": "10063021",
"quantidade": 2,
"unidadeMedida": "UN",
"valorUnitario": 25.15,
"impostos": {
"icms": { "situacaoTributaria": "00" },
"pis": { "situacaoTributaria": "07" },
"cofins": { "situacaoTributaria": "07" }
}
}
]
}
字段填写说明
id必填收银单据号。最长 64 个字符,是幂等键:每笔销售一个新 id,重试同一单必须用同一个 id
ambienteEmissao必填开票环境。与设备配对时的环境一致
modoResposta不填SDK 始终等待结果
pedido.presencaConsumidor必填在场方式。门店现场为 OperacaoPresencial
pedido.pagamento.formas必填支付明细。各项 tipo 与 valor,合计须覆盖票面总额
pedido.pagamento.troco可选找零。现金多付时填写,支付合计减找零须等于票面总额
cliente可选消费者。不识别时整组不传;报 CPF 时只传 tipoPessoa 与 cpfCnpj;超过本州识别门槛时必须传
itens[].cfop / codigo / descricao / ncm / quantidade / unidadeMedida / valorUnitario必填商品行基本信息
itens[].ean / cest / valorDesconto可选条码、CEST、行折扣
itens[].impostos.icms.situacaoTributaria必填ICMS 税码。简易税制如 102,常规税制如 00
itens[].impostos.icms.aliquota可选ICMS 税率。百分比
itens[].impostos.pis / cofins必填PIS / COFINS 税码,例如简易税制 49、常规税制 07
itens[].classeImposto可选税种编号。传了可不传 cfop 与 impostos;须联网,断网时返回 10029780,改传 impostos

完整字段见开具 NFC-e。

3.2 构造请求并开票

下面的代码从上面的 JSON 文件读入请求,换上新的 id 后开票,再按返回状态决定是否打印。你的收银软件可以用任何方式拼出同样结构的 JSON。

java
import com.tffiscal.nfce.sdk.ResultadoEmissao;
import com.tffiscal.nfce.sdk.TfFiscalException;
import com.tffiscal.nfce.sdk.TfFiscalNfce;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
public final class NfceVenda {
private NfceVenda() {}
/** 读取请求文件并换上新的 id(每笔销售一个新 id)。 */
public static String lerPedido(String arquivo, String id) throws IOException {
String json = new String(Files.readAllBytes(Paths.get(arquivo)), StandardCharsets.UTF_8);
return json.replaceFirst("\"id\"\\s*:\\s*\"[^\"]*\"", "\"id\": \"" + id + "\"");
}
/** 开票并按状态处理;返回是否可以打印小票。 */
public static boolean vender(TfFiscalNfce nfce, String pedidoJson) {
try {
ResultadoEmissao r = nfce.emitir(pedidoJson);
System.out.println("Nota " + r.getId() + ": " + r.getStatus() + " | serie " + r.getSerie() + " n. "
+ r.getNumero() + " | chave " + r.getChave() + " | protocolo " + r.getProtocolo());
switch (r.getStatus()) {
case "Autorizada":
case "ContingenciaPendente":
// 离线签发的票照常打印交给消费者,补传自动进行
return true;
case "AguardandoAutorizacao":
// 在线已受理但 SEFAZ 未返回:先不打印,等 NOTA_AUTORIZADA(授权)或 NOTA_NEGADA(被拒)事件
return false;
default:
// Negada:按 SEFAZ 结果修正后用新 id 重开
System.out.println("Rejeitada: " + r.getCStat() + " " + r.getXMotivo());
return false;
}
} catch (TfFiscalException e) {
// 请求校验失败、离线条件不满足等:getMessage() 已翻译,可直接展示
System.out.println("Erro " + e.getCodigo() + " " + e.getTipo() + ": " + e.getMessage() + " " + e.getDetalhesJson());
return false;
}
}
}

3.3 各种返回状态

Status发生了什么收银界面
Autorizada在线授权成功打印小票,完成销售
ContingenciaPendente连不上平台,已在本机离线签发照常打印交给消费者,小票自带离线应急标识;可在界面角落显示「离线开票」
AguardandoAutorizacao平台已受理,SEFAZ 还没返回,且当时不能改为离线签发先不打印,提示「等待授权」;收到 NOTA_AUTORIZADA 事件后再打印。收到 NOTA_NEGADA 表示 SEFAZ 最终驳回,这张票不能同号修正,修正销售数据后用新 id 重开
NegadaSEFAZ 驳回显示 SEFAZ 结果码与结果说明,修正后用新 id 重开
抛出异常请求不合法、离线条件不满足等显示异常说明;见常见错误

同一个 id 重复调用 Emitir 不会重复开票,返回的是原票。网络超时、程序崩溃后,用同一个 id 重发即可拿回结果。

4 打印小票

4.1 打印小票

Cupom(id, 格式) 返回小票字节,原样送打印机即可。离线票自带应急标识,打印份数由平台配置。格式取值:

格式含义
ESCPOS_8080mm 热敏打印机的 ESC/POS 指令
ESCPOS_5858mm 热敏打印机的 ESC/POS 指令
TEXTO纯文本,UTF-8
HTMLHTML 页面,UTF-8,适合屏幕预览或浏览器打印
PDF_8080mm 宽的 PDF,每联一页,交 Windows 打印驱动打印,适合不支持 ESC/POS 直连的打印机,见 4.2

下面的代码取 ESC/POS 小票并送打印机:

  • 示例把字节发给网络热敏打印机的 9100 端口。
  • USB 打印机可在 Windows 里共享后写到共享路径;串口打印机用串口库写入同样的字节即可。
java
import com.tffiscal.nfce.sdk.FormatoCupom;
import com.tffiscal.nfce.sdk.TfFiscalNfce;
import java.io.IOException;
import java.io.OutputStream;
import java.net.Socket;
public final class NfceImpressao {
private NfceImpressao() {}
/** 把 ESC/POS 小票发到网络打印机。 */
public static void imprimir(TfFiscalNfce nfce, String id, String ipImpressora) throws IOException {
byte[] cupom = nfce.cupom(id, FormatoCupom.ESCPOS_80);
try (Socket socket = new Socket(ipImpressora, 9100); OutputStream saida = socket.getOutputStream()) {
saida.write(cupom);
}
}
}

4.2 PDF 小票、打印参数与二维码图像

PDF 小票:打印机只有 Windows 驱动、不能直接收 ESC/POS 指令时,用 PDF_80 取 80mm PDF,交系统关联的 PDF 程序经打印驱动打印。PDF 使用阅读器自带的标准字体,葡语重音正常显示。

打印参数:同一种格式要适配不同打印机时,用带打印参数的重载 cupom(id, 格式, OpcoesCupom, empresaId)。没设的项用缺省值;取值越界返回 10029874。

参数取值缺省
Colunas每行字符数。48、42 或 32按格式:80mm 为 48,58mm 为 32
PaginaCodigo打印机代码页。CP1252、CP860(葡语打印机常用)、CP850 或 CP437;代码页里没有的字符先去掉重音再打印CP1252
ModoQrCode二维码打法。NATIVO:用打印机自带的二维码指令;IMAGEM:印成位图,用于不支持原生二维码的打印机NATIVO
TamanhoModuloQr二维码模块大小。1 到 16 点4
Cortar打完切纸。true 切纸,false 不切(打印机没有切刀时)true
Vias打印联数。1 到 9由平台配置

二维码图像:QrCodePng(id, 像素) 返回黑白、带留白的 PNG,像素取 64 到 2048、须显式传,越界返回 10029817。收银软件自己排版单据(例如 A4 收据)时用它。

下面的代码与示例工程的场景 05 一致:取 PDF 小票与二维码图像写成文件并交缺省打印机,再按 58mm 打印机的参数(32 列、CP850、位图二维码、模块 6 点、两联、不切纸)取 ESC/POS 小票。

java
import com.tffiscal.nfce.sdk.FormatoCupom;
import com.tffiscal.nfce.sdk.OpcoesCupom;
import com.tffiscal.nfce.sdk.TfFiscalNfce;
import java.awt.Desktop;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
public final class NfceImpressaoArquivos {
private NfceImpressaoArquivos() {}
/** 80mm PDF 小票与二维码 PNG 写成文件,并交缺省打印机。 */
public static void pdfEQrCode(TfFiscalNfce nfce, String id, Path pasta) throws IOException {
Path pdf = pasta.resolve(id + ".pdf");
Files.write(pdf, nfce.cupom(id, FormatoCupom.PDF_80, null, null));
Path png = pasta.resolve(id + "-qrcode.png");
Files.write(png, nfce.qrCodePng(id, 300, null));
// PDF 由系统关联的 PDF 程序按缺省打印机打印(走打印驱动)
if (Desktop.isDesktopSupported() && Desktop.getDesktop().isSupported(Desktop.Action.PRINT)) {
Desktop.getDesktop().print(pdf.toFile());
}
}
/** 58mm 打印机:32 列、CP850、位图二维码、模块 6 点、两联、不切纸。 */
public static byte[] cupom58mm(TfFiscalNfce nfce, String id) {
OpcoesCupom opcoes = new OpcoesCupom()
.colunas(32)
.paginaCodigo("CP850")
.modoQrCode(OpcoesCupom.ModoQrCode.IMAGEM)
.tamanhoModuloQr(6)
.vias(2)
.cortar(false);
return nfce.cupom(id, FormatoCupom.ESCPOS_58, opcoes, null);
}
}

5 接收结果

补传结果、取消结果、设备停用、许可证与证书提醒都以事件推给收银软件。事件至少一次、按顺序投递:处理器正常返回即确认,抛出异常则约 30 秒后重投。请按 EventoId 去重(下例用内存集合演示,正式环境请存进收银软件的数据库)。集成商服务端还可以经 Webhook 收到结果,见结果怎么收到。

事件收银软件做什么
NOTA_AUTORIZADA单据标为已授权;在线等待授权(AguardandoAutorizacao)的票此时打印
NOTA_NEGADA在线已受理、等待授权的票后来被 SEFAZ 拒绝。单据标为被拒并提示收银员;这张票不能同号修正,修正销售数据后用新 id 重开
NOTA_REJEITADA离线票补传被 SEFAZ 拒绝。提示管理员,用 Substituir 同号修正,不能另开新票
NOTA_RECUSADA_PLATAFORMA平台拒收离线票,记录后联系平台
CANCELAMENTO_CONCLUIDO / CANCELAMENTO_REJEITADO更新取消结果;被拒时票仍有效
NUMERO_INUTILIZACAO_RECUSADA未用号码的作废申报被平台拒绝。definitivo 为 false 时内核自动重试,记录即可;为 true 时是终态(号码区间不合法或区间内已有票据),须人工与集成商核对这段号码
DISPOSITIVO_DESATIVADO醒目提示「本机已不能开票」
LICENCA_EXPIRANDO / PRAZO_TRANSMISSAO_PROXIMO提示尽快恢复网络
CERTIFICADO_EXPIRANDO提示续期证书,续期后调 TrocarCertificado

全部事件与数据字段见 SDK 参考。

事件在哪个线程上到达:子进程模式在封装专用的后台线程上串行回调,进程内模式在内核的投递线程上同步回调。Swing 界面用 SwingUtilities.invokeLater 切回界面线程。

处理器里只记录、不调用 SDK 方法:把要后续处理的单据(例如补传被拒的 id)放进队列,由收银软件主流程取出处理。

下面的代码按 EventoId 去重、按事件类型处理,并把补传被拒的票放进队列,由主流程用 Substituir 同号修正:

java
import com.tffiscal.nfce.sdk.EventoNfce;
import com.tffiscal.nfce.sdk.ResultadoEmissao;
import com.tffiscal.nfce.sdk.SituacaoNota;
import com.tffiscal.nfce.sdk.TfFiscalNfce;
import java.util.Map;
import java.util.Queue;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentLinkedQueue;
public final class NfceEventos {
private final Set<String> vistos = ConcurrentHashMap.newKeySet();
private final Queue<String> rejeitadas = new ConcurrentLinkedQueue<>();
/** 事件监听器:传给 Configuracao.Builder.aoReceberEvento。正常返回即确认,抛异常会被重投。 */
public void aoReceber(EventoNfce e) {
// 至少一次投递:同一事件可能收到多次,按 eventoId 去重(正式环境请把已处理的 eventoId 存进数据库)
if (!vistos.add(e.getEventoId())) {
return;
}
Map<String, Object> d = e.getDados();
switch (e.getTipo()) {
case "NOTA_AUTORIZADA":
System.out.println("Nota " + e.getId() + " autorizada, protocolo " + d.get("protocolo")
+ (Boolean.TRUE.equals(d.get("aposCorrecao")) ? " (apos correcao)" : ""));
break;
case "NOTA_NEGADA":
// 在线等待授权的票后来被 SEFAZ 拒绝:不能同号修正,修正销售数据后用新 id 重开
System.out.println("Nota " + e.getId() + " negada pela SEFAZ: " + d.get("cStat") + " " + d.get("motivo")
+ " - corrija a venda e emita de novo com um novo id");
break;
case "NOTA_REJEITADA":
// 离线票补传被拒:放进队列,由主流程用 substituir 同号修正
System.out.println("Nota " + e.getId() + " rejeitada pela SEFAZ: " + d.get("cStat") + " " + d.get("motivo"));
rejeitadas.add(e.getId());
break;
case "NOTA_RECUSADA_PLATAFORMA":
System.out.println("Nota " + e.getId() + " recusada pela plataforma: " + d.get("codigo") + " " + d.get("mensagem"));
break;
case "CANCELAMENTO_CONCLUIDO":
case "CANCELAMENTO_REJEITADO":
System.out.println("Cancelamento da nota " + e.getId() + ": " + e.getTipo() + " " + d.get("cStat") + " " + d.get("motivo"));
break;
case "NUMERO_INUTILIZACAO_RECUSADA":
// definitivo=true:区间非法或区间内已有票据,需人工核对;false:内核会自行重试
System.out.println("Inutilizacao recusada: serie " + d.get("serie") + " " + d.get("inicio") + "-" + d.get("fim")
+ ": " + d.get("mensagem") + (Boolean.TRUE.equals(d.get("definitivo")) ? " - verificar manualmente" : ""));
break;
case "DISPOSITIVO_DESATIVADO":
System.out.println("Este caixa nao emite mais: " + d.get("situacao") + " " + d.get("motivo"));
break;
case "LICENCA_EXPIRANDO":
case "PRAZO_TRANSMISSAO_PROXIMO":
System.out.println("Restabeleca a internet o quanto antes");
break;
case "CERTIFICADO_EXPIRANDO":
System.out.println("Certificado A1 valido ate " + d.get("validoAte") + "; troque com trocarCertificado");
break;
default:
// 新增的事件类型可以安全忽略
break;
}
}
/** 主流程定时调用:对补传被拒的票同号修正。 */
public void corrigirRejeitadas(TfFiscalNfce nfce) {
String id;
while ((id = rejeitadas.poll()) != null) {
SituacaoNota original = nfce.consultar(id);
// 按 NOTA_REJEITADA 的 cStat / motivo 改正对应的非金额字段(如 NCM、CFOP),金额与税额不能变
String corrigido = original.getPedido();
ResultadoEmissao r = nfce.substituir(id, corrigido, null);
System.out.println("Substituir " + r.getId() + ": " + r.getStatus() + ", numero " + r.getNumero() + " (mesmo numero)");
}
}
}

同号修正只能改不影响金额与税额的内容(例如商品 NCM、CFOP、消费者证件),号码、访问密钥与开票时间保持不变;金额或税额变化返回 10029821。修正后再次补传授权时收到的 NOTA_AUTORIZADA 里 aposCorrecao 为 true。

6 断网时会发生什么

断网时收银员照常开票,收银软件不需要写额外的分支。补传本身的规则(待补传状态、自动补传、被拒后同号修正、补传时限、哪些票不能离线)见离线票与补传,这里只说 SDK 这一侧的行为:

  1. Emitir 先尝试在线;等待超时或连不上平台时,在本机签发离线应急票,返回 ContingenciaPendente。最近一次联网刚失败过时直接离线签发,不再等待。
  2. 小票照常打印,自动带离线应急标识与「待授权」提示,不印协议号。
  3. 网络恢复后内核自动补传,无需任何调用;想立即补传可调 SincronizarAgora,例如检测到网络恢复时;它只触发后台下一轮同步并立即返回,可以在界面线程调用。
  4. 补传授权后收到 NOTA_AUTORIZADA 事件;离线票补传被 SEFAZ 拒绝收到 NOTA_REJEITADA,用 Substituir 同号修正,见第 5 节。

离线开不了票时,Emitir 抛出异常:

错误码情形怎么解除
10029804 / 10029807 / 10029810许可证到期 / 离线截止已过 / 最早待补传票超过补传时限恢复网络后自动解除
10029808本设备系列号码用到 999999999停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列
10029811州或主体不允许离线只能在线开票
10029812含燃料的票不能离线开,只能在线开票

建议收银界面定时(例如每 10 秒)读 Situacao 提示收银员:

Situacao 中的字段界面提示
Conectado 为 false「离线中,票据将在联网后补传」
PendentesTransmissao「待补传 N 张」
PrazoTransmissaoAte「请在某时之前恢复网络」,临近时醒目提示
OfflineAte离线时长即将用完时提示尽快联网
Avisos 不为空运行环境需要技术人员调整,原文记进日志或显示给技术支持

7 上线前检查清单

  1. 测试环境走通:配对、联网开票(Autorizada)、断网开票(ContingenciaPendente)、恢复网络后收到 NOTA_AUTORIZADA。
  2. 同一个 id 重发不会多开票;崩溃重启后能用 Consultar 取回结果。
  3. 事件按 EventoId 去重,且去重记录持久化;NOTA_NEGADA(换新 id 重开)与 NOTA_REJEITADA(同号修正)分开处理。
  4. 小票在实体店实际使用的打印机上打印清晰,二维码可扫;不支持 ESC/POS 直连的打印机用 PDF_80 测过。
  5. 安装包带上运行时目录;升级与卸载都不删数据目录;收银软件固定用同一个 Windows 用户运行。
  6. 收银界面能显示离线状态、待补传张数与补传截止时间。
  7. 证书到期、设备停用时有醒目提示。
  8. XmlAutorizado、XmlCancelamento、ExportarXmls、Backup、RestaurarBackup、ExportarPendentes 都在后台线程调用,界面不卡;SincronizarAgora 立即返回,可以直接调用。
  9. 实体店经代理上网时,在实际网络里测过配对与开票。
  10. 有定期加密备份,口令与备份文件分开保管、不写进程序;演练过在 Iniciar 之前从备份恢复;店员知道电脑坏了时怎样导出待补传包交给平台,见备份与坏机恢复。
  11. 主体切换到生产环境后,在生产环境重新生成配对码、配对新设备,并停用测试设备。
  12. 用主从模式的,演练过主机关机时从机返回 10029880、收银切到备用机,以及吊销一台从机后它返回 10029882。

下一步

  • 运维与进阶:取消、替代取消、查询与补打小票、取回与按月导出 XML、备份与坏机恢复、关闭与重启。
  • 多收银台(主从模式):一个门店多台收银台共用一个设备系列。
  • SDK 参考:配置项、每个方法、数据类型、事件与错误码。

常见错误与处理

错误码情形处理
10029801 / 10029802本机未配对该主体 / 配对了多个主体但没传 empresaId先配对;传 empresaId
10029804 / 10029807断网且许可证到期 / 离线截止已过恢复网络,自动续签
10029808本设备系列号码已用到 999999999停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列
10029809系统时钟被往回调校正系统时间
10029810最早待补传票已超补传时限尽快恢复网络补传
10029811 / 10029812不允许离线,或刚从备份恢复、还没拿到新许可证 / 含燃料的票只能联网开票;刚恢复的联网同步一轮后自动恢复离线开票
10029813 / 10029814证书不可用 / 已过期检查证书,续期后 TrocarCertificado
10029816设备已被停用联系集成商
10029817请求校验失败:缺必填字段、取值不合法、带了契约里没有的字段(逐个点名字段路径)按 Detalhes 修正;可先用 Previsualizar 预校验
10029780商品行引用了税种,但连不上平台展开;未占用票号恢复网络后用同一 id 重发;断网时商品行改传 impostos
10029818同一 id 已用于内容不同的票新单用新 id
10029819本机没有这个 id 的单据检查 id 与 empresaId
10029822当前状态不能取消已取消或已有取消在处理时不再重试;替代取消时原票须是在线开出的正常票
10029827数据目录来自别的电脑或别的 Windows 用户用原用户运行;换电脑须停用旧设备、重新配对
10029828数据目录被其他进程占用只开一个实例;恢复备份要在 Iniciar 之前,已启动的先 Encerrar
10029832 / 10029833运行时意外退出 / 等待超时用同一个 id 重试
10029841授权 XML 暂不可用还没授权时等 NOTA_AUTORIZADA;已授权仍报说明平台未归档或暂时不可达,稍后重试
10029842本地库比程序新数据目录被更新版本的 SDK 用过,拒绝启动:把 SDK 与运行时升级到不低于上次使用的版本;绝不删除数据目录
10029843取消 XML 暂不可用还没取消成功时等 CANCELAMENTO_CONCLUIDO;已取消仍报说明平台未归档或暂时不可达,稍后重试
10029844写文件失败导出或备份目录不可写、备份文件已存在:换目录或文件名,检查磁盘空间与权限
10029845替代票密钥不合法传本机开出、同一 CNPJ、未被平台拒收的离线替代票的 44 位密钥
10029846备份无法恢复口令错误或备份文件被改动、损坏:核对口令,换一份完好的备份;原库没有被改动
10029874参数不合法,例如初始化缺少收银软件名称或版本、代理格式不对、打印参数或导出日期越界按 Detalhes 补齐或修正参数
10029877找不到运行时检查安装包里的运行时目录
10029880 / 10029881从机连不上主机 / 请求已发出但没收到主机响应稍后重试或切到备用机;结果未知的,主机恢复后用同一个 id 调 Consultar
10029882从机的终端令牌无效或已吊销在主机重新签发终端令牌,更新 TokenTerminal
10029884从机调用了只在主机可用的方法配对、换证书、备份与导出在主机做
10029307设备环境与主体当前环境不一致在主体当前环境重新生成配对码、配对新设备

全部错误码与处理建议见 SDK 参考与错误码。

断网时开票为什么要等一会儿?

内核先尝试在线,等待超时后才改为离线签发,结果里 TentativaOnline 为 true;这张离线票用下一个号码,在线尝试的原号码由平台核对后收口,无需处理。最近一次联网刚失败过时直接离线签发,不再等待。

怎么测试离线开票?

在测试环境配对一台测试电脑,断开这台电脑的网络后开票;测试环境的票没有税务效力。

更换收银电脑怎么办?

先让旧电脑联网补传完全部离线票,再停用旧设备,为新电脑生成新配对码配对。不要拷贝数据目录。

旧电脑坏了、离线票还没补传怎么办?

电脑还能开机时,用 ExportarPendentes 导出待补传票,把这次导出的整个 pendentes-… 子目录压成一个 zip,交给平台运营在「导入待补传包」直接上传(导出时已按设备分目录、每包至多 500 张,不用解压也不用再拆),再停用旧设备、为新电脑重新配对,见备份与坏机恢复的路径一。加密备份只能在原电脑恢复,帮不了换电脑。电脑已无法开机时,联系平台处理。

在线开的票被拒(NOTA_NEGADA)和离线票补传被拒(NOTA_REJEITADA)有什么不同?

在线票被拒后不能修正,修正销售数据后用新 id 重开;离线票已经打印交给消费者,补传被拒时用 Substituir 同号修正,号码与访问密钥不变。