TF Fiscal
开发文档

NFC-e 离线开票

SDK 参考

NFC-e 离线开票内置 SDK 查阅手册:配置项、每个方法的签名与错误、数据类型、事件与错误码。

内置 SDK 的查阅手册,按配置项、方法、数据类型、事件、开票请求、错误码分节,每节可单独查。方法名为葡语,本页标题与正文用首字母大写的写法(如 Emitir),Java 代码里首字母小写(如 emitir);第一次接入请先看内置 SDK 教程。

配置项

配置在调用 Iniciar 时一次性传入,初始化后不能修改;要换配置,先 Encerrar 再重新 Iniciar。配置用 Configuracao.builder() ... .build() 链式设置。

表中最后五项(主从角色、主机端口、允许网段、主机地址、终端令牌)只用于一店多台收银台共用一个设备系列的主从部署,角色划分、部署步骤与从机可用的方法见多收银台(主从模式)。

配置项Java必填说明
数据目录diretorioDados(Path)是本地库目录。每台收银机一个,同一时刻只能由一个进程打开;补传前离线票的已签名文件只存在这里,不要删除,见内置 SDK 教程
运行时目录diretorioRuntime(Path)子进程模式必填运行时安装目录。其下须有 tffiscal-nfce.exe;找不到返回 10029877
收银软件名称nomeAplicativo(String)是收银软件名称。平台据此自动识别收银软件,同一软件在每台收银机上用同一个名称;缺少时返回 10029874
收银程序版本versaoAplicativo(String)是收银程序版本号。平台据此做最低版本与封禁版本管控,例如 3.2.1
错误文案语言idioma(String)否异常说明的语言。pt-BR(缺省)、en、zh-CN、es;只看语言部分,例如 en-US 按英语,其他语言按葡语。平台返回、SDK 原样转出的错误(例如税种不存在、与税制不符)也用这个语言
调用超时tempoLimitePadraoMs(long)否单次调用等待上限。缺省 30 秒;超时返回 10029833,迟到的结果被丢弃。配对、取授权或取消 XML 至少等 120 秒;ExportarXmls、ExportarPendentes、Backup、RestaurarBackup 至少等 30 分钟;配置得更长时以本项为准
启动超时tempoLimiteInicioMs(long)否等待运行时就绪的上限。缺省 5 秒;超时返回 10029831
自动重启reiniciarAutomaticamente(boolean)否运行时意外退出后自动重启。缺省开启,按 1、2、4 秒直到 60 秒的间隔重试
日志转发encaminharLog(boolean)否内核日志转给收银程序。缺省关闭;开启后写到 java.util.logging
出站代理proxy(String)否手工代理地址。host:porta 形式;缺省不设,不用代理直连;格式不对返回 10029874。见出站代理
代理认证proxyAutenticacao(String, String)否代理用户名与口令。手工代理与系统代理都可以带;口令只在内存中交给运行时,不写入磁盘与日志;只给认证、既没设代理地址也没开系统代理时返回 10029874
使用系统代理usarProxyDoSistema(boolean)否系统代理开关。缺省关闭;开启后使用 Windows 系统代理设置,优先于 Proxy;不支持 PAC 自动代理脚本
XML 保留天数retencaoXmlDias(int)否本机 XML 保留天数。授权 XML 与取消 XML 在本机保留的天数,取值 1 到 3650;不设或设 0 为 90 天;越界返回 10029874。超过保留期被清理的 XML 在读取时自动从平台取回;按月导出 XML 时,导出区间应在保留期内
运行模式modo(Modo)否Java 运行模式。SUBPROCESSO(缺省)或 EM_PROCESSO,见下
事件监听aoReceberEvento(Consumer<EventoNfce>)否启动时挂上的事件处理器。启动前积压的事件不会错过,见事件
运行时命令comandoRuntime(String)否高级项。运行时可执行文件的完整路径,只在开发与测试时使用
运行时参数argumentosRuntime(List<String>)否高级项。运行时启动参数,缺省 --stdio;只在开发与测试时使用
替身引擎motorSimulado(boolean)否测试用替身引擎。只供示例与自动化测试,不产生有效票据;正式环境不要开启
主从角色modoOperacao(ModoOperacao)否一店多台收银台共用一个系列时本机的角色。独立(缺省)、主机或从机,取值为 INDEPENDENTE / PRINCIPAL / SECUNDARIO;见多收银台(主从模式)
主机端口portaPrincipal(int)否主机的局域网端口。只用于主机;不设或设 0 为 8786;端口被占用时 Iniciar 返回 10029887
允许网段redesPermitidas(List<String>)否主机接受的从机网段。只用于主机;CIDR 写法,例如 192.168.0.0/24;不设为主机所在的 /24 网段;只接受局域网私有地址;格式不对返回 10029874
主机地址enderecoPrincipal(String)从机必填从机要连的主机地址。host:porta 形式,例如 192.168.0.10:8786;必须是局域网私有地址,否则返回 10029883
终端令牌tokenTerminal(String)从机必填从机的终端令牌。主机 CriarTerminal 签发、以 tfl_ 开头;只在内存中交给运行时,不写入磁盘与日志;无效或已吊销时 Iniciar 返回 10029882

Java 运行模式

Modo含义要求
SUBPROCESSO缺省。SDK 启动运行时子进程宿主 Java 8 及以上;须分发运行时并设 diretorioRuntime
EM_PROCESSO内核直接在收银程序的 JVM 里运行,不启动子进程宿主 Java 21 及以上,类路径含运行时与内核的 jar;低于 Java 21 启动即返回 10029835。配置代理认证时 JVM 启动参数须加 -Djdk.http.auth.tunneling.disabledSchemes=,见出站代理

出站代理

内核访问平台时按下表决定是否走代理:

配置代理方式
开启 UsarProxyDoSistema系统代理。先读 Windows 的 WinHTTP 本机代理设置,没有再读当前 Windows 用户的 Internet 选项代理设置;同时设了 Proxy 时以系统代理为准
只设 Proxy手工代理。使用 Proxy 给出的地址
都不设直连
  • 不支持 PAC 自动代理脚本:Windows 只配置了自动代理脚本、没有固定代理地址时,内核记一条警告日志后直连。这类网络请改为手工设置 Proxy。
  • 代理认证:proxyAutenticacao对手工代理与系统代理都生效。
  • Java 进程内模式的启动参数:HTTPS 隧道上的代理 Basic 认证取决于 JVM 系统属性 jdk.http.auth.tunneling.disabledSchemes,JVM 只在自带 HTTP 客户端首次使用时读一次,之后再改无效。Java 进程内模式(EM_PROCESSO)配置代理认证时,宿主必须在 JVM 启动参数里加 -Djdk.http.auth.tunneling.disabledSchemes=(等号后留空)。内核加载时也会在宿主未设该属性时尽早置空,并判断是否生效:宿主显式禁用了 Basic、宿主已先用过 JVM 自带的 HTTP 客户端,或无法判断时,Situacao 的 Avisos 报告代理认证可能无效并记一条警告日志。Java 子进程模式由运行时子进程在启动时设置,宿主不需要处理。

下面示范手工代理加认证。

java
Configuracao configuracao = Configuracao.builder()
// 其余配置同上
.proxy("10.0.0.5:3128")
.proxyAutenticacao("caixa01", senhaProxy)
.build();

配置示例

一份常用的基础配置,未列出的项取缺省值。

java
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")
.tempoLimitePadraoMs(30_000)
.build();

方法

每个方法按同一顺序给出:用途与是否联网、签名、参数、返回、可能的错误、示例。除各方法列出的错误外,任何方法都可能返回通用错误,见错误码开头。

Iniciar

启动 SDK:拉起运行时(子进程模式)或加载内核(Java 进程内模式),打开数据目录,恢复上次未完成的流程,并开始后台心跳、补传与结果拉取。其他方法都要在 Iniciar 成功之后调用;一个数据目录同一时刻只能有一个实例。

联网:不需要。断网时也能启动,启动后有网即开始同步。

签名

java
public static TfFiscalNfce iniciar(Configuracao config);

参数

参数Java必填说明
配置config是初始化配置。字段见配置项

返回

已就绪的 SDK 实例 TfFiscalNfce。用完调用 Encerrar,也可以用 try-with-resources 自动关闭。

可能的错误

错误码情形处理
10029877找不到运行时检查运行时目录与 tffiscal-nfce.exe 是否随安装包分发
10029831运行时启动失败或未在启动超时内就绪查看日志;电脑过慢时可调大启动超时
10029830SDK 与运行时版本不兼容运行时与 SDK 用同一版本分发
10029835Java 进程内模式但宿主低于 Java 21改用子进程模式,或升级 Java
10029828数据目录已被其他进程打开同一目录只开一个实例;检查是否有残留进程
10029827本机密钥无法解开:数据目录来自别的电脑或别的 Windows 用户用原 Windows 用户运行;换电脑须停用旧设备、重新配对
10029829本地库不一致不要删除数据目录,联系平台
10029842本地库版本高于当前内核:数据目录曾被更新版本的 SDK 使用过,拒绝启动把 SDK 与运行时升级到不低于上次使用的版本;绝不要删除数据目录,未补传的离线票原件在里面
10029840配置非法按 Message 修正配置项
10029874配置项取值不对:缺少收银软件名称或版本、代理地址格式不对、只给代理认证、XML 保留天数越界按 Detalhes.campo 修正配置项
10029882从机的终端令牌无效或已吊销在主机重新签发终端令牌,更新 TokenTerminal
10029883从机的主机地址格式不对,或不是局域网私有地址修正 EnderecoPrincipal
10029887主机的局域网端口无法监听换 PortaPrincipal,或释放被占用的端口

另可能返回通用错误。

示例

java
try (TfFiscalNfce nfce = TfFiscalNfce.iniciar(configuracao)) {
System.out.println("ativado=" + nfce.isAtivado());
}

Ativado / Empresas

  • Ativado:本数据目录是否至少配对了一个主体。收银程序启动时据此决定是否进入配对流程。
  • Empresas:已配对的主体清单。一个数据目录配对多个主体(多个 CNPJ)时,用它找到每个主体的 empresaId。

两者每次都向内核查询、不缓存:设备被平台停用后,状态会如实反映在 Situacao 字段里。

联网:不需要。

签名

java
public boolean isAtivado();
public List<Resultados.EmpresaAtivada> getEmpresas();

参数

无。

返回

Ativado 返回布尔值。Empresas 返回已配对主体清单,元素字段见数据类型:已配对主体。

可能的错误

只有通用错误。

示例

java
if (!nfce.isAtivado()) {
nfce.ativar(codigoAtivacao, Certificado.doRepositorio(thumbprint, false));
}
for (Resultados.EmpresaAtivada empresa : nfce.getEmpresas()) {
System.out.println(empresa.getEmpresaId() + " " + empresa.getCnpj() + " " + empresa.getSituacao());
}

InspecionarCodigoAtivacao

