TF Fiscal
Documentação

NFC-e offline

Vários caixas (modo principal e secundário)

Vários caixas com o SDK embarcado (modo principal e secundário): vários caixas da mesma loja com uma só série de dispositivo, papéis, passos de implantação, código de exemplo, métodos disponíveis no secundário, rede local e falhas, gestão dos terminais secundários.

Quando a loja tem vários caixas e quer uma só série de dispositivo para todos, use o modo principal e secundário: um caixa inicia como principal e os outros como secundários; o principal atribui todos os números, então as notas de todos os caixas têm numeração contínua e nunca colidem. Ao terminar, você saberá implantar o principal e os secundários, gerenciar os terminais secundários e o que fazer quando o principal falhar. Pré-requisito: pareamento e emissão já funcionando num caixa conforme o tutorial do SDK embarcado.

Quando usar

Por padrão cada caixa é pareado como um dispositivo, com sua própria série de dispositivo; é o modo independente, e os caixas não dependem uns dos outros. Quando a loja quer uma só série de dispositivo, com os números atribuídos num único ponto, use o modo principal e secundário. Regras de série do dispositivo e de numeração em Números e série.

Os três papéis

O papel vem da configuração ModoOperacao:

ModoValor de ModoOperacaoNúcleo localO que este caixa faz
IndependenteINDEPENDENTE (padrão)RodaRoda o núcleo e é pareado; um dispositivo e uma série de dispositivo para este caixa
PrincipalPRINCIPALRodaRoda o núcleo e é pareado; sua série de dispositivo é a da loja toda; também atende os secundários na rede local, porta padrão 8786, e emite e revoga os tokens dos terminais secundários
SecundárioSECUNDARIONão rodaSem pareamento e sem certificado; emissão, consulta, cancelamento, cupom, XML, situação e eventos vão ao principal pela rede local, com as mesmas assinaturas e resultados do modo independente, e série e números vêm do dispositivo principal

Passos de implantação

  1. Principal: escolha um caixa estável que fique sempre ligado, defina ModoOperacao como principal e faça Iniciar e o pareamento normalmente (veja Inicialização e pareamento). Pareamento, troca de certificado, backup, exportação de pendentes e exportação mensal de XML só acontecem no principal.
  2. Emita um token de terminal para cada secundário: no principal, chame CriarTerminal com o nome do caixa, por exemplo Caixa 2; o retorno traz o identificador do terminal e o token (começa com tfl_). O token completo vem só uma vez; configure-o na hora no secundário. O nome tem de 1 a 60 caracteres e não pode repetir entre terminais ativos.
  3. Secundário: defina ModoOperacao como secundário, EnderecoPrincipal com o endereço de rede local e a porta do principal, por exemplo 192.168.0.10:8786, e TokenTerminal com o token do passo anterior; depois faça Iniciar normalmente. O secundário não chama Ativar.
  4. O PDV chama o SDK como sempre: no secundário, emissão, consulta, cancelamento e os demais métodos têm as mesmas assinaturas e resultados do modo independente; série e números vêm do dispositivo principal.

Valores e códigos de erro da porta do principal (PortaPrincipal), das redes permitidas (RedesPermitidas), do endereço do principal e do token do terminal estão na configuração da Referência do SDK.

Exemplo de código

O código abaixo inicia o caixa 1 como principal e emite o token de terminal de Caixa 2; depois inicia o caixa 2 como secundário e emite uma nota:

java
// Caixa 1: principal. Pareie normalmente e emita um token de terminal por secundário
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");
// Caixa 2: secundário. Sem pareamento; a emissão é escrita como no modo independente
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"; série e número vêm do dispositivo principal

O que o secundário pode fazer

AlcanceMétodos
Disponíveis no secundárioAtivado, Empresas, InspecionarCodigoAtivacao, Emitir, Previsualizar, Consultar, ListarNotas, Cancelar, CancelarPorSubstituicao, Substituir, Cupom, QrCodePng, XmlAutorizado, XmlCancelamento, Situacao, SincronizarAgora e eventos
Só no principalAtivar, TrocarCertificado, Backup, RestaurarBackup, ExportarPendentes, ExportarXmls e a gestão de terminais CriarTerminal, ListarTerminais, RevogarTerminal

