TF Fiscal
Documentación

NFC-e offline

Varias cajas (modo principal y secundario)

Varias cajas con el SDK embebido (modo principal y secundario): varias cajas de una tienda comparten una serie de dispositivo; roles, pasos de despliegue, código de ejemplo, métodos disponibles en el secundario, red local y fallos, y gestión de terminales secundarios.

Cuando una tienda tiene varias cajas y quiere una sola serie de dispositivo para todas, use el modo principal y secundario: una caja inicia como principal y las demás como secundarias; el principal asigna todos los números, así que las notas de todas las cajas tienen numeración continua y nunca chocan. Al terminar podrá desplegar el principal y los secundarios, gestionar los terminales secundarios y sabrá qué hacer cuando falle el principal. Requisitos: haber completado el emparejamiento y la emisión en una caja según el tutorial del SDK embebido.

Cuándo usarlo

Por defecto cada caja se empareja como un dispositivo, con su propia serie de dispositivo; es el modo independiente, y las cajas no dependen unas de otras. Cuando quiera una sola serie de dispositivo para toda la tienda, con los números tomados en un único lugar, use el modo principal y secundario. Las reglas de serie del dispositivo y numeración están en Números y serie.

Los tres roles

El rol lo define la opción ModoOperacao:

ModoValor de ModoOperacaoNúcleo localQué hace esta caja
IndependienteINDEPENDENTE (por defecto)CorreCorre el núcleo y se empareja; un dispositivo y una serie de dispositivo para esta caja
PrincipalPRINCIPALCorreCorre el núcleo y se empareja; su serie de dispositivo es la de toda la tienda; además atiende a los secundarios en la red local, puerto por defecto 8786, y emite y revoca los tokens de terminal
SecundarioSECUNDARIONo correSin emparejamiento ni certificado; emisión, consulta, cancelación, cupón, XML, estado y eventos van al principal por la red local, con las mismas firmas y resultados que el modo independiente; la serie y los números vienen del dispositivo principal

Pasos de despliegue

  1. Principal: elija una caja estable que quede siempre encendida, ponga ModoOperacao en principal y haga Iniciar y el emparejamiento como siempre (vea Inicialización y emparejamiento). Emparejamiento, cambio de certificado, copia de seguridad, exportación de pendientes y exportación mensual de XML solo se hacen en el principal.
  2. Emita un token de terminal para cada secundario: en el principal, llame CriarTerminal con el nombre de la caja, por ejemplo Caixa 2; devuelve el identificador del terminal y el token (empieza con tfl_). El token completo llega una sola vez; configúrelo en ese momento en el secundario. El nombre tiene de 1 a 60 caracteres y no se puede repetir entre terminales activos.
  3. Secundario: ponga ModoOperacao en secundario, EnderecoPrincipal con la dirección de red local y el puerto del principal, por ejemplo 192.168.0.10:8786, y TokenTerminal con el token del paso anterior; luego haga Iniciar como siempre. El secundario no llama Ativar.
  4. El PDV llama al SDK como siempre: en el secundario, emisión, consulta, cancelación y los demás métodos tienen las mismas firmas y resultados que el modo independiente; la serie y los números devueltos vienen del dispositivo principal.

Los valores y códigos de error del puerto del principal (PortaPrincipal), las redes permitidas (RedesPermitidas), la dirección del principal y el token del terminal están en la configuración de la Referencia del SDK.

Ejemplo de código

El código siguiente inicia la caja 1 como principal y emite el token de terminal para Caixa 2; luego inicia la caja 2 como secundario y emite una nota:

java
// Caja 1: principal. Empareje como siempre y emita un token de terminal por secundario
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");
// Caja 2: secundario. Sin emparejamiento; la emisión se escribe igual que en modo independiente
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() es "Caixa 2"; la serie y el número vienen del dispositivo principal

Qué puede hacer el secundario

AlcanceMétodos
Disponibles en el secundarioAtivado, Empresas, InspecionarCodigoAtivacao, Emitir, Previsualizar, Consultar, ListarNotas, Cancelar, CancelarPorSubstituicao, Substituir, Cupom, QrCodePng, XmlAutorizado, XmlCancelamento, Situacao, SincronizarAgora y eventos
Solo en el principalAtivar, TrocarCertificado, Backup, RestaurarBackup, ExportarPendentes, ExportarXmls y la gestión de terminales CriarTerminal, ListarTerminais, RevogarTerminal