在本机核验配对码的格式、平台签名、有效期与指向的平台地址,并读出主体、环境与允许形态。不联网,也不消耗配对码。适合在配对前给收银员确认「这是测试环境的码,72 小时内有效」,或提前拦下格式错误、已过期、形态不符的配对码。

联网:不需要。配对码有效不代表配对一定成功:已使用、已作废等情况只有平台在 Ativar 时才能判断。

签名

java
public Resultados.CodigoAtivacao inspecionarCodigoAtivacao(String codigo);

参数

参数Java必填说明
配对码codigo是配对码全文。TFA1. 开头;.tfa 文件的内容即配对码全文,首尾空白会被去掉

返回

配对码信息,字段见数据类型:配对码信息。

可能的错误

错误码情形处理
10029825配对码格式、签名或有效期不对确认复制完整;已过期请集成商重新生成
10029826配对码指向的平台地址不受信配对码不是本平台签发,或运行时版本与环境不匹配;联系集成商

另可能返回通用错误。

示例

java
Resultados.CodigoAtivacao info = nfce.inspecionarCodigoAtivacao(codigoAtivacao);
System.out.println("ambiente " + info.getAmbiente() + " expira " + info.getExpiraEm());

Ativar

用集成商生成的设备配对码与主体的 A1 证书,把本机配对为该主体的一台设备。配对时内核生成设备密钥、绑定证书并向平台登记,成功后得到设备系列与首张许可证,平台推送 nfce.device.activated(见结果怎么收到)。每个主体在一个数据目录里只配对一次;同一数据目录可以再配对其他主体。

联网:需要。连不上平台返回 10029824,配对码不会被消耗。

签名

java
public Resultados.Ativacao ativar(String codigoAtivacao, Certificado certificado);

参数

参数Java必填说明
配对码codigoAtivacao是配对码全文。TFA1. 开头,一次性、72 小时有效
证书certificado是主体的 A1 证书。来源写法见数据类型:证书来源;证书 CNPJ 须与主体一致

返回

配对结果,字段见数据类型:配对结果。

可能的错误

错误码情形处理
10029825 / 10029826配对码本机核验失败 / 指向的平台不受信见 InspecionarCodigoAtivacao
10029824连不上平台联网后重试
10029837该主体已在本数据目录配对无需再次配对
10029813 / 10029814证书找不到、无私钥、CNPJ 不符 / 已过期选用主体的有效 A1 证书
10029839平台已配对但本机保存失败用同一配对码再次调用 Ativar
10029806许可证不属于本设备重新配对;仍失败联系平台
10029874证书参数不合法:指纹不是 40 位十六进制,或 PFX 为空修正证书参数
10029205 到 10029208平台返回:配对码无效 / 已过期 / 已使用 / 已作废重新生成配对码
10029209平台返回:配对码不允许 SDK 形态按 Sdk 或 Qualquer 重新生成
10029210 / 10029211平台返回:缺少收银软件名称 / 收银程序版本被封禁或过低配置收银软件名称;升级收银程序
10029213 / 10029214平台返回:证书 CNPJ 与主体不符 / 证书已过期换用主体的有效证书
10029219平台返回:配对码环境与主体当前环境不一致在主体当前环境重新生成配对码
10029221 到 10029225平台返回:配对码指定的设备系列已不可用集成商换一个系列或起始号码重新生成配对码

另可能返回通用错误。

示例

java
Resultados.Ativacao a = nfce.ativar(codigoAtivacao, Certificado.doRepositorio(thumbprint, false));
System.out.println("empresa " + a.getEmpresaId() + " dispositivo " + a.getDispositivoId() + " serie " + a.getSerieOffline());

Emitir

开一张 NFC-e。内核在本设备系列上取号、签名,先把签好的票交平台在线授权;连不上平台、平台超时或结果不明时,改为本机离线签发,当场返回可打印的离线票。请求体与云端开票接口完全相同,见开票请求。

处理顺序:

  1. 按 id 查本地:已开过同一 id 直接返回原票,不重复取号;内容不同返回 10029818。
  2. 商品行引用了税种(classeImposto)时,先交平台展开为完整的 impostos:须联网,连不上平台返回 10029780,不占用票号;税种被拒(不存在、与税制不符等)原样返回平台的错误码与说明。
  3. 规范化与校验,规则与云端相同;不通过返回 10029817,Detalhes 逐字段列出原因。
  4. 在本设备系列上取号、签名后在线提交,结果与云端同步开票相同;平台返回业务错误时原样返回,不转离线,号码留给下一张票。唯一例外是平台回号码已被占用(10029424):内核弃掉这个号,与平台同步一轮刷新已确认号后只重试一次,再冲突就原样返回,不会逐号撞下去卡住收银。
  5. 在线失败或超时,核对许可证、补传时限、离线开关等条件后离线签发,返回 ContingenciaPendente。结果不明时原号码不再使用,离线票用下一个号码,原号码由平台核对后收口:已授权的由平台替代取消,未授权的申报作废(见平台自动处理的号码情形);当时不能离线签发则返回 AguardandoAutorizacao,稍后用原号码原样重提。最近一次联网刚失败过时跳过第 4 步,直接离线签发。

同一主体的开票在内核内部按顺序执行,保证设备系列号码连续,在线票与离线票共用;不同主体可以并行。

联网:可选。联网时在线开票,断网时离线签发。

签名

java
public ResultadoEmissao emitir(String pedidoJson);
public ResultadoEmissao emitir(String pedidoJson, String empresaId);

参数

参数Java必填说明
开票请求pedidoJson是开票请求。JSON 文本;结构与云端开票接口相同,modoResposta 无需传。商品行可传 impostos,也可用 classeImposto 引用税种(须联网)
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略;配对多个而不传返回 10029802

返回

开票结果,字段与状态见数据类型:开票结果。

Status收银程序怎么做
Autorizada打印小票
ContingenciaPendente离线签发:用 Cupom 打印小票交给消费者,补传自动进行
AguardandoAutorizacao在线已受理但 SEFAZ 未返回,且当时不能改为离线签发:先不打印,等 NOTA_AUTORIZADA 事件或稍后查询;之后被 SEFAZ 拒绝时收到 NOTA_NEGADA
Negada在线开票被 SEFAZ 拒绝:不能同号修正,按 SEFAZ 结果码与结果说明修正销售数据后用新 id 重开

可能的错误

错误码情形处理
10029817请求校验失败按 Detalhes 修正
10029780商品行引用了税种,但连不上平台展开;未占用票号恢复网络后用同一 id 重发;断网时商品行改传 impostos
10029818同一 id 已用于内容不同的票新单用新 id;重试用原请求
10029801 / 10029802主体未配对 / 多主体未传 empresaId先配对;传 empresaId
10029816设备已被停用联系集成商
10029805 / 10029806许可证签名无效 / 不属于本设备联系平台;必要时重新配对
10029874请求不是 JSON 对象传 JSON 对象文本
10029803 / 10029804 / 10029807断网且无许可证 / 许可证过期 / 离线截止已过恢复网络,续签后自动恢复
10029808本设备系列号码已用到 999999999停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列
10029809系统时钟被往回调校正系统时间
10029810最早待补传票已超补传时限恢复网络补传
10029811 / 10029812主体或州不允许离线 / 含燃料的票只能联网开票
10029813 / 10029814证书不可用 / 已过期检查证书,必要时 TrocarCertificado
10029815本机配置或计税数据缺失联网同步一次
10029823设备系列号码已用尽停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列
10029307平台返回:设备环境与主体当前环境不一致在主体当前环境重新配对新设备
10029424平台返回:号码已被占用。内核已自动弃号并重试一次,仍冲突说明本机库与平台记录不一致不要换号重试;导出日志联系平台排查
10029426平台返回:同一 id 在平台已有未被拒绝的票,例如已由云端接口或其他设备开出用查询 NFC-e核对原票;新的销售用新 id
其他平台码在线开票时平台返回的业务错误,如 10022004按开具 NFC-e的错误说明处理

另可能返回通用错误。

示例

java
ResultadoEmissao r = nfce.emitir(pedidoJson);
if ("Autorizada".equals(r.getStatus()) || "ContingenciaPendente".equals(r.getStatus())) {
impressora.enviar(nfce.cupom(r.getId(), FormatoCupom.ESCPOS_80));
}

Previsualizar

用与 Emitir 相同的规范化、校验与计税规则检查一份开票请求,返回是否通过、逐字段的错误说明、票面合计与税额合计。不取号、不签名、不落库,也不联网。适合在收银界面边录入边校验:校验不通过时不抛异常,返回 Valido 为 false。

联网:不需要。

签名

java
public Resultados.PreVisualizacao previsualizar(String pedidoJson, String empresaId);

参数

参数Java必填说明
开票请求pedidoJson是待校验的开票请求。结构同 Emitir;id 可以先不填
主体标识empresaId多主体时必填开票主体。Java 只配对一个主体时传 null

返回

预览结果,字段见数据类型:预览结果。Erros 已按配置的错误文案语言翻译,可直接展示给收银员。

可能的错误

校验不通过不抛错。除通用错误外只有主体相关的错误:10029801(主体未配对)、10029802(多主体未传 empresaId)、10029815(本机计税数据缺失,联网同步一次)。

另可能返回通用错误。

示例

java
Resultados.PreVisualizacao p = nfce.previsualizar(pedidoJson, null);
if (!p.isValido()) {
p.getErros().forEach(System.out::println);
}

建议在输入停顿约 300 毫秒后再调用,不要每个按键都调。

Consultar

按开票时的 id 查询本机票据的当前状态:是否已授权、是否已补传、是否有待执行的取消、修正过几次、授权 XML 是否已下载,以及原始开票请求。在线票与离线票都存在本机,离线票补传前也能查。收银程序崩溃重启后,用它取回崩溃前开出的票。

联网:不需要。返回的是本机记录,补传与授权结果随后台同步更新;需要尽快拿到最新结果时先调 SincronizarAgora。

签名

java
public SituacaoNota consultar(String id);
public SituacaoNota consultar(String id, String empresaId);

参数

参数Java必填说明
单据标识id是开票请求里的 id
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略

返回

查询状态,字段见数据类型:查询状态。

可能的错误

错误码情形处理
10029819本机没有这张票核对 id 与 empresaId;票不是在本机开出的,请用云端查询
10029801 / 10029802主体未配对 / 多主体未传 empresaId先配对;传 empresaId

另可能返回通用错误。

示例

java
SituacaoNota s = nfce.consultar("PDV01-000131");
System.out.println(s.getStatus() + " transmitida=" + s.isTransmitida() + " protocolo=" + s.getProtocolo());

ListarNotas

分页列出本机票据(在线票与离线票都在内),按开票时间倒序,每页 50 张。适合做「当日票据」界面、交班核对待补传张数。为了不做全表计数,结果不给总数,只给是否还有下一页。

联网:不需要。

签名

java
public Resultados.PaginaNotas listarNotas(LocalDate data, String status, int pagina, String empresaId);

参数

参数Java必填说明
开票日期data否按开票日筛选。日期按主体所在州时区;不传则不限日期,做当日列表时请总是传
状态status否按状态筛选。取值见数据类型:单据状态;不传则不限
页码pagina否页码。从 1 开始,缺省 1
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略,Java 传 null

