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 子进程模式由运行时子进程在启动时设置,宿主不需要处理。
下面示范手工代理加认证。
Configuracao configuracao = Configuracao.builder()// 其余配置同上.proxy("10.0.0.5:3128").proxyAutenticacao("caixa01", senhaProxy).build();
配置示例
一份常用的基础配置,未列出的项取缺省值。
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 成功之后调用;一个数据目录同一时刻只能有一个实例。
联网:不需要。断网时也能启动,启动后有网即开始同步。
签名
public static TfFiscalNfce iniciar(Configuracao config);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 配置 | config | 是 | 初始化配置。字段见配置项 |
返回
已就绪的 SDK 实例 TfFiscalNfce。用完调用 Encerrar,也可以用 try-with-resources 自动关闭。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029877 | 找不到运行时 | 检查运行时目录与 tffiscal-nfce.exe 是否随安装包分发 |
| 10029831 | 运行时启动失败或未在启动超时内就绪 | 查看日志;电脑过慢时可调大启动超时 |
| 10029830 | SDK 与运行时版本不兼容 | 运行时与 SDK 用同一版本分发 |
| 10029835 | Java 进程内模式但宿主低于 Java 21 | 改用子进程模式,或升级 Java |
| 10029828 | 数据目录已被其他进程打开 | 同一目录只开一个实例;检查是否有残留进程 |
| 10029827 | 本机密钥无法解开:数据目录来自别的电脑或别的 Windows 用户 | 用原 Windows 用户运行;换电脑须停用旧设备、重新配对 |
| 10029829 | 本地库不一致 | 不要删除数据目录,联系平台 |
| 10029842 | 本地库版本高于当前内核:数据目录曾被更新版本的 SDK 使用过,拒绝启动 | 把 SDK 与运行时升级到不低于上次使用的版本;绝不要删除数据目录,未补传的离线票原件在里面 |
| 10029840 | 配置非法 | 按 Message 修正配置项 |
| 10029874 | 配置项取值不对:缺少收银软件名称或版本、代理地址格式不对、只给代理认证、XML 保留天数越界 | 按 Detalhes.campo 修正配置项 |
| 10029882 | 从机的终端令牌无效或已吊销 | 在主机重新签发终端令牌,更新 TokenTerminal |
| 10029883 | 从机的主机地址格式不对,或不是局域网私有地址 | 修正 EnderecoPrincipal |
| 10029887 | 主机的局域网端口无法监听 | 换 PortaPrincipal,或释放被占用的端口 |
另可能返回通用错误。
示例
try (TfFiscalNfce nfce = TfFiscalNfce.iniciar(configuracao)) {System.out.println("ativado=" + nfce.isAtivado());}
Ativado / Empresas
Ativado:本数据目录是否至少配对了一个主体。收银程序启动时据此决定是否进入配对流程。Empresas:已配对的主体清单。一个数据目录配对多个主体(多个 CNPJ)时,用它找到每个主体的empresaId。
两者每次都向内核查询、不缓存:设备被平台停用后,状态会如实反映在 Situacao 字段里。
联网:不需要。
签名
public boolean isAtivado();public List<Resultados.EmpresaAtivada> getEmpresas();
参数
无。
返回
Ativado 返回布尔值。Empresas 返回已配对主体清单,元素字段见数据类型:已配对主体。
可能的错误
只有通用错误。
示例
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 时才能判断。
签名
public Resultados.CodigoAtivacao inspecionarCodigoAtivacao(String codigo);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 配对码 | codigo | 是 | 配对码全文。TFA1. 开头;.tfa 文件的内容即配对码全文,首尾空白会被去掉 |
返回
配对码信息,字段见数据类型:配对码信息。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029825 | 配对码格式、签名或有效期不对 | 确认复制完整;已过期请集成商重新生成 |
| 10029826 | 配对码指向的平台地址不受信 | 配对码不是本平台签发,或运行时版本与环境不匹配;联系集成商 |
另可能返回通用错误。
示例
Resultados.CodigoAtivacao info = nfce.inspecionarCodigoAtivacao(codigoAtivacao);System.out.println("ambiente " + info.getAmbiente() + " expira " + info.getExpiraEm());
Ativar
用集成商生成的设备配对码与主体的 A1 证书,把本机配对为该主体的一台设备。配对时内核生成设备密钥、绑定证书并向平台登记,成功后得到设备系列与首张许可证,平台推送 nfce.device.activated(见结果怎么收到)。每个主体在一个数据目录里只配对一次;同一数据目录可以再配对其他主体。
联网:需要。连不上平台返回 10029824,配对码不会被消耗。
签名
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 | 平台返回:配对码指定的设备系列已不可用 | 集成商换一个系列或起始号码重新生成配对码 |
另可能返回通用错误。
示例
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。内核在本设备系列上取号、签名,先把签好的票交平台在线授权;连不上平台、平台超时或结果不明时,改为本机离线签发,当场返回可打印的离线票。请求体与云端开票接口完全相同,见开票请求。
处理顺序:
- 按
id查本地:已开过同一id直接返回原票,不重复取号;内容不同返回10029818。 - 商品行引用了税种(
classeImposto)时,先交平台展开为完整的impostos:须联网,连不上平台返回10029780,不占用票号;税种被拒(不存在、与税制不符等)原样返回平台的错误码与说明。 - 规范化与校验,规则与云端相同;不通过返回
10029817,Detalhes逐字段列出原因。 - 在本设备系列上取号、签名后在线提交,结果与云端同步开票相同;平台返回业务错误时原样返回,不转离线,号码留给下一张票。唯一例外是平台回号码已被占用(
10029424):内核弃掉这个号,与平台同步一轮刷新已确认号后只重试一次,再冲突就原样返回,不会逐号撞下去卡住收银。 - 在线失败或超时,核对许可证、补传时限、离线开关等条件后离线签发,返回
ContingenciaPendente。结果不明时原号码不再使用,离线票用下一个号码,原号码由平台核对后收口:已授权的由平台替代取消,未授权的申报作废(见平台自动处理的号码情形);当时不能离线签发则返回AguardandoAutorizacao,稍后用原号码原样重提。最近一次联网刚失败过时跳过第 4 步,直接离线签发。
同一主体的开票在内核内部按顺序执行,保证设备系列号码连续,在线票与离线票共用;不同主体可以并行。
联网:可选。联网时在线开票,断网时离线签发。
签名
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的错误说明处理 |
另可能返回通用错误。
示例
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。
联网:不需要。
签名
public Resultados.PreVisualizacao previsualizar(String pedidoJson, String empresaId);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 开票请求 | pedidoJson | 是 | 待校验的开票请求。结构同 Emitir;id 可以先不填 |
| 主体标识 | empresaId | 多主体时必填 | 开票主体。Java 只配对一个主体时传 null |
返回
预览结果,字段见数据类型:预览结果。Erros 已按配置的错误文案语言翻译,可直接展示给收银员。
可能的错误
校验不通过不抛错。除通用错误外只有主体相关的错误:10029801(主体未配对)、10029802(多主体未传 empresaId)、10029815(本机计税数据缺失,联网同步一次)。
另可能返回通用错误。
示例
Resultados.PreVisualizacao p = nfce.previsualizar(pedidoJson, null);if (!p.isValido()) {p.getErros().forEach(System.out::println);}
建议在输入停顿约 300 毫秒后再调用,不要每个按键都调。
Consultar
按开票时的 id 查询本机票据的当前状态:是否已授权、是否已补传、是否有待执行的取消、修正过几次、授权 XML 是否已下载,以及原始开票请求。在线票与离线票都存在本机,离线票补传前也能查。收银程序崩溃重启后,用它取回崩溃前开出的票。
联网:不需要。返回的是本机记录,补传与授权结果随后台同步更新;需要尽快拿到最新结果时先调 SincronizarAgora。
签名
public SituacaoNota consultar(String id);public SituacaoNota consultar(String id, String empresaId);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 单据标识 | id | 是 | 开票请求里的 id |
| 主体标识 | empresaId | 多主体时必填 | 开票主体。只配对一个主体时可省略 |
返回
查询状态,字段见数据类型:查询状态。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029819 | 本机没有这张票 | 核对 id 与 empresaId;票不是在本机开出的,请用云端查询 |
| 10029801 / 10029802 | 主体未配对 / 多主体未传 empresaId | 先配对;传 empresaId |
另可能返回通用错误。
示例
SituacaoNota s = nfce.consultar("PDV01-000131");System.out.println(s.getStatus() + " transmitida=" + s.isTransmitida() + " protocolo=" + s.getProtocolo());
ListarNotas
分页列出本机票据(在线票与离线票都在内),按开票时间倒序,每页 50 张。适合做「当日票据」界面、交班核对待补传张数。为了不做全表计数,结果不给总数,只给是否还有下一页。
联网:不需要。
签名
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 |
另可能返回通用错误。
示例
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。收银流程里的用法见运维与进阶:取消。
联网:可选。断网时本机排队。
签名
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处理 |
另可能返回通用错误。
示例
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。完整的重开与替代取消流程见运维与进阶:替代取消。
联网:可选。断网或替代票尚未补传时本机排队,满足条件后自动提交。
签名
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处理 |
另可能返回通用错误。
示例
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、消费者证件;票面合计与任一行税额变化都会被拒绝。
联网:不需要。修正在本机完成,补传在后台进行。
签名
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 | 本机配置或计税数据缺失 | 联网同步一次 |
另可能返回通用错误。
示例
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 打印驱动打印。断网时也能出小票。
需要调整每行列数、代码页、二维码打法、切纸或联数时,用带打印参数的重载,参数见下文「打印参数」。
联网:不需要。
签名
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_80 | 80mm 热敏打印机的 ESC/POS 字节 |
ESCPOS_58 | 58mm 热敏打印机的 ESC/POS 字节 |
TEXTO | UTF-8 纯文本 |
HTML | UTF-8 HTML,用于屏幕预览或浏览器打印 |
PDF_80 | 80mm 宽的 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 | 格式取值不对,或打印参数越界 | 用上表的取值 |
另可能返回通用错误。
示例
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 相同。断网时也能生成。
联网:不需要。
签名
public byte[] qrCodePng(String id, int tamanhoPx, String empresaId);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 单据标识 | id | 是 | 开票请求里的 id |
| 图像边长 | tamanhoPx | 否 | 图像边长像素。64 到 2048,须显式传 |
| 主体标识 | empresaId | 多主体时必填 | 开票主体。只配对一个主体时可省略,Java 传 null |
返回
PNG 图像字节。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029819 | 本机没有这张票 | 核对 id |
| 10029817 | 图像边长不在 64 到 2048 之间 | 修正边长 |
另可能返回通用错误。
示例
Files.write(Paths.get("PDV01-000131-qrcode.png"), nfce.qrCodePng("PDV01-000131", 240, null));
XmlAutorizado
读取一张票的授权 XML 原文(含授权协议)。在线票授权后、离线票补传授权后,内核自动把授权 XML 下载到本机,保留天数由配置项 RetencaoXmlDias 决定(缺省 90 天)。本机没有时(尚未下载,或已按保留期清理),内核当场联网从平台取回;平台的归档是正本。
Consultar 的 XmlAutorizadoDisponivel 为 true 时直接读本机,不联网。
不要在界面线程调用:本机没有时要等平台返回,最长约 120 秒(调用超时配置得更长时以调用超时为准),请放到后台线程。
联网:可能。本机没有时同步从平台取回,最长约 120 秒;不要在界面线程调用。
签名
public byte[] xmlAutorizado(String id, String empresaId);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 单据标识 | id | 是 | 开票请求里的 id |
| 主体标识 | empresaId | 多主体时必填 | 开票主体。只配对一个主体时可省略,Java 传 null |
返回
授权 XML 的 UTF-8 字节。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029841 | 授权 XML 不可用:还没授权,或本机没有且从平台取不回 | 未授权的等 NOTA_AUTORIZADA 事件后再取;已授权的说明平台尚未归档或当前连不上平台,稍后重试 |
| 10029819 | 本机没有这张票 | 核对 id |
另可能返回通用错误。
示例
// 可能联网回取,放到后台线程CompletableFuture.supplyAsync(() -> nfce.xmlAutorizado("PDV01-000131", null)).thenAccept(xml -> gravar("PDV01-000131-nfce.xml", xml));
XmlCancelamento
读取一张已取消票据的取消 XML 原文(取消事件及其回执)。本机保留天数与授权 XML 相同,由配置项 RetencaoXmlDias 决定(缺省 90 天);本机没有时,内核当场联网从平台取回。
不要在界面线程调用:本机没有时要等平台返回,最长约 120 秒(调用超时配置得更长时以调用超时为准)。
联网:可能。本机没有时同步从平台取回,最长约 120 秒;不要在界面线程调用。
签名
public byte[] xmlCancelamento(String id, String empresaId);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 单据标识 | id | 是 | 开票请求里的 id |
| 主体标识 | empresaId | 多主体时必填 | 开票主体。只配对一个主体时可省略,Java 传 null |
返回
取消 XML 的 UTF-8 字节。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029843 | 取消 XML 不可用:票没有取消,或本机没有且从平台取不回 | 未取消的等 CANCELAMENTO_CONCLUIDO 事件后再取;已取消的说明平台尚未归档或当前连不上平台,稍后重试 |
| 10029819 | 本机没有这张票 | 核对 id |
另可能返回通用错误。
示例
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)时运行时可能仍在写文件,不要马上对同一目录重试,稍等片刻后换一个新目录重新导出。
签名
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。
另可能返回通用错误。
示例
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 天各一次),可据此提醒管理员。
联网:不需要。
签名
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 |
另可能返回通用错误。
示例
nfce.trocarCertificado(Certificado.deArquivoPfx(Files.readAllBytes(Paths.get("C:/deploy/novo.pfx")), senha), null);
Situacao
读取内核整体状态:内核版本、引擎级告警,以及每个已配对主体的连接情况、许可证剩余、待补传张数、补传截止、证书到期与最近一次错误。适合在收银界面显示「离线中」「待补传 N 张」「证书 7 天后到期」等提示;可定时调用(例如每 10 秒一次),开销很小。
联网:不需要。
签名
public Resultados.Nucleo situacao();
参数
无。
返回
内核状态,字段见数据类型:内核状态;每主体状态是 getEmpresas() 返回的键值对列表。
建议的界面提示:
| 条件 | 提示 |
|---|---|
Conectado 为 false | 离线中,票据将在联网后补传 |
PendentesTransmissao 大于 0 | 待补传张数;结合 PrazoTransmissaoAte 显示补传截止 |
OfflineAte 临近 | 离线时长即将用完,请尽快联网 |
CertificadoValidoAte 临近 | 证书即将到期,续期后调用 TrocarCertificado |
Situacao 不是 Ativo | 设备已不能开新票,联系集成商 |
UltimoErro 有值 | 最近一次同步失败的原因,排障时提供给技术支持 |
Avisos 不为空 | 运行环境需要调整,例如 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 查看。调用只触发后台下一轮同步并立即返回,不等同步结果,可以在界面线程直接调用;某个主体的一轮同步正在进行时不会并发再跑,这一轮结束后接着同步。断网时调用不报错。
联网:触发联网,不等待同步结果,调用立即返回。
签名
public void sincronizarAgora();
参数
无。
返回
无。
可能的错误
只有通用错误。
示例
// 只触发后台下一轮同步并立即返回,可以在界面线程直接调用nfce.sincronizarAgora();
Backup
把本地库加密备份成一个文件,用于定期留存或换硬盘前的保护。备份取的是某一时刻的完整快照,期间可以照常开票。备份策略与坏机恢复的整体流程见运维与进阶:备份与坏机恢复。
- 加密:口令经 PBKDF2-SHA256 派生密钥,整份库用 AES-256-GCM 加密。SDK 与平台都不保存口令,口令丢失后备份无法恢复,请与备份文件分开保管。
- 只能在同一台电脑、同一 Windows 用户下恢复:本地库里的设备密钥受 Windows 用户级保护,换电脑或换 Windows 用户后备份无法使用,须停用旧设备、重新配对。
- 恢复:用 RestaurarBackup。恢复时使用的 SDK 与运行时版本不能低于备份时的版本,结果的
VersaoBanco记录了本地库结构版本。 - 写入:先写临时文件再改名,失败时不会留下不完整的备份文件。
联网:不需要。等待上限至少 30 分钟,调用超时配置得更长时以调用超时为准;本地库较大时要几分钟,不要在界面线程调用。等待超时(10029833)时运行时可能仍在写文件,不要马上用同一文件名重试,稍等片刻后换一个新文件名。
签名
public Resultados.Backup backup(Path destino, String senha);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 备份文件 | destino | 是 | 备份文件路径。文件不能已存在;相对路径按收银程序当前目录转为绝对路径 |
| 口令 | senha | 是 | 备份口令。至少 8 位;恢复时须提供同一口令,不进日志 |
返回
备份结果,字段见数据类型:备份结果。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029874 | 口令为空,Detalhes.campo 为 senha | 传入口令 |
| 10029817 | 口令不足 8 位 | 换更长的口令 |
| 10029844 | 目标文件已存在,或目录不可写 | 换文件名或目录;检查磁盘空间与权限 |
另可能返回通用错误。
示例
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 分钟,调用超时配置得更长时以调用超时为准;不要在界面线程调用。
签名
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 | 读写文件失败 | 检查备份文件路径、数据目录的磁盘空间与权限 |
另可能返回通用错误。
示例
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 张:
{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)时运行时可能仍在写文件,不要马上对同一目录重试,稍等片刻后换一个新目录重新导出。
签名
public Resultados.ExportacaoPendentes exportarPendentes(Path diretorio);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 目标目录 | diretorio | 是 | 导出目录。相对路径按收银程序当前目录转为绝对路径 |
导出本数据目录内全部已配对主体的待补传票,每个主体的设备各一个目录、各自的清单,清单里逐张记录所属主体。
返回
导出结果,字段见数据类型:待补传导出结果。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029844 | 目录不可写 | 换目录;检查磁盘空间与权限 |
另可能返回通用错误。
示例
Resultados.ExportacaoPendentes p = nfce.exportarPendentes(Paths.get("E:/Pendentes"));System.out.println(p.getQuantidade() + " notas, " + p.getManifestos().size() + " pacote(s)");
CriarTerminal
主机为一台从机签发终端令牌。名称就是这台从机开出的票上的收银台标识,请用门店里认得出的收银台编号,例如 Caixa 2。令牌全文只在返回时出现这一次,主机只保存摘要:当场配置到从机的 TokenTerminal,丢失了就吊销后重新签发。只在主机模式可用,从机的部署与管理见多收银台(主从模式)。
联网:不需要。
签名
public Resultados.TerminalCriado criarTerminal(String nome);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 终端名称 | nome | 是 | 收银台名称。1 到 60 个字符;有效终端之间不得重名,不区分大小写 |
返回
新终端,字段见数据类型:从机终端。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029874 | 名称为空、超过 60 个字符,或与有效终端重名(Detalhes.motivo 为 duplicado) | 换一个名称;要沿用旧名称时先吊销旧终端 |
| 10029884 | 当前不是主机模式 | 只在主机调用 |
另可能返回通用错误。
示例
Resultados.TerminalCriado t = principal.criarTerminal("Caixa 2");// 令牌全文只返回这一次,当场配置到收银台 2System.out.println(t.getId() + " " + t.getToken());
ListarTerminais
主机列出从机终端,按创建时间倒序,不含令牌。缺省不列出吊销满 30 天的终端,传 todos 为 true 时全部列出;记录一直保留。只在主机模式可用。
联网:不需要。
签名
public List<Resultados.Terminal> listarTerminais(boolean todos);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 全部列出 | todos | 否 | 含吊销满 30 天的终端。缺省 false |
返回
终端列表,字段见数据类型:从机终端。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029884 | 当前不是主机模式 | 只在主机调用 |
另可能返回通用错误。
示例
for (Resultados.Terminal t : principal.listarTerminais(false)) {System.out.println(t.getNome() + " " + t.getSituacao() + " " + t.getUltimoUsoEm());}
RevogarTerminal
主机吊销一台从机的终端令牌,立即生效:该从机之后的调用返回 10029882,尚未投递给它的事件一并删除。从机丢失、停用或令牌泄露时调用。吊销不能撤销,需要时重新签发。只在主机模式可用。
联网:不需要。
签名
public void revogarTerminal(String id);
参数
| 参数 | Java | 必填 | 说明 |
|---|---|---|---|
| 终端标识 | id | 是 | CriarTerminal 返回的 id,以 trm_ 开头 |
返回
无。
可能的错误
| 错误码 | 情形 | 处理 |
|---|---|---|
| 10029888 | 终端不存在 | 用 ListarTerminais 核对 id |
| 10029884 | 当前不是主机模式 | 只在主机调用 |
另可能返回通用错误。
示例
principal.revogarTerminal("trm_8Kq2Xc0vLm4R");
Encerrar
关闭 SDK:停止后台同步,等进行中的开票完成(最多 10 秒),关闭本地库,再结束运行时(再等 5 秒仍未退出则强制结束)。整个过程最长约 15 秒。收银程序退出前调用。可以重复调用;关闭后再调用其他方法返回 10029834,需要重新 Iniciar。
关闭期间不补传;下次 Iniciar 后立即同步一轮;若仍有待补传的票或未确认的事件,会发出 PENDENCIAS_NA_INICIALIZACAO。退出与重启时的注意事项见运维与进阶:关闭与重启。
联网:不需要。
签名
public void encerrar();public void close();
close 等同于 Encerrar,可配合 try-with-resources。
参数
无。
返回
无。
可能的错误
不抛错误,可以重复调用。
示例
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 | 类型 | 可空 | 说明 |
|---|---|---|---|---|
id | getId() | 文本 | 否 | 单据标识。开票请求里的 id |
status | getStatus() | 文本 | 否 | 单据状态。取值见上 |
emitidaEmContingencia | isEmitidaEmContingencia() | 布尔 | 否 | 离线签发标志。授权后仍为 true |
chave | getChave() | 文本 | 是 | 访问密钥。44 位数字 |
serie | getSerie()(Long) | 整数 | 是 | 系列 |
numero | getNumero()(Long) | 整数 | 是 | 票号 |
dataEmissao | getDataEmissao() | 时间 | 是 | 开票时间 |
protocolo | getProtocolo() | 文本 | 是 | 授权协议号。离线待补传时为 null |
qrCode | getQrCode() | 文本 | 是 | 二维码内容。自行排版小票时编码成二维码 |
urlConsulta | getUrlConsulta() | 文本 | 是 | 消费者查询网址 |
motivo | getMotivo() | 文本 | 是 | 原因说明。来自 SEFAZ 或平台 |
cStat | getCStat()(Long) | 整数 | 是 | SEFAZ 结果码。没有 SEFAZ 结果时为 null |
xMotivo | getXMotivo() | 文本 | 是 | SEFAZ 结果说明。与结果码成对出现 |
tentativaOnline | isTentativaOnline() | 布尔 | 否 | 在线尝试标志。先尝试在线、结果不明后转离线时为 true,这张票用的是在线尝试那个号码的下一个号,原号码由平台在补传时核对后收口;在线授权的票为 false |
respostaPlataforma | getRespostaPlataforma() | 文本 | 是 | 平台响应原文。在线开票时为平台返回的 JSON,结构同查询 NFC-e;离线为 null |
terminal | getTerminal() | 文本 | 是 | 收银台标识。主从模式下从机开出的票为该从机的终端名称;主机或独立模式自己开的票为 null。随提交上报平台,与查询 NFC-e 和 Webhook 的 terminal 同值 |
查询状态
Consultar 的返回与票据分页的元素。Java SituacaoNota;包含开票结果的全部字段,另有:
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
transmitida | isTransmitida() | 布尔 | 否 | 已补传标志。离线票已补传到平台 |
cancelamentoPendente | isCancelamentoPendente() | 布尔 | 否 | 取消待执行标志。有挂起或本机排队的取消 |
correcoes | getCorrecoes()(Long) | 整数 | 否 | 修正次数 |
atualizadoEm | getAtualizadoEm() | 时间 | 是 | 最后更新时间 |
xmlAutorizadoDisponivel | isXmlAutorizadoDisponivel() | 布尔 | 否 | 本机 XML 就绪标志。授权 XML 已在本机时为 true,XmlAutorizado 直接读本机;已授权但为 false 时调用会联网回取 |
pedido | getPedido() | 文本 | 是 | 开票请求。JSON 文本,同号修正时作为底稿;引用税种的商品行已换成平台展开后的 impostos,可留作断网时改传 |
票据分页
ListarNotas 的返回。Java Resultados.PaginaNotas。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
itens | getItens() | 数组 | 否 | 本页票据。元素为查询状态,按开票时间倒序 |
pagina | getPagina() | 整数 | 否 | 页码。从 1 开始 |
tamanhoPagina | getTamanhoPagina() | 整数 | 否 | 每页张数。固定 50 |
temMais | isTemMais() | 布尔 | 否 | 下一页标志。不提供总数 |
预览结果
Previsualizar 的返回。Java Resultados.PreVisualizacao。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
valido | isValido() | 布尔 | 否 | 校验通过标志 |
erros | getErros() | 文本数组 | 否 | 校验错误。已按错误文案语言翻译;通过时为空数组 |
pedidoNormalizado | getPedidoNormalizado() | 文本 | 是 | 规范化后的请求。JSON 文本,一般不用 |
valorTotal | getValorTotal()(BigDecimal) | 小数 | 是 | 票面合计 |
valorTributos | getValorTributos()(BigDecimal) | 小数 | 是 | 税额合计 |
取消结果
Cancelar 与 CancelarPorSubstituicao 的返回。Java Resultados.Cancelamento。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
situacao | getSituacao() | 文本 | 否 | 受理去向。取值见下 |
motivo | getMotivo() | 文本 | 是 | 说明 |
situacao | 含义 |
|---|---|
Solicitado | 已授权的票,取消已提交平台;结果经 CANCELAMENTO_CONCLUIDO 或 CANCELAMENTO_REJEITADO 事件到达 |
Agendado | 离线票已补传、尚未授权,平台挂起取消,授权后自动发起 |
EnfileiradoLocal | 本机排队:断网,或离线票 / 替代票尚未补传;补传后同一轮立即提交 |
配对码信息
InspecionarCodigoAtivacao 的返回。Java Resultados.CodigoAtivacao。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
ambiente | getAmbiente()(Long) | 整数 | 否 | 开票环境。1 生产,2 测试 |
formasPermitidas | getFormasPermitidas()(Long) | 整数 | 否 | 允许形态。0 不限形态,1 仅发票助手,2 仅内置 SDK |
expiraEm | getExpiraEm() | 时间 | 否 | 配对码到期时间 |
plataforma | getPlataforma() | 文本 | 否 | 平台地址。配对码指向的平台 |
serie | getSerie()(Long) | 整数 | 是 | 指定的设备系列。集成商生成配对码时指定的系列;未指定为 null,配对时由平台分配 |
numeroInicial | getNumeroInicial()(Long) | 整数 | 是 | 指定的起始号码。只指定了系列时为生成配对码时平台算出的号码;未指定为 null,从 1 开始 |
配对结果
Ativar 的返回。Java Resultados.Ativacao。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
empresaId | getEmpresaId() | 文本 | 否 | 主体标识。其他方法的 empresaId |
dispositivoId | getDispositivoId() | 文本 | 否 | 设备标识 |
cnpj | getCnpj() | 文本 | 否 | 主体 CNPJ |
uf | 经 getCampos() | 文本 | 否 | 所在州 |
ambiente | 经 getCampos() | 整数 | 否 | 开票环境。1 生产,2 测试 |
serieOffline | getSerieOffline()(Long) | 整数 | 否 | 设备系列。本设备专用,在线票与离线票共用、号码连续;字段名沿用旧名 |
licencaExpiraEm | getLicencaExpiraEm() | 时间 | 是 | 许可证到期时间 |
numeroInicial | getNumeroInicial()(Long) | 整数 | 否 | 起始号码。本设备第一张票的号码;配对码未指定时为 1 |
已配对主体
Empresas 的元素。Java Resultados.EmpresaAtivada。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
empresaId | getEmpresaId() | 文本 | 否 | 主体标识 |
dispositivoId | getDispositivoId() | 文本 | 否 | 设备标识 |
cnpj | getCnpj() | 文本 | 否 | 主体 CNPJ |
uf | 经 getCampos() | 文本 | 否 | 所在州 |
ambiente | 经 getCampos() | 整数 | 否 | 开票环境。1 生产,2 测试 |
serieOffline | 经 getCampos() | 整数 | 否 | 设备系列 |
situacao | getSituacao() | 文本 | 否 | 设备状态。取值见下 |
situacao | 含义 | 处理 |
|---|---|---|
Ativo | 可以开票 | 无 |
Desativado | 集成商已停用设备 | 不可恢复;同一电脑要继续用须重新配对 |
Revogado | 平台已吊销设备 | 联系平台 |
EmpresaDesativada | 该主体的离线开票被停用 | 联系平台 |
AplicativoBloqueado | 收银软件被平台封禁 | 联系平台 |
VersaoBloqueada | 收银程序版本被封禁或低于最低版本 | 升级收银程序 |
除 Ativo 外都不能开新票,已开出的离线票照常补传。
内核状态
Situacao 的返回。Java Resultados.Nucleo。
| JSON 名 | Java | 类型 | 说明 |
|---|---|---|---|
versaoNucleo | getVersaoNucleo() | 文本 | 内核版本 |
empresas | getEmpresas()(元素为键值对) | 数组 | 每个已配对主体的状态,字段见下 |
avisos | getAvisos() | 文本数组 | 引擎告警。需要宿主处理的运行环境问题,没有时为空数组。例如配置了代理认证,但 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 | 类型 | 可空 | 说明 |
|---|---|---|---|---|
quantidadeNotas | getQuantidadeNotas() | 整数 | 否 | 导出张数。至少写出一个文件的单据张数 |
quantidadeArquivos | getQuantidadeArquivos() | 整数 | 否 | 文件数。写出的授权 XML 与取消 XML 文件总数;一张已取消的票授权与取消 XML 都写出时算两个 |
arquivos | getArquivos() | 文本数组 | 否 | 导出文件。写出的文件绝对路径,授权 XML 与取消 XML 各一个文件 |
falhas | getFalhas()(元素为键值对) | 数组 | 否 | 缺失清单。区间内取不到 XML 的单据,没有时为空数组;元素字段见下 |
falhas 元素:
| JSON 名 | Java 键 | 类型 | 说明 |
|---|---|---|---|
id | id | 文本 | 单据标识 |
chave | chave | 文本 | 访问密钥 |
motivo | motivo | 文本 | 缺失原因。包括是否已按保留期清理 |
备份结果
Backup 的返回。Java Resultados.Backup。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
arquivo | getArquivo() | 文本 | 否 | 备份文件。绝对路径 |
bytes | getBytes() | 整数 | 否 | 文件大小。单位字节 |
versaoBanco | getVersaoBanco() | 整数 | 否 | 本地库结构版本。恢复时内核版本须不低于此版本 |
sha256 | getSha256() | 文本 | 否 | 文件摘要。加密后备份文件的 SHA-256,小写十六进制 |
恢复结果
RestaurarBackup 的返回。Java Resultados.Restauracao。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
versaoBanco | getVersaoBanco() | 整数 | 否 | 本地库结构版本。恢复进来的库的版本;低于当前 SDK 时下次启动自动升级 |
copiaAnterior | getCopiaAnterior() | 文本 | 是 | 原库副本。恢复前另存的原库文件绝对路径;原来没有库时为空 |
待补传导出结果
ExportarPendentes 的返回。Java Resultados.ExportacaoPendentes。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
quantidade | getQuantidade() | 整数 | 否 | 导出张数 |
manifesto | getManifesto() | 文本 | 是 | 第一份清单。第一包 manifesto.json 的绝对路径;没有待补传票时为空 |
manifestos | getManifestos() | 文本数组 | 否 | 全部清单。每个设备目录下每个 pacote-NNN 一份,每包至多 500 张;没有待补传票时为空数组 |
arquivos | getArquivos() | 文本数组 | 否 | 签名 XML 文件。绝对路径 |
证书来源
Ativar 与 TrocarCertificado 的证书参数。
| 来源 | Java |
|---|---|
| Windows 证书存储中已有的证书 | Certificado.doRepositorio(thumbprint, maquinaLocal) |
| PFX 文件 | Certificado.deArquivoPfx(bytes, senha) |
| 参数 | 说明 |
|---|---|
thumbprint | 证书指纹。SHA-1,40 位十六进制,空格会被忽略;格式不对返回 10029874 |
maquinaLocal | 本机证书存储标志。true 用本机证书存储,false(缺省)用当前 Windows 用户的证书存储 |
PFX 字节与 senha | PFX 证书与密码。内核把证书导入证书存储并设为私钥不可导出,之后只保存指纹,密码不保存 |
用 PFX 配对或换证时(Certificado.deArquivoPfx),内核把证书导入运行 SDK 的 Windows 用户的「当前用户 > 个人」证书存储,私钥不可导出,并长期保留在那里,每次签名都从这里取。不要删除这张证书:删除后设备无法签名,开票返回 10029813。
设备不再使用时按顺序清理:
- 确认状态中各公司的
pendentesTransmissao为 0,离线票已全部补传 - 在控制台停用或吊销设备;只是换证书的,先用 TrocarCertificado 换上新证书
- 以同一 Windows 用户打开
certmgr.msc,在「个人 > 证书」中按指纹删除旧证书,或在 PowerShell 执行Remove-Item Cert:\CurrentUser\My\<指纹>
从机终端
CriarTerminal 的返回。Java Resultados.TerminalCriado。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
id | getId() | 文本 | 否 | 终端标识。以 trm_ 开头,吊销时用 |
nome | getNome() | 文本 | 否 | 终端名称。即该从机开出的票上的收银台标识 |
token | getToken() | 文本 | 否 | 终端令牌。以 tfl_ 开头,只返回这一次,配置到从机的 TokenTerminal |
ListarTerminais 的元素。Java Resultados.Terminal;不含令牌。
| JSON 名 | Java | 类型 | 可空 | 说明 |
|---|---|---|---|---|
id | getId() | 文本 | 否 | 终端标识 |
nome | getNome() | 文本 | 否 | 终端名称 |
situacao | getSituacao() | 文本 | 否 | 终端状态。Ativo 或 Revogado |
criadoEm | getCriadoEm() | 时间 | 否 | 签发时间 |
ultimoUsoEm | getUltimoUsoEm() | 时间 | 是 | 最后使用时间。从未使用时为 null |
revogadoEm | getRevogadoEm() | 时间 | 是 | 吊销时间。有效终端为 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 | 类型 | 可空 | 说明 |
|---|---|---|---|---|
eventoId | getEventoId() | 文本 | 否 | 事件标识。去重键,重投时不变 |
seq | getSeq()(long) | 整数 | 否 | 本机序号。单调递增;SDK 本地事件为 0 |
tipo | getTipo() | 文本 | 否 | 事件类型。见下文各节 |
ocorridoEm | getOcorridoEm() | 时间文本 | 否 | 发生时间。ISO 8601 UTC |
empresaId | getEmpresaId() | 文本 | 是 | 主体标识。SDK 本地事件为 null |
dispositivoId | 经 getCampos() | 文本 | 是 | 设备标识 |
id | getId() | 文本 | 是 | 单据标识。只有票据类事件有值 |
chave | getChave() | 文本 | 是 | 访问密钥。只有票据类事件有值 |
status | getStatus() | 文本 | 是 | 单据当前状态。只有票据类事件有值,取值见单据状态 |
dados | getDados()(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 规则相同。
请求示例
现场销售、消费者不识别、现金付款:
{"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(内核内部错误);联网操作中平台返回的业务错误原样透传。各方法「可能的错误」只列该方法特有的码。全站错误码与处理建议见错误码。
| 错误码 | 常量 | 场景 | 处理 |
|---|---|---|---|
| 10029800 | ENGINE_NOT_STARTED | 未初始化 | 正常使用不会出现;出现说明 SDK 封装有缺陷,重新初始化 |
| 10029801 | ENGINE_NOT_ACTIVATED | 该主体未在本机配对,或本机尚未配对任何主体 | 引导配对;多主体时检查 empresaId |
| 10029802 | ENGINE_EMPRESA_REQUIRED | 配对了多个主体但未指定 empresaId | 传 empresaId |
| 10029803 | ENGINE_LICENSE_MISSING | 没有可用于离线开票的许可证 | 联网同步一次(SincronizarAgora) |
| 10029804 | ENGINE_LICENSE_EXPIRED | 许可证已过期;离线开票被拒,在线开票照常 | 恢复网络,自动续签 |
| 10029805 | ENGINE_LICENSE_SIGNATURE_INVALID | 许可证签名无效 | 人工处理:联系平台,本地库可能被篡改 |
| 10029806 | ENGINE_LICENSE_NOT_FOR_DEVICE | 许可证不属于本设备 | 人工处理:重新配对 |
| 10029807 | ENGINE_OFFLINE_WINDOW_CLOSED | 已过离线开票截止时间 | 恢复网络后在线开票 |
| 10029808 | ENGINE_LICENSE_QUOTA_EXHAUSTED | 本设备系列号码已用到 999999999 | 停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列 |
| 10029809 | ENGINE_CLOCK_ROLLBACK | 系统时钟被往回调 | 人工处理:校正系统时间 |
| 10029810 | ENGINE_TRANSMISSION_DEADLINE_REACHED | 最早待补传票已超补传时限 | 人工处理:尽快恢复网络补传 |
| 10029811 | ENGINE_OFFLINE_NOT_ALLOWED | 主体或州不允许离线开票;或刚从备份恢复、尚未拿到新许可证 | 只能在线开票;刚恢复的联网同步一轮后自动恢复离线开票 |
| 10029812 | ENGINE_OFFLINE_FUEL_NOT_SUPPORTED | 含燃料的票不能离线开 | 网络恢复后开票 |
| 10029813 | ENGINE_CERTIFICATE_UNAVAILABLE | 证书找不到、无私钥或 CNPJ 不符 | 人工处理:检查证书存储,必要时 TrocarCertificado |
| 10029814 | ENGINE_CERTIFICATE_EXPIRED | 证书已过期 | 人工处理:续期后 TrocarCertificado |
| 10029815 | ENGINE_SNAPSHOT_MISSING | 本机配置或计税数据缺失或校验失败 | 联网同步;持续出现联系平台 |
| 10029816 | ENGINE_DEVICE_DEACTIVATED | 设备已被停用 | 人工处理:联系集成商;已开离线票照常补传 |
| 10029817 | ENGINE_REQUEST_INVALID | 请求校验失败,Detalhes 逐字段列出原因 | 修正请求;可先用 Previsualizar 预校验 |
| 10029780 | ENGINE_TAX_CLASS_REQUIRES_ONLINE | 商品行引用了税种,但连不上平台展开;未占用票号 | 恢复网络后用同一 id 重发;断网时商品行改传 impostos |
| 10029818 | ENGINE_DUPLICATE_ID_DIFFERENT_CONTENT | 同一 id 已用于内容不同的票 | 新单用新 id;重试用原请求取回原票 |
| 10029819 | ENGINE_NOTE_NOT_FOUND | 本机没有这张票 | 核对 id 与 empresaId |
| 10029820 | ENGINE_NOTE_NOT_CORRECTABLE | 当前状态不可修正 | 只有 Rejeitada 可以 Substituir |
| 10029821 | ENGINE_CORRECTION_CHANGES_TOTALS | 修正改变了金额或税额 | 只改非金额内容 |
| 10029822 | ENGINE_CANCEL_NOT_ALLOWED | 当前状态不可取消 | 不要重试 |
| 10029823 | ENGINE_SERIE_EXHAUSTED | 设备系列号码已用尽 | 停用该设备,生成指定新系列(serie)的配对码重新配对;平台不会自动更换系列 |
| 10029824 | ENGINE_PLATFORM_UNREACHABLE | 需要联网的操作(配对)连不上平台 | 检查网络后重试 |
| 10029825 | ENGINE_ACTIVATION_CODE_INVALID | 配对码格式、签名或有效期不对 | 人工处理:重新生成配对码 |
| 10029826 | ENGINE_ACTIVATION_HOST_UNTRUSTED | 配对码指向的平台地址不受信 | 人工处理:确认配对码来源与安装包环境(测试 / 生产) |
| 10029827 | ENGINE_KEY_PROTECTION_FAILED | 数据目录来自别的电脑或别的 Windows 用户 | 人工处理:用原电脑、原用户运行,或重新配对 |
| 10029828 | ENGINE_DATA_DIR_LOCKED | 数据目录被其他进程占用,包括恢复备份时本程序还没 Encerrar 的实例 | 关闭另一个实例;恢复备份前先 Encerrar |
| 10029829 | ENGINE_LOCAL_STORE_CORRUPTED | 本地库不一致 | 人工处理:不要删除数据目录,联系平台 |
| 10029830 | ENGINE_PROTOCOL_VERSION_UNSUPPORTED | SDK 与运行时版本不兼容 | SDK 与运行时配套升级 |
| 10029831 | ENGINE_RUNTIME_START_FAILED | 运行时启动失败 | 检查运行时目录是否完整、是否被杀毒软件拦截 |
| 10029832 | ENGINE_RUNTIME_CRASHED | 运行时意外退出 | 可重试;开启自动重启时 SDK 自行恢复,开票用同一 id 重发 |
| 10029833 | ENGINE_TIMEOUT | 等待超时 | 开票用同一 id 重发,或先 Consultar |
| 10029834 | ENGINE_SHUTTING_DOWN | 正在关闭或已关闭 | 重新 Iniciar |
| 10029835 | ENGINE_IN_PROCESS_UNSUPPORTED | Java 进程内模式需要 Java 21 及以上 | 改用子进程模式 |
| 10029836 | ENGINE_INTERNAL_ERROR | 内核内部错误,说明里带定位号 | 联系平台并提供定位号与日志 |
| 10029837 | ENGINE_ALREADY_ACTIVATED | 该主体已在本数据目录配对 | 无需再配对;换设备须先停用旧设备 |
| 10029838 | ENGINE_PLATFORM_RESPONSE_UNTRUSTED | 平台响应校验失败,已保留原数据 | 稍后自动重试;持续出现检查网络代理是否改写了响应 |
| 10029839 | ENGINE_ACTIVATION_PERSIST_FAILED | 平台已配对但本机保存失败 | 用同一配对码再次配对 |
| 10029840 | ENGINE_CONFIG_INVALID | 初始化配置非法 | 修正配置 |
| 10029841 | ENGINE_AUTHORIZED_XML_UNAVAILABLE | 授权 XML 不可用:还没授权,或本机没有且从平台取不回 | 未授权的等授权事件后再取;已授权的说明平台尚未归档或当前连不上平台,稍后重试 |
| 10029842 | ENGINE_LOCAL_STORE_NEWER_VERSION | 本地库版本高于当前内核:数据目录曾被更新版本的 SDK 使用过,拒绝启动 | 把 SDK 与运行时升级到不低于上次使用的版本;绝不要删除数据目录 |
| 10029843 | ENGINE_CANCEL_XML_UNAVAILABLE | 取消 XML 不可用:票没有取消,或本机没有且从平台取不回 | 未取消的等 CANCELAMENTO_CONCLUIDO 后再取;已取消的稍后重试 |
| 10029844 | ENGINE_EXPORT_FAILED | 写文件失败:导出或备份的目标不可写,或备份文件已存在 | 换目录或文件名;检查磁盘空间与权限 |
| 10029845 | ENGINE_SUBSTITUTE_KEY_INVALID | 替代取消的替代票密钥不合法,或不是本机、本主体未被拒收的离线票 | 传本机为同一笔销售开出的离线票的 44 位访问密钥 |
| 10029846 | ENGINE_BACKUP_INVALID | 备份无法恢复:口令错误,或备份文件被改动、损坏、不是本 SDK 的备份 | 核对口令;换一份完好的备份。原库没有被改动 |
| 10029870 | ENGINE_PROTOCOL_INVALID_JSON | 运行时收到的消息不是合法 JSON | SDK 封装缺陷,升级 SDK |
| 10029871 | ENGINE_PROTOCOL_LINE_TOO_LONG | 单条消息超过 8 MB | 请求过大,拆分商品明细 |
| 10029872 | ENGINE_PROTOCOL_MESSAGE_INVALID | 消息结构不合法 | SDK 封装缺陷,升级 SDK |
| 10029873 | ENGINE_METHOD_UNKNOWN | 运行时不认识该方法 | SDK 比运行时新,升级运行时 |
| 10029874 | ENGINE_PARAMS_INVALID | 参数缺失或类型错误,Detalhes.campo 点名参数 | 修正参数,例如请求不是 JSON 对象、证书指纹格式、日期格式 |
| 10029875 | ENGINE_ALREADY_STARTED | 重复初始化;或同一运行时连接已 Iniciar 后又调用恢复备份的协议方法 | 封装的正常调用不会出现,出现说明 SDK 封装有缺陷,升级 SDK;自行对接运行时协议时先 Encerrar,再另开连接恢复 |
| 10029876 | ENGINE_REQUEST_ID_DUPLICATED | 同一调用仍在处理中 | SDK 封装缺陷,升级 SDK |
| 10029877 | ENGINE_RUNTIME_NOT_FOUND | 找不到运行时 | 检查安装包与运行时目录 |
| 10029878 | ENGINE_TOO_MANY_PENDING | 同时等待中的调用超过 64 个 | 降低并发 |
| 10029879 | ENGINE_RESPONSE_TOO_LARGE | 单次响应超过上限 | 联系平台 |
| 10029880 | ENGINE_PRINCIPAL_UNREACHABLE | 从机连不上主机,请求没有送到 | 稍后重试,或把收银切到备用机 |
| 10029881 | ENGINE_PRINCIPAL_RESULT_UNKNOWN | 请求已发到主机但没收到响应,结果未知 | 主机恢复后用同一个 id 调 Consultar;同一 id 同样内容重发 Emitir 不会重复开票 |
| 10029882 | ENGINE_TERMINAL_TOKEN_INVALID | 从机的终端令牌无效或已吊销 | 在主机重新 CriarTerminal,更新从机的 TokenTerminal |
| 10029883 | ENGINE_PRINCIPAL_ADDRESS_INVALID | 主机地址格式不对,或不是局域网私有地址 | 修正 EnderecoPrincipal |
| 10029884 | ENGINE_MODE_METHOD_UNAVAILABLE | 当前模式不提供该方法 | 配对、换证书、备份与导出在主机做;终端管理只在主机调用 |
| 10029885 | ENGINE_PRINCIPAL_REJECTED | 主机拒绝了请求来源,例如从机不在允许网段内 | 检查主机的 RedesPermitidas 与网络 |
| 10029886 | ENGINE_PRINCIPAL_RATE_LIMITED | 鉴权失败过多,被主机限频 | 核对令牌,1 分钟后再试 |
| 10029887 | ENGINE_PRINCIPAL_LISTEN_FAILED | 主机的局域网端口无法监听 | 换 PortaPrincipal,或释放被占用的端口 |
| 10029888 | ENGINE_TERMINAL_NOT_FOUND | 要吊销的终端不存在 | 用 ListarTerminais 核对终端 id |
全部错误码与发票助手错误码见错误码。
