TF Fiscal
开发文档

NFC-e 离线开票

运维与进阶

内置 SDK 运维与进阶:取消、替代取消、查询与补打小票、取回 XML、按月导出 XML 给会计、备份与坏机恢复、关闭与重启,附 Java 示例。

这页讲收银软件上线后日常要用的 SDK 操作:取消、替代取消、查询与补打小票、取回与按月导出 XML、备份与坏机恢复、关闭与重启。读完你能处理取消与对账,并在电脑出问题时保住离线票。前置:已按内置 SDK 教程完成配对并能开票;用主从模式时,备份、导出等方法只在主机可用,见从机能做什么。

1 取消

Cancelar(id, 原因) 取消一张票,原因 15 到 255 个字符。返回值说明取消请求走到了哪一步:

返回含义
Solicitado已提交平台
Agendado离线票已补传、尚未授权,授权那一刻自动发起
EnfileiradoLocal本机排队:断网,或离线票 / 替代票尚未补传;补传后同一轮立即提交
  • 最终结果:经 CANCELAMENTO_CONCLUIDO / CANCELAMENTO_REJEITADO 事件到达,被拒时票仍有效,见接收结果。
  • 时限:取消时限与云端相同,见取消 NFC-e。离线票授权前的取消怎样挂起,见离线票与补传。
  • 不能取消:已取消或已有取消在处理时返回 10029822,不要再重试。
  • 被离线票取代:在线开出的票要由本机随后开出的离线票取代时,改用替代取消。

取消的示例代码与查询、补打放在一起,见第 3 节的 Executar。

2 替代取消

什么时候用:一笔销售已经在线开出了票(原票),之后在本机断网时又为同一笔销售开出了离线应急票(替代票),例如消费者要求补上 CPF 重开、而此时恰好断网。原票要用替代取消作废,并指明取代它的离线票。普通取消见第 1 节。

调用 CancelarPorSubstituicao(原票 id, 替代票密钥, 原因),原因 15 到 255 个字符。前提:

  • 原票:本机在线开出、经平台转发的正常票。原票是离线票、已取消或已有取消在处理时返回 10029822。
  • 替代票:本机、同一主体随后开出的离线应急票,传它的 44 位访问密钥(开票结果里的 Chave)。密钥格式不对、不是 NFC-e、CNPJ 与原票不同、与原票密钥相同,或不是本机未被平台拒收的离线票时返回 10029845。

结果怎么看:替代票还没补传(或断网)时返回 EnfileiradoLocal,在本机排队,替代票补传成功后才自动提交;替代票已补传且联网时直接提交平台。最终结果都经事件到达:CANCELAMENTO_CONCLUIDO 表示原票已取消,CANCELAMENTO_REJEITADO 表示被拒、原票仍有效,按事件里的 motivo 处理。取消成功后可取取消 XML,写法见第 3 节。

下面的代码与示例工程场景 05 一致:用替代票的开票结果取出密钥,对原票发起替代取消。

java
import com.tffiscal.nfce.sdk.ResultadoEmissao;
import com.tffiscal.nfce.sdk.Resultados;
import com.tffiscal.nfce.sdk.TfFiscalException;
import com.tffiscal.nfce.sdk.TfFiscalNfce;
public final class NfceSubstituicao {
private NfceSubstituicao() {}
/** 用本机随后开出的离线替代票取代在线开出的原票;最终结果经 CANCELAMENTO_* 事件到达。 */
public static Resultados.Cancelamento cancelarOriginal(TfFiscalNfce nfce, String idOriginal, ResultadoEmissao substituta) {
try {
Resultados.Cancelamento c = nfce.cancelarPorSubstituicao(idOriginal, substituta.getChave(),
"Cliente pediu nova nota com CPF", null);
// EnfileiradoLocal:替代票还没补传,补传成功后自动提交
System.out.println("Cancelamento por substituicao: " + c.getSituacao());
return c;
} catch (TfFiscalException e) {
// 10029822:原票不是在线开出的正常票;10029845:替代票密钥不合法或不是本机的离线票
System.out.println("Erro " + e.getCodigo() + " " + e.getTipo() + ": " + e.getMessage());
return null;
}
}
}