返回

票据分页,字段见数据类型:票据分页。界面分页只做「上一页 / 下一页」,TemMais 为 false 时禁用下一页。

可能的错误

错误码情形处理
10029874日期不是 yyyy-mm-dd、状态取值不对,或页码小于 1按取值表传参
10029801 / 10029802主体未配对 / 多主体未传 empresaId先配对;传 empresaId

另可能返回通用错误。

示例

java
Resultados.PaginaNotas pagina = nfce.listarNotas(LocalDate.now(), "ContingenciaPendente", 1, null);
pagina.getItens().forEach(n -> System.out.println(n.getId() + " " + n.getNumero()));

Cancelar

取消一张已开出的 NFC-e。按票的状态与网络情况分三种去向:

情形去向 Situacao之后
票已授权且联网Solicitado已提交平台,结果经 CANCELAMENTO_CONCLUIDO 或 CANCELAMENTO_REJEITADO 事件获知
离线票已补传、尚未授权Agendado平台挂起取消,在票授权那一刻自动发起,不要求收银程序仍在运行
当前断网,或离线票尚未补传EnfileiradoLocal本机排队;补传后同一轮立即提交,motivo 说明原因

取消时限与云端相同,见取消 NFC-e。收银流程里的用法见运维与进阶:取消。

联网:可选。断网时本机排队。

签名

java
public Resultados.Cancelamento cancelar(String id, String justificativa, String empresaId);

参数

参数Java必填说明
单据标识id是开票请求里的 id
取消原因justificativa是取消原因。15 到 255 个字符
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略,Java 传 null

返回

取消受理结果,字段见数据类型:取消结果。受理不代表已取消,最终结果看事件或 Consultar 的 Status。

可能的错误

错误码情形处理
10029822当前状态不可取消:已取消、已有挂起的取消,或不是已授权、待授权状态;本机状态尚未同步、由平台判定不可取消(如票在平台已被拒)时也是此码,detalhes 带平台原因不要重试;用 Consultar 确认状态
10029819本机没有这张票核对 id
10029817原因长度不在 15 到 255 个字符修正原因
其他平台码联网提交时平台返回的错误,如超出取消时限 10022007按取消 NFC-e处理

另可能返回通用错误。

示例

java
Resultados.Cancelamento c = nfce.cancelar("PDV01-000131", "Cliente desistiu da compra no caixa", null);
System.out.println(c.getSituacao());

CancelarPorSubstituicao

替代取消:一张在线开出的票,被本机随后开出的离线应急票取代时(同一笔销售重新开票),用它取消原票,并在取消中注明替代票的访问密钥。

前提条件:

对象必须满足不满足时
原票在线转发开出的正常票:不是离线票,未取消,也没有挂起的取消10029822
替代票本机、本主体开出的离线票,未被平台拒收;访问密钥为 44 位、模型 65、校验位正确、CNPJ 与原票相同,且不等于原票密钥10029845

替代票尚未补传时返回 EnfileiradoLocal:取消在本机排队,替代票补传成功后才提交。最终结果经 CANCELAMENTO_CONCLUIDO 或 CANCELAMENTO_REJEITADO 事件到达。取消时限与云端相同,见取消 NFC-e。完整的重开与替代取消流程见运维与进阶:替代取消。

联网:可选。断网或替代票尚未补传时本机排队,满足条件后自动提交。

签名

java
public Resultados.Cancelamento cancelarPorSubstituicao(String id, String chaveSubstituta, String justificativa,
String empresaId);

参数

参数Java必填说明
单据标识id是被取代的原票的 id
替代票密钥chaveSubstituta是替代票的访问密钥。44 位数字,从替代票开票结果的 Chave 取得
取消原因justificativa是取消原因。15 到 255 个字符
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略,Java 传 null

返回

取消受理结果,字段见数据类型:取消结果。受理不代表已取消,最终结果看事件或 Consultar 的 Status。

可能的错误

错误码情形处理
10029822原票不是在线开出的正常票:是离线票、已取消,或已有挂起的取消不要重试;离线票用 Cancelar
10029845替代票密钥不合法,或不是本机、本主体未被拒收的离线票传本机为同一笔销售开出的离线票的 44 位访问密钥
10029819本机没有原票核对 id
10029817原因长度不在 15 到 255 个字符修正原因
其他平台码提交时平台返回的错误,如超出取消时限 10022007按取消 NFC-e处理

另可能返回通用错误。

示例

java
ResultadoEmissao substituta = nfce.emitir(pedidoRefeitoJson);
Resultados.Cancelamento c = nfce.cancelarPorSubstituicao("PDV01-000131", substituta.getChave(),
"Venda refeita em contingencia offline", null);
System.out.println(c.getSituacao());

Substituir

离线票补传后被 SEFAZ 拒绝时(状态 Rejeitada,事件 NOTA_REJEITADA),这张票已经交给消费者,不能另开一张代替,只能用同一号码修正后重传。Substituir 用修正后的请求重新组包签名,号码、系列、访问密钥与开票时间保持不变,然后放回补传队列;内核在下一次同步时自动补传。补传与被拒后的规则见离线票与补传。

只能改不影响金额与税额的内容,例如商品 NCM、CFOP、消费者证件;票面合计与任一行税额变化都会被拒绝。

联网:不需要。修正在本机完成,补传在后台进行。

签名

java
public ResultadoEmissao substituir(String id, String pedidoJsonCorrigido, String empresaId);

参数

参数Java必填说明
单据标识id是被拒那张票的 id
修正后的请求pedidoJsonCorrigido是完整的开票请求。以原请求为底稿修改,原请求可从 Consultar 的 Pedido 取得;id 与原请求相同
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略,Java 传 null

返回

开票结果,结构同 Emitir,Status 回到 ContingenciaPendente。再次补传授权后收到 NOTA_AUTORIZADA,其 Dados.aposCorrecao 为 true。

可能的错误

错误码情形处理
10029820当前状态不可修正:只有 Rejeitada 可以修正用 Consultar 确认状态
10029821修正改变了金额或税额只改非金额内容
10029817请求校验失败按 Detalhes 修正
10029780商品行引用了税种,但连不上平台展开;未占用票号恢复网络后用同一 id 重发;断网时商品行改传 impostos
10029819本机没有这张票核对 id
10029815本机配置或计税数据缺失联网同步一次

另可能返回通用错误。

示例

java
SituacaoNota original = nfce.consultar("PDV01-000131");
ResultadoEmissao r = nfce.substituir("PDV01-000131", corrigirNcm(original.getPedido()), null);
System.out.println(r.getStatus());

Cupom

为一张本机票据生成小票。离线票的小票自动印离线应急标识与「待授权」提示、不印协议号;打印联数由平台配置。ESC/POS 字节可直接送热敏打印机,PDF 可交 Windows 打印驱动打印。断网时也能出小票。

需要调整每行列数、代码页、二维码打法、切纸或联数时,用带打印参数的重载,参数见下文「打印参数」。

联网:不需要。

签名

java
public byte[] cupom(String id, FormatoCupom formato);
public byte[] cupom(String id, FormatoCupom formato, String empresaId);
public byte[] cupom(String id, FormatoCupom formato, OpcoesCupom opcoes, String empresaId);

参数

参数Java必填说明
单据标识id是开票请求里的 id
格式formato是小票格式。取值见下表
打印参数opcoes(OpcoesCupom)否小票打印参数。只在带打印参数的重载里有,可传 null;字段见下文「打印参数」
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略
Java FormatoCupom内容
ESCPOS_8080mm 热敏打印机的 ESC/POS 字节
ESCPOS_5858mm 热敏打印机的 ESC/POS 字节
TEXTOUTF-8 纯文本
HTMLUTF-8 HTML,用于屏幕预览或浏览器打印
PDF_8080mm 宽的 PDF,每联一页。交 Windows 打印驱动打印,适合不能直接接收 ESC/POS 的打印机;使用 PDF 标准等宽字体、不嵌入字体,葡语重音正常显示;二维码为黑白图像

打印参数

OpcoesCupom 类,链式设置。没有设置的项用缺省值;取值越界返回 10029874,Detalhes.campo 为 opcoes。

参数Java必填说明
每行列数colunas(int)否每行字符数。48、42、32;不设或设 0 时按格式,80mm 为 48,58mm 为 32
代码页paginaCodigo(String)否打印机代码页。CP1252(缺省,西欧)、CP860(葡萄牙语)、CP850(西欧多语言)、CP437(美式英语);代码页里没有的字符先去掉重音再打印
二维码打法modoQrCode(OpcoesCupom.ModoQrCode)否二维码打印方式。NATIVO(缺省)用打印机自带的二维码指令;IMAGEM 把二维码作为位图打印,用于不支持二维码指令的打印机
二维码模块大小tamanhoModuloQr(int)否二维码模块点数。1 到 16;不设或设 0 时为 4
切纸cortar(boolean)否切纸开关。缺省 true,打印后切纸
联数vias(int)否打印联数。1 到 9;不设或设 0 时按平台配置

返回

小票字节。PDF_80 为 PDF 文件内容。

可能的错误

错误码情形处理
10029819本机没有这张票核对 id
10029874格式取值不对,或打印参数越界用上表的取值

另可能返回通用错误。

示例

java
byte[] cupom = nfce.cupom("PDV01-000131", FormatoCupom.ESCPOS_80);
Files.write(Paths.get("PDV01-000131.escpos"), cupom);
// 80mm PDF,交 Windows 打印驱动
byte[] pdf = nfce.cupom("PDV01-000131", FormatoCupom.PDF_80, new OpcoesCupom().vias(1), null);
Files.write(Paths.get("PDV01-000131.pdf"), pdf);

QrCodePng

生成一张本机票据的二维码 PNG 图像(黑白、带静区)。自行排版小票或在屏幕上展示二维码时使用;内容与开票结果的 QrCode 相同。断网时也能生成。

联网:不需要。

签名

java
public byte[] qrCodePng(String id, int tamanhoPx, String empresaId);

参数

参数Java必填说明
单据标识id是开票请求里的 id
图像边长tamanhoPx否图像边长像素。64 到 2048,须显式传
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略,Java 传 null

返回

PNG 图像字节。

可能的错误

错误码情形处理
10029819本机没有这张票核对 id
10029817图像边长不在 64 到 2048 之间修正边长

另可能返回通用错误。

示例

java
Files.write(Paths.get("PDV01-000131-qrcode.png"), nfce.qrCodePng("PDV01-000131", 240, null));

XmlAutorizado

读取一张票的授权 XML 原文(含授权协议)。在线票授权后、离线票补传授权后,内核自动把授权 XML 下载到本机,保留天数由配置项 RetencaoXmlDias 决定(缺省 90 天)。本机没有时(尚未下载,或已按保留期清理),内核当场联网从平台取回;平台的归档是正本。

Consultar 的 XmlAutorizadoDisponivel 为 true 时直接读本机,不联网。

不要在界面线程调用:本机没有时要等平台返回,最长约 120 秒(调用超时配置得更长时以调用超时为准),请放到后台线程。

