TF Fiscal
Documentación

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:

text
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 eventos
Dí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:

http
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:

json
{ "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 ambiente se 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):

xml
<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:

text
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 empresaId de 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 con ExportarPendentes y 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 con InspecionarCodigoAtivacao y 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.

java
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 emparejamiento
System.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 cual
System.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íaCódigo de errorQué hacer
Reintentable10029824 (sin conexión con la plataforma), 10029833 (tiempo agotado)Pida revisar la red y reintente
Reintentable10029839 (emparejada en la plataforma pero falló el guardado local)Empareje de nuevo con el mismo código
Requiere otro código10029825, 10029205 a 10029209, 10029219, 10029221 a 10029225Pida al integrador un código de emparejamiento nuevo
Requiere otro certificado10029813, 10029814, 10029213, 10029214Use un certificado válido de la empresa
Falla al iniciar10029842 (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:

FormaCómo se configuraDescripción
DirectaNo configure ninguna opción de proxyForma por defecto
Proxy manualProxy con host:porta, por ejemplo 10.0.0.1:3128Con formato inválido devuelve 10029874
Proxy del sistemaUsarProxyDoSistema en trueLee 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, devuelve 10029874.
  • 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 caso Avisos de 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:

java
// Agregado a la cadena Configuracao.builder() de 2.1: salida por proxy manual que exige autenticación
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")
.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.

json
{
"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.

json
{
"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" }
}
}
]
}
CampoEnvíoDescripción
idObligatorioNú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
ambienteEmissaoObligatorioAmbiente de emisión. Igual al ambiente de emparejamiento del dispositivo
modoRespostaNo se envíaEl SDK siempre espera el resultado
pedido.presencaConsumidorObligatorioForma de presencia. En la tienda es OperacaoPresencial
pedido.pagamento.formasObligatorioDetalle del pago. tipo y valor de cada forma; la suma debe cubrir el total de la nota
pedido.pagamento.trocoOpcionalCambio. 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
clienteOpcionalConsumidor. 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 / valorUnitarioObligatorioDatos básicos del ítem
itens[].ean / cest / valorDescontoOpcionalCódigo de barras, CEST y descuento del ítem
itens[].impostos.icms.situacaoTributariaObligatorioCó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.aliquotaOpcionalAlícuota del ICMS. En porcentaje
itens[].impostos.pis / cofinsObligatorioCódigos de tributación de PIS / COFINS, por ejemplo 49 en el régimen simplificado y 07 en el régimen normal
itens[].classeImpostoOpcionalCó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.

java
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ática
return 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 nuevo
System.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 cual
System.out.println("Erro " + e.getCodigo() + " " + e.getTipo() + ": " + e.getMessage() + " " + e.getDetalhesJson());
return false;
}
}
}

3.3 Cada estado devuelto

StatusQué pasóPantalla de la caja
AutorizadaAutorizada en líneaImprima el cupón y cierre la venta
ContingenciaPendenteSin conexión con la plataforma; emitida offline en la computadoraImprima 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
AguardandoAutorizacaoAceptada por la plataforma; la SEFAZ aún no respondió y en ese momento no se podía firmar offlineNo 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
NegadaRechazada por la SEFAZMuestre el código y el mensaje de resultado de la SEFAZ, corrija y emita con un id nuevo
ExcepciónSolicitud 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:

FormatoSignificado
ESCPOS_80Comandos ESC/POS para impresora térmica de 80 mm
ESCPOS_58Comandos ESC/POS para impresora térmica de 58 mm
TEXTOTexto plano, UTF-8
HTMLPágina HTML, UTF-8, para vista previa en pantalla o impresión desde el navegador
PDF_80PDF 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.
java
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ámetroValoresPor defecto
ColunasCaracteres por línea. 48, 42 o 32Según el formato: 48 en 80 mm, 32 en 58 mm
PaginaCodigoPá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 acentoCP1252
ModoQrCodeCó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 nativoNATIVO
TamanhoModuloQrTamaño del módulo del código QR. De 1 a 16 puntos4
CortarCorte del papel al terminar. true corta, false no corta (impresora sin guillotina)true
ViasCantidad de copias. De 1 a 9Configurado 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).

java
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.

EventoQué hace el software de caja
NOTA_AUTORIZADAMarca la venta como autorizada; la nota en línea que esperaba autorización (AguardandoAutorizacao) se imprime ahora
NOTA_NEGADALa 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_REJEITADALa 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_PLATAFORMALa plataforma rechazó la nota offline; registre y contacte a la plataforma
CANCELAMENTO_CONCLUIDO / CANCELAMENTO_REJEITADOActualiza el resultado de la cancelación; si se rechazó, la nota sigue válida
NUMERO_INUTILIZACAO_RECUSADALa 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_DESATIVADOAviso destacado: «esta caja ya no puede emitir»
LICENCA_EXPIRANDO / PRAZO_TRANSMISSAO_PROXIMOPide restablecer la red cuanto antes
CERTIFICADO_EXPIRANDOPide 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:

java
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 nuevo
System.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úmero
System.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 solo
System.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 riesgo
break;
}
}
/** 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 cambiar
String 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:

  1. Emitir intenta 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 devuelve ContingenciaPendente. Si la última conexión acaba de fallar, emite offline directamente, sin esperar.
  2. 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.
  3. 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.
  4. Tras la autorización de la transmisión llega el evento NOTA_AUTORIZADA; si la SEFAZ rechaza la nota offline transmitida, llega NOTA_REJEITADA: corríjala con Substituir usando el mismo número; vea la sección 5.

Cuando no se puede emitir offline, Emitir lanza una excepción:

Código de errorSituaciónCómo se resuelve
10029804 / 10029807 / 10029810Licencia vencida / plazo offline vencido / la nota pendiente más antigua superó el plazo de transmisiónDesaparece sola al volver la red
10029808La serie del dispositivo llegó al número 999999999Desactive 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
10029811El estado o la empresa no permiten offlineSolo emisión en línea
10029812Nota con combustibleNo 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 SituacaoAviso 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
OfflineAtePedir conexión cuando el tiempo offline esté por acabarse
Avisos no vacíoEl 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

  1. En el ambiente de pruebas: emparejar, emitir en línea (Autorizada), emitir sin red (ContingenciaPendente) y recibir NOTA_AUTORIZADA tras volver la red.
  2. Reenviar el mismo id no emite otra nota; tras una caída y reinicio, Consultar recupera el resultado.
  3. Los eventos se deduplican por EventoId y el registro de deduplicación se guarda de forma persistente; NOTA_NEGADA (emitir de nuevo con un id nuevo) y NOTA_REJEITADA (corrección con el mismo número) se tratan por separado.
  4. 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.
  5. 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.
  6. La pantalla de la caja muestra el estado offline, las notas por transmitir y el plazo de transmisión.
  7. Hay avisos destacados para certificado por vencer y dispositivo desactivado.
  8. XmlAutorizado, XmlCancelamento, ExportarXmls, Backup, RestaurarBackup y ExportarPendentes se llaman en un hilo de fondo, sin congelar la interfaz; SincronizarAgora retorna de inmediato y puede llamarse directamente.
  9. Si la tienda sale a internet por proxy, el emparejamiento y la emisión se probaron en la red real.
  10. 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.
  11. 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.
  12. Si usa el modo principal y secundario, ensayó el principal fuera de servicio (el secundario devuelve 10029880 y la caja pasa a la caja de reserva) y la revocación de un secundario (que pasa a devolver 10029882).

Próximos pasos

Errores frecuentes y solución

Código de errorSituaciónSolución
10029801 / 10029802La empresa no está emparejada en esta computadora / hay varias empresas emparejadas y falta empresaIdEmpareje primero; informe empresaId
10029804 / 10029807Sin red y licencia vencida / plazo offline vencidoRestablezca la red; la licencia se renueva sola
10029808La serie del dispositivo llegó al número 999999999Desactive 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
10029809El reloj del sistema retrocedióCorrija la hora del sistema
10029810La nota pendiente más antigua superó el plazo de transmisiónRestablezca la red cuanto antes para transmitir
10029811 / 10029812Offline no permitido, o se acaba de restaurar la copia de seguridad y aún no hay licencia nueva / nota con combustibleSolo 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 / 10029814Certificado no disponible / vencidoRevise el certificado; tras renovarlo, TrocarCertificado
10029816Dispositivo desactivadoContacte al integrador
10029817Solicitud 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
10029780Un ítem referencia una clase de impuesto, pero no se pudo acceder a la plataforma para expandirla; no se consumió ningún númeroReenvíe con el mismo id cuando vuelva la red; sin red, envíe impostos en los ítems
10029818El mismo id ya se usó con otro contenidoUse un id nuevo para una venta nueva
10029819No hay venta con ese id en esta computadoraRevise id y empresaId
10029822El estado actual no permite cancelarSi 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
10029827El directorio de datos vino de otra computadora o de otro usuario de WindowsEjecute con el usuario original; al cambiar de computadora desactive el dispositivo anterior y empareje de nuevo
10029828El directorio de datos está en uso por otro procesoAbra una sola instancia; la copia de seguridad se restaura antes de Iniciar; si ya hay una instancia iniciada, primero llame Encerrar
10029832 / 10029833Caída del runtime / tiempo agotadoReintente con el mismo id
10029841XML autorizado no disponible por el momentoSi 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
10029842La base local es más nueva que el programaEl 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
10029843XML de cancelación no disponible por el momentoSi 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
10029844Falla al escribir el archivoDirectorio 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
10029845Clave de la nota sustituta inválidaInforme 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
10029846La copia de seguridad no se puede restaurarContraseñ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ó
10029874Pará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 rangoComplete o corrija los parámetros según Detalhes
10029877No se encuentra el runtimeRevise el directorio del runtime en el instalador
10029880 / 10029881El secundario no alcanza al principal / la solicitud se envió pero no volvió respuesta del principalReintente más tarde o pase a la caja de reserva; con resultado desconocido, llame Consultar con el mismo id cuando vuelva el principal
10029882Token del terminal secundario inválido o revocadoEmita otro token en el principal y actualice TokenTerminal
10029884El secundario llamó un método solo del principalHaga emparejamiento, cambio de certificado, copia de seguridad y exportación en el principal
10029307El ambiente del dispositivo difiere del ambiente actual de la empresaGenere 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.