3 查询、补打小票与取回 XML

  • 查询:Consultar(id) 返回本机记录,离线票补传前也能查;含原始请求 Pedido、Transmitida、XmlAutorizadoDisponivel 等。
  • 补打小票:对同一个 id 再调 Cupom 即可。
  • 授权 XML 与取消 XML:XmlAutorizado(id) 取授权 XML,XmlCancelamento(id) 取取消成功后的取消 XML。授权或取消后 SDK 自动下载到本机,保留 RetencaoXmlDias 天(缺省 90 天,见代理与 XML 保留天数)。本机没有时(尚未下载完,或已过保留期被清理)会同步联网回取:内核单次回取最长 30 秒,SDK 一次调用最多等约 120 秒。

不要在界面线程调用 XmlAutorizado / XmlCancelamento,否则联网回取期间收银界面会卡住。取不到时抛 10029841(授权 XML)或 10029843(取消 XML):票还没授权或还没取消成功时,等 NOTA_AUTORIZADA 或 CANCELAMENTO_CONCLUIDO 事件后再取;已授权仍取不到,说明平台尚未归档或暂时连不上,稍后重试。

下面的代码与示例工程场景 04 一致:查询、补打、取消、列当天票据都在本机完成,直接调用;取 XML 放到后台线程。

java
import com.tffiscal.nfce.sdk.FormatoCupom;
import com.tffiscal.nfce.sdk.Resultados;
import com.tffiscal.nfce.sdk.SituacaoNota;
import com.tffiscal.nfce.sdk.TfFiscalNfce;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.LocalDate;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
public final class NfceOperacoes {
/** 取 XML 专用的后台线程:本地没有时联网回取,最长约 120 秒,不能占用界面线程。 */
private static final ExecutorService XML = Executors.newSingleThreadExecutor(r -> {
Thread t = new Thread(r, "nfce-xml");
t.setDaemon(true);
return t;
});
private NfceOperacoes() {}
/** 查询、补打小票、作废,并列出当天票据;都在本机完成,可以在界面线程调用。 */
public static void executar(TfFiscalNfce nfce, String id) {
SituacaoNota situacao = nfce.consultar(id);
System.out.println("Consultar: " + situacao.getStatus() + ", transmitida " + situacao.isTransmitida()
+ ", XML autorizado disponivel " + situacao.isXmlAutorizadoDisponivel());
// 补打小票:对同一个 id 再取一次
byte[] cupom = nfce.cupom(id, FormatoCupom.ESCPOS_80);
System.out.println("Cupom: " + cupom.length + " bytes");
// 作废:最终结果经 CANCELAMENTO_CONCLUIDO / CANCELAMENTO_REJEITADO 事件到达
Resultados.Cancelamento c = nfce.cancelar(id, "Cliente desistiu da compra", null);
System.out.println("Cancelar: " + c.getSituacao() + (c.getMotivo() == null ? "" : " - " + c.getMotivo()));
// 当天的本地票据(第 1 页,每页 50 张)
Resultados.PaginaNotas pagina = nfce.listarNotas(LocalDate.now(), null, 1, null);
System.out.println("Notas de hoje: " + pagina.getItens().size() + (pagina.isTemMais() ? " ou mais" : ""));
}
/** 在后台线程取授权 XML 并另存;授权 XML 是法律原件,收银软件可按需另存一份。 */
public static CompletableFuture<Path> salvarXmlAutorizado(TfFiscalNfce nfce, String id, String chave, Path pasta) {
return CompletableFuture.supplyAsync(
() -> gravar(pasta.resolve("nfe-" + chave + ".xml"), nfce.xmlAutorizado(id, null)), XML);
}
/** 在后台线程取取消 XML 并另存;收到 CANCELAMENTO_CONCLUIDO 后调用。 */
public static CompletableFuture<Path> salvarXmlCancelamento(TfFiscalNfce nfce, String id, String chave, Path pasta) {
return CompletableFuture.supplyAsync(
() -> gravar(pasta.resolve(chave + "-can.xml"), nfce.xmlCancelamento(id, null)), XML);
}
private static Path gravar(Path arquivo, byte[] conteudo) {
try {
Files.write(arquivo, conteudo);
return arquivo;
} catch (IOException e) {
throw new UncheckedIOException(e);
}
}
}

