TF Fiscal
Documentation

Offline NFC-e

Multiple tills (primary and secondary mode)

Embedded SDK with several tills (primary and secondary mode): several tills in one store share one device series; roles, deployment steps, sample code, methods available on a secondary, local network and failure handling, secondary terminal management.

When a store has several tills and wants one device series for the whole store, use primary/secondary mode: one till starts as the primary and the others as secondaries. The primary assigns every number, so invoices from all tills are numbered continuously and never collide. By the end you can deploy the primary and the secondaries, manage secondary terminals, and know what to do when the primary fails. Prerequisites: pairing and issuing already work on one till as in the embedded SDK tutorial.

When to use it

By default each till is paired as its own device with its own device series; this is standalone mode, and the tills do not depend on each other. When you want the whole store to use only one device series, with numbers taken from one place, use primary/secondary mode instead. Device series and numbering rules are in Numbers and series.

The three roles

The role is set by the ModoOperacao setting:

ModeModoOperacao settingLocal coreWhat this till does
StandaloneINDEPENDENTE (default)RunsRuns the core and is paired; one device and one device series for this till
PrimaryPRINCIPALRunsRuns the core and is paired; its device series is the one shared by the store; also serves the secondaries on the local network, default port 8786, and issues and revokes their terminal tokens
SecondarySECUNDARIODoes not runNo pairing and no certificate; issuing, query, cancellation, receipts, XML, status and events all go to the primary over the local network, with the same method signatures and results as standalone mode, and the series and numbers come from the primary device

Deployment steps

  1. Primary: pick a till that runs steadily and stays on, set ModoOperacao to primary, then Iniciar and pair as usual (see Initialization and pairing). Pairing, certificate change, backup, pending-package export and the monthly XML export only run on the primary.
  2. Issue a terminal token for each secondary: on the primary, call CriarTerminal with the till name, for example Caixa 2; it returns the terminal identifier and the token (starting with tfl_). The full token is returned only once, so configure it on that secondary right away. Names have 1 to 60 characters and must be unique among active terminals.
  3. Secondary: set ModoOperacao to secondary, EnderecoPrincipal to the primary's local network address and port, for example 192.168.0.10:8786, and TokenTerminal to the token from the previous step, then Iniciar as usual. A secondary does not call Ativar.
  4. The POS calls the SDK as usual: on a secondary, issuing, query, cancellation and the other methods have the same signatures and results as in standalone mode; the series and numbers returned come from the primary device.

Values and error codes for the primary port (PortaPrincipal), allowed networks (RedesPermitidas), the primary address and the terminal token are in the SDK reference configuration.

Code example

The code below first starts till 1 as the primary and issues a terminal token for Caixa 2, then starts till 2 as a secondary and issues an invoice:

java
// Till 1: primary. Pair as usual, then issue a terminal token once per secondary
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");
// Till 2: secondary. No pairing; issuing is written as in standalone mode
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() is "Caixa 2"; series and number come from the primary device

What a secondary can do

ScopeMethods
Available on a secondaryAtivado, Empresas, InspecionarCodigoAtivacao, Emitir, Previsualizar, Consultar, ListarNotas, Cancelar, CancelarPorSubstituicao, Substituir, Cupom, QrCodePng, XmlAutorizado, XmlCancelamento, Situacao, SincronizarAgora and events
Primary onlyAtivar, TrocarCertificado, Backup, RestaurarBackup, ExportarPendentes, ExportarXmls, and terminal management CriarTerminal, ListarTerminais, RevogarTerminal

Calling a primary-only method on a secondary or in standalone mode returns 10029884.

The terminal name is the till identifier: invoices issued by a secondary carry its terminal name as the till identifier, stored on the invoice and reported to the platform with it. The SDK result Terminal (Java getTerminal()) holds this name, see Issuing result; invoices issued by the primary itself or in standalone mode have no till identifier, and the SDK result is null. The integrator server also gets this identifier in Query NFC-e and in webhooks, so it knows which till issued the invoice; the payload is described in How you get the results.

Events: a secondary only receives the events of invoices it issued, plus device-level events such as license, certificate, connection and deactivation; the primary still receives all events. Acknowledgement and redelivery rules are unchanged, see Receiving results.

Local network and failures

Local network and security

  • The primary only accepts private local network sources inside the networks listed in RedesPermitidas, by default the /24 network of the primary; add the network of any secondary that sits elsewhere. Windows Firewall must allow the primary port (PortaPrincipal, default 8786); if the port is taken, Iniciar on the primary returns 10029887.
  • EnderecoPrincipal must be a private local network address, otherwise 10029883 is returned.
  • After 20 failed authentications from one source within 1 minute the source is rate-limited with 10029886; retry after 1 minute.
  • The token is only handed to the runtime in memory and never written to disk or logs; if the POS stores the token itself, store it encrypted.

Primary failure and standby till

  • The primary is a single point of failure: when it is off, offline from the network or its POS software is not running, secondary calls return 10029880 right away and the request does not reach the primary. A secondary never takes over by itself and does not copy the primary's data. Keep the primary running and powered on; a UPS is recommended.
  • Unknown result: when the request reached the primary but no response came back, issuing, cancellation, correction and cancellation by substitution return 10029881. After the primary recovers, call Consultar with the same id; resending Emitir with the same id and content does not issue twice.
  • A secondary starts even when the primary is unreachable: Iniciar succeeds as usual with an empty list of paired companies, and each later call connects to the primary live.
  • Backup machine: pair another till beforehand in standalone mode as a device of its own, with its own device series. When the primary fails, the POS moves the till to the backup machine; when the primary recovers, its series continues as before, each series continuous on its own. The rules only require continuous numbering within one series, so several series in one store are equally compliant.

Managing secondary terminals

All three terminal management methods are primary only:

  • Issue: CriarTerminal takes the till name; the name is the till identifier on the invoices that secondary issues, so use a till number the store recognizes, for example Caixa 2. It returns the terminal identifier (starting with trm_), the name and the token (starting with tfl_). The full token appears only once, in this return; the primary keeps only a digest. Configure it on the secondary's TokenTerminal right away; if it is lost, revoke it and issue a new one.
  • List: ListarTerminais lists every terminal with its name, status and last use, newest first, without tokens. By default terminals revoked more than 30 days ago are hidden; pass todos as true to list all of them.
  • Revoke: when a secondary is lost, retired or its token leaked, call RevogarTerminal on the primary. It takes effect immediately: later calls from that secondary return 10029882, and events not yet delivered to it are dropped. Revocation cannot be undone; issue a new token when needed.

Returned fields are in Secondary terminal.