TF Fiscal
开发文档

NFC-e 离线开票

多收银台(主从模式)

内置 SDK 多收银台(主从模式):一店多台收银台共用一个设备系列,角色、部署步骤、示例代码、从机可用的方法、局域网与故障处理、从机终端管理。

一个门店有多台收银台、希望全店共用一个设备系列时,用主从模式:一台收银台以主机启动,其余以从机启动,号码统一由主机分配,各收银台开出的票号码连续、不会撞号。读完你能部署主机与从机、管理从机终端,并知道主机故障时怎么办。前置:已按内置 SDK 教程在一台收银台上走通配对与开票。

什么时候用

缺省情况下每台收银台各自配对为一台设备、各用一个设备系列,这是独立模式,各收银台互不依赖。希望全店只用一个设备系列、由一处统一取号时,改用主从模式。设备系列与号码规则见号码与系列。

三种角色

角色由配置 ModoOperacao 决定:

模式配置 ModoOperacao本机内核本机做什么
独立INDEPENDENTE(缺省)运行运行内核并配对,本收银台一台设备、一个设备系列
主机PRINCIPAL运行运行内核并配对,本机设备系列就是全店共用的系列;另在局域网为从机提供服务,缺省端口 8786,签发与吊销从机的终端令牌
从机SECUNDARIO不运行不配对、不需要证书;开票、查询、取消、小票、XML、状态与事件都经局域网转给主机,方法签名与结果同独立模式,系列与号码来自主机设备

部署步骤

  1. 主机:选一台稳定运行、不关机的收银台,ModoOperacao 设为主机,照常 Iniciar 并配对(见初始化与配对)。配对、换证书、备份、导出待补传包与按月导出 XML 都只在主机做。
  2. 为每台从机签发终端令牌:在主机调用 CriarTerminal,传收银台名称,例如 Caixa 2,返回终端标识与令牌(tfl_ 开头)。令牌全文只返回这一次,请当场配置到那台从机。名称 1 到 60 个字符,有效终端之间不得重名。
  3. 从机:ModoOperacao 设为从机,EnderecoPrincipal 填主机的局域网地址与端口,例如 192.168.0.10:8786,TokenTerminal 填上一步的令牌,然后照常 Iniciar。从机不调用 Ativar。
  4. 收银程序照常调用:从机上的开票、查询、取消等方法与独立模式签名相同、结果相同,返回的系列与号码来自主机设备。

主机端口(PortaPrincipal)、允许网段(RedesPermitidas)、主机地址与终端令牌的取值与错误码见 SDK 参考的配置项。

代码示例

下面的代码先在收银台 1 以主机启动并为 Caixa 2 签发终端令牌,再在收银台 2 以从机启动并开票:

java
// 收银台 1:主机。照常配对,再为每台从机签发一次终端令牌
TfFiscalNfce principal = TfFiscalNfce.iniciar(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")
.modoOperacao(ModoOperacao.PRINCIPAL)
.aoReceberEvento(aoEvento)
.build());
Resultados.TerminalCriado caixa2 = principal.criarTerminal("Caixa 2");
// 收银台 2:从机。不配对,开票写法与独立模式相同
TfFiscalNfce secundario = TfFiscalNfce.iniciar(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")
.modoOperacao(ModoOperacao.SECUNDARIO)
.enderecoPrincipal("192.168.0.10:8786")
.tokenTerminal(tokenDoCaixa2)
.aoReceberEvento(aoEvento)
.build());
ResultadoEmissao nota = secundario.emitir(pedido);
// nota.getTerminal() 为 "Caixa 2",系列与号码来自主机设备

从机能做什么

范围方法
从机可用Ativado、Empresas、InspecionarCodigoAtivacao、Emitir、Previsualizar、Consultar、ListarNotas、Cancelar、CancelarPorSubstituicao、Substituir、Cupom、QrCodePng、XmlAutorizado、XmlCancelamento、Situacao、SincronizarAgora 与事件
只在主机可用Ativar、TrocarCertificado、Backup、RestaurarBackup、ExportarPendentes、ExportarXmls,以及终端管理 CriarTerminal、ListarTerminais、RevogarTerminal

在从机或独立模式下调用只在主机可用的方法返回 10029884。

终端名称就是收银台标识:从机开出的票,以这台从机的终端名称为收银台标识,记在票据上并随提交上报平台。SDK 结果的 Terminal(Java getTerminal())就是这个名称,见开票结果;主机自己开的票、独立模式开的票没有收银台标识,SDK 结果为 null。集成商服务端在查询 NFC-e 与 Webhook 里也能拿到这个标识,据此知道票是哪台收银台开的,载荷说明见结果怎么收到。

事件:从机只收到自己开出的票的事件,以及许可证、证书、连接、设备停用等设备级事件;主机照常收到全部事件。确认与重投规则不变,见接收结果。

局域网与故障

局域网与安全

  • 主机只接受局域网私有地址来源,且须在 RedesPermitidas 列出的网段内,缺省为主机所在的 /24 网段;从机在其他网段时把那个网段加进来。Windows 防火墙须放行主机端口(PortaPrincipal,缺省 8786);端口被占用时主机 Iniciar 返回 10029887。
  • EnderecoPrincipal 必须是局域网私有地址,否则返回 10029883。
  • 同一来源 1 分钟内鉴权失败 20 次后被限频,返回 10029886,1 分钟后再试。
  • 令牌只在内存中交给运行时,不写入磁盘与日志;收银程序自己保存令牌时请加密保存。

主机故障与备用机

  • 主机是单点:主机关机、断网或收银程序未运行时,从机调用立即返回 10029880,请求没有送到主机。从机不会自动接管,也不复制主机的数据。主机应稳定运行、不关机,建议接 UPS。
  • 结果未知:请求已发到主机但没收到响应时,开票、取消、修正与替代取消返回 10029881。主机恢复后用同一个 id 调 Consultar;同一 id 同样内容重发 Emitir 不会重复开票。
  • 主机不可达时从机仍能启动:Iniciar 照常成功,已配对主体列表为空,之后每次调用实时连接主机。
  • 备用机:事先另找一台收银台以独立模式配对为一台设备,有自己的设备系列。主机故障时由收银程序把收银切到备用机;主机恢复后原系列照常续号,两个系列各自连续。法规只要求同一系列内号码连续,一店多系列同样合规。

管理从机终端

终端管理的三个方法都只在主机可用:

  • 签发:CriarTerminal 传收银台名称,名称就是这台从机开出的票上的收银台标识,请用门店里认得出的收银台编号,例如 Caixa 2。返回终端标识(trm_ 开头)、名称与令牌(tfl_ 开头)。令牌全文只在返回时出现这一次,主机只保存摘要:当场配置到从机的 TokenTerminal,丢失了就吊销后重新签发。
  • 列出:ListarTerminais 列出全部终端的名称、状态与最后使用时间,按创建时间倒序,不含令牌。缺省不列出吊销满 30 天的终端,传 todos 为 true 时全部列出。
  • 吊销:从机丢失、停用或令牌泄露时,在主机调用 RevogarTerminal 吊销,立即生效:该从机之后的调用返回 10029882,尚未投递给它的事件一并删除。吊销不能撤销,需要时重新签发。

返回字段见从机终端。