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:
| Mode | ModoOperacao setting | Local core | What this till does |
|---|---|---|---|
| Standalone | INDEPENDENTE (default) | Runs | Runs the core and is paired; one device and one device series for this till |
| Primary | PRINCIPAL | Runs | Runs 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 |
| Secondary | SECUNDARIO | Does not run | No 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
- Primary: pick a till that runs steadily and stays on, set
ModoOperacaoto primary, thenIniciarand pair as usual (see Initialization and pairing). Pairing, certificate change, backup, pending-package export and the monthly XML export only run on the primary. - Issue a terminal token for each secondary: on the primary, call
CriarTerminalwith the till name, for exampleCaixa 2; it returns the terminal identifier and the token (starting withtfl_). 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. - Secondary: set
ModoOperacaoto secondary,EnderecoPrincipalto the primary's local network address and port, for example192.168.0.10:8786, andTokenTerminalto the token from the previous step, thenIniciaras usual. A secondary does not callAtivar. - 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:
// Till 1: primary. Pair as usual, then issue a terminal token once per secondaryTfFiscalNfce 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 modeTfFiscalNfce 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
| Scope | Methods |
|---|---|
| Available on a secondary | Ativado, Empresas, InspecionarCodigoAtivacao, Emitir, Previsualizar, Consultar, ListarNotas, Cancelar, CancelarPorSubstituicao, Substituir, Cupom, QrCodePng, XmlAutorizado, XmlCancelamento, Situacao, SincronizarAgora and events |
| Primary only | Ativar, 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,Iniciaron the primary returns10029887. EnderecoPrincipalmust be a private local network address, otherwise10029883is 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
10029880right 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, callConsultarwith the sameid; resendingEmitirwith the sameidand content does not issue twice. - A secondary starts even when the primary is unreachable:
Iniciarsucceeds 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 withtrm_), the name and the token (starting withtfl_). The full token appears only once, in this return; the primary keeps only a digest. Configure it on the secondary'sTokenTerminalright 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
todosastrueto 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.
