NFC-e offline
Tutorial del SDK embebido
Inicio rápido del SDK embebido: generar el código de emparejamiento, incluir el SDK, inicialización y emparejamiento, emitir la primera nota, imprimir el cupón, recibir los resultados, qué pasa sin red y checklist antes de producción, con ejemplos completos en Java.
Esta página le guía para integrar el SDK embebido en el software de caja: con red el SDK toma un número de la serie del dispositivo, firma la nota y la autoriza en línea a través de la plataforma; sin red emite en la propia computadora la nota de contingencia offline, que se imprime en el momento y se transmite sola cuando vuelve la conexión. Al terminar podrá emparejar una caja, emitir e imprimir la primera nota y recibir los resultados de transmisión y de cancelación. Requisitos: poder llamar a la API abierta de la plataforma para generar el código de emparejamiento y un software de caja que corra en Windows; la solicitud de emisión es la misma de la API de emisión en la nube, y los ítems que referencian una clase de impuesto requieren conexión.
Usted solo trabaja con el SDK, que ejecuta el núcleo de emisión offline en segundo plano. El proceso completo de integración es este:
Preparación: generar código de emparejamiento, incluir el SDK, distribuir el runtime│▼Iniciar ──► ¿No emparejado? ──► Emparejar (solo la primera vez, con red)│▼Emitir ──► Tratar según el estado ──► Imprimir el cupón│└─ En segundo plano: sin red emite offline, con red transmite solo, los resultados llegan como eventosDía a día: cancelar y consultar, obtener el XML autorizado, cancelación por sustitución, exportación mensual de XML, copia de seguridad y recuperación de un equipo dañado
Cada paso trae la versión en Java. La descripción completa de métodos y tipos está en la Referencia del SDK; los términos serie del dispositivo, nota de contingencia offline y transmisión se explican en Números y serie.
1 Preparación
1.1 Generar el código de emparejamiento
Cada caja se empareja una vez; el integrador genera el código de emparejamiento llamando a la API de la plataforma. Este es el endpoint que genera el código de emparejamiento:
POST /openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacao
El cuerpo puede ir vacío; para dar nombre a la caja y limitar el emparejamiento al SDK, envíe:
{ "nomeDispositivo": "Caixa 01", "formaPermitida": "Sdk" }
La primera llamada habilita la emisión offline de la empresa; no hay una etapa de habilitación separada. Campos y errores en Generar código de emparejamiento. El codigoAtivacao de la respuesta (empieza con TFA1.) es el código de emparejamiento:
- El texto completo solo viene en esta respuesta; entréguelo enseguida al responsable de la caja en la tienda. Vale 72 horas y se usa una sola vez.
- Puede entregarse como texto o guardarse como archivo
.tfa(UTF-8, una sola línea, con el texto completo del código de emparejamiento). - Sin
ambientese usa el ambiente actual de la empresa; tras el emparejamiento el dispositivo queda fijo en ese ambiente.
El software de caja no necesita registro previo en la plataforma: al iniciar informa el nombre y la versión del software de caja y la plataforma lo reconoce sola.
1.2 Incluir el SDK
El SDK y el runtime se obtienen en la pestaña "Descargas" de la página "Emisión offline → Emisión offline" del menú lateral de la consola: basta con haber iniciado sesión, y la tabla muestra el tamaño y el SHA-256 de cada versión; verifique el SHA-256 después de descargar.
El SDK se ofrece como artefacto Maven com.tffiscal:tffiscal-nfce-sdk-java, compatible con Java 8 o superior. Así se declara la dependencia en el pom.xml (en version, la versión publicada):
<dependency><groupId>com.tffiscal</groupId><artifactId>tffiscal-nfce-sdk-java</artifactId><version>VERSAO_PUBLICADA</version></dependency>
Los ejemplos de esta página coinciden con los proyectos de ejemplo Java del paquete del SDK (cinco escenarios: inicio rápido, sin red y transmisión, manejo de eventos, cancelación, consulta y XML, archivos e impresión).
1.3 Distribuir el runtime con el instalador
El SDK inicia en segundo plano un subproceso de runtime que ejecuta el núcleo de emisión offline. Incluya el directorio tffiscal-runtime completo, tal cual, en el instalador del software de caja (unos 60 MB); la estructura del directorio es esta:
tffiscal-runtime/├── tffiscal-nfce.exe├── app/├── runtime/└── VERSION
Al iniciar, apunte el directorio del runtime hacia él; si no lo encuentra, devuelve 10029877. Distribuya el SDK y el runtime juntos, en la misma versión. Un software de caja Java en Java 21 o superior también puede usar el modo en proceso sin distribuir el runtime; vea la Referencia del SDK.
1.4 Directorio de datos
Un directorio de datos por caja, por ejemplo C:\ProgramData\MinhaLoja\TFFiscal:
- Antes de la transmisión, los archivos firmados de las notas offline solo existen aquí y son el único original legal. No lo borre al desinstalar ni al actualizar el software de caja.
- La clave del dispositivo se cifra para el usuario de Windows actual: ejecute siempre el software de caja con el mismo usuario de Windows; el directorio no se puede copiar a otra computadora ni a otro usuario (
10029827). - Solo un proceso a la vez puede abrirlo (
10029828). Si la misma computadora tiene dos sistemas de caja, use dos directorios, emparejados como dos dispositivos. - Un directorio puede emparejar varias empresas (varios CNPJ). Con una sola, el
empresaIdde los métodos puede omitirse; con varias es obligatorio. - El XML autorizado y el XML de cancelación se descargan aquí automáticamente tras la autorización o la cancelación; los días que se guardan los define la opción
RetencaoXmlDias(vea 2.2). Al vencer se borran solos y, si se vuelven a pedir, se descargan de nuevo por la red. - Haga copias periódicas con
Backup; si la computadora se daña antes de transmitir, exporte conExportarPendentesy entréguelo a la plataforma; vea Copia de seguridad y recuperación de un equipo dañado.
2 Inicialización y emparejamiento
Inicie el SDK una vez al arrancar el software de caja y use la misma instancia durante toda la ejecución; la primera vez en esta computadora también hay que emparejar una vez.
2.1 Inicialización y emparejamiento
Al iniciar es obligatorio informar el nombre y la versión del software de caja: con ellos la plataforma reconoce su software de caja y puede aplicar control por versión; si faltan, devuelve 10029874.
La primera vez en esta computadora Ativado es false; empareje con el código de emparejamiento y el certificado A1 de la empresa:
- Código de emparejamiento: el cajero pega el texto o elige el archivo
.tfa. Primero verifíquelo localmente conInspecionarCodigoAtivacaoy muestre ambiente y vencimiento para que el cajero confirme; no usa la red ni consume el código. - Certificado: elija un certificado que ya esté en el almacén de certificados de Windows (por la huella), o importe un archivo PFX con su contraseña. Tras importar el PFX la clave privada no es exportable y la contraseña no se guarda; el certificado queda en "Usuario actual > Personal" para uso permanente y, si se borra, el dispositivo no puede firmar. Desactivación y limpieza en Origen del certificado.
El código siguiente inicia el SDK, conecta el manejador de eventos y, si no está emparejado, verifica el código de emparejamiento y empareja. Si la tienda sale a internet por proxy o necesita ajustar los días de retención del XML, agregue en la misma configuración las opciones de 2.2.
import com.tffiscal.nfce.sdk.Certificado;import com.tffiscal.nfce.sdk.Configuracao;import com.tffiscal.nfce.sdk.EventoNfce;import com.tffiscal.nfce.sdk.Resultados;import com.tffiscal.nfce.sdk.TfFiscalException;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.io.IOException;import java.nio.charset.StandardCharsets;import java.nio.file.Files;import java.nio.file.Path;import java.nio.file.Paths;import java.util.function.Consumer;public final class NfceInicio {private NfceInicio() {}/** Inicia el SDK; el oyente se conecta al inicio, así no se pierden los eventos acumulados antes del inicio. */public static TfFiscalNfce iniciar(Consumer<EventoNfce> aoEvento) {Configuracao configuracao = 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").idioma("pt-BR").aoReceberEvento(aoEvento).build();return TfFiscalNfce.iniciar(configuracao);}/** Empareja si no está emparejado. codigoOuArquivo puede ser el texto del código de emparejamiento o la ruta de un archivo .tfa; con senhaPfx en null toma el certificado del almacén por la huella. */public static boolean ativarSeNecessario(TfFiscalNfce nfce, String codigoOuArquivo, String thumbprintOuPfx, String senhaPfx)throws IOException {if (nfce.isAtivado()) {return true;}Path arquivo = Paths.get(codigoOuArquivo);String codigo = Files.isRegularFile(arquivo)? new String(Files.readAllBytes(arquivo), StandardCharsets.UTF_8): codigoOuArquivo;codigo = codigo.replace("\uFEFF", "").trim();Certificado certificado = senhaPfx == null? Certificado.doRepositorio(thumbprintOuPfx, false): Certificado.deArquivoPfx(Files.readAllBytes(Paths.get(thumbprintOuPfx)), senhaPfx);try {Resultados.CodigoAtivacao info = nfce.inspecionarCodigoAtivacao(codigo);System.out.println("Codigo de pareamento: ambiente " + info.getAmbiente() + ", expira em " + info.getExpiraEm());Resultados.Ativacao a = nfce.ativar(codigo, certificado);System.out.println("Pareado: empresa " + a.getEmpresaId() + ", CNPJ " + a.getCnpj() + ", serie do dispositivo " + a.getSerieOffline());return true;} catch (TfFiscalException e) {int c = e.getCodigo();if (c == 10029824 || c == 10029833 || c == 10029839) {// Reintentable: revise la red y reintente con el mismo código de emparejamientoSystem.out.println("Tente de novo: " + e.getMessage());} else {// Necesita un código nuevo u otro certificado: getMessage() ya viene traducido según idioma y se puede mostrar tal cualSystem.out.println("Erro " + c + " " + e.getTipo() + ": " + e.getMessage());}return false;}}}
Si el emparejamiento o el inicio fallan, trátelo según el código de error:
| Categoría | Código de error | Qué hacer |
|---|---|---|
| Reintentable | 10029824 (sin conexión con la plataforma), 10029833 (tiempo agotado) | Pida revisar la red y reintente |
| Reintentable | 10029839 (emparejada en la plataforma pero falló el guardado local) | Empareje de nuevo con el mismo código |
| Requiere otro código | 10029825, 10029205 a 10029209, 10029219, 10029221 a 10029225 | Pida al integrador un código de emparejamiento nuevo |
| Requiere otro certificado | 10029813, 10029814, 10029213, 10029214 | Use un certificado válido de la empresa |
| Falla al iniciar | 10029842 (el directorio de datos ya lo usó una versión más nueva del SDK; la base local es más nueva que el programa y el inicio se rechaza) | Actualice el SDK y el runtime a una versión no inferior a la última usada; nunca borre el directorio de datos |
2.2 Proxy y días de retención del XML
Proxy de salida: configúrelo cuando la red de la tienda necesite un proxy para salir a internet; sin ninguna opción la conexión es directa. Hay tres formas:
| Forma | Cómo se configura | Descripción |
|---|---|---|
| Directa | No configure ninguna opción de proxy | Forma por defecto |
| Proxy manual | Proxy con host:porta, por ejemplo 10.0.0.1:3128 | Con formato inválido devuelve 10029874 |
| Proxy del sistema | UsarProxyDoSistema en true | Lee la configuración de proxy de Windows: primero la de la máquina y luego la del navegador del usuario de Windows actual; si también se informa Proxy, el proxy del sistema tiene prioridad |
- Autenticación del proxy: se configura con
proxyAutenticacao(usuario, senha); sirve tanto para el proxy manual como para el del sistema. La contraseña solo pasa en memoria al runtime al iniciar; no se graba en disco ni en los logs. Si el software de caja guarda la contraseña, guárdela cifrada. Si solo se configura la autenticación, sin dirección de proxy ni proxy del sistema, devuelve10029874. - Sin soporte para scripts de proxy automático: si Windows solo tiene configurado un script PAC de proxy automático, el SDK conecta en directo y registra una advertencia en el log. En esas redes use un proxy manual o configure un proxy fijo en Windows.
- El modo en proceso de Java requiere un parámetro de inicio: al acceder a la plataforma por HTTPS, la autenticación Basic del proxy exige que la JVM permita Basic en el túnel, y la JVM lee esa configuración una sola vez, la primera vez que usa su cliente HTTP integrado; cambiarla después no tiene efecto. Si usa el modo en proceso de Java (
EM_PROCESSO) con autenticación de proxy configurada, agregue a los parámetros de inicio de la JVM del software de caja-Djdk.http.auth.tunneling.disabledSchemes=(vacío después del signo igual). Al cargarse, el núcleo también la deja vacía lo antes posible, pero si el software de caja ya usó antes el cliente HTTP integrado de la JVM, o él mismo la configuró para deshabilitar Basic, vaciarla no surte efecto; en ese casoAvisosde Situacao muestra un aviso y la autenticación del proxy puede fallar. En el modo subproceso de Java lo resuelve el propio runtime y no hace falta ningún parámetro.
Días de retención del XML: RetencaoXmlDias es la cantidad de días que el XML autorizado y el XML de cancelación se guardan en esta computadora; acepta de 1 a 3650, por defecto 90 días; fuera de rango devuelve 10029874. Lo que supera el plazo se borra solo y, si se vuelve a pedir, se descarga de nuevo por la red (vea Obtener el XML). Para la exportación mensual al contador conviene que el período exportado quede dentro del plazo de retención; vea Exportación mensual de XML para el contador.
El ejemplo siguiente agrega a la configuración de 2.1 un proxy manual, la autenticación del proxy y una retención de XML de 180 días:
// Agregado a la cadena Configuracao.builder() de 2.1: salida por proxy manual que exige autenticaciónConfiguracao configuracao = 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").proxy("10.0.0.1:3128").proxyAutenticacao("caixa01", senhaProxy)// O use el proxy del sistema de Windows (tiene prioridad sobre proxy): .usarProxyDoSistema(true)// El XML autorizado y el de cancelación se guardan 180 días en esta computadora.retencaoXmlDias(180).aoReceberEvento(aoEvento).build();
3 Emitir la primera nota
3.1 Solicitud de emisión
El cuerpo es el mismo de Emitir NFC-e; la descripción de los campos, las reglas por estado y más escenarios están en esa página. En el SDK no se envía modoResposta. Las clases de impuesto requieren conexión: los ítems pueden referenciar una clase de impuesto con classeImposto, que la plataforma expande antes de emitir en el dispositivo; sin red o sin acceso a la plataforma, devuelve 10029780, con la indicación de enviar impostos, sin consumir número, vea Clases de impuesto y conexión. Los códigos de tributación deben coincidir con el régimen de la empresa: el régimen simplificado (Simples Nacional) usa el CSOSN de tres dígitos y el régimen normal usa el CST de dos dígitos. Las dos solicitudes de abajo son iguales a pedido-exemplo.json y pedido-exemplo-regime-normal.json del paquete del SDK.
Régimen simplificado: venta presencial en la tienda, consumidor no identificado, pago en efectivo.
{"id": "EXEMPLO-0001","ambienteEmissao": "Homologacao","pedido": {"presencaConsumidor": "OperacaoPresencial","pagamento": {"formas": [{ "tipo": "Dinheiro", "valor": 50.30 }]}},"itens": [{"cfop": "5102","codigo": "7891000100101","descricao": "ARROZ BRANCO TIPO 1 5KG","ncm": "10063021","quantidade": 2,"unidadeMedida": "UN","valorUnitario": 25.15,"impostos": {"icms": { "situacaoTributaria": "102" },"pis": { "situacaoTributaria": "49" },"cofins": { "situacaoTributaria": "49" }}}]}
Régimen normal: la misma venta, solo cambian los códigos de tributación.
{"id": "EXEMPLO-RN-0001","ambienteEmissao": "Homologacao","pedido": {"presencaConsumidor": "OperacaoPresencial","pagamento": {"formas": [{ "tipo": "Dinheiro", "valor": 50.30 }]}},"itens": [{"cfop": "5102","codigo": "7891000100101","descricao": "ARROZ BRANCO TIPO 1 5KG","ncm": "10063021","quantidade": 2,"unidadeMedida": "UN","valorUnitario": 25.15,"impostos": {"icms": { "situacaoTributaria": "00" },"pis": { "situacaoTributaria": "07" },"cofins": { "situacaoTributaria": "07" }}}]}
| Campo | Envío | Descripción |
|---|---|---|
id | Obligatorio | Número de la venta en la caja. Hasta 64 caracteres; es la clave de idempotencia: un id nuevo por venta y el mismo id al reintentar la misma venta |
ambienteEmissao | Obligatorio | Ambiente de emisión. Igual al ambiente de emparejamiento del dispositivo |
modoResposta | No se envía | El SDK siempre espera el resultado |
pedido.presencaConsumidor | Obligatorio | Forma de presencia. En la tienda es OperacaoPresencial |
pedido.pagamento.formas | Obligatorio | Detalle del pago. tipo y valor de cada forma; la suma debe cubrir el total de la nota |
pedido.pagamento.troco | Opcional | Cambio. Se informa cuando el pago en efectivo supera el total; la suma de los pagos menos el cambio debe ser igual al total de la nota |
cliente | Opcional | Consumidor. Si no se identifica, no se envía el grupo; si informa el CPF, solo tipoPessoa y cpfCnpj; por encima del límite de identificación del estado es obligatorio |
itens[].cfop / codigo / descricao / ncm / quantidade / unidadeMedida / valorUnitario | Obligatorio | Datos básicos del ítem |
itens[].ean / cest / valorDesconto | Opcional | Código de barras, CEST y descuento del ítem |
itens[].impostos.icms.situacaoTributaria | Obligatorio | Código de tributación del ICMS. En el régimen simplificado, por ejemplo 102; en el régimen normal, por ejemplo 00 |
itens[].impostos.icms.aliquota | Opcional | Alícuota del ICMS. En porcentaje |
itens[].impostos.pis / cofins | Obligatorio | Códigos de tributación de PIS / COFINS, por ejemplo 49 en el régimen simplificado y 07 en el régimen normal |
itens[].classeImposto | Opcional | Código de la clase de impuesto. Si se envía, cfop e impostos se pueden omitir; requiere conexión y, sin red, devuelve 10029780, en cuyo caso se envía impostos |
Todos los campos en Emitir NFC-e.
3.2 Armar la solicitud y emitir
El código siguiente lee la solicitud del archivo JSON de arriba, la emite con un id nuevo y decide según el estado devuelto si imprime. Su software de caja puede armar un JSON con la misma estructura de cualquier forma.
import com.tffiscal.nfce.sdk.ResultadoEmissao;import com.tffiscal.nfce.sdk.TfFiscalException;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.io.IOException;import java.nio.charset.StandardCharsets;import java.nio.file.Files;import java.nio.file.Paths;public final class NfceVenda {private NfceVenda() {}/** Lee el archivo de la solicitud y pone un id nuevo (un id nuevo por venta). */public static String lerPedido(String arquivo, String id) throws IOException {String json = new String(Files.readAllBytes(Paths.get(arquivo)), StandardCharsets.UTF_8);return json.replaceFirst("\"id\"\\s*:\\s*\"[^\"]*\"", "\"id\": \"" + id + "\"");}/** Emite y trata según el estado; devuelve si se puede imprimir el cupón. */public static boolean vender(TfFiscalNfce nfce, String pedidoJson) {try {ResultadoEmissao r = nfce.emitir(pedidoJson);System.out.println("Nota " + r.getId() + ": " + r.getStatus() + " | serie " + r.getSerie() + " n. "+ r.getNumero() + " | chave " + r.getChave() + " | protocolo " + r.getProtocolo());switch (r.getStatus()) {case "Autorizada":case "ContingenciaPendente":// La nota emitida offline se imprime y se entrega al consumidor como siempre; la transmisión es automáticareturn true;case "AguardandoAutorizacao":// Aceptada en línea pero sin respuesta de la SEFAZ: no imprima aún, espere el evento NOTA_AUTORIZADA (autorizada) o NOTA_NEGADA (denegada)return false;default:// Negada: corrija según el resultado de la SEFAZ y emita de nuevo con un id nuevoSystem.out.println("Rejeitada: " + r.getCStat() + " " + r.getXMotivo());return false;}} catch (TfFiscalException e) {// Solicitud inválida, condiciones offline no cumplidas, etc.: getMessage() ya viene traducido y se puede mostrar tal cualSystem.out.println("Erro " + e.getCodigo() + " " + e.getTipo() + ": " + e.getMessage() + " " + e.getDetalhesJson());return false;}}}
3.3 Cada estado devuelto
Status | Qué pasó | Pantalla de la caja |
|---|---|---|
Autorizada | Autorizada en línea | Imprima el cupón y cierre la venta |
ContingenciaPendente | Sin conexión con la plataforma; emitida offline en la computadora | Imprima y entregue al consumidor como siempre; el cupón ya lleva la marca de contingencia offline; puede mostrar «Emisión offline» en un rincón de la pantalla |
AguardandoAutorizacao | Aceptada por la plataforma; la SEFAZ aún no respondió y en ese momento no se podía firmar offline | No imprima aún, muestre «Esperando autorización»; imprima al recibir el evento NOTA_AUTORIZADA. Si llega NOTA_NEGADA, la SEFAZ la rechazó en forma definitiva: esta nota no admite corrección con el mismo número; corrija los datos de la venta y emita de nuevo con un id nuevo |
Negada | Rechazada por la SEFAZ | Muestre el código y el mensaje de resultado de la SEFAZ, corrija y emita con un id nuevo |
| Excepción | Solicitud inválida, condiciones offline no cumplidas, etc. | Muestre el mensaje de la excepción; vea Errores frecuentes |
Llamar Emitir otra vez con el mismo id no emite otra nota: devuelve la nota original. Tras un tiempo agotado o una caída del programa, reenvíe con el mismo id para recuperar el resultado.
4 Imprimir el cupón
4.1 Imprimir el cupón
Cupom(id, formato) devuelve los bytes del cupón; envíelos tal cual a la impresora. La nota offline ya viene con la marca de contingencia y la cantidad de copias la configura la plataforma. Valores de formato:
| Formato | Significado |
|---|---|
ESCPOS_80 | Comandos ESC/POS para impresora térmica de 80 mm |
ESCPOS_58 | Comandos ESC/POS para impresora térmica de 58 mm |
TEXTO | Texto plano, UTF-8 |
HTML | Página HTML, UTF-8, para vista previa en pantalla o impresión desde el navegador |
PDF_80 | PDF de 80 mm de ancho, una página por copia, impreso por el driver de impresión de Windows; para impresoras sin conexión directa ESC/POS; vea 4.2 |
El código siguiente obtiene el cupón ESC/POS y lo envía a la impresora:
- El ejemplo envía los bytes al puerto 9100 de una impresora térmica de red.
- Una impresora USB puede compartirse en Windows y recibir los bytes por la ruta compartida; una impresora serie puede recibir los mismos bytes con una biblioteca de puerto serie.
import com.tffiscal.nfce.sdk.FormatoCupom;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.io.IOException;import java.io.OutputStream;import java.net.Socket;public final class NfceImpressao {private NfceImpressao() {}/** Envía el cupón ESC/POS a la impresora de red. */public static void imprimir(TfFiscalNfce nfce, String id, String ipImpressora) throws IOException {byte[] cupom = nfce.cupom(id, FormatoCupom.ESCPOS_80);try (Socket socket = new Socket(ipImpressora, 9100); OutputStream saida = socket.getOutputStream()) {saida.write(cupom);}}}
4.2 Cupón PDF, parámetros de impresión e imagen del código QR
Cupón PDF: cuando la impresora solo tiene driver de Windows y no acepta comandos ESC/POS directos, pida con PDF_80 el PDF de 80 mm y entréguelo al programa de PDF asociado del sistema para imprimir por el driver. El PDF usa las fuentes estándar del lector, y los acentos del portugués se ven correctamente.
Parámetros de impresión: para adaptar un mismo formato a impresoras distintas, use la sobrecarga con parámetros de impresión cupom(id, formato, OpcoesCupom, empresaId). Las opciones no informadas usan el valor por defecto; fuera de rango devuelve 10029874.
| Parámetro | Valores | Por defecto |
|---|---|---|
Colunas | Caracteres por línea. 48, 42 o 32 | Según el formato: 48 en 80 mm, 32 en 58 mm |
PaginaCodigo | Página de códigos de la impresora. CP1252, CP860 (común en impresoras en portugués), CP850 o CP437; los caracteres que no existen en la página de códigos se imprimen sin acento | CP1252 |
ModoQrCode | Cómo se imprime el código QR. NATIVO: con el comando de QR propio de la impresora; IMAGEM: como mapa de bits, para impresoras sin QR nativo | NATIVO |
TamanhoModuloQr | Tamaño del módulo del código QR. De 1 a 16 puntos | 4 |
Cortar | Corte del papel al terminar. true corta, false no corta (impresora sin guillotina) | true |
Vias | Cantidad de copias. De 1 a 9 | Configurado por la plataforma |
Imagen del código QR: QrCodePng(id, píxeles) devuelve un PNG en blanco y negro con margen; píxeles de 64 a 2048, indicados explícitamente; fuera de rango devuelve 10029817. Úselo cuando el software de caja arma su propio comprobante (por ejemplo un recibo A4).
El código siguiente coincide con el escenario 05 de los proyectos de ejemplo: guarda en archivos el cupón PDF y la imagen del código QR y los envía a la impresora predeterminada; luego pide el cupón ESC/POS con los parámetros de una impresora de 58 mm (32 columnas, CP850, QR como mapa de bits, módulo de 6 puntos, dos copias, sin corte).
import com.tffiscal.nfce.sdk.FormatoCupom;import com.tffiscal.nfce.sdk.OpcoesCupom;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.awt.Desktop;import java.io.IOException;import java.nio.file.Files;import java.nio.file.Path;public final class NfceImpressaoArquivos {private NfceImpressaoArquivos() {}/** Guarda en archivos el cupón PDF de 80 mm y el PNG del código QR, y los envía a la impresora predeterminada. */public static void pdfEQrCode(TfFiscalNfce nfce, String id, Path pasta) throws IOException {Path pdf = pasta.resolve(id + ".pdf");Files.write(pdf, nfce.cupom(id, FormatoCupom.PDF_80, null, null));Path png = pasta.resolve(id + "-qrcode.png");Files.write(png, nfce.qrCodePng(id, 300, null));// El programa de PDF asociado del sistema imprime el PDF en la impresora predeterminada (por el driver)if (Desktop.isDesktopSupported() && Desktop.getDesktop().isSupported(Desktop.Action.PRINT)) {Desktop.getDesktop().print(pdf.toFile());}}/** Impresora de 58 mm: 32 columnas, CP850, QR como mapa de bits, módulo de 6 puntos, dos copias, sin corte. */public static byte[] cupom58mm(TfFiscalNfce nfce, String id) {OpcoesCupom opcoes = new OpcoesCupom().colunas(32).paginaCodigo("CP850").modoQrCode(OpcoesCupom.ModoQrCode.IMAGEM).tamanhoModuloQr(6).vias(2).cortar(false);return nfce.cupom(id, FormatoCupom.ESCPOS_58, opcoes, null);}}
5 Recibir los resultados
Los resultados de transmisión y de cancelación, la desactivación del dispositivo y los avisos de licencia y certificado llegan al software de caja como eventos. Los eventos se entregan al menos una vez y en orden: cuando el manejador vuelve normalmente queda confirmado; si lanza una excepción, se reenvía a los 30 segundos aproximadamente. Deduplique por EventoId (el ejemplo usa una colección en memoria; en producción guárdelo en la base de datos del software de caja). El servidor del integrador también puede recibir los resultados por webhook; vea Cómo llegan los resultados.
| Evento | Qué hace el software de caja |
|---|---|
NOTA_AUTORIZADA | Marca la venta como autorizada; la nota en línea que esperaba autorización (AguardandoAutorizacao) se imprime ahora |
NOTA_NEGADA | La SEFAZ rechazó después una nota aceptada en línea que esperaba autorización. Marca la venta como denegada y avisa al cajero; esta nota no admite corrección con el mismo número: corrija los datos de la venta y emita de nuevo con un id nuevo |
NOTA_REJEITADA | La SEFAZ rechazó la nota offline transmitida. Avisa al responsable y corrige con Substituir usando el mismo número; no se emite otra nota |
NOTA_RECUSADA_PLATAFORMA | La plataforma rechazó la nota offline; registre y contacte a la plataforma |
CANCELAMENTO_CONCLUIDO / CANCELAMENTO_REJEITADO | Actualiza el resultado de la cancelación; si se rechazó, la nota sigue válida |
NUMERO_INUTILIZACAO_RECUSADA | La plataforma rechazó la inutilización de números no usados. Con definitivo en false el núcleo reintenta solo; basta registrar. Con true es un estado final (rango de números inválido o con notas ya emitidas en el rango): revise ese rango manualmente con el integrador |
DISPOSITIVO_DESATIVADO | Aviso destacado: «esta caja ya no puede emitir» |
LICENCA_EXPIRANDO / PRAZO_TRANSMISSAO_PROXIMO | Pide restablecer la red cuanto antes |
CERTIFICADO_EXPIRANDO | Pide renovar el certificado y, tras renovarlo, llamar TrocarCertificado |
Todos los eventos y sus campos en la Referencia del SDK.
El hilo en que llegan los eventos: en modo subproceso, llamadas en serie en un hilo de fondo dedicado del wrapper; en modo en proceso, llamada síncrona en el hilo de entrega del núcleo. En interfaces Swing vuelva al hilo de la interfaz con SwingUtilities.invokeLater.
En el manejador solo registre, no llame métodos del SDK: ponga en una cola las ventas que necesiten tratamiento posterior (por ejemplo el id de una nota rechazada en la transmisión) y deje que el flujo principal del software de caja las saque y las trate.
El código siguiente deduplica por EventoId, trata cada tipo de evento y pone en una cola las notas rechazadas en la transmisión para que el flujo principal las corrija con Substituir usando el mismo número:
import com.tffiscal.nfce.sdk.EventoNfce;import com.tffiscal.nfce.sdk.ResultadoEmissao;import com.tffiscal.nfce.sdk.SituacaoNota;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.util.Map;import java.util.Queue;import java.util.Set;import java.util.concurrent.ConcurrentHashMap;import java.util.concurrent.ConcurrentLinkedQueue;public final class NfceEventos {private final Set<String> vistos = ConcurrentHashMap.newKeySet();private final Queue<String> rejeitadas = new ConcurrentLinkedQueue<>();/** Oyente de eventos: se pasa a Configuracao.Builder.aoReceberEvento. Volver normalmente confirma; lanzar una excepción provoca el reenvío. */public void aoReceber(EventoNfce e) {// Entrega al menos una vez: el mismo evento puede llegar varias veces; deduplique por eventoId (en producción guarde los eventoId tratados en la base de datos)if (!vistos.add(e.getEventoId())) {return;}Map<String, Object> d = e.getDados();switch (e.getTipo()) {case "NOTA_AUTORIZADA":System.out.println("Nota " + e.getId() + " autorizada, protocolo " + d.get("protocolo")+ (Boolean.TRUE.equals(d.get("aposCorrecao")) ? " (apos correcao)" : ""));break;case "NOTA_NEGADA":// La SEFAZ rechazó después una nota en línea que esperaba autorización: no admite corrección con el mismo número; corrija los datos de la venta y emita de nuevo con un id nuevoSystem.out.println("Nota " + e.getId() + " negada pela SEFAZ: " + d.get("cStat") + " " + d.get("motivo")+ " - corrija a venda e emita de novo com um novo id");break;case "NOTA_REJEITADA":// Nota offline rechazada en la transmisión: a la cola, para que el flujo principal la corrija con substituir usando el mismo númeroSystem.out.println("Nota " + e.getId() + " rejeitada pela SEFAZ: " + d.get("cStat") + " " + d.get("motivo"));rejeitadas.add(e.getId());break;case "NOTA_RECUSADA_PLATAFORMA":System.out.println("Nota " + e.getId() + " recusada pela plataforma: " + d.get("codigo") + " " + d.get("mensagem"));break;case "CANCELAMENTO_CONCLUIDO":case "CANCELAMENTO_REJEITADO":System.out.println("Cancelamento da nota " + e.getId() + ": " + e.getTipo() + " " + d.get("cStat") + " " + d.get("motivo"));break;case "NUMERO_INUTILIZACAO_RECUSADA":// definitivo=true: rango inválido o con notas ya emitidas, requiere revisión manual; false: el núcleo reintenta soloSystem.out.println("Inutilizacao recusada: serie " + d.get("serie") + " " + d.get("inicio") + "-" + d.get("fim")+ ": " + d.get("mensagem") + (Boolean.TRUE.equals(d.get("definitivo")) ? " - verificar manualmente" : ""));break;case "DISPOSITIVO_DESATIVADO":System.out.println("Este caixa nao emite mais: " + d.get("situacao") + " " + d.get("motivo"));break;case "LICENCA_EXPIRANDO":case "PRAZO_TRANSMISSAO_PROXIMO":System.out.println("Restabeleca a internet o quanto antes");break;case "CERTIFICADO_EXPIRANDO":System.out.println("Certificado A1 valido ate " + d.get("validoAte") + "; troque com trocarCertificado");break;default:// Los tipos de evento nuevos se pueden ignorar sin riesgobreak;}}/** Lo llama periódicamente el flujo principal: corrige con el mismo número las notas rechazadas en la transmisión. */public void corrigirRejeitadas(TfFiscalNfce nfce) {String id;while ((id = rejeitadas.poll()) != null) {SituacaoNota original = nfce.consultar(id);// Según cStat / motivo de NOTA_REJEITADA corrija los campos que no son de valores (como NCM y CFOP); valores e impuestos no pueden cambiarString corrigido = original.getPedido();ResultadoEmissao r = nfce.substituir(id, corrigido, null);System.out.println("Substituir " + r.getId() + ": " + r.getStatus() + ", numero " + r.getNumero() + " (mesmo numero)");}}}
La corrección con el mismo número solo puede cambiar lo que no afecta valores ni impuestos (por ejemplo NCM o CFOP del producto, documento del consumidor); el número, la clave de acceso y la fecha de emisión no cambian; si cambian valores o impuestos devuelve 10029821. Cuando la nota corregida se autoriza en la nueva transmisión, el NOTA_AUTORIZADA recibido trae aposCorrecao en true.
6 Qué pasa sin red
Sin red el cajero emite como siempre; el software de caja no necesita ramas adicionales. Las reglas de la transmisión en sí (estado pendiente de transmisión, transmisión automática, corrección con el mismo número tras un rechazo, plazo de transmisión, qué notas no se emiten offline) están en Notas offline y transmisión; aquí solo se describe el comportamiento del lado del SDK:
Emitirintenta primero en línea; si se agota la espera o no hay conexión con la plataforma, emite la nota de contingencia offline en la computadora y devuelveContingenciaPendente. Si la última conexión acaba de fallar, emite offline directamente, sin esperar.- El cupón se imprime como siempre, con la marca de contingencia offline y el aviso «pendiente de autorización», sin número de protocolo.
- Al volver la red, el núcleo transmite solo, sin ninguna llamada; para transmitir de inmediato llame
SincronizarAgora, por ejemplo al detectar que la red volvió; solo dispara la siguiente ronda de sincronización en segundo plano y retorna de inmediato, así que puede llamarse en el hilo de la interfaz. - Tras la autorización de la transmisión llega el evento
NOTA_AUTORIZADA; si la SEFAZ rechaza la nota offline transmitida, llegaNOTA_REJEITADA: corríjala conSubstituirusando el mismo número; vea la sección 5.
Cuando no se puede emitir offline, Emitir lanza una excepción:
| Código de error | Situación | Cómo se resuelve |
|---|---|---|
10029804 / 10029807 / 10029810 | Licencia vencida / plazo offline vencido / la nota pendiente más antigua superó el plazo de transmisión | Desaparece sola al volver la red |
10029808 | La serie del dispositivo llegó al número 999999999 | Desactive el dispositivo y emparéjelo de nuevo con un código de emparejamiento nuevo que indique otra serie en serie; la plataforma no cambia la serie por sí sola |
10029811 | El estado o la empresa no permiten offline | Solo emisión en línea |
10029812 | Nota con combustible | No se emite offline; solo emisión en línea |
Se recomienda que la pantalla de la caja lea Situacao periódicamente (por ejemplo cada 10 segundos) para avisar al cajero:
Campo de Situacao | Aviso en pantalla |
|---|---|
Conectado en false | «Sin conexión; las notas se transmitirán al volver la red» |
PendentesTransmissao | «N notas por transmitir» |
PrazoTransmissaoAte | «Restablezca la red antes de tal hora», destacado cuando se acerque |
OfflineAte | Pedir conexión cuando el tiempo offline esté por acabarse |
Avisos no vacío | El entorno de ejecución requiere ajustes de un técnico; registre el texto original en el log o muéstrelo al soporte técnico |
7 Checklist antes de producción
- En el ambiente de pruebas: emparejar, emitir en línea (
Autorizada), emitir sin red (ContingenciaPendente) y recibirNOTA_AUTORIZADAtras volver la red. - Reenviar el mismo
idno emite otra nota; tras una caída y reinicio,Consultarrecupera el resultado. - Los eventos se deduplican por
EventoIdy el registro de deduplicación se guarda de forma persistente;NOTA_NEGADA(emitir de nuevo con unidnuevo) yNOTA_REJEITADA(corrección con el mismo número) se tratan por separado. - El cupón sale legible en la impresora real de la tienda y el QR se puede escanear; las impresoras sin conexión directa ESC/POS se probaron con
PDF_80. - El instalador incluye el directorio del runtime; actualizar y desinstalar no borran el directorio de datos; el software de caja corre siempre con el mismo usuario de Windows.
- La pantalla de la caja muestra el estado offline, las notas por transmitir y el plazo de transmisión.
- Hay avisos destacados para certificado por vencer y dispositivo desactivado.
XmlAutorizado,XmlCancelamento,ExportarXmls,Backup,RestaurarBackupyExportarPendentesse llaman en un hilo de fondo, sin congelar la interfaz;SincronizarAgoraretorna de inmediato y puede llamarse directamente.- Si la tienda sale a internet por proxy, el emparejamiento y la emisión se probaron en la red real.
- Hay copias de seguridad cifradas periódicas, con la contraseña guardada separada del archivo de copia de seguridad y sin escribirla en el programa; se practicó restaurar la copia de seguridad antes de
Iniciar; el personal de la tienda sabe cómo exportar el paquete de pendientes y entregarlo a la plataforma si la computadora se daña; vea Copia de seguridad y recuperación de un equipo dañado. - Cuando la empresa pase al ambiente de producción, genere códigos de emparejamiento en producción, empareje dispositivos nuevos y desactive los dispositivos de pruebas.
- Si usa el modo principal y secundario, ensayó el principal fuera de servicio (el secundario devuelve
10029880y la caja pasa a la caja de reserva) y la revocación de un secundario (que pasa a devolver10029882).
Próximos pasos
- Operación y tareas avanzadas: cancelación, cancelación por sustitución, consulta y reimpresión del cupón, obtención y exportación mensual de XML, copia de seguridad y recuperación de un equipo dañado, cierre y reinicio.
- Varias cajas (modo principal y secundario): varias cajas de una misma tienda comparten una serie de dispositivo.
- Referencia del SDK: configuración, cada método, tipos de datos, eventos y códigos de error.
Errores frecuentes y solución
| Código de error | Situación | Solución |
|---|---|---|
| 10029801 / 10029802 | La empresa no está emparejada en esta computadora / hay varias empresas emparejadas y falta empresaId | Empareje primero; informe empresaId |
| 10029804 / 10029807 | Sin red y licencia vencida / plazo offline vencido | Restablezca la red; la licencia se renueva sola |
| 10029808 | La serie del dispositivo llegó al número 999999999 | Desactive el dispositivo y emparéjelo de nuevo con un código de emparejamiento nuevo que indique otra serie en serie; la plataforma no cambia la serie por sí sola |
| 10029809 | El reloj del sistema retrocedió | Corrija la hora del sistema |
| 10029810 | La nota pendiente más antigua superó el plazo de transmisión | Restablezca la red cuanto antes para transmitir |
| 10029811 / 10029812 | Offline no permitido, o se acaba de restaurar la copia de seguridad y aún no hay licencia nueva / nota con combustible | Solo emisión en línea; tras una restauración reciente, la emisión offline vuelve sola después de una sincronización en línea |
| 10029813 / 10029814 | Certificado no disponible / vencido | Revise el certificado; tras renovarlo, TrocarCertificado |
| 10029816 | Dispositivo desactivado | Contacte al integrador |
| 10029817 | Solicitud inválida: campo obligatorio ausente, valor inválido o campo que no existe en el contrato (cada uno con la ruta del campo) | Corrija según Detalhes; puede validar antes con Previsualizar |
| 10029780 | Un ítem referencia una clase de impuesto, pero no se pudo acceder a la plataforma para expandirla; no se consumió ningún número | Reenvíe con el mismo id cuando vuelva la red; sin red, envíe impostos en los ítems |
| 10029818 | El mismo id ya se usó con otro contenido | Use un id nuevo para una venta nueva |
| 10029819 | No hay venta con ese id en esta computadora | Revise id y empresaId |
| 10029822 | El estado actual no permite cancelar | Si ya está cancelada o ya hay una cancelación en curso, no reintente; en la cancelación por sustitución la nota original debe ser una nota normal emitida en línea |
| 10029827 | El directorio de datos vino de otra computadora o de otro usuario de Windows | Ejecute con el usuario original; al cambiar de computadora desactive el dispositivo anterior y empareje de nuevo |
| 10029828 | El directorio de datos está en uso por otro proceso | Abra una sola instancia; la copia de seguridad se restaura antes de Iniciar; si ya hay una instancia iniciada, primero llame Encerrar |
| 10029832 / 10029833 | Caída del runtime / tiempo agotado | Reintente con el mismo id |
| 10029841 | XML autorizado no disponible por el momento | Si aún no se autorizó, espere NOTA_AUTORIZADA; si ya está autorizada y el error sigue, la plataforma no la archivó o no está accesible por el momento; reintente más tarde |
| 10029842 | La base local es más nueva que el programa | El directorio de datos lo usó una versión más nueva del SDK y el inicio se rechaza: actualice el SDK y el runtime a una versión no inferior a la última usada; nunca borre el directorio de datos |
| 10029843 | XML de cancelación no disponible por el momento | Si la cancelación aún no concluyó, espere CANCELAMENTO_CONCLUIDO; si ya está cancelada y el error sigue, la plataforma no lo archivó o no está accesible por el momento; reintente más tarde |
| 10029844 | Falla al escribir el archivo | Directorio de exportación o de copia sin permiso de escritura, o el archivo de copia ya existe: cambie de directorio o de nombre y revise el espacio en disco y los permisos |
| 10029845 | Clave de la nota sustituta inválida | Informe la clave de 44 dígitos de una nota sustituta offline emitida en esta computadora, con el mismo CNPJ y no rechazada por la plataforma |
| 10029846 | La copia de seguridad no se puede restaurar | Contraseña incorrecta, o el archivo de copia de seguridad fue modificado o está dañado: verifique la contraseña y use otra copia de seguridad íntegra; la base original no se modificó |
| 10029874 | Parámetro inválido, por ejemplo falta el nombre o la versión del software de caja al iniciar, formato de proxy inválido, o parámetros de impresión o fechas de exportación fuera de rango | Complete o corrija los parámetros según Detalhes |
| 10029877 | No se encuentra el runtime | Revise el directorio del runtime en el instalador |
| 10029880 / 10029881 | El secundario no alcanza al principal / la solicitud se envió pero no volvió respuesta del principal | Reintente más tarde o pase a la caja de reserva; con resultado desconocido, llame Consultar con el mismo id cuando vuelva el principal |
| 10029882 | Token del terminal secundario inválido o revocado | Emita otro token en el principal y actualice TokenTerminal |
| 10029884 | El secundario llamó un método solo del principal | Haga emparejamiento, cambio de certificado, copia de seguridad y exportación en el principal |
| 10029307 | El ambiente del dispositivo difiere del ambiente actual de la empresa | Genere un código de emparejamiento en el ambiente actual y empareje un dispositivo nuevo |
Todos los códigos y su solución en la Referencia del SDK y en Códigos de error.
¿Por qué sin red la emisión tarda un poco?
El núcleo intenta primero en línea y solo emite offline cuando se agota la espera; el resultado trae TentativaOnline en true; esta nota offline usa el número siguiente, y la plataforma resuelve el número del intento en línea sin que usted tenga que hacer nada. Si la última conexión acaba de fallar, emite offline directamente, sin esperar.
¿Cómo probar la emisión offline?
Empareje una computadora de pruebas en el ambiente de pruebas, desconecte la red de esa computadora y emita; las notas del ambiente de pruebas no tienen valor fiscal.
¿Qué hacer al cambiar la computadora de la caja?
Deje que la computadora anterior se conecte y transmita todas las notas offline, desactive el dispositivo anterior y empareje la computadora nueva con un código de emparejamiento nuevo. No copie el directorio de datos.
¿Qué hacer si la computadora anterior se dañó con notas offline aún sin transmitir?
Si la computadora todavía enciende, exporte las notas pendientes con ExportarPendentes, comprima en un solo zip todo el subdirectorio pendentes-… de esta exportación y entréguelo al equipo de operación de la plataforma, que lo sube directamente en «Importar paquete de pendientes» (la exportación ya viene con un directorio por dispositivo y hasta 500 notas por paquete: no hace falta descomprimirla ni dividirla); luego desactive el dispositivo anterior y empareje la computadora nueva; vea la vía 1 de Copia de seguridad y recuperación de un equipo dañado. La copia de seguridad cifrada solo se restaura en la computadora original y no sirve para cambiar de computadora. Si la computadora ya no enciende, contacte a la plataforma.
¿Qué diferencia hay entre una nota en línea rechazada (NOTA_NEGADA) y una nota offline rechazada en la transmisión (NOTA_REJEITADA)?
La nota en línea rechazada no se puede corregir: corrija los datos de la venta y emita de nuevo con un id nuevo. La nota offline ya se imprimió y se entregó al consumidor; si se rechaza en la transmisión, corríjala con Substituir usando el mismo número, sin cambiar el número ni la clave de acceso.
