NFC-e 离线开票
内置 SDK 教程
内置 SDK 快速上手:生成配对码、引入 SDK、初始化与配对、开第一张票、打印小票、接收结果、断网时的行为与上线前检查,附 Java 完整示例。
这页带你在收银软件里接入内置 SDK:联网时 SDK 在本设备系列上取号、签名,经平台在线授权;断网时在本机签发离线应急票、当场打印,联网后自动补传。读完你能配对一台收银机、开出并打印第一张票、收到补传与取消结果。前置:能调用平台开放接口生成配对码,收银软件运行在 Windows 上;开票请求与云端开票接口相同;商品行引用税种须联网。
全程你只和 SDK 打交道,SDK 在后台运行离线开票内核。整个接入过程如下:
准备:生成配对码、引入 SDK、分发运行时│▼初始化 ──► 未配对?──► 配对(只在首次,需联网)│▼开票 ──► 按状态处理 ──► 打印小票│└─ 后台:断网时离线签发,联网后自动补传,结果以事件通知日常:作废与查询、取授权 XML、替代取消、月度导出 XML、备份与坏机恢复
每一步都给 Java 写法。方法与类型的完整说明见 SDK 参考;设备系列、离线应急票、补传等术语见号码与系列。
1 准备
1.1 生成配对码
每台收银机配对一次,配对码由集成商调用平台接口生成。下面是生成配对码的接口:
POST /openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacao
请求体可以为空;给收银机起名、限定只能由 SDK 配对时这样传:
{ "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 填发布版本号):
<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),目录结构如下:
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 的配置项。
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 保留期:
// 在 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 相同。
简易税制:门店现场销售、消费者不识别、现金付款。
{"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" }}}]}
常规税制:同一笔销售,只是税码不同。
{"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。
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 重开 |
Negada | SEFAZ 驳回 | 显示 SEFAZ 结果码与结果说明,修正后用新 id 重开 |
| 抛出异常 | 请求不合法、离线条件不满足等 | 显示异常说明;见常见错误 |
同一个 id 重复调用 Emitir 不会重复开票,返回的是原票。网络超时、程序崩溃后,用同一个 id 重发即可拿回结果。
4 打印小票
4.1 打印小票
Cupom(id, 格式) 返回小票字节,原样送打印机即可。离线票自带应急标识,打印份数由平台配置。格式取值:
| 格式 | 含义 |
|---|---|
ESCPOS_80 | 80mm 热敏打印机的 ESC/POS 指令 |
ESCPOS_58 | 58mm 热敏打印机的 ESC/POS 指令 |
TEXTO | 纯文本,UTF-8 |
HTML | HTML 页面,UTF-8,适合屏幕预览或浏览器打印 |
PDF_80 | 80mm 宽的 PDF,每联一页,交 Windows 打印驱动打印,适合不支持 ESC/POS 直连的打印机,见 4.2 |
下面的代码取 ESC/POS 小票并送打印机:
- 示例把字节发给网络热敏打印机的 9100 端口。
- USB 打印机可在 Windows 里共享后写到共享路径;串口打印机用串口库写入同样的字节即可。
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 小票。
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 同号修正:
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 这一侧的行为:
Emitir先尝试在线;等待超时或连不上平台时,在本机签发离线应急票,返回ContingenciaPendente。最近一次联网刚失败过时直接离线签发,不再等待。- 小票照常打印,自动带离线应急标识与「待授权」提示,不印协议号。
- 网络恢复后内核自动补传,无需任何调用;想立即补传可调
SincronizarAgora,例如检测到网络恢复时;它只触发后台下一轮同步并立即返回,可以在界面线程调用。 - 补传授权后收到
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 上线前检查清单
- 测试环境走通:配对、联网开票(
Autorizada)、断网开票(ContingenciaPendente)、恢复网络后收到NOTA_AUTORIZADA。 - 同一个
id重发不会多开票;崩溃重启后能用Consultar取回结果。 - 事件按
EventoId去重,且去重记录持久化;NOTA_NEGADA(换新id重开)与NOTA_REJEITADA(同号修正)分开处理。 - 小票在实体店实际使用的打印机上打印清晰,二维码可扫;不支持 ESC/POS 直连的打印机用
PDF_80测过。 - 安装包带上运行时目录;升级与卸载都不删数据目录;收银软件固定用同一个 Windows 用户运行。
- 收银界面能显示离线状态、待补传张数与补传截止时间。
- 证书到期、设备停用时有醒目提示。
XmlAutorizado、XmlCancelamento、ExportarXmls、Backup、RestaurarBackup、ExportarPendentes都在后台线程调用,界面不卡;SincronizarAgora立即返回,可以直接调用。- 实体店经代理上网时,在实际网络里测过配对与开票。
- 有定期加密备份,口令与备份文件分开保管、不写进程序;演练过在
Iniciar之前从备份恢复;店员知道电脑坏了时怎样导出待补传包交给平台,见备份与坏机恢复。 - 主体切换到生产环境后,在生产环境重新生成配对码、配对新设备,并停用测试设备。
- 用主从模式的,演练过主机关机时从机返回
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 | 设备环境与主体当前环境不一致 | 在主体当前环境重新生成配对码、配对新设备 |
断网时开票为什么要等一会儿?
内核先尝试在线,等待超时后才改为离线签发,结果里 TentativaOnline 为 true;这张离线票用下一个号码,在线尝试的原号码由平台核对后收口,无需处理。最近一次联网刚失败过时直接离线签发,不再等待。
怎么测试离线开票?
在测试环境配对一台测试电脑,断开这台电脑的网络后开票;测试环境的票没有税务效力。
更换收银电脑怎么办?
先让旧电脑联网补传完全部离线票,再停用旧设备,为新电脑生成新配对码配对。不要拷贝数据目录。
旧电脑坏了、离线票还没补传怎么办?
电脑还能开机时,用 ExportarPendentes 导出待补传票,把这次导出的整个 pendentes-… 子目录压成一个 zip,交给平台运营在「导入待补传包」直接上传(导出时已按设备分目录、每包至多 500 张,不用解压也不用再拆),再停用旧设备、为新电脑重新配对,见备份与坏机恢复的路径一。加密备份只能在原电脑恢复,帮不了换电脑。电脑已无法开机时,联系平台处理。
在线开的票被拒(NOTA_NEGADA)和离线票补传被拒(NOTA_REJEITADA)有什么不同?
在线票被拒后不能修正,修正销售数据后用新 id 重开;离线票已经打印交给消费者,补传被拒时用 Substituir 同号修正,号码与访问密钥不变。
