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:
| Modo | Valor de ModoOperacao | Núcleo local | O que este caixa faz |
|---|---|---|---|
| Independente | INDEPENDENTE (padrão) | Roda | Roda o núcleo e é pareado; um dispositivo e uma série de dispositivo para este caixa |
| Principal | PRINCIPAL | Roda | Roda 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ário | SECUNDARIO | Não roda | Sem 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
- Principal: escolha um caixa estável que fique sempre ligado, defina
ModoOperacaocomo principal e façaIniciare 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. - Emita um token de terminal para cada secundário: no principal, chame
CriarTerminalcom o nome do caixa, por exemploCaixa 2; o retorno traz o identificador do terminal e o token (começa comtfl_). 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. - Secundário: defina
ModoOperacaocomo secundário,EnderecoPrincipalcom o endereço de rede local e a porta do principal, por exemplo192.168.0.10:8786, eTokenTerminalcom o token do passo anterior; depois façaIniciarnormalmente. O secundário não chamaAtivar. - 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:
// Caixa 1: principal. Pareie normalmente e emita um token de terminal por secundárioTfFiscalNfce 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 independenteTfFiscalNfce 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
| Alcance | Métodos |
|---|---|
| Disponíveis no secundário | Ativado, Empresas, InspecionarCodigoAtivacao, Emitir, Previsualizar, Consultar, ListarNotas, Cancelar, CancelarPorSubstituicao, Substituir, Cupom, QrCodePng, XmlAutorizado, XmlCancelamento, Situacao, SincronizarAgora e eventos |
| Só no principal | Ativar, 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,Iniciarno principal devolve10029887. EnderecoPrincipalprecisa ser endereço privado de rede local, senão10029883.- 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
10029880na 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, chameConsultarcom o mesmoid; reenviarEmitircom o mesmoide conteúdo não emite duas vezes. - O secundário inicia mesmo com o principal inacessível:
Iniciarfunciona 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 comtrm_), o nome e o token (começa comtfl_). O token completo aparece só uma vez, neste retorno, e o principal guarda só um resumo: configure-o na hora emTokenTerminaldo 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
todosemtruelista 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
10029882e 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.