联网:可能。本机没有时同步从平台取回,最长约 120 秒;不要在界面线程调用。

签名

java
public byte[] xmlAutorizado(String id, String empresaId);

参数

参数Java必填说明
单据标识id是开票请求里的 id
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略,Java 传 null

返回

授权 XML 的 UTF-8 字节。

可能的错误

错误码情形处理
10029841授权 XML 不可用:还没授权,或本机没有且从平台取不回未授权的等 NOTA_AUTORIZADA 事件后再取;已授权的说明平台尚未归档或当前连不上平台,稍后重试
10029819本机没有这张票核对 id

另可能返回通用错误。

示例

java
// 可能联网回取,放到后台线程
CompletableFuture.supplyAsync(() -> nfce.xmlAutorizado("PDV01-000131", null))
.thenAccept(xml -> gravar("PDV01-000131-nfce.xml", xml));

XmlCancelamento

读取一张已取消票据的取消 XML 原文(取消事件及其回执)。本机保留天数与授权 XML 相同,由配置项 RetencaoXmlDias 决定(缺省 90 天);本机没有时,内核当场联网从平台取回。

不要在界面线程调用:本机没有时要等平台返回,最长约 120 秒(调用超时配置得更长时以调用超时为准)。

联网:可能。本机没有时同步从平台取回,最长约 120 秒;不要在界面线程调用。

签名

java
public byte[] xmlCancelamento(String id, String empresaId);

参数

参数Java必填说明
单据标识id是开票请求里的 id
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略,Java 传 null

返回

取消 XML 的 UTF-8 字节。

可能的错误

错误码情形处理
10029843取消 XML 不可用:票没有取消,或本机没有且从平台取不回未取消的等 CANCELAMENTO_CONCLUIDO 事件后再取;已取消的说明平台尚未归档或当前连不上平台,稍后重试
10029819本机没有这张票核对 id

另可能返回通用错误。

示例

java
CompletableFuture.supplyAsync(() -> nfce.xmlCancelamento("PDV01-000131", null))
.thenAccept(xml -> gravar("PDV01-000131-can.xml", xml));

ExportarXmls

按开票日期把一段时间内的授权 XML 与取消 XML 导出到目录,用于按月交给会计或留档。日期按主体所在州时区计算,起止日期都包含在内。操作步骤见运维与进阶:按月导出 XML 给会计。

  • 文件名:授权 XML 为 {chave}-nfe.xml,取消 XML 为 {chave}-can.xml({chave} 为 44 位访问密钥);同名文件直接覆盖。
  • 本机没有的 XML 先联网从平台取回;仍取不到的不中断导出,逐张列在结果的 Falhas 里并写明原因(包括是否已按保留期清理)。
  • 导出区间应在配置项 RetencaoXmlDias 的保留期内;超出保留期的 XML 要逐张从平台回取,取不到的列入 Falhas。
  • 断网时快速结束:导出开始前刚连不上平台,或导出途中第一次连不上平台,其余缺 XML 的票不再联网,直接列入 Falhas。
  • 只导本机已有:somenteLocal 设为 true 时完全不联网,只写出本机已有的 XML,缺的票列入 Falhas。

联网:可能。本机没有的 XML 联网回取,somenteLocal 为 true 时不联网。等待上限至少 30 分钟,调用超时配置得更长时以调用超时为准;不要在界面线程调用。等待超时(10029833)时运行时可能仍在写文件,不要马上对同一目录重试,稍等片刻后换一个新目录重新导出。

签名

java
public Resultados.ExportacaoXml exportarXmls(LocalDate de, LocalDate ate, Path diretorio, String empresaId);
public Resultados.ExportacaoXml exportarXmls(LocalDate de, LocalDate ate, Path diretorio, boolean somenteLocal,
String empresaId);

参数

参数Java必填说明
起始日期de是开票日期起点。包含当天
结束日期ate是开票日期终点。包含当天
目标目录diretorio是导出目录。相对路径按收银程序当前目录转为绝对路径
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略,Java 传 null
只导本机somenteLocal否本机导出标志。true 只导本机已有的 XML、不联网;缺省 false,本机没有的先联网回取。Java 用五个参数的重载

返回

导出结果,字段见数据类型:XML 导出结果。

可能的错误

错误码情形处理
10029874日期缺失或格式不对,Detalhes.campo 为 de 或 ate修正日期
10029844目录不可写换目录;检查磁盘空间与权限
10029801 / 10029802主体未配对 / 多主体未传 empresaId先配对;传 empresaId

单张缺 XML 不报错,见结果的 Falhas。

另可能返回通用错误。

示例

java
Resultados.ExportacaoXml r = nfce.exportarXmls(LocalDate.of(2026, 10, 1), LocalDate.of(2026, 10, 31),
Paths.get("C:/Exportacao/2026-10"), null);
System.out.println("exportadas " + r.getQuantidadeNotas() + " notas, " + r.getQuantidadeArquivos() + " arquivos, falhas "
+ r.getFalhas().size());

TrocarCertificado

主体 A1 证书续期或更换后,用新证书替换内核里登记的证书。设备身份、设备系列、许可证都不变,不需要重新配对;新证书在下次心跳时上报平台。证书到期前内核会发出 CERTIFICADO_EXPIRANDO 事件(30、7、1 天各一次),可据此提醒管理员。

联网:不需要。

签名

java
public void trocarCertificado(Certificado certificado, String empresaId);

参数

参数Java必填说明
证书certificado是新的 A1 证书。写法见数据类型:证书来源;CNPJ 须与主体一致
主体标识empresaId多主体时必填开票主体。只配对一个主体时可省略,Java 传 null

返回

无。成功后 Situacao 的 CertificadoValidoAte 更新为新证书的到期时间。

可能的错误

错误码情形处理
10029813证书不可用:找不到、无私钥,或 CNPJ 与主体不符检查证书存储,选用主体的证书
10029814证书已过期换用有效证书
10029874证书参数不合法:指纹不是 40 位十六进制,或 PFX 为空修正证书参数
10029801 / 10029802主体未配对 / 多主体未传 empresaId先配对;传 empresaId

另可能返回通用错误。

示例

java
nfce.trocarCertificado(Certificado.deArquivoPfx(Files.readAllBytes(Paths.get("C:/deploy/novo.pfx")), senha), null);

Situacao

读取内核整体状态:内核版本、引擎级告警,以及每个已配对主体的连接情况、许可证剩余、待补传张数、补传截止、证书到期与最近一次错误。适合在收银界面显示「离线中」「待补传 N 张」「证书 7 天后到期」等提示;可定时调用(例如每 10 秒一次),开销很小。

联网:不需要。

签名

java
public Resultados.Nucleo situacao();

参数

无。

返回

内核状态,字段见数据类型:内核状态;每主体状态是 getEmpresas() 返回的键值对列表。

建议的界面提示:

条件提示
Conectado 为 false离线中,票据将在联网后补传
PendentesTransmissao 大于 0待补传张数;结合 PrazoTransmissaoAte 显示补传截止
OfflineAte 临近离线时长即将用完,请尽快联网
CertificadoValidoAte 临近证书即将到期,续期后调用 TrocarCertificado
Situacao 不是 Ativo设备已不能开新票,联系集成商
UltimoErro 有值最近一次同步失败的原因,排障时提供给技术支持
Avisos 不为空运行环境需要调整,例如 Java 进程内模式缺少代理认证所需的启动参数,见出站代理;原文显示给技术人员

可能的错误

只有通用错误。

示例

java
Resultados.Nucleo s = nfce.situacao();
for (Map<String, Object> empresa : s.getEmpresas()) {
System.out.println(empresa.get("empresaId") + " conectado=" + empresa.get("conectado"));
}
for (String aviso : s.getAvisos()) {
System.out.println("aviso: " + aviso);
}

SincronizarAgora

立即触发一轮同步:心跳、续签许可证、补传离线票、提交排队的取消、拉取平台结果。内核本来就会定时自动同步,这个方法用于缩短等待,例如收银程序检测到网络恢复时、交班前希望尽快补传完时。

同步在后台进行,结果经事件到达,或之后用 Consultar、Situacao 查看。调用只触发后台下一轮同步并立即返回,不等同步结果,可以在界面线程直接调用;某个主体的一轮同步正在进行时不会并发再跑,这一轮结束后接着同步。断网时调用不报错。

联网:触发联网,不等待同步结果,调用立即返回。

签名

java
public void sincronizarAgora();

参数

无。

返回

无。

可能的错误

只有通用错误。

示例

java
// 只触发后台下一轮同步并立即返回,可以在界面线程直接调用
nfce.sincronizarAgora();

Backup

把本地库加密备份成一个文件,用于定期留存或换硬盘前的保护。备份取的是某一时刻的完整快照,期间可以照常开票。备份策略与坏机恢复的整体流程见运维与进阶:备份与坏机恢复。

  • 加密:口令经 PBKDF2-SHA256 派生密钥,整份库用 AES-256-GCM 加密。SDK 与平台都不保存口令,口令丢失后备份无法恢复,请与备份文件分开保管。
  • 只能在同一台电脑、同一 Windows 用户下恢复:本地库里的设备密钥受 Windows 用户级保护,换电脑或换 Windows 用户后备份无法使用,须停用旧设备、重新配对。
  • 恢复:用 RestaurarBackup。恢复时使用的 SDK 与运行时版本不能低于备份时的版本,结果的 VersaoBanco 记录了本地库结构版本。
  • 写入:先写临时文件再改名,失败时不会留下不完整的备份文件。

联网:不需要。等待上限至少 30 分钟,调用超时配置得更长时以调用超时为准;本地库较大时要几分钟,不要在界面线程调用。等待超时(10029833)时运行时可能仍在写文件,不要马上用同一文件名重试,稍等片刻后换一个新文件名。

签名

java
public Resultados.Backup backup(Path destino, String senha);

参数

参数Java必填说明
备份文件destino是备份文件路径。文件不能已存在;相对路径按收银程序当前目录转为绝对路径
口令senha是备份口令。至少 8 位;恢复时须提供同一口令,不进日志

返回

备份结果,字段见数据类型:备份结果。

可能的错误

错误码情形处理
10029874口令为空,Detalhes.campo 为 senha传入口令
10029817口令不足 8 位换更长的口令
10029844目标文件已存在,或目录不可写换文件名或目录;检查磁盘空间与权限

另可能返回通用错误。

示例

java
Resultados.Backup b = nfce.backup(Paths.get("D:/Backup/tffiscal-20261031.bak"), senhaBackup);
System.out.println(b.getArquivo() + " " + b.getBytes() + " sha256=" + b.getSha256());

RestaurarBackup