Chamar um método só do principal no secundário ou no modo independente devolve 10029884.

O nome do terminal é a identificação do caixa: as notas emitidas por um secundário levam o nome do terminal como identificação do caixa, gravada na nota e enviada à plataforma junto com ela. Terminal no resultado do SDK (Java getTerminal()) traz esse nome, veja Resultado da emissão; notas emitidas pelo próprio principal ou em modo independente não têm identificação do caixa, e o resultado do SDK traz null. O servidor do integrador também recebe essa identificação em Consultar NFC-e e nos webhooks, e assim sabe qual caixa emitiu a nota; a descrição da carga está em Como os resultados chegam.

Eventos: o secundário só recebe os eventos das notas que ele emitiu e os eventos do dispositivo, como licença, certificado, conexão e desativação; o principal continua recebendo todos. As regras de confirmação e reentrega não mudam, veja Receber os resultados.

Rede local e falhas

Rede local e segurança

  • O principal só aceita origens com endereço privado de rede local dentro das redes de RedesPermitidas, por padrão a rede /24 do principal; inclua a rede de qualquer secundário que esteja em outra. O Firewall do Windows precisa liberar a porta do principal (PortaPrincipal, padrão 8786); com a porta ocupada, Iniciar no principal devolve 10029887.
  • EnderecoPrincipal precisa ser endereço privado de rede local, senão 10029883.
  • Depois de 20 falhas de autenticação de uma origem em 1 minuto, ela é limitada com 10029886; tente de novo após 1 minuto.
  • O token só vai para o runtime em memória, nunca para disco ou log; se o PDV guardar o token, guarde-o criptografado.

Falha do principal e caixa reserva

  • O principal é ponto único de falha: desligado, fora da rede ou com o PDV fechado, as chamadas dos secundários devolvem 10029880 na hora e o pedido não chega ao principal. O secundário nunca assume sozinho nem copia os dados do principal. Mantenha o principal sempre ligado; recomenda-se nobreak.
  • Resultado desconhecido: se o pedido chegou ao principal mas a resposta não voltou, emissão, cancelamento, correção e cancelamento por substituição devolvem 10029881. Com o principal de volta, chame Consultar com o mesmo id; reenviar Emitir com o mesmo id e conteúdo não emite duas vezes.
  • O secundário inicia mesmo com o principal inacessível: Iniciar funciona com a lista de empresas pareadas vazia, e cada chamada seguinte conecta ao principal na hora.
  • Caixa reserva: pareie antes outro caixa em modo independente, como dispositivo próprio, com sua própria série de dispositivo. Quando o principal falhar, o PDV passa o caixa para a máquina reserva; quando o principal voltar, a série dele continua de onde parou, cada série contínua por si. A legislação só exige numeração contínua dentro de uma mesma série, então várias séries na mesma loja são igualmente regulares.

Gerenciar terminais secundários

Os três métodos de gestão de terminais só existem no principal:

  • Emitir: CriarTerminal recebe o nome do caixa; o nome é a identificação do caixa nas notas que esse secundário emite, então use um número de caixa que a loja reconheça, por exemplo Caixa 2. Devolve o identificador do terminal (começa com trm_), o nome e o token (começa com tfl_). O token completo aparece só uma vez, neste retorno, e o principal guarda só um resumo: configure-o na hora em TokenTerminal do secundário; se perder, revogue e emita outro.
  • Listar: ListarTerminais lista todos os terminais com nome, situação e último uso, do mais novo para o mais antigo, sem os tokens. Por padrão oculta os terminais revogados há mais de 30 dias; com todos em true lista todos.
  • Revogar: quando um secundário for perdido, desativado ou o token vazar, chame RevogarTerminal no principal, com efeito imediato: as chamadas seguintes desse secundário devolvem 10029882 e os eventos ainda não entregues a ele são descartados. A revogação não pode ser desfeita; emita outro token quando precisar.

Campos devolvidos em Terminal secundário.