NFC-e 离线开票
多收银台(主从模式)
内置 SDK 多收银台(主从模式):一店多台收银台共用一个设备系列,角色、部署步骤、示例代码、从机可用的方法、局域网与故障处理、从机终端管理。
一个门店有多台收银台、希望全店共用一个设备系列时,用主从模式:一台收银台以主机启动,其余以从机启动,号码统一由主机分配,各收银台开出的票号码连续、不会撞号。读完你能部署主机与从机、管理从机终端,并知道主机故障时怎么办。前置:已按内置 SDK 教程在一台收银台上走通配对与开票。
什么时候用
缺省情况下每台收银台各自配对为一台设备、各用一个设备系列,这是独立模式,各收银台互不依赖。希望全店只用一个设备系列、由一处统一取号时,改用主从模式。设备系列与号码规则见号码与系列。
三种角色
角色由配置 ModoOperacao 决定:
| 模式 | 配置 ModoOperacao | 本机内核 | 本机做什么 |
|---|---|---|---|
| 独立 | INDEPENDENTE(缺省) | 运行 | 运行内核并配对,本收银台一台设备、一个设备系列 |
| 主机 | PRINCIPAL | 运行 | 运行内核并配对,本机设备系列就是全店共用的系列;另在局域网为从机提供服务,缺省端口 8786,签发与吊销从机的终端令牌 |
| 从机 | SECUNDARIO | 不运行 | 不配对、不需要证书;开票、查询、取消、小票、XML、状态与事件都经局域网转给主机,方法签名与结果同独立模式,系列与号码来自主机设备 |
部署步骤
- 主机:选一台稳定运行、不关机的收银台,
ModoOperacao设为主机,照常Iniciar并配对(见初始化与配对)。配对、换证书、备份、导出待补传包与按月导出 XML 都只在主机做。 - 为每台从机签发终端令牌:在主机调用
CriarTerminal,传收银台名称,例如Caixa 2,返回终端标识与令牌(tfl_开头)。令牌全文只返回这一次,请当场配置到那台从机。名称 1 到 60 个字符,有效终端之间不得重名。 - 从机:
ModoOperacao设为从机,EnderecoPrincipal填主机的局域网地址与端口,例如192.168.0.10:8786,TokenTerminal填上一步的令牌,然后照常Iniciar。从机不调用Ativar。 - 收银程序照常调用:从机上的开票、查询、取消等方法与独立模式签名相同、结果相同,返回的系列与号码来自主机设备。
主机端口(PortaPrincipal)、允许网段(RedesPermitidas)、主机地址与终端令牌的取值与错误码见 SDK 参考的配置项。
代码示例
下面的代码先在收银台 1 以主机启动并为 Caixa 2 签发终端令牌,再在收银台 2 以从机启动并开票:
// 收银台 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,尚未投递给它的事件一并删除。吊销不能撤销,需要时重新签发。
返回字段见从机终端。