在界面里这样调用取授权 XML,捕获 10029841 后稍后重试。结果回调在后台线程上,Swing 界面用 SwingUtilities.invokeLater 切回界面线程再更新。

java
NfceOperacoes.salvarXmlAutorizado(nfce, id, chave, pastaXml).whenComplete((arquivo, erro) -> {
if (erro == null) {
System.out.println("XML salvo em " + arquivo);
} else if (erro.getCause() instanceof TfFiscalException
&& ((TfFiscalException) erro.getCause()).getCodigo() == 10029841) {
// 还没授权,或本地没有且平台未归档 / 不可达:稍后重试
System.out.println(erro.getCause().getMessage());
}
});

4 按月导出 XML 给会计

什么时候用:每月初把上个月的授权 XML 与取消 XML 交给会计。ExportarXmls(起始日期, 截止日期, 目录) 按开票日期(主体所在州的当地日期)导出区间内本机的票据,起止日期都包含在内。

  • 文件:每张授权票一个 {chave}-nfe.xml,已取消的票另有一个 {chave}-can.xml({chave} 为 44 位访问密钥);目录里已有同名文件时覆盖。
  • 结果:QuantidadeNotas 是至少导出了一个文件的票据张数,QuantidadeArquivos 是写出的文件数(一张已取消的票算两个文件),Arquivos 列出写出的全部文件,Falhas 列出区间内缺 XML 的票据(单据 id、密钥与原因)。单张缺 XML 不中断导出。
  • 保留期:本机没有的 XML 先自动联网回取,仍取不到的列进 Falhas,原因里会写明是否已过本机保留期。导出区间最好落在 RetencaoXmlDias 之内(见代理与 XML 保留天数),否则要逐张回取,耗时更长;更早的票请走云端查询。
  • 断网时:导出开始前刚连不上平台,或导出途中第一次连不上平台,其余缺 XML 的票不再联网、直接列进 Falhas,不会逐张等超时。断网时想先拿到本机已有的文件,打开只导本机选项:只导本机已有的 XML、完全不联网,缺的票同样列进 Falhas。用五个参数的重载 exportarXmls(de, ate, diretorio, true, empresaId)。
  • 耗时:可能要逐张联网回取,SDK 最多等 30 分钟,放在后台线程调用,不要在界面线程里等。等待超时(10029833)时运行时可能仍在写文件,不要马上对同一目录重试,稍等片刻后换一个新目录重新导出。
  • 常见错误:日期缺失或格式不对返回 10029874;目录不可写返回 10029844。

下面的代码在后台线程导出上个月的授权与取消 XML,再列出结果与缺 XML 的票据:

java
import com.tffiscal.nfce.sdk.Resultados;
import com.tffiscal.nfce.sdk.TfFiscalNfce;
import java.nio.file.Path;
import java.time.LocalDate;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executor;
public final class NfceContador {
private NfceContador() {}
/** 在后台线程导出上个月的授权与取消 XML;executor 用收银软件自己的后台线程池。 */
public static CompletableFuture<Resultados.ExportacaoXml> exportarMesAnterior(TfFiscalNfce nfce, Path pasta, Executor executor) {
LocalDate primeiroDoMes = LocalDate.now().withDayOfMonth(1);
LocalDate de = primeiroDoMes.minusMonths(1);
LocalDate ate = primeiroDoMes.minusDays(1);
return CompletableFuture.supplyAsync(() -> nfce.exportarXmls(de, ate, pasta, null), executor);
}
/** 导出完成后列出结果;缺 XML 的票据要另行处理。 */
public static void mostrar(Resultados.ExportacaoXml r) {
System.out.println("XML exportados: " + r.getQuantidadeNotas() + " notas, " + r.getQuantidadeArquivos()
+ " arquivos, falhas " + r.getFalhas().size());
for (Map<String, Object> falha : r.getFalhas()) {
System.out.println(" " + falha.get("id") + " " + falha.get("chave") + ": " + falha.get("motivo"));
}
}
}

5 备份与坏机恢复

本机数据目录在补传前保存着离线票唯一的法律原件。平时要做两件事:定期加密备份,以及让店员知道电脑出问题时走哪条路。

定期备份