用 Backup 生成的加密备份换回本地库,用于本地库丢失、损坏或误操作后的恢复。这是静态方法,在 Iniciar 之前调用:它不启动引擎、不联网,子进程模式下 SDK 临时拉起一个运行时,恢复完即退出。调用时这个数据目录不能有实例在运行,已经启动的实例先 Encerrar,恢复完成后再 Iniciar。什么情况下用备份、什么情况下改用导出待补传包,见运维与进阶:备份与坏机恢复。

  • 只能在原电脑恢复:备份里的设备密钥受 Windows 数据保护,只能在生成备份的同一台电脑、同一个 Windows 用户下使用。换电脑或换 Windows 用户时不要靠备份,用 ExportarPendentes 导出待补传票交平台,再为新电脑重新配对。
  • 原库另存:恢复前把数据目录里的原库改名另存(文件名以 nfce.db.antes-restauracao- 开头),结果的 CopiaAnterior 给出路径;恢复失败时原库不动。
  • 版本:备份的本地库结构版本高于当前 SDK 时拒绝;低于时下次 Iniciar 自动升级。
  • 恢复后的保护:备份里的号码与许可证都停在备份时刻。恢复后 Iniciar,各主体先进入恢复对齐:离线开票返回 10029811,联网开票在取号前先与平台同步一轮。拿到新的许可证后,设备系列号码向后跳过 50 个号,在线票与离线票共用这一次跳号,跳过的号自动向平台申报作废(结果经 NUMERO_INUTILIZADO 事件到达),之后在线与离线开票都照常。对齐完成前连不上平台就开不了票。备份之后开出的票即使已交给消费者,也不会出现重号。
  • 备份之后开出的离线票:备份里没有它们。旧库还能启动时,恢复前先用旧库调 ExportarPendentes 导出交平台,否则这些票会丢失。

联网:不需要。等待上限至少 30 分钟,调用超时配置得更长时以调用超时为准;不要在界面线程调用。

签名

java
public static Resultados.Restauracao restaurarBackup(Configuracao config, Path origem, String senha);

参数

参数Java必填说明
配置config是初始化配置。与 Iniciar 用同一份,取其中的数据目录与运行时位置,见配置项
备份文件origem是备份文件路径。相对路径按收银程序当前目录转为绝对路径
口令senha是备份口令。生成备份时用的口令

返回

恢复结果,字段见数据类型:恢复结果。

可能的错误

错误码情形处理
10029846口令错误,或备份文件被改动、损坏、不是本 SDK 的备份;两种情况不区分核对口令;换一份完好的备份。原库没有被改动
10029842备份来自更新版本的 SDK把 SDK 与运行时升级到不低于备份时的版本
10029828数据目录有其他引擎在运行,包括本程序还没 Encerrar 的实例。SDK 的静态 RestaurarBackup 每次另开一个运行时连接,遇到的就是这个码先 Encerrar 使用这个数据目录的实例,再恢复
10029875同一个运行时连接已经 Iniciar 之后,又调用恢复备份的协议方法 restaurarBackup。SDK 的静态 RestaurarBackup 每次另开连接,不会遇到;只在自行对接运行时协议时出现先 Encerrar,再另开一个连接、在 Iniciar 之前恢复
10029817口令不足 8 位输入生成备份时的口令
10029874备份文件或口令为空,Detalhes.campo 为 origem 或 senha补齐参数
10029844读写文件失败检查备份文件路径、数据目录的磁盘空间与权限

另可能返回通用错误。

示例

java
nfce.encerrar();
Resultados.Restauracao r = TfFiscalNfce.restaurarBackup(config, Paths.get("D:/Backup/tffiscal-20261031.bak"), senhaBackup);
System.out.println("versao " + r.getVersaoBanco() + " anterior " + r.getCopiaAnterior());
nfce = TfFiscalNfce.iniciar(config);
// 拿到新许可证前离线开票暂停,立即同步一轮(本段放在后台线程执行)
nfce.sincronizarAgora();

ExportarPendentes

把本机已签名、尚未补传的离线票导出成平台可直接导入的待补传包,用于收银机损坏或长期无法联网、来不及在本机补传的情形。导出不改变本机状态,这些票仍留在本机的补传队列里。坏机时的整体处理步骤见运维与进阶:备份与坏机恢复。

每次调用都在目标目录下新建一个以导出时刻(UTC)命名的子目录,按设备分目录,每包至多 500 张:

text
{diretorio}/pendentes-20261111-150000/{dispositivoId}/pacote-001/manifesto.json
/pacote-001/{chave}.xml
/pacote-002/…
  • {diretorio} 是调用时传入的目标目录,{dispositivoId} 是设备标识,{chave} 是 44 位访问密钥。
  • 每份清单 manifesto.json 记录所属设备,每张票连同签名 XML 一起写在清单里,可直接交平台导入;同目录的 {chave}.xml 是同一份签名 XML,方便人工查看。
  • 交平台时把这次导出的整个 pendentes-… 子目录压成一个 zip,交给平台运营在「导入待补传包」直接上传,不用解压,也不用按包或按设备拆开。多主体时 zip 里有多个设备目录,运营按设备筛选后分批提交。
  • 没有待补传票时不报错:Quantidade 为 0,Manifesto 为空,Manifestos 为空数组。
  • 清单先写临时文件再改名,读到的清单一定完整。

联网:不需要。等待上限至少 30 分钟,调用超时配置得更长时以调用超时为准;不要在界面线程调用。等待超时(10029833)时运行时可能仍在写文件,不要马上对同一目录重试,稍等片刻后换一个新目录重新导出。

签名

java
public Resultados.ExportacaoPendentes exportarPendentes(Path diretorio);

参数

参数Java必填说明
目标目录diretorio是导出目录。相对路径按收银程序当前目录转为绝对路径

导出本数据目录内全部已配对主体的待补传票,每个主体的设备各一个目录、各自的清单,清单里逐张记录所属主体。

返回

导出结果,字段见数据类型:待补传导出结果。

可能的错误

错误码情形处理
10029844目录不可写换目录;检查磁盘空间与权限

另可能返回通用错误。

示例

java
Resultados.ExportacaoPendentes p = nfce.exportarPendentes(Paths.get("E:/Pendentes"));
System.out.println(p.getQuantidade() + " notas, " + p.getManifestos().size() + " pacote(s)");

CriarTerminal

主机为一台从机签发终端令牌。名称就是这台从机开出的票上的收银台标识,请用门店里认得出的收银台编号,例如 Caixa 2。令牌全文只在返回时出现这一次,主机只保存摘要:当场配置到从机的 TokenTerminal,丢失了就吊销后重新签发。只在主机模式可用,从机的部署与管理见多收银台(主从模式)。

联网:不需要。

签名

java
public Resultados.TerminalCriado criarTerminal(String nome);

参数

参数Java必填说明
终端名称nome是收银台名称。1 到 60 个字符;有效终端之间不得重名,不区分大小写

返回

新终端,字段见数据类型:从机终端。

可能的错误

错误码情形处理
10029874名称为空、超过 60 个字符,或与有效终端重名(Detalhes.motivo 为 duplicado)换一个名称;要沿用旧名称时先吊销旧终端
10029884当前不是主机模式只在主机调用

另可能返回通用错误。

示例

java
Resultados.TerminalCriado t = principal.criarTerminal("Caixa 2");
// 令牌全文只返回这一次,当场配置到收银台 2
System.out.println(t.getId() + " " + t.getToken());

ListarTerminais

主机列出从机终端,按创建时间倒序,不含令牌。缺省不列出吊销满 30 天的终端,传 todos 为 true 时全部列出;记录一直保留。只在主机模式可用。

联网:不需要。

签名

java
public List<Resultados.Terminal> listarTerminais(boolean todos);

参数

参数Java必填说明
全部列出todos否含吊销满 30 天的终端。缺省 false

返回

终端列表,字段见数据类型:从机终端。

可能的错误

错误码情形处理
10029884当前不是主机模式只在主机调用

另可能返回通用错误。

示例

java
for (Resultados.Terminal t : principal.listarTerminais(false)) {
System.out.println(t.getNome() + " " + t.getSituacao() + " " + t.getUltimoUsoEm());
}

RevogarTerminal

主机吊销一台从机的终端令牌,立即生效:该从机之后的调用返回 10029882,尚未投递给它的事件一并删除。从机丢失、停用或令牌泄露时调用。吊销不能撤销,需要时重新签发。只在主机模式可用。

联网:不需要。

签名

java
public void revogarTerminal(String id);

参数

参数Java必填说明
终端标识id是CriarTerminal 返回的 id,以 trm_ 开头

返回

无。

可能的错误

错误码情形处理
10029888终端不存在用 ListarTerminais 核对 id
10029884当前不是主机模式只在主机调用

另可能返回通用错误。

示例

java
principal.revogarTerminal("trm_8Kq2Xc0vLm4R");

Encerrar

关闭 SDK:停止后台同步,等进行中的开票完成(最多 10 秒),关闭本地库,再结束运行时(再等 5 秒仍未退出则强制结束)。整个过程最长约 15 秒。收银程序退出前调用。可以重复调用;关闭后再调用其他方法返回 10029834,需要重新 Iniciar。

关闭期间不补传;下次 Iniciar 后立即同步一轮;若仍有待补传的票或未确认的事件,会发出 PENDENCIAS_NA_INICIALIZACAO。退出与重启时的注意事项见运维与进阶:关闭与重启。

联网:不需要。

签名

java
public void encerrar();
public void close();

close 等同于 Encerrar,可配合 try-with-resources。

参数

无。

返回

无。

可能的错误

不抛错误,可以重复调用。

示例

java
Runtime.getRuntime().addShutdownHook(new Thread(nfce::encerrar));

数据类型

方法返回的结果对象、事件里的状态取值与证书参数。各表的列这样读:

  • JSON 名:getJson() 原文里的字段名。
  • Java:取值方法;标「经 getCampos()」的字段没有专门方法,用 getCampos().get("字段名") 读。
  • 时间字段为 ISO 8601 UTC 文本。
  • 所有结果都保留原文(getJson());新版本运行时增加的字段,旧版 SDK 也能从原文读到。
  • 「可空」为「是」的字段可能为 null。

单据状态

开票结果、查询状态与事件里的 Status 取值。

取值含义收银程序怎么做
Autorizada已授权打印小票
ContingenciaPendente本机离线签发,待补传打印小票交给消费者,补传自动进行
AguardandoAutorizacao在线已受理,SEFAZ 尚未返回先不打印,等授权事件;之后被拒时收到 NOTA_NEGADA
Negada在线转发的票被 SEFAZ 拒绝,包括等待授权后才被拒的票(事件 NOTA_NEGADA)不能同号修正;修正销售数据后用新 id 重开
Rejeitada离线票补传被 SEFAZ 拒绝(事件 NOTA_REJEITADA)用 Substituir 同号修正,不能另开
Recusada平台拒收这张离线票需人工介入,联系平台
Cancelada已取消无

开票结果

Emitir 与 Substituir 的返回。Java ResultadoEmissao。

