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:
| Modo | Valor de ModoOperacao | Núcleo local | Qué hace esta caja |
|---|---|---|---|
| Independiente | INDEPENDENTE (por defecto) | Corre | Corre el núcleo y se empareja; un dispositivo y una serie de dispositivo para esta caja |
| Principal | PRINCIPAL | Corre | Corre 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 |
| Secundario | SECUNDARIO | No corre | Sin 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
- Principal: elija una caja estable que quede siempre encendida, ponga
ModoOperacaoen principal y hagaIniciary 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. - Emita un token de terminal para cada secundario: en el principal, llame
CriarTerminalcon el nombre de la caja, por ejemploCaixa 2; devuelve el identificador del terminal y el token (empieza contfl_). 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. - Secundario: ponga
ModoOperacaoen secundario,EnderecoPrincipalcon la dirección de red local y el puerto del principal, por ejemplo192.168.0.10:8786, yTokenTerminalcon el token del paso anterior; luego hagaIniciarcomo siempre. El secundario no llamaAtivar. - 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:
// Caja 1: principal. Empareje como siempre y emita un token de terminal por secundarioTfFiscalNfce 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 independienteTfFiscalNfce 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
| Alcance | Métodos |
|---|---|
| Disponibles en el secundario | Ativado, Empresas, InspecionarCodigoAtivacao, Emitir, Previsualizar, Consultar, ListarNotas, Cancelar, CancelarPorSubstituicao, Substituir, Cupom, QrCodePng, XmlAutorizado, XmlCancelamento, Situacao, SincronizarAgora y eventos |
| Solo en el principal | Ativar, 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,Iniciaren el principal devuelve10029887. EnderecoPrincipaldebe ser una dirección privada de red local, si no10029883.- 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
10029880al 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, llameConsultarcon el mismoid; reenviarEmitircon el mismoidy contenido no emite dos veces. - El secundario inicia aunque el principal no esté accesible:
Iniciarfunciona 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 contrm_), el nombre y el token (empieza contfl_). El token completo aparece una sola vez, en este retorno, y el principal guarda solo un resumen: configúrelo en el momento enTokenTerminaldel 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
todosentruelista 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
10029882y 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.