Backup(目标文件, 口令) 把整个本地库加密成一个备份文件,开票可以同时进行。

  • 口令:至少 8 位,不足时返回 10029817,为空时返回 10029874。口令经 PBKDF2-SHA256 派生密钥,整份库用 AES-256-GCM 加密;SDK 与平台都不保存口令,口令丢失后备份无法恢复,请与备份文件分开保管。不要把口令写进程序或命令行参数,本节的示例代码与示例工程场景 05 一样,从环境变量 TFFISCAL_BACKUP_SENHA 读取。
  • 文件:目标文件已存在时返回 10029844,所以文件名带上时间;写出途中失败不会留下不完整的文件。
  • 结果:Arquivo(文件路径)、Bytes(大小)、VersaoBanco(本地库结构版本)与 Sha256(文件摘要)。
  • 恢复范围:备份里的设备密钥受 Windows 数据保护,只能在生成备份的同一台电脑、同一个 Windows 用户下恢复;换电脑不能靠备份,必须重新配对。

电脑出问题时选哪条路

情形走哪条路
电脑要撤换或修不好,离线票来不及在本机补传路径一:导出待补传包交平台
同一台电脑上本地库丢失或损坏,手里有这台电脑的加密备份路径二:在这台电脑上从备份恢复

路径一:电脑坏了来不及补传。电脑还能开机、但已经无法联网补传(例如要立刻撤换),用 ExportarPendentes(目录) 导出全部已签名、未补传的离线票,交给平台代为补传:

  1. 照常 Iniciar 后调用 ExportarPendentes。它只导出、不改变本机状态,这些票仍在本机的补传队列里。每次调用都在目标目录下新建一个以导出时刻(UTC)命名的子目录,按设备分目录、每包至多 500 张:

    text
    {diretorio}/pendentes-20261111-150000/{dispositivoId}/pacote-001/manifesto.json
    /pacote-001/{chave}.xml
    /pacote-002/…

    {diretorio} 是传入的目标目录,{dispositivoId} 是设备标识,{chave} 是 44 位访问密钥。

  2. 每份清单 manifesto.json 记录所属设备,每张票连同签名 XML 一起写在清单里,可直接交平台导入;同目录下的 {chave}.xml 是同一份签名 XML,方便人工查看。结果里的 Manifestos 列出全部清单;没有待补传票时 Quantidade 为 0、Manifestos 为空,不必再交平台。

  3. 把这次导出的整个 pendentes-… 子目录压成一个 zip,交给平台运营在「导入待补传包」直接上传,不用解压,也不用按包或按设备拆开。本机配对了多个主体时 zip 里有多个设备目录,运营按设备筛选后分批提交。

  4. 在平台停用这台旧设备,为新电脑生成新配对码配对。不要把数据目录拷到新电脑(10029827)。

目录不可写返回 10029844。电脑已无法开机时,联系平台处理。

路径二:有加密备份。同一台电脑换了硬盘、本地库损坏或被误删,用 RestaurarBackup(配置, 备份文件, 口令) 换回备份里的库:

  1. 先保住备份之后开出的离线票,备份里没有它们:旧库还能启动时,先照常 Iniciar,按路径一导出待补传包交平台,再 Encerrar。
  2. RestaurarBackup 是静态方法,在 Iniciar 之前调用:它不启动引擎、不联网,用的是与 Iniciar 同一份配置。数据目录还有引擎在运行(包括本程序尚未 Encerrar 的实例)时返回 10029828,先 Encerrar 再恢复。
  3. 口令错误或备份文件被改动、损坏时返回 10029846,两种情况不区分;备份来自更新版本的 SDK 时返回 10029842。失败时原库保持不动。
  4. 成功后原库另存在数据目录里,文件名以 nfce.db.antes-restauracao- 开头,结果的 CopiaAnterior 给出路径(原来没有库时为空);VersaoBanco 是恢复进来的本地库结构版本,低于当前 SDK 时下次启动自动升级。
  5. 然后照常 Iniciar。备份里的号码与许可证都停在备份时刻,所以各主体先进入恢复对齐:离线开票暂停(返回 10029811),联网开票在取号前先与平台同步一轮。拿到新的许可证后,设备系列号码向后跳过 50 个号,在线票与离线票共用这一次跳号,跳过的号自动向平台申报作废(结果经 NUMERO_INUTILIZADO 事件到达),之后在线与离线开票都照常。这样即使备份之后开出的票已经交给消费者,也不会出现重号。对齐完成前连不上平台就开不了票;恢复后尽快联网,调 SincronizarAgora 立即开始同步。

在后台线程调用

Backup、RestaurarBackup 与 ExportarPendentes 都要大量读写文件,SDK 最多等 30 分钟,界面程序放到后台线程调用,写法同第 3 节。等待超时(10029833)时运行时可能仍在写文件,不要马上对同一文件或目录重试,稍等片刻后换新文件名或新目录。

下面的代码依次演示定期备份、路径一导出待补传包、路径二从备份恢复后启动并立即同步:

java
import com.tffiscal.nfce.sdk.Configuracao;
import com.tffiscal.nfce.sdk.Resultados;
import com.tffiscal.nfce.sdk.TfFiscalException;
import com.tffiscal.nfce.sdk.TfFiscalNfce;
import java.nio.file.Path;
public final class NfceContingencia {
private NfceContingencia() {}
/** 备份口令从环境变量读取,不写进程序与命令行。 */
public static String senhaBackup() {
String senha = System.getenv("TFFISCAL_BACKUP_SENHA");
if (senha == null || senha.isEmpty()) {
throw new IllegalStateException("Defina TFFISCAL_BACKUP_SENHA (minimo 8 caracteres)");
}
return senha;
}
/** 定期加密备份本地库;目标文件已存在会被拒(10029844),所以文件名带时间。在后台线程调用。 */
public static Resultados.Backup backup(TfFiscalNfce nfce, Path pasta) {
Resultados.Backup bak = nfce.backup(pasta.resolve("caixa-" + System.currentTimeMillis() + ".bak"), senhaBackup());
System.out.println("Backup: " + bak.getArquivo() + " (" + bak.getBytes() + " bytes, sha256 " + bak.getSha256() + ")");
return bak;
}
/** 路径一:导出已签名未补传的离线票,把这次导出的 pendentes-… 目录整个压成 zip 交给平台。在后台线程调用。 */
public static void exportarPendentes(TfFiscalNfce nfce, Path pasta) {
Resultados.ExportacaoPendentes pend = nfce.exportarPendentes(pasta);
System.out.println("Pendentes exportados: " + pend.getQuantidade());
for (String manifesto : pend.getManifestos()) {
System.out.println(" manifesto " + manifesto);
}
}
/** 路径二:在 iniciar 之前从加密备份恢复,再启动并立即同步。在后台线程调用。 */
public static TfFiscalNfce restaurarEIniciar(Configuracao config, Path arquivoBackup) {
try {
Resultados.Restauracao r = TfFiscalNfce.restaurarBackup(config, arquivoBackup, senhaBackup());
System.out.println("Backup restaurado: versao do banco " + r.getVersaoBanco() + ", copia anterior " + r.getCopiaAnterior());
} catch (TfFiscalException e) {
if (e.getCodigo() == 10029846) {
// 口令错误或备份文件损坏,原库没有被改动
System.out.println("Senha incorreta ou backup corrompido");
}
throw e;
}
TfFiscalNfce nfce = TfFiscalNfce.iniciar(config);
// 拿到新许可证前离线开票暂停,立即同步一轮
nfce.sincronizarAgora();
return nfce;
}
}

6 关闭与重启

  • 关闭:退出前调用 Encerrar(close 等价)。它等进行中的开票完成后再关闭,最长约 15 秒;不要强制结束进程。关闭期间不补传。
  • 重启:照常 Iniciar,不需要重新配对。启动后内核立即同步一轮;若仍有待补传的票或未确认的事件,会收到 PENDENCIAS_NA_INICIALIZACAO,未确认的事件随后重投。
  • 崩溃后:已开出的票都在数据目录里。不确定某单是否开成的,用同一个 id 调 Consultar 或重发 Emitir,不会重复开票。
  • 运行时意外退出:SDK 自动重启(RUNTIME_FALHOU、RUNTIME_REINICIADO 事件),进行中的调用以 10029832 失败,用同一个 id 重试即可。
  • 升级与降级:升级收银软件时 SDK 与运行时一起升级,数据目录原样保留。装回旧版本时,本地库比程序新会拒绝启动(10029842),升级回不低于上次使用的版本即可,不要删除数据目录。