JSON 名Java类型可空说明
idgetId()文本否单据标识。开票请求里的 id
statusgetStatus()文本否单据状态。取值见上
emitidaEmContingenciaisEmitidaEmContingencia()布尔否离线签发标志。授权后仍为 true
chavegetChave()文本是访问密钥。44 位数字
seriegetSerie()(Long)整数是系列
numerogetNumero()(Long)整数是票号
dataEmissaogetDataEmissao()时间是开票时间
protocologetProtocolo()文本是授权协议号。离线待补传时为 null
qrCodegetQrCode()文本是二维码内容。自行排版小票时编码成二维码
urlConsultagetUrlConsulta()文本是消费者查询网址
motivogetMotivo()文本是原因说明。来自 SEFAZ 或平台
cStatgetCStat()(Long)整数是SEFAZ 结果码。没有 SEFAZ 结果时为 null
xMotivogetXMotivo()文本是SEFAZ 结果说明。与结果码成对出现
tentativaOnlineisTentativaOnline()布尔否在线尝试标志。先尝试在线、结果不明后转离线时为 true,这张票用的是在线尝试那个号码的下一个号,原号码由平台在补传时核对后收口;在线授权的票为 false
respostaPlataformagetRespostaPlataforma()文本是平台响应原文。在线开票时为平台返回的 JSON,结构同查询 NFC-e;离线为 null
terminalgetTerminal()文本是收银台标识。主从模式下从机开出的票为该从机的终端名称;主机或独立模式自己开的票为 null。随提交上报平台,与查询 NFC-e 和 Webhook 的 terminal 同值

查询状态

Consultar 的返回与票据分页的元素。Java SituacaoNota;包含开票结果的全部字段,另有:

JSON 名Java类型可空说明
transmitidaisTransmitida()布尔否已补传标志。离线票已补传到平台
cancelamentoPendenteisCancelamentoPendente()布尔否取消待执行标志。有挂起或本机排队的取消
correcoesgetCorrecoes()(Long)整数否修正次数
atualizadoEmgetAtualizadoEm()时间是最后更新时间
xmlAutorizadoDisponivelisXmlAutorizadoDisponivel()布尔否本机 XML 就绪标志。授权 XML 已在本机时为 true,XmlAutorizado 直接读本机;已授权但为 false 时调用会联网回取
pedidogetPedido()文本是开票请求。JSON 文本,同号修正时作为底稿;引用税种的商品行已换成平台展开后的 impostos,可留作断网时改传

票据分页

ListarNotas 的返回。Java Resultados.PaginaNotas。

JSON 名Java类型可空说明
itensgetItens()数组否本页票据。元素为查询状态,按开票时间倒序
paginagetPagina()整数否页码。从 1 开始
tamanhoPaginagetTamanhoPagina()整数否每页张数。固定 50
temMaisisTemMais()布尔否下一页标志。不提供总数

预览结果

Previsualizar 的返回。Java Resultados.PreVisualizacao。

JSON 名Java类型可空说明
validoisValido()布尔否校验通过标志
errosgetErros()文本数组否校验错误。已按错误文案语言翻译;通过时为空数组
pedidoNormalizadogetPedidoNormalizado()文本是规范化后的请求。JSON 文本,一般不用
valorTotalgetValorTotal()(BigDecimal)小数是票面合计
valorTributosgetValorTributos()(BigDecimal)小数是税额合计

取消结果

Cancelar 与 CancelarPorSubstituicao 的返回。Java Resultados.Cancelamento。

JSON 名Java类型可空说明
situacaogetSituacao()文本否受理去向。取值见下
motivogetMotivo()文本是说明
situacao含义
Solicitado已授权的票,取消已提交平台;结果经 CANCELAMENTO_CONCLUIDO 或 CANCELAMENTO_REJEITADO 事件到达
Agendado离线票已补传、尚未授权,平台挂起取消,授权后自动发起
EnfileiradoLocal本机排队:断网,或离线票 / 替代票尚未补传;补传后同一轮立即提交

配对码信息

InspecionarCodigoAtivacao 的返回。Java Resultados.CodigoAtivacao。

JSON 名Java类型可空说明
ambientegetAmbiente()(Long)整数否开票环境。1 生产,2 测试
formasPermitidasgetFormasPermitidas()(Long)整数否允许形态。0 不限形态,1 仅发票助手,2 仅内置 SDK
expiraEmgetExpiraEm()时间否配对码到期时间
plataformagetPlataforma()文本否平台地址。配对码指向的平台
seriegetSerie()(Long)整数是指定的设备系列。集成商生成配对码时指定的系列;未指定为 null,配对时由平台分配
numeroInicialgetNumeroInicial()(Long)整数是指定的起始号码。只指定了系列时为生成配对码时平台算出的号码;未指定为 null,从 1 开始

配对结果

Ativar 的返回。Java Resultados.Ativacao。

JSON 名Java类型可空说明
empresaIdgetEmpresaId()文本否主体标识。其他方法的 empresaId
dispositivoIdgetDispositivoId()文本否设备标识
cnpjgetCnpj()文本否主体 CNPJ
uf经 getCampos()文本否所在州
ambiente经 getCampos()整数否开票环境。1 生产,2 测试
serieOfflinegetSerieOffline()(Long)整数否设备系列。本设备专用,在线票与离线票共用、号码连续;字段名沿用旧名
licencaExpiraEmgetLicencaExpiraEm()时间是许可证到期时间
numeroInicialgetNumeroInicial()(Long)整数否起始号码。本设备第一张票的号码;配对码未指定时为 1

已配对主体

Empresas 的元素。Java Resultados.EmpresaAtivada。

JSON 名Java类型可空说明
empresaIdgetEmpresaId()文本否主体标识
dispositivoIdgetDispositivoId()文本否设备标识
cnpjgetCnpj()文本否主体 CNPJ
uf经 getCampos()文本否所在州
ambiente经 getCampos()整数否开票环境。1 生产,2 测试
serieOffline经 getCampos()整数否设备系列
situacaogetSituacao()文本否设备状态。取值见下
situacao含义处理
Ativo可以开票无
Desativado集成商已停用设备不可恢复;同一电脑要继续用须重新配对
Revogado平台已吊销设备联系平台
EmpresaDesativada该主体的离线开票被停用联系平台
AplicativoBloqueado收银软件被平台封禁联系平台
VersaoBloqueada收银程序版本被封禁或低于最低版本升级收银程序

除 Ativo 外都不能开新票,已开出的离线票照常补传。

内核状态

Situacao 的返回。Java Resultados.Nucleo。

JSON 名Java类型说明
versaoNucleogetVersaoNucleo()文本内核版本
empresasgetEmpresas()(元素为键值对)数组每个已配对主体的状态,字段见下
avisosgetAvisos()文本数组引擎告警。需要宿主处理的运行环境问题,没有时为空数组。例如配置了代理认证,但 Java 进程内模式缺少代理认证所需的 JVM 启动参数或设置未生效,见出站代理。文案为葡萄牙语,可直接展示

empresas 元素:

JSON 名类型可空说明
empresaId文本否主体标识
dispositivoId文本否设备标识
situacao文本否设备状态。取值同已配对主体
conectado布尔否在线标志。当前能否连上平台
ultimoContato时间是最后联系时间
licencaExpiraEm时间是许可证到期时间
offlineAte时间是离线开票截止时间。许可证到期与证书到期中较早的一个
pendentesTransmissao整数否待补传张数
pendenteMaisAntigaEm时间是最早待补传时间。最早一张待补传票的开票时间
prazoTransmissaoAte时间是补传截止时间。最早一张待补传票的补传时限;过了这个时间设备不能继续离线开票
certificadoValidoAte时间是证书到期时间
ultimoErro文本是最近错误。最近一次同步失败的原因
numerosNaoUtilizadosPendentes整数否待作废号段数。取号后未用、尚待向平台申报作废的号码区间数;申报被拒且不是终态时自动重试,见 NUMERO_INUTILIZACAO_RECUSADA
restauradoPendenteSincronizacao布尔否恢复待对齐标志。从备份恢复后、拿到新许可证前为 true,期间离线开票返回 10029811,联网开票先与平台同步一轮;对齐后为 false。界面据此提示收银员联网,不要解析错误文案

XML 导出结果

ExportarXmls 的返回。Java Resultados.ExportacaoXml。

JSON 名Java类型可空说明
quantidadeNotasgetQuantidadeNotas()整数否导出张数。至少写出一个文件的单据张数
quantidadeArquivosgetQuantidadeArquivos()整数否文件数。写出的授权 XML 与取消 XML 文件总数;一张已取消的票授权与取消 XML 都写出时算两个
arquivosgetArquivos()文本数组否导出文件。写出的文件绝对路径,授权 XML 与取消 XML 各一个文件
falhasgetFalhas()(元素为键值对)数组否缺失清单。区间内取不到 XML 的单据,没有时为空数组;元素字段见下

falhas 元素:

JSON 名Java 键类型说明
idid文本单据标识
chavechave文本访问密钥
motivomotivo文本缺失原因。包括是否已按保留期清理

备份结果

Backup 的返回。Java Resultados.Backup。

JSON 名Java类型可空说明
arquivogetArquivo()文本否备份文件。绝对路径
bytesgetBytes()整数否文件大小。单位字节
versaoBancogetVersaoBanco()整数否本地库结构版本。恢复时内核版本须不低于此版本
sha256getSha256()文本否文件摘要。加密后备份文件的 SHA-256,小写十六进制

恢复结果

RestaurarBackup 的返回。Java Resultados.Restauracao。

JSON 名Java类型可空说明
versaoBancogetVersaoBanco()整数否本地库结构版本。恢复进来的库的版本;低于当前 SDK 时下次启动自动升级
copiaAnteriorgetCopiaAnterior()文本是原库副本。恢复前另存的原库文件绝对路径;原来没有库时为空

待补传导出结果

ExportarPendentes 的返回。Java Resultados.ExportacaoPendentes。

JSON 名Java类型可空说明
quantidadegetQuantidade()整数否导出张数
manifestogetManifesto()文本是第一份清单。第一包 manifesto.json 的绝对路径;没有待补传票时为空
manifestosgetManifestos()文本数组否全部清单。每个设备目录下每个 pacote-NNN 一份,每包至多 500 张;没有待补传票时为空数组
arquivosgetArquivos()文本数组否签名 XML 文件。绝对路径

证书来源

Ativar 与 TrocarCertificado 的证书参数。

来源Java
Windows 证书存储中已有的证书Certificado.doRepositorio(thumbprint, maquinaLocal)
PFX 文件Certificado.deArquivoPfx(bytes, senha)
参数说明
thumbprint证书指纹。SHA-1,40 位十六进制,空格会被忽略;格式不对返回 10029874
maquinaLocal本机证书存储标志。true 用本机证书存储,false(缺省)用当前 Windows 用户的证书存储
PFX 字节与 senhaPFX 证书与密码。内核把证书导入证书存储并设为私钥不可导出,之后只保存指纹,密码不保存

用 PFX 配对或换证时(Certificado.deArquivoPfx),内核把证书导入运行 SDK 的 Windows 用户的「当前用户 > 个人」证书存储,私钥不可导出,并长期保留在那里,每次签名都从这里取。不要删除这张证书:删除后设备无法签名,开票返回 10029813。