Llamar un método solo del principal en el secundario o en modo independiente devuelve 10029884.

El nombre del terminal es la identificación de la caja: las notas emitidas por un secundario llevan el nombre del terminal como identificación de la caja, guardada en la nota y enviada a la plataforma junto con ella. Terminal en el resultado del SDK (Java getTerminal()) lleva ese nombre; vea Resultado de la emisión. Las notas emitidas por el propio principal o en modo independiente no tienen identificación de la caja: null en el resultado del SDK. El servidor del integrador también recibe esa identificación en Consultar NFC-e y en los webhooks, y así sabe qué caja emitió la nota; el contenido del payload está en Cómo llegan los resultados.

Eventos: el secundario solo recibe los eventos de las notas que emitió y los eventos del dispositivo, como licencia, certificado, conexión y desactivación; el principal sigue recibiendo todos. La confirmación y la reentrega no cambian; vea Recibir los resultados.

Red local y fallos

Red local y seguridad

  • El principal solo acepta orígenes con dirección privada de red local dentro de las redes de RedesPermitidas, por defecto la red /24 del principal; agregue la red de cualquier secundario que esté en otra. El Firewall de Windows debe permitir el puerto del principal (PortaPrincipal, por defecto 8786); si el puerto está ocupado, Iniciar en el principal devuelve 10029887.
  • EnderecoPrincipal debe ser una dirección privada de red local, si no 10029883.
  • Tras 20 fallos de autenticación de un origen en 1 minuto, el origen queda limitado con 10029886; reintente tras 1 minuto.
  • El token solo se entrega al runtime en memoria y nunca se escribe en disco ni en el log; si el PDV guarda el token, guárdelo cifrado.

Fallo del principal y caja de reserva

  • El principal es un punto único de falla: apagado, fuera de la red o con el PDV cerrado, las llamadas de los secundarios devuelven 10029880 al instante y la solicitud no llega al principal. El secundario nunca asume solo ni copia los datos del principal. Mantenga el principal siempre encendido; se recomienda un UPS.
  • Resultado desconocido: si la solicitud llegó al principal pero no volvió respuesta, emisión, cancelación, corrección y cancelación por sustitución devuelven 10029881. Cuando vuelva el principal, llame Consultar con el mismo id; reenviar Emitir con el mismo id y contenido no emite dos veces.
  • El secundario inicia aunque el principal no esté accesible: Iniciar funciona con la lista de empresas emparejadas vacía, y cada llamada siguiente se conecta al principal en el momento.
  • Caja de reserva: empareje antes otra caja en modo independiente, como dispositivo propio, con su propia serie de dispositivo. Cuando falle el principal, el PDV pasa la caja a la caja de reserva; cuando vuelva el principal, su serie sigue donde quedó, cada serie continua por sí sola. La normativa solo exige numeración continua dentro de una misma serie, así que varias series en la misma tienda son igualmente regulares.

Gestionar terminales secundarios

Los tres métodos de gestión de terminales solo están disponibles en el principal:

  • Emitir: CriarTerminal recibe el nombre de la caja; el nombre es la identificación de la caja en las notas que emite ese secundario, así que use un número de caja que la tienda reconozca, por ejemplo Caixa 2. Devuelve el identificador del terminal (empieza con trm_), el nombre y el token (empieza con tfl_). El token completo aparece una sola vez, en este retorno, y el principal guarda solo un resumen: configúrelo en el momento en TokenTerminal del secundario; si se pierde, revóquelo y emita otro.
  • Listar: ListarTerminais lista todos los terminales con nombre, estado y último uso, del más nuevo al más antiguo, sin los tokens. Por defecto oculta los terminales revocados hace más de 30 días; con todos en true lista todos.
  • Revocar: cuando un secundario se pierda, se retire o se filtre su token, llame RevogarTerminal en el principal, con efecto inmediato: las llamadas siguientes de ese secundario devuelven 10029882 y los eventos aún no entregados a él se descartan. La revocación no se puede deshacer; emita otro token cuando haga falta.

Campos devueltos en Terminal secundario.