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 一致:用替代票的开票结果取出密钥,对原票发起替代取消。
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 放到后台线程。
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 切回界面线程再更新。
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 的票据:
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(目录) 导出全部已签名、未补传的离线票,交给平台代为补传:
-
照常
Iniciar后调用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,方便人工查看。结果里的Manifestos列出全部清单;没有待补传票时Quantidade为 0、Manifestos为空,不必再交平台。 -
把这次导出的整个
pendentes-…子目录压成一个 zip,交给平台运营在「导入待补传包」直接上传,不用解压,也不用按包或按设备拆开。本机配对了多个主体时 zip 里有多个设备目录,运营按设备筛选后分批提交。 -
在平台停用这台旧设备,为新电脑生成新配对码配对。不要把数据目录拷到新电脑(
10029827)。
目录不可写返回 10029844。电脑已无法开机时,联系平台处理。
路径二:有加密备份。同一台电脑换了硬盘、本地库损坏或被误删,用 RestaurarBackup(配置, 备份文件, 口令) 换回备份里的库:
- 先保住备份之后开出的离线票,备份里没有它们:旧库还能启动时,先照常
Iniciar,按路径一导出待补传包交平台,再Encerrar。 RestaurarBackup是静态方法,在Iniciar之前调用:它不启动引擎、不联网,用的是与Iniciar同一份配置。数据目录还有引擎在运行(包括本程序尚未Encerrar的实例)时返回10029828,先Encerrar再恢复。- 口令错误或备份文件被改动、损坏时返回
10029846,两种情况不区分;备份来自更新版本的 SDK 时返回10029842。失败时原库保持不动。 - 成功后原库另存在数据目录里,文件名以
nfce.db.antes-restauracao-开头,结果的CopiaAnterior给出路径(原来没有库时为空);VersaoBanco是恢复进来的本地库结构版本,低于当前 SDK 时下次启动自动升级。 - 然后照常
Iniciar。备份里的号码与许可证都停在备份时刻,所以各主体先进入恢复对齐:离线开票暂停(返回10029811),联网开票在取号前先与平台同步一轮。拿到新的许可证后,设备系列号码向后跳过 50 个号,在线票与离线票共用这一次跳号,跳过的号自动向平台申报作废(结果经 NUMERO_INUTILIZADO 事件到达),之后在线与离线开票都照常。这样即使备份之后开出的票已经交给消费者,也不会出现重号。对齐完成前连不上平台就开不了票;恢复后尽快联网,调SincronizarAgora立即开始同步。
在后台线程调用
Backup、RestaurarBackup 与 ExportarPendentes 都要大量读写文件,SDK 最多等 30 分钟,界面程序放到后台线程调用,写法同第 3 节。等待超时(10029833)时运行时可能仍在写文件,不要马上对同一文件或目录重试,稍等片刻后换新文件名或新目录。
下面的代码依次演示定期备份、路径一导出待补传包、路径二从备份恢复后启动并立即同步:
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),升级回不低于上次使用的版本即可,不要删除数据目录。