设备不再使用时按顺序清理:

  1. 确认状态中各公司的 pendentesTransmissao 为 0,离线票已全部补传
  2. 在控制台停用或吊销设备;只是换证书的,先用 TrocarCertificado 换上新证书
  3. 以同一 Windows 用户打开 certmgr.msc,在「个人 > 证书」中按指纹删除旧证书,或在 PowerShell 执行 Remove-Item Cert:\CurrentUser\My\<指纹>

从机终端

CriarTerminal 的返回。Java Resultados.TerminalCriado。

JSON 名Java类型可空说明
idgetId()文本否终端标识。以 trm_ 开头,吊销时用
nomegetNome()文本否终端名称。即该从机开出的票上的收银台标识
tokengetToken()文本否终端令牌。以 tfl_ 开头,只返回这一次,配置到从机的 TokenTerminal

ListarTerminais 的元素。Java Resultados.Terminal;不含令牌。

JSON 名Java类型可空说明
idgetId()文本否终端标识
nomegetNome()文本否终端名称
situacaogetSituacao()文本否终端状态。Ativo 或 Revogado
criadoEmgetCriadoEm()时间否签发时间
ultimoUsoEmgetUltimoUsoEm()时间是最后使用时间。从未使用时为 null
revogadoEmgetRevogadoEm()时间是吊销时间。有效终端为 null

异常

所有失败都抛出异常。

字段Java TfFiscalException说明
错误码getCodigo()整数。按它判断,见错误码
错误常量getTipo()例如 ENGINE_LICENSE_EXPIRED;平台错误为平台的常量名
说明getMessage()按配置的错误文案语言翻译,可直接展示
补充信息getDetalhes()、getDetalhesJson()例如请求校验失败时的 erros 逐字段原因、参数错误时的 campo

错误码常量:TfFiscalErrorCodes 里登记了常用的码;未登记的码同样以数字出现在错误码字段上。

事件

内核在票据状态、许可证、证书、连接等变化时向收银程序投递的本机事件。平台向集成商服务器推送的 Webhook 是另一条通道,见结果怎么收到;主从模式下从机收到哪些事件见多收银台(主从模式)。

订阅

订阅方式回调线程
配置的 aoReceberEvento(Consumer<EventoNfce>),或实例方法 aoReceberEvento,返回值关闭即取消订阅子进程模式在 SDK 专用线程上逐个回调;进程内模式在内核的投递线程上同步回调。处理器抛出异常即不确认

用配置里的 aoReceberEvento 在启动时挂上处理器,启动前积压的事件不会错过。

投递与确认

  • 至少一次、按顺序:事件与触发它的状态变化在本机同一事务里落库,再投递。
  • 确认:处理器正常返回即确认。处理器抛出异常则不确认,约 30 秒后从最早未确认的事件起重投,EventoId 与 Seq 不变。
  • 去重:同一事件可能收到多次,请按 EventoId 去重。
  • 不要在处理器里长时间阻塞:耗时处理先记下事件再异步执行,否则后续事件积压。
  • SDK 本地事件:RUNTIME_FALHOU 与 RUNTIME_REINICIADO 由 SDK 自己产生,Seq 为 0,不需要确认,也不会重投。

公共字段

JSON 名Java类型可空说明
eventoIdgetEventoId()文本否事件标识。去重键,重投时不变
seqgetSeq()(long)整数否本机序号。单调递增;SDK 本地事件为 0
tipogetTipo()文本否事件类型。见下文各节
ocorridoEmgetOcorridoEm()时间文本否发生时间。ISO 8601 UTC
empresaIdgetEmpresaId()文本是主体标识。SDK 本地事件为 null
dispositivoId经 getCampos()文本是设备标识
idgetId()文本是单据标识。只有票据类事件有值
chavegetChave()文本是访问密钥。只有票据类事件有值
statusgetStatus()文本是单据当前状态。只有票据类事件有值,取值见单据状态
dadosgetDados()(Map<String, Object>)对象否事件数据。字段见下文各节

NOTA_EMITIDA_OFFLINE

离线签发成功。票据类事件,status 为 ContingenciaPendente。

dados 字段类型说明
serie整数设备系列
numero整数票号
qrCode文本二维码内容
tentativaOnline布尔在线尝试标志。先尝试在线、结果不明后转离线时为 true;在线授权的票为 false

处理:把收银单据标为「离线待补传」。开票当时已经从 Emitir 拿到同样的结果,这个事件主要用于收银程序崩溃重启后补齐状态。

NOTA_AUTORIZADA

离线票补传后授权、同号修正后授权,或在线未决的票授权。票据类事件,status 为 Autorizada。

dados 字段类型说明
protocolo文本授权协议号
dataAutorizacao时间文本,可空授权时间
foraDoPrazo布尔逾期送达标志。超过 24 小时才送达 SEFAZ 时为 true,票仍然有效
aposCorrecao布尔修正后授权标志。同号修正后授权时为 true

处理:把收银单据标为已授权并记录协议号;在线未决的票此时可以打印小票。

NOTA_REJEITADA

离线票补传被 SEFAZ 拒绝。票据类事件,status 为 Rejeitada。

dados 字段类型说明
cStat整数SEFAZ 结果码
motivo文本SEFAZ 结果说明

处理:提示管理员修正,用 Substituir 同号修正,不能另开新票。原请求从 Consultar 的 Pedido 取得。

NOTA_NEGADA

在线转发、处于等待授权(AguardandoAutorizacao)的票,之后被 SEFAZ 拒绝。票据类事件,status 为 Negada。离线票补传被拒不发这个事件,发 NOTA_REJEITADA。

dados 字段类型说明
cStat整数SEFAZ 结果码
motivo文本SEFAZ 结果说明
numeroLiberado布尔号码已回收。为 true 时 SEFAZ 没有使用这个号码,内核会把它留给下一张在线开的票,不产生断号

处理:这张票不能同号修正。按结果码与说明修正销售数据,用新 id 重新调用 Emitir 开票。

NOTA_RECUSADA_PLATAFORMA

平台拒收这张离线票。票据类事件,status 为 Recusada。

dados 字段类型说明
codigo整数,可空平台错误码
mensagem文本平台说明

处理:需要人工介入,记录错误码与说明后联系平台。

CANCELAMENTO_CONCLUIDO

取消成功。票据类事件,status 为 Cancelada。

dados 字段类型说明
cStat整数,可空SEFAZ 结果码
motivo文本结果说明
protocolo文本,可空取消协议号

处理:把收银单据标为已取消。

CANCELAMENTO_REJEITADO

取消被拒绝,例如超出取消时限,或平台拒绝挂起的取消。票据类事件,status 为票的原状态。

dados 字段类型说明
cStat整数,可空SEFAZ 结果码
motivo文本拒绝原因
protocolo文本,可空协议号

处理:票仍然有效。提示管理员按取消 NFC-e的规则另行处理。

NUMERO_INUTILIZADO

取号后未完成签发的设备系列号码已结案:已在 SEFAZ 作废,或在 AC、BA、SP 等不再受理作废的州按规定免于申报。两种情况号码都视为已用,不会再开出。不是票据类事件。

dados 字段类型说明
serie整数设备系列
inicio整数起始号码
fim整数结束号码

处理:无需操作,可记入日志用于对账。

NUMERO_INUTILIZACAO_RECUSADA

未用号码的作废申报被平台拒绝。不是票据类事件。不是终态的拒绝只在第一次失败时发一次,内核随后自动退避重试;终态的拒绝需要人工核对。

dados 字段类型说明
serie整数设备系列
inicio整数起始号码
fim整数结束号码
codigo整数平台错误码
mensagem文本平台说明
definitivo布尔终态标志。true 表示不会再重试,例如区间不合法或区间内已有票据;false 表示内核会自动重试

处理:definitivo 为 false 时记入日志即可,待作废的区间数见 Situacao 的 NumerosNaoUtilizadosPendentes;为 true 时记录错误码与说明,由管理员核对该号码区间后联系平台。

DISPOSITIVO_DESATIVADO

设备被停用或吊销、主体离线开票被停用、收银软件或其版本被封禁。之后新开票被拒,已开出的离线票照常补传。

dados 字段类型说明
situacao文本设备状态。取值见已配对主体
motivo文本原因。可能为空文本

处理:在收银界面醒目提示「本机已不能开票」,按 situacao 指引联系集成商或升级收银程序。

LICENCA_EXPIRANDO

许可证剩余不足 12 小时且未能续签,通常是长时间断网。每 6 小时至多一次。

dados 字段类型说明
expiraEm时间文本许可证到期时间
offlineAte时间文本离线开票截止时间

处理:提示收银员尽快恢复网络,联网后自动续签。

LICENCA_EXPIRADA

许可证已过期,离线开票被拒,在线开票不受影响。

dados 字段类型说明
expiradaEm时间文本过期时间

处理:恢复网络后自动续签。

PRAZO_TRANSMISSAO_PROXIMO

最早一张待补传票已过补传时限的 80%。

dados 字段类型说明
pendenteMaisAntigaEm时间文本最早待补传票的开票时间
prazoAte时间文本补传截止时间

处理:醒目提示收银员立即恢复网络。超过截止时间后本机不能继续离线开票。

CERTIFICADO_EXPIRANDO

主体证书将在 30、7、1 天内到期,各提醒一次。

dados 字段类型说明
validoAte时间文本证书到期时间

处理:提醒管理员续期证书,续期后调 TrocarCertificado。

CONEXAO_ALTERADA

在线与离线之间切换。

dados 字段类型说明
conectado布尔在线标志。true 表示恢复连接

处理:更新收银界面的在线 / 离线标识。

PENDENCIAS_NA_INICIALIZACAO

启动时本机还有待补传的离线票,或尚未确认的事件。

dados 字段类型说明
pendentesTransmissao整数待补传张数
eventosNaoEntregues整数未确认的事件数

处理:收银界面可提示「有 N 张离线票待补传」并确认网络畅通;未确认的事件随后会重投,无需另行处理。

RUNTIME_FALHOU

SDK 本地事件:运行时进程意外退出。Seq 为 0。进行中的调用以 10029832 失败。

dados 字段类型说明
codigoSaida整数进程退出码
tentativa整数重启尝试次数
proximaTentativaMs整数下次重启前的等待毫秒数

处理:开启自动重启时无需操作;记入日志,频繁出现时导出日志联系平台。失败的开票用同一 id 重发即可,内核按 id 幂等。

RUNTIME_REINICIADO

SDK 本地事件:运行时已自动重启并重新初始化。Seq 为 0。

dados 字段类型说明
tentativa整数第几次重启

处理:无需操作;重启前未确认的事件会重投。

开票请求

Emitir、Previsualizar、Substituir 接收的开票请求,就是开具 NFC-e 接口的请求体:字段名、取值、校验规则相同,内核与平台使用同一份规范化与校验规则;引用税种须联网,见下表。字段逐项说明、枚举与各场景示例请直接看开具 NFC-e。

区别有三点:

字段SDK 中
modoResposta不需要传。SDK 总是等待结果;传了也会被忽略
ambienteEmissao与设备环境保持一致。设备环境由配对码决定,见生成设备配对码
itens[].classeImposto可用,须联网。开票前由平台展开,与云端开票结果相同;断网或连不上平台返回 10029780,改传 impostos。见税种与联网

id 是幂等键:同一 id 重复调用 Emitir 返回原票;断网重启、超时后请用同一 id 重发,不要换新 id。

请求的传法

开票请求以 JSON 文本传入。宿主 Java 21 及以上另有类型化入口 TfFiscalNfceTipado,请求类型与平台使用同一份;classeImposto 规则相同。

请求示例

现场销售、消费者不识别、现金付款:

json
{
"id": "PDV01-000131",
"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" }
}
}
]
}

错误码

发票助手与内置 SDK 共用离线开票内核。内核错误在 SDK 中以异常抛出(Codigo 为错误码、Tipo 为常量),在发票助手本机接口中以 codigo 返回。10029800 到 10029846 来自内核,10029870 到 10029888 来自 SDK 封装、运行时通信与主从模式;其余号段未分配。平台返回的错误码原样透传。

通用错误:任何方法都可能返回 10029832(运行时意外退出)、10029833(等待超时)、10029834(已关闭)、10029836(内核内部错误);联网操作中平台返回的业务错误原样透传。各方法「可能的错误」只列该方法特有的码。全站错误码与处理建议见错误码。

错误码常量场景处理
10029800ENGINE_NOT_STARTED未初始化正常使用不会出现;出现说明 SDK 封装有缺陷,重新初始化
10029801ENGINE_NOT_ACTIVATED该主体未在本机配对,或本机尚未配对任何主体引导配对;多主体时检查 empresaId
10029802ENGINE_EMPRESA_REQUIRED配对了多个主体但未指定 empresaId传 empresaId
10029803ENGINE_LICENSE_MISSING没有可用于离线开票的许可证联网同步一次(SincronizarAgora)
10029804ENGINE_LICENSE_EXPIRED许可证已过期;离线开票被拒,在线开票照常恢复网络,自动续签
10029805ENGINE_LICENSE_SIGNATURE_INVALID许可证签名无效人工处理:联系平台,本地库可能被篡改
10029806ENGINE_LICENSE_NOT_FOR_DEVICE许可证不属于本设备人工处理:重新配对
10029807ENGINE_OFFLINE_WINDOW_CLOSED已过离线开票截止时间恢复网络后在线开票
10029808ENGINE_LICENSE_QUOTA_EXHAUSTED本设备系列号码已用到 999999999停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列
10029809ENGINE_CLOCK_ROLLBACK系统时钟被往回调人工处理:校正系统时间
10029810ENGINE_TRANSMISSION_DEADLINE_REACHED最早待补传票已超补传时限人工处理:尽快恢复网络补传
10029811ENGINE_OFFLINE_NOT_ALLOWED主体或州不允许离线开票;或刚从备份恢复、尚未拿到新许可证只能在线开票;刚恢复的联网同步一轮后自动恢复离线开票
10029812ENGINE_OFFLINE_FUEL_NOT_SUPPORTED含燃料的票不能离线开网络恢复后开票
10029813ENGINE_CERTIFICATE_UNAVAILABLE证书找不到、无私钥或 CNPJ 不符人工处理:检查证书存储,必要时 TrocarCertificado
10029814ENGINE_CERTIFICATE_EXPIRED证书已过期人工处理:续期后 TrocarCertificado
10029815ENGINE_SNAPSHOT_MISSING本机配置或计税数据缺失或校验失败联网同步;持续出现联系平台
10029816ENGINE_DEVICE_DEACTIVATED设备已被停用人工处理:联系集成商;已开离线票照常补传
10029817ENGINE_REQUEST_INVALID请求校验失败,Detalhes 逐字段列出原因修正请求;可先用 Previsualizar 预校验
10029780ENGINE_TAX_CLASS_REQUIRES_ONLINE商品行引用了税种,但连不上平台展开;未占用票号恢复网络后用同一 id 重发;断网时商品行改传 impostos
10029818ENGINE_DUPLICATE_ID_DIFFERENT_CONTENT同一 id 已用于内容不同的票新单用新 id;重试用原请求取回原票
10029819ENGINE_NOTE_NOT_FOUND本机没有这张票核对 id 与 empresaId
10029820ENGINE_NOTE_NOT_CORRECTABLE当前状态不可修正只有 Rejeitada 可以 Substituir
10029821ENGINE_CORRECTION_CHANGES_TOTALS修正改变了金额或税额只改非金额内容
10029822ENGINE_CANCEL_NOT_ALLOWED当前状态不可取消不要重试
10029823ENGINE_SERIE_EXHAUSTED设备系列号码已用尽停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列
10029824ENGINE_PLATFORM_UNREACHABLE需要联网的操作(配对)连不上平台检查网络后重试
10029825ENGINE_ACTIVATION_CODE_INVALID配对码格式、签名或有效期不对人工处理:重新生成配对码
10029826ENGINE_ACTIVATION_HOST_UNTRUSTED配对码指向的平台地址不受信人工处理:确认配对码来源与安装包环境(测试 / 生产)
10029827ENGINE_KEY_PROTECTION_FAILED数据目录来自别的电脑或别的 Windows 用户人工处理:用原电脑、原用户运行,或重新配对
10029828ENGINE_DATA_DIR_LOCKED数据目录被其他进程占用,包括恢复备份时本程序还没 Encerrar 的实例关闭另一个实例;恢复备份前先 Encerrar
10029829ENGINE_LOCAL_STORE_CORRUPTED本地库不一致人工处理:不要删除数据目录,联系平台
10029830ENGINE_PROTOCOL_VERSION_UNSUPPORTEDSDK 与运行时版本不兼容SDK 与运行时配套升级
10029831ENGINE_RUNTIME_START_FAILED运行时启动失败检查运行时目录是否完整、是否被杀毒软件拦截
10029832ENGINE_RUNTIME_CRASHED运行时意外退出可重试;开启自动重启时 SDK 自行恢复,开票用同一 id 重发
10029833ENGINE_TIMEOUT等待超时开票用同一 id 重发,或先 Consultar
10029834ENGINE_SHUTTING_DOWN正在关闭或已关闭重新 Iniciar
10029835ENGINE_IN_PROCESS_UNSUPPORTEDJava 进程内模式需要 Java 21 及以上改用子进程模式
10029836ENGINE_INTERNAL_ERROR内核内部错误,说明里带定位号联系平台并提供定位号与日志
10029837ENGINE_ALREADY_ACTIVATED该主体已在本数据目录配对无需再配对;换设备须先停用旧设备
10029838ENGINE_PLATFORM_RESPONSE_UNTRUSTED平台响应校验失败,已保留原数据稍后自动重试;持续出现检查网络代理是否改写了响应
10029839ENGINE_ACTIVATION_PERSIST_FAILED平台已配对但本机保存失败用同一配对码再次配对
10029840ENGINE_CONFIG_INVALID初始化配置非法修正配置
10029841ENGINE_AUTHORIZED_XML_UNAVAILABLE授权 XML 不可用:还没授权,或本机没有且从平台取不回未授权的等授权事件后再取;已授权的说明平台尚未归档或当前连不上平台,稍后重试
10029842ENGINE_LOCAL_STORE_NEWER_VERSION本地库版本高于当前内核:数据目录曾被更新版本的 SDK 使用过,拒绝启动把 SDK 与运行时升级到不低于上次使用的版本;绝不要删除数据目录
10029843ENGINE_CANCEL_XML_UNAVAILABLE取消 XML 不可用:票没有取消,或本机没有且从平台取不回未取消的等 CANCELAMENTO_CONCLUIDO 后再取;已取消的稍后重试
10029844ENGINE_EXPORT_FAILED写文件失败:导出或备份的目标不可写,或备份文件已存在换目录或文件名;检查磁盘空间与权限
10029845ENGINE_SUBSTITUTE_KEY_INVALID替代取消的替代票密钥不合法,或不是本机、本主体未被拒收的离线票传本机为同一笔销售开出的离线票的 44 位访问密钥
10029846ENGINE_BACKUP_INVALID备份无法恢复:口令错误,或备份文件被改动、损坏、不是本 SDK 的备份核对口令;换一份完好的备份。原库没有被改动
10029870ENGINE_PROTOCOL_INVALID_JSON运行时收到的消息不是合法 JSONSDK 封装缺陷,升级 SDK
10029871ENGINE_PROTOCOL_LINE_TOO_LONG单条消息超过 8 MB请求过大,拆分商品明细
10029872ENGINE_PROTOCOL_MESSAGE_INVALID消息结构不合法SDK 封装缺陷,升级 SDK
10029873ENGINE_METHOD_UNKNOWN运行时不认识该方法SDK 比运行时新,升级运行时
10029874ENGINE_PARAMS_INVALID参数缺失或类型错误,Detalhes.campo 点名参数修正参数,例如请求不是 JSON 对象、证书指纹格式、日期格式
10029875ENGINE_ALREADY_STARTED重复初始化;或同一运行时连接已 Iniciar 后又调用恢复备份的协议方法封装的正常调用不会出现,出现说明 SDK 封装有缺陷,升级 SDK;自行对接运行时协议时先 Encerrar,再另开连接恢复
10029876ENGINE_REQUEST_ID_DUPLICATED同一调用仍在处理中SDK 封装缺陷,升级 SDK
10029877ENGINE_RUNTIME_NOT_FOUND找不到运行时检查安装包与运行时目录
10029878ENGINE_TOO_MANY_PENDING同时等待中的调用超过 64 个降低并发
10029879ENGINE_RESPONSE_TOO_LARGE单次响应超过上限联系平台
10029880ENGINE_PRINCIPAL_UNREACHABLE从机连不上主机,请求没有送到稍后重试,或把收银切到备用机
10029881ENGINE_PRINCIPAL_RESULT_UNKNOWN请求已发到主机但没收到响应,结果未知主机恢复后用同一个 id 调 Consultar;同一 id 同样内容重发 Emitir 不会重复开票
10029882ENGINE_TERMINAL_TOKEN_INVALID从机的终端令牌无效或已吊销在主机重新 CriarTerminal,更新从机的 TokenTerminal
10029883ENGINE_PRINCIPAL_ADDRESS_INVALID主机地址格式不对,或不是局域网私有地址修正 EnderecoPrincipal
10029884ENGINE_MODE_METHOD_UNAVAILABLE当前模式不提供该方法配对、换证书、备份与导出在主机做;终端管理只在主机调用
10029885ENGINE_PRINCIPAL_REJECTED主机拒绝了请求来源,例如从机不在允许网段内检查主机的 RedesPermitidas 与网络
10029886ENGINE_PRINCIPAL_RATE_LIMITED鉴权失败过多,被主机限频核对令牌,1 分钟后再试
10029887ENGINE_PRINCIPAL_LISTEN_FAILED主机的局域网端口无法监听换 PortaPrincipal,或释放被占用的端口
10029888ENGINE_TERMINAL_NOT_FOUND要吊销的终端不存在用 ListarTerminais 核对终端 id

全部错误码与发票助手错误码见错误码。