TF Fiscal
Documentación

NFC-e offline

Referencia del SDK

Manual de consulta del SDK embebido de NFC-e offline: configuración, firma y errores de cada método, tipos de datos, eventos y códigos de error.

Manual de consulta del SDK embebido, dividido en configuración, métodos, tipos de datos, eventos, solicitud de emisión y códigos de error; cada sección se puede consultar por separado. Los nombres de los métodos están en portugués; los títulos y el texto de esta página usan la inicial mayúscula (por ejemplo Emitir) y el código Java, la inicial minúscula (por ejemplo emitir); si es su primera integración, empiece por el tutorial del SDK embebido.

Configuración

La configuración se pasa una sola vez al llamar Iniciar y no se puede cambiar después; para usar otra, llame primero Encerrar y luego Iniciar de nuevo. La configuración se escribe encadenada con Configuracao.builder() ... .build().

Las cinco últimas opciones de la tabla (rol principal o secundario, puerto del principal, redes permitidas, dirección del principal y token del terminal) solo se usan en el despliegue principal y secundario, cuando varias cajas de una tienda comparten una serie de dispositivo; la división de roles, los pasos de despliegue y los métodos disponibles en el secundario están en Varias cajas (modo principal y secundario).

OpciónJavaObligatorioDescripción
Directorio de datosdiretorioDados(Path)SíDirectorio de la base local. Uno por caja; solo un proceso puede abrirlo a la vez. Antes de la transmisión, los archivos firmados de las notas offline solo existen ahí: no lo borre, vea SDK embebido
Directorio del runtimediretorioRuntime(Path)Obligatorio en modo subprocesoDirectorio de instalación del runtime. Debe contener tffiscal-nfce.exe; si no lo encuentra devuelve 10029877
Nombre del software de cajanomeAplicativo(String)SíNombre del software de caja. La plataforma reconoce el software de caja por este nombre; use el mismo nombre en todas las cajas; si falta, devuelve 10029874
Versión del PDVversaoAplicativo(String)SíNúmero de versión del PDV. La plataforma lo usa para la versión mínima y las versiones bloqueadas, por ejemplo 3.2.1
Idioma de los erroresidioma(String)NoIdioma de los mensajes de excepción. pt-BR (por defecto), en, zh-CN, es; solo cuenta la parte del idioma, por ejemplo en-US es inglés, y cualquier otro idioma usa portugués. Los errores que devuelve la plataforma y el SDK transmite tal cual (como una clase de impuesto inexistente o incompatible con el régimen) también usan este idioma
Tiempo límite por llamadatempoLimitePadraoMs(long)NoEspera máxima por llamada. Por defecto 30 segundos; al agotarse devuelve 10029833 y el resultado que llegue tarde se descarta. El emparejamiento y la obtención de la autorización o del XML de cancelación esperan al menos 120 segundos; ExportarXmls, ExportarPendentes, Backup y RestaurarBackup esperan al menos 30 minutos; si se configura un valor mayor, rige este
Tiempo límite de iniciotempoLimiteInicioMs(long)NoEspera máxima hasta que el runtime esté listo. Por defecto 5 segundos; al agotarse devuelve 10029831
Reinicio automáticoreiniciarAutomaticamente(boolean)NoReinicio automático del runtime si termina inesperadamente. Activado por defecto, con intervalos de 1, 2, 4 segundos hasta 60
Reenvío de logsencaminharLog(boolean)NoEnvío de los logs del núcleo al PDV. Desactivado por defecto; al activarlo se escriben en java.util.logging
Proxy de salidaproxy(String)NoDirección del proxy manual. Forma host:porta; por defecto no se configura y la conexión es directa, sin proxy; con formato inválido devuelve 10029874. Vea Proxy de salida
Autenticación del proxyproxyAutenticacao(String, String)NoUsuario y contraseña del proxy. Sirven para el proxy manual y para el del sistema; la contraseña solo pasa en memoria al runtime, no se graba en disco ni en los logs; si solo se informa la autenticación, sin dirección de proxy ni proxy del sistema, devuelve 10029874
Usar el proxy del sistemausarProxyDoSistema(boolean)NoInterruptor del proxy del sistema. Desactivado por defecto; emparejado, usa la configuración de proxy del sistema Windows, con prioridad sobre Proxy; no admite scripts PAC de proxy automático
Días de retención del XMLretencaoXmlDias(int)NoDías de retención local del XML. Días que el XML autorizado y el XML de cancelación se guardan en el equipo, de 1 a 3650; sin valor o con 0 son 90 días; fuera de rango devuelve 10029874. Los XML borrados al vencer el plazo se recuperan solos de la plataforma al leerlos; en la exportación mensual de XML, el período debe quedar dentro del plazo de retención
Modo de ejecuciónmodo(Modo)NoModo de ejecución en Java. SUBPROCESSO (por defecto) o EM_PROCESSO, vea abajo
Oyente de eventosaoReceberEvento(Consumer<EventoNfce>)NoManejador conectado al inicio. Así no se pierden los eventos acumulados antes del inicio, vea Eventos
Comando del runtimecomandoRuntime(String)NoOpción avanzada. Ruta completa del ejecutable del runtime, solo para desarrollo y pruebas
Argumentos del runtimeargumentosRuntime(List<String>)NoOpción avanzada. Argumentos de inicio del runtime, por defecto --stdio; solo para desarrollo y pruebas
Motor simuladomotorSimulado(boolean)NoMotor sustituto para pruebas. Solo para ejemplos y pruebas automatizadas, no genera notas válidas; no lo active en producción
Rol principal o secundariomodoOperacao(ModoOperacao)NoRol de esta caja cuando varias cajas comparten una serie. Independiente (por defecto), principal o secundario, con los valores INDEPENDENTE / PRINCIPAL / SECUNDARIO; vea Varias cajas (modo principal y secundario)
Puerto del principalportaPrincipal(int)NoPuerto de red local del principal. Solo en el principal; sin valor o 0 es 8786; si el puerto está ocupado, Iniciar devuelve 10029887
Redes permitidasredesPermitidas(List<String>)NoRedes de los secundarios que acepta el principal. Solo en el principal; notación CIDR, por ejemplo 192.168.0.0/24; sin valor es la red /24 del principal; solo acepta direcciones privadas de red local; un formato inválido devuelve 10029874
Dirección del principalenderecoPrincipal(String)Obligatorio en el secundarioDirección del principal al que se conecta el secundario. Forma host:porta, por ejemplo 192.168.0.10:8786; debe ser una dirección privada de red local, si no 10029883
Token del terminaltokenTerminal(String)Obligatorio en el secundarioToken del terminal secundario. Lo emite CriarTerminal en el principal y empieza con tfl_; solo se entrega al runtime en memoria, nunca se escribe en disco ni en el log; inválido o revocado, Iniciar devuelve 10029882

Modo de ejecución en Java

ModoSignificadoRequisitos
SUBPROCESSOPor defecto. El SDK inicia el runtime como subprocesoJava 8 o superior en el anfitrión; hay que distribuir el runtime y configurar diretorioRuntime
EM_PROCESSOEl núcleo corre dentro de la JVM del PDV, sin subprocesoJava 21 o superior en el anfitrión, con los jar del runtime y del núcleo en el classpath; con menos de Java 21 el inicio devuelve 10029835. Con autenticación de proxy configurada, los parámetros de inicio de la JVM deben incluir -Djdk.http.auth.tunneling.disabledSchemes=; vea Proxy de salida

Proxy de salida

El núcleo decide según la tabla siguiente si usa proxy para llegar a la plataforma:

ConfiguraciónForma de proxy
UsarProxyDoSistema activadoProxy del sistema. Primero lee la configuración de proxy WinHTTP de la máquina en Windows y, si no hay, la configuración de proxy de las opciones de Internet del usuario de Windows actual; si también se informa Proxy, prevalece el proxy del sistema
Solo ProxyProxy manual. Usa la dirección informada en Proxy
NingunaDirecta
  • Sin soporte para scripts PAC de proxy automático: si Windows solo tiene configurado un script de proxy automático, sin dirección de proxy fija, el núcleo registra una advertencia en el log y conecta en directo. En esas redes configure Proxy manualmente.
  • Autenticación del proxy: proxyAutenticacao vale para el proxy manual y para el del sistema.
  • Parámetro de inicio del modo en proceso de Java: la autenticación Basic del proxy en el túnel HTTPS depende de la propiedad de sistema de la JVM jdk.http.auth.tunneling.disabledSchemes, que la JVM lee una sola vez, la primera vez que se usa su cliente HTTP integrado; cambiarla después no tiene efecto. Con el modo en proceso de Java (EM_PROCESSO) y autenticación de proxy configurada, el anfitrión debe agregar -Djdk.http.auth.tunneling.disabledSchemes= a los parámetros de inicio de la JVM (vacío después del signo igual). Al cargarse, si el anfitrión no definió la propiedad, el núcleo también la deja vacía lo antes posible y comprueba si surtió efecto: si el anfitrión deshabilitó Basic de forma explícita, ya usó antes el cliente HTTP integrado de la JVM o no se puede determinar, Avisos de Situacao informa que la autenticación del proxy puede no funcionar y se registra una advertencia en el log. En el modo subproceso de Java la define el subproceso del runtime al iniciar, y el anfitrión no tiene que hacer nada.

Abajo se muestra el proxy manual con autenticación.

java
Configuracao configuracao = Configuracao.builder()
// El resto de la configuración, igual que arriba
.proxy("10.0.0.5:3128")
.proxyAutenticacao("caixa01", senhaProxy)
.build();

Ejemplo de configuración

Una configuración básica habitual; las opciones no indicadas toman el valor por defecto.

java
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")
.tempoLimitePadraoMs(30_000)
.build();

Métodos

Cada método sigue el mismo orden: uso y conexión, firma, parámetros, retorno, errores posibles y ejemplo. Además de los errores indicados en cada método, cualquier método puede devolver los errores comunes, vea el inicio de Códigos de error.

Iniciar

Inicia el SDK: levanta el runtime (modo subproceso) o carga el núcleo (modo en proceso de Java), abre el directorio de datos, retoma los flujos que quedaron sin terminar y arranca en segundo plano el heartbeat, la transmisión y la descarga de resultados. Los demás métodos se llaman después de que Iniciar termine bien; un directorio de datos admite una sola instancia a la vez.

Red: No hace falta. Inicia también sin red y empieza a sincronizar en cuanto haya conexión.

Firma

java
public static TfFiscalNfce iniciar(Configuracao config);

Parámetros

ParámetroJavaObligatorioDescripción
ConfiguraciónconfigSíConfiguración de inicio. Campos en Configuración

Retorno

La instancia del SDK lista para usar, TfFiscalNfce. Al terminar llame Encerrar; también puede cerrarla con try-with-resources.

Errores posibles

CódigoSituaciónAcción
10029877Runtime no encontradoRevise que el directorio del runtime y tffiscal-nfce.exe se distribuyan con el instalador
10029831El runtime no inició o no estuvo listo dentro del tiempo límite de inicioRevise los logs; en computadoras lentas aumente el tiempo límite de inicio
10029830Versiones de SDK y runtime incompatiblesDistribuya el runtime y el SDK de la misma versión
10029835Modo en proceso de Java con anfitrión por debajo de Java 21Use el modo subproceso o actualice Java
10029828El directorio de datos ya está abierto por otro procesoUna sola instancia por directorio; revise si quedó algún proceso
10029827No se puede abrir la clave local: el directorio de datos viene de otra computadora o de otro usuario de WindowsEjecute con el usuario de Windows original; para cambiar de computadora, desactive el dispositivo anterior y empareje de nuevo
10029829Base local inconsistenteNo borre el directorio de datos; contacte a la plataforma
10029842La versión de la base local es superior a la del núcleo actual: el directorio de datos ya lo usó una versión más nueva del SDK y el inicio se rechazaActualice el SDK y el runtime a una versión no inferior a la última usada; nunca borre el directorio de datos: ahí están los originales de las notas offline no transmitidas
10029840Configuración inválidaCorrija la configuración según Message
10029874Valor de configuración inválido: falta el nombre o la versión del software de caja, dirección de proxy con formato inválido, solo autenticación de proxy, o días de retención del XML fuera de rangoCorrija la configuración según Detalhes.campo
10029882Token del terminal secundario inválido o revocadoEmita otro token en el principal y actualice TokenTerminal
10029883Dirección del principal mal formada o fuera de la red local privadaCorrija EnderecoPrincipal
10029887No se puede escuchar en el puerto de red local del principalCambie PortaPrincipal o libere el puerto

También puede devolver los errores comunes.

Ejemplos

java
try (TfFiscalNfce nfce = TfFiscalNfce.iniciar(configuracao)) {
System.out.println("ativado=" + nfce.isAtivado());
}

Ativado / Empresas

  • Ativado: indica si el directorio de datos tiene al menos una empresa emparejada. El PDV lo usa al iniciar para decidir si entra en el flujo de emparejamiento.
  • Empresas: lista de empresas emparejadas. Cuando un directorio de datos empareja varias empresas (varios CNPJ), sirve para encontrar el empresaId de cada una.

Los dos consultan al núcleo en cada llamada, sin caché: si la plataforma desactiva el dispositivo, el estado aparece tal cual en el campo Situacao.

Red: No hace falta.

Firma

java
public boolean isAtivado();
public List<Resultados.EmpresaAtivada> getEmpresas();

Parámetros

Ninguno.

Retorno

Ativado devuelve un booleano. Empresas devuelve la lista de empresas emparejadas; los campos del elemento están en Tipos de datos: empresa emparejada.

Errores posibles

Solo los errores comunes.

Ejemplos

java
if (!nfce.isAtivado()) {
nfce.ativar(codigoAtivacao, Certificado.doRepositorio(thumbprint, false));
}
for (Resultados.EmpresaAtivada empresa : nfce.getEmpresas()) {
System.out.println(empresa.getEmpresaId() + " " + empresa.getCnpj() + " " + empresa.getSituacao());
}

InspecionarCodigoAtivacao

Verifica en el equipo el formato, la firma de la plataforma, la vigencia y la dirección de plataforma del código de emparejamiento, y lee la empresa, el ambiente y la forma permitida. No usa la red ni consume el código. Sirve para que el cajero confirme antes de emparejar algo como «es un código de pruebas, válido por 72 horas», o para descartar antes códigos con formato inválido, vencidos o de otra forma.

Red: No hace falta. Que el código sea válido no garantiza que el emparejamiento funcione: si ya se usó o si se anuló solo lo sabe la plataforma al llamar Ativar.

Firma

java
public Resultados.CodigoAtivacao inspecionarCodigoAtivacao(String codigo);

Parámetros

ParámetroJavaObligatorioDescripción
Código de emparejamientocodigoSíTexto completo del código de emparejamiento. Empieza con TFA1.; el contenido del archivo .tfa es el código completo y se quitan los espacios al inicio y al final

Retorno

Información del código de emparejamiento; campos en Tipos de datos: información del código de emparejamiento.

Errores posibles

CódigoSituaciónAcción
10029825Formato, firma o vigencia del código incorrectosConfirme que se copió completo; si venció, pida al integrador uno nuevo
10029826El código apunta a una dirección de plataforma no confiableEl código no fue emitido por esta plataforma, o la versión del runtime no corresponde al ambiente; contacte al integrador

También puede devolver los errores comunes.

Ejemplos

java
Resultados.CodigoAtivacao info = nfce.inspecionarCodigoAtivacao(codigoAtivacao);
System.out.println("ambiente " + info.getAmbiente() + " expira " + info.getExpiraEm());

Ativar

Con el código de emparejamiento generado por el integrador y el certificado A1 de la empresa, empareja el equipo como un dispositivo de la empresa. En el emparejamiento el núcleo genera la clave del dispositivo, vincula el certificado y se registra en la plataforma; al terminar obtiene la serie del dispositivo y la primera licencia, y la plataforma envía nfce.device.activated (vea Cómo llegan los resultados). Cada empresa se empareja una sola vez por directorio de datos; el mismo directorio puede emparejar otras empresas.

Red: Obligatoria. Si no llega a la plataforma devuelve 10029824 y el código no se consume.

Firma

java
public Resultados.Ativacao ativar(String codigoAtivacao, Certificado certificado);

Parámetros

ParámetroJavaObligatorioDescripción
Código de emparejamientocodigoAtivacaoSíTexto completo del código de emparejamiento. Empieza con TFA1., es de un solo uso y vale 72 horas
CertificadocertificadoSíCertificado A1 de la empresa. Formas en Tipos de datos: origen del certificado; el CNPJ del certificado debe ser el de la empresa de la tienda

Retorno

Resultado del emparejamiento; campos en Tipos de datos: resultado del emparejamiento.

Errores posibles

CódigoSituaciónAcción
10029825 / 10029826El código no pasó la verificación local / apunta a una plataforma no confiableVea InspecionarCodigoAtivacao
10029824No llega a la plataformaReintente con conexión
10029837La empresa ya está emparejada en este directorio de datosNo hace falta emparejar de nuevo
10029813 / 10029814Certificado no encontrado, sin clave privada o con CNPJ distinto / vencidoUse un certificado A1 vigente de la empresa
10029839La plataforma emparejó pero falló el guardado localLlame de nuevo Ativar con el mismo código de emparejamiento
10029806La licencia no pertenece a este dispositivoEmpareje de nuevo; si persiste, contacte a la plataforma
10029874Parámetro de certificado inválido: la huella no tiene 40 dígitos hexadecimales o el PFX está vacíoCorrija el parámetro del certificado
10029205 a 10029208De la plataforma: código inválido / vencido / ya usado / anuladoGenere un código nuevo
10029209De la plataforma: el código no permite la forma SDKGenere otro con Sdk o Qualquer
10029210 / 10029211De la plataforma: falta el nombre del software de caja / versión del PDV bloqueada o muy antiguaConfigure el nombre del software de caja; actualice el PDV
10029213 / 10029214De la plataforma: CNPJ del certificado distinto del de la empresa / certificado vencidoUse un certificado vigente de la empresa
10029219De la plataforma: el ambiente del código difiere del ambiente actual de la empresaGenere un código nuevo en el ambiente actual de la empresa
10029221 a 10029225De la plataforma: la serie del dispositivo indicada en el código ya no está disponibleEl integrador genera un código nuevo con otra serie u otro número inicial

También puede devolver los errores comunes.

Ejemplos

java
Resultados.Ativacao a = nfce.ativar(codigoAtivacao, Certificado.doRepositorio(thumbprint, false));
System.out.println("empresa " + a.getEmpresaId() + " dispositivo " + a.getDispositivoId() + " serie " + a.getSerieOffline());

Emitir

Emite una NFC-e. El núcleo toma el siguiente número de la serie del dispositivo, firma la nota y primero la entrega a la plataforma para autorizarla en línea; si no llega a la plataforma, si la plataforma agota el tiempo o si el resultado es incierto, firma la nota offline en el propio equipo y devuelve en el momento una nota offline lista para imprimir. El cuerpo de la solicitud es idéntico al de la interfaz de emisión en la nube, vea Solicitud de emisión.

Orden de procesamiento:

  1. Busca el id en el equipo: si ya emitió el mismo id, devuelve la nota original sin tomar otro número; si el contenido es distinto, devuelve 10029818.
  2. Si un ítem referencia una clase de impuesto (classeImposto), la solicitud va primero a la plataforma, que la expande en impostos completos: requiere conexión, y sin acceso a la plataforma devuelve 10029780 sin consumir número; una clase de impuesto rechazada (inexistente, incompatible con el régimen, etc.) devuelve el código y el mensaje de la plataforma tal cual.
  3. Normaliza y valida con las mismas reglas de la nube; si no pasa, devuelve 10029817 y Detalhes lista los motivos campo por campo.
  4. Toma un número de la serie del dispositivo, firma y envía en línea, con el mismo resultado que la emisión síncrona en la nube; si la plataforma devuelve un error de negocio, lo devuelve tal cual, no pasa a offline y el número queda para la nota siguiente. La única excepción es que la plataforma informe el número como ya usado (10029424): el núcleo descarta ese número, sincroniza una vez con la plataforma para actualizar el número confirmado y reintenta una sola vez; un segundo conflicto se devuelve tal cual, sin seguir probando número tras número ni bloquear la caja.
  5. Si la emisión en línea falla o se agota el tiempo, verifica licencia, plazo de transmisión, permiso offline y demás condiciones y firma offline, devolviendo ContingenciaPendente. Si el resultado fue incierto, el número original no se reutiliza: la nota offline lleva el número siguiente y la plataforma resuelve el original, cancelándolo por sustitución si fue autorizado o inutilizándolo si no (vea Números que la plataforma gestiona por usted); si en ese momento no se puede firmar offline, devuelve AguardandoAutorizacao y más tarde reenvía el número original sin cambios. Si la última conexión acaba de fallar, omite el paso 4 y firma offline de inmediato.

Las emisiones de una misma empresa se ejecutan en orden dentro del núcleo, para que los números de la serie del dispositivo sean continuos entre notas en línea y offline; empresas distintas pueden emitir en paralelo.

Red: Opcional. Con conexión emite en línea; sin conexión firma offline.

Firma

java
public ResultadoEmissao emitir(String pedidoJson);
public ResultadoEmissao emitir(String pedidoJson, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Solicitud de emisiónpedidoJsonSíSolicitud de emisión. Texto JSON; misma estructura que la interfaz de emisión en la nube, sin modoResposta. Los ítems pueden llevar impostos o referenciar una clase de impuesto con classeImposto (requiere conexión)
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; con varias, omitirlo devuelve 10029802

Retorno

Resultado de la emisión; campos y estados en Tipos de datos: resultado de la emisión.

StatusQué hace el PDV
AutorizadaImprime el cupón
ContingenciaPendenteFirma offline: imprima el cupón con Cupom y entréguelo al consumidor; la transmisión es automática
AguardandoAutorizacaoAceptada en línea pero la SEFAZ no respondió, y en ese momento no se podía firmar offline: no imprima todavía, espere el evento NOTA_AUTORIZADA o consulte más tarde; si después la SEFAZ la rechaza, llega NOTA_NEGADA
NegadaLa SEFAZ rechazó la emisión en línea: no admite corrección con el mismo número; corrija los datos de la venta según el código y el mensaje de resultado de la SEFAZ y emita de nuevo con un id nuevo

Errores posibles

CódigoSituaciónAcción
10029817Solicitud inválidaCorrija según Detalhes
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 contenido distintoVenta nueva con id nuevo; para reintentar, use la solicitud original
10029801 / 10029802Empresa no emparejada / varias empresas sin empresaIdEmpareje primero; envíe empresaId
10029816Dispositivo desactivadoContacte al integrador
10029805 / 10029806Firma de la licencia inválida / licencia de otro dispositivoContacte a la plataforma; si hace falta, empareje de nuevo
10029874La solicitud no es un objeto JSONEnvíe el texto de un objeto JSON
10029803 / 10029804 / 10029807Sin red y sin licencia / licencia vencida / pasó el plazo offlineRestablezca la red; tras renovar se recupera solo
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 para transmitir
10029811 / 10029812La empresa o el estado no permite offline / nota con combustibleSolo emisión en línea
10029813 / 10029814Certificado no disponible / vencidoRevise el certificado; si hace falta, TrocarCertificado
10029815Faltan la configuración local o los datos tributariosSincronice en línea una vez
10029823Numeración de la serie del dispositivo agotadaDesactive 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
10029307De la plataforma: el ambiente del dispositivo difiere del ambiente actual de la empresaEmpareje un dispositivo nuevo en el ambiente actual de la empresa
10029424De la plataforma: número ya usado. El núcleo ya descartó el número y reintentó una vez; si el conflicto se repite, la base local y los registros de la plataforma no coincidenNo reintente con otro número; exporte los registros y contacte a la plataforma
10029426De la plataforma: el mismo id ya tiene una nota no rechazada en la plataforma, por ejemplo emitida por la API en la nube u otro dispositivoVerifique la nota original en Consultar NFC-e; use un id nuevo para una venta nueva
Otros códigos de la plataformaError de negocio devuelto por la plataforma en la emisión en línea, como 10022004Trátelo según la descripción de errores de Emitir NFC-e

También puede devolver los errores comunes.

Ejemplos

java
ResultadoEmissao r = nfce.emitir(pedidoJson);
if ("Autorizada".equals(r.getStatus()) || "ContingenciaPendente".equals(r.getStatus())) {
impressora.enviar(nfce.cupom(r.getId(), FormatoCupom.ESCPOS_80));
}

Previsualizar

Revisa una solicitud de emisión con la misma normalización, validación y cálculo de impuestos de Emitir y devuelve si pasa, los errores campo por campo, el total de la nota y el total de impuestos. No toma número, no firma, no guarda y no usa la red. Sirve para validar mientras se carga la venta en el PDV: si la validación no pasa no lanza excepción y devuelve Valido en false.

Red: No hace falta.

Firma

java
public Resultados.PreVisualizacao previsualizar(String pedidoJson, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Solicitud de emisiónpedidoJsonSíSolicitud a validar. Misma estructura que Emitir; el id puede faltar todavía
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. En Java pase null si solo hay una empresa emparejada

Retorno

Resultado de la vista previa; campos en Tipos de datos: resultado de la vista previa. Erros ya viene traducido al idioma de errores configurado y se puede mostrar directamente al cajero.

Errores posibles

La validación que no pasa no lanza error. Además de los errores comunes, solo hay errores de empresa: 10029801 (empresa no emparejada), 10029802 (varias empresas sin empresaId), 10029815 (faltan los datos tributarios locales; sincronice en línea una vez).

También puede devolver los errores comunes.

Ejemplos

java
Resultados.PreVisualizacao p = nfce.previsualizar(pedidoJson, null);
if (!p.isValido()) {
p.getErros().forEach(System.out::println);
}

Se recomienda llamarlo tras una pausa de unos 300 milisegundos en la escritura, no en cada tecla.

Consultar

Consulta por el id de la emisión el estado actual de una nota del equipo: si está autorizada, si ya se transmitió, si tiene una cancelación pendiente, cuántas veces se corrigió, si el XML autorizado ya se descargó y la solicitud original. Las notas en línea y offline quedan en el equipo, y las offline se pueden consultar antes de transmitirse. Si el PDV se cayó y reinició, úselo para recuperar las notas emitidas antes de la caída.

Red: No hace falta. Devuelve el registro del equipo; los resultados de transmisión y autorización se actualizan con la sincronización en segundo plano. Para obtener lo más reciente cuanto antes, llame primero SincronizarAgora.

Firma

java
public SituacaoNota consultar(String id);
public SituacaoNota consultar(String id, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Identificador de la notaidSíEl id de la solicitud de emisión
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada

Retorno

Estado de consulta; campos en Tipos de datos: estado de consulta.

Errores posibles

CódigoSituaciónAcción
10029819La nota no existe en este equipoRevise id y empresaId; si la nota no se emitió en este equipo, use la consulta en la nube
10029801 / 10029802Empresa no emparejada / varias empresas sin empresaIdEmpareje primero; envíe empresaId

También puede devolver los errores comunes.

Ejemplos

java
SituacaoNota s = nfce.consultar("PDV01-000131");
System.out.println(s.getStatus() + " transmitida=" + s.isTransmitida() + " protocolo=" + s.getProtocolo());

ListarNotas

Lista por páginas las notas del equipo (en línea y offline), de la emisión más reciente a la más antigua, 50 por página. Sirve para la pantalla de «notas del día» y para revisar al cambio de turno cuántas quedan por transmitir. Para no contar toda la tabla, el resultado no trae el total, solo si hay una página siguiente.

Red: No hace falta.

Firma

java
public Resultados.PaginaNotas listarNotas(LocalDate data, String status, int pagina, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Fecha de emisióndataNoFiltro por día de emisión. La fecha usa la zona horaria del estado de la empresa; sin él no se filtra por fecha, para la lista del día envíelo siempre
EstadostatusNoFiltro por estado. Valores en Tipos de datos: estado de la nota; sin él no se filtra
PáginapaginaNoNúmero de página. Empieza en 1, por defecto 1
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null

Retorno

Página de notas; campos en Tipos de datos: página de notas. La paginación de la interfaz solo tiene «anterior / siguiente»; con TemMais en false, desactive «siguiente».

Errores posibles

CódigoSituaciónAcción
10029874Fecha que no es yyyy-mm-dd, estado con valor inválido, o página menor que 1Use los valores de la tabla
10029801 / 10029802Empresa no emparejada / varias empresas sin empresaIdEmpareje primero; envíe empresaId

También puede devolver los errores comunes.

Ejemplos

java
Resultados.PaginaNotas pagina = nfce.listarNotas(LocalDate.now(), "ContingenciaPendente", 1, null);
pagina.getItens().forEach(n -> System.out.println(n.getId() + " " + n.getNumero()));

Cancelar

Cancela una NFC-e ya emitida. Según el estado de la nota y la red, la solicitud sigue uno de tres caminos:

SituaciónDestino SituacaoDespués
Nota autorizada y con conexiónSolicitadoYa se envió a la plataforma; el resultado llega por el evento CANCELAMENTO_CONCLUIDO o CANCELAMENTO_REJEITADO
Nota offline transmitida y aún no autorizadaAgendadoLa plataforma deja la cancelación pendiente y la ejecuta sola en el momento de la autorización, aunque el PDV ya no esté en ejecución
Sin conexión en ese momento, o nota offline aún no transmitidaEnfileiradoLocalQueda en cola en el equipo; se envía en la misma ronda justo después de la transmisión; motivo indica la causa

El plazo de cancelación es el mismo de la nube, vea Cancelar NFC-e. El uso dentro del flujo de caja está en Operación y tareas avanzadas: cancelación.

Red: Opcional. Sin conexión queda en cola en el equipo.

Firma

java
public Resultados.Cancelamento cancelar(String id, String justificativa, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Identificador de la notaidSíEl id de la solicitud de emisión
Motivo de la cancelaciónjustificativaSíMotivo de la cancelación. De 15 a 255 caracteres
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null

Retorno

Resultado de la cancelación; campos en Tipos de datos: resultado de la cancelación. Aceptada no significa cancelada: el resultado final está en el evento o en el Status de Consultar.

Errores posibles

CódigoSituaciónAcción
10029822El estado actual no permite cancelar: ya cancelada, ya hay una cancelación pendiente, o no está autorizada ni a la espera de autorización; también cuando el estado local aún no se sincronizó y la plataforma rechaza la cancelación (por ejemplo, la nota ya fue rechazada), con el motivo de la plataforma en detalhesNo reintente; confirme el estado con Consultar
10029819La nota no existe en este equipoRevise el id
10029817El motivo no tiene de 15 a 255 caracteresCorrija el motivo
Otros códigos de la plataformaError de la plataforma al enviar en línea, como plazo de cancelación vencido 10022007Trátelo según Cancelar NFC-e

También puede devolver los errores comunes.

Ejemplos

java
Resultados.Cancelamento c = nfce.cancelar("PDV01-000131", "Cliente desistiu da compra no caixa", null);
System.out.println(c.getSituacao());

CancelarPorSubstituicao

Cancelación por sustitución: cuando una nota emitida en línea es sustituida por una nota de contingencia offline emitida después en este equipo (la misma venta emitida de nuevo), cancela la nota original e indica en la cancelación la clave de acceso de la nota sustituta.

Requisitos:

ObjetoDebe cumplirSi no se cumple
Nota originalNota normal emitida en línea por la plataforma: no es offline, no está cancelada y no tiene una cancelación pendiente10029822
Nota sustitutaNota offline emitida en este equipo para la misma empresa, no rechazada por la plataforma; clave de acceso de 44 dígitos, modelo 65, dígito verificador correcto, mismo CNPJ que la nota original y distinta de la clave de la nota original10029845

Si la nota sustituta aún no se transmitió, devuelve EnfileiradoLocal: la cancelación queda en cola en el equipo y se envía cuando la nota sustituta se transmite con éxito. El resultado final llega por el evento CANCELAMENTO_CONCLUIDO o CANCELAMENTO_REJEITADO. El plazo de cancelación es el mismo de la nube; vea Cancelar NFC-e. El flujo completo de nueva emisión y cancelación por sustitución está en Operación y tareas avanzadas: cancelación por sustitución.

Red: Opcional. Sin red, o mientras la nota sustituta no se transmita, queda en cola en el equipo y se envía sola cuando se cumplen las condiciones.

Firma

java
public Resultados.Cancelamento cancelarPorSubstituicao(String id, String chaveSubstituta, String justificativa,
String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Identificador de la notaidSíEl id de la nota original sustituida
Clave de la nota sustitutachaveSubstitutaSíClave de acceso de la nota sustituta. 44 dígitos, se toma de Chave en el resultado de la emisión de la nota sustituta
Motivo de la cancelaciónjustificativaSíMotivo de la cancelación. De 15 a 255 caracteres
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null

Retorno

Resultado de la recepción de la cancelación, campos en Tipos de datos: Resultado de la cancelación. Que se reciba no significa que ya esté cancelada; el resultado final está en los eventos o en Status de Consultar.

Errores posibles

CódigoSituaciónAcción
10029822La nota original no es una nota normal emitida en línea: es offline, ya está cancelada o tiene una cancelación pendienteNo reintente; para notas offline use Cancelar
10029845Clave de la nota sustituta inválida, o no es una nota offline de este equipo y de la misma empresa no rechazadaInforme la clave de acceso de 44 dígitos de la nota offline emitida en este equipo para la misma venta
10029819La nota original no existe en este equipoRevise el id
10029817El motivo no tiene entre 15 y 255 caracteresCorrija el motivo
Otros códigos de la plataformaError devuelto por la plataforma al enviar, por ejemplo plazo de cancelación superado 10022007Trátelo según Cancelar NFC-e

También puede devolver los errores comunes.

Ejemplos

java
ResultadoEmissao substituta = nfce.emitir(pedidoRefeitoJson);
Resultados.Cancelamento c = nfce.cancelarPorSubstituicao("PDV01-000131", substituta.getChave(),
"Venda refeita em contingencia offline", null);
System.out.println(c.getSituacao());

Substituir

Cuando la SEFAZ rechaza una nota offline transmitida (estado Rejeitada, evento NOTA_REJEITADA), esa nota ya se entregó al consumidor: no se puede reemplazar por otra, solo corregir con el mismo número y transmitir de nuevo. Substituir vuelve a armar y firmar la nota con la solicitud corregida, manteniendo número, serie, clave de acceso y fecha de emisión, y la devuelve a la cola de transmisión; el núcleo la transmite sola en la siguiente sincronización. Las reglas de transmisión y de rechazo están en Notas offline y transmisión.

Solo se puede cambiar lo que no afecta valores ni impuestos, por ejemplo el NCM o el CFOP de un ítem o el documento del consumidor; si cambia el total de la nota o el impuesto de cualquier línea, la corrección se rechaza.

Red: No hace falta. La corrección se hace en el equipo y la transmisión sigue en segundo plano.

Firma

java
public ResultadoEmissao substituir(String id, String pedidoJsonCorrigido, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Identificador de la notaidSíEl id de la nota rechazada
Solicitud corregidapedidoJsonCorrigidoSíSolicitud de emisión completa. Corrija a partir de la solicitud original, que se obtiene en Pedido de Consultar; el id es el mismo de la original
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null

Retorno

Resultado de la emisión, con la misma estructura de Emitir, con Status de vuelta en ContingenciaPendente. Al autorizarse tras la nueva transmisión llega NOTA_AUTORIZADA con Dados.aposCorrecao en true.

Errores posibles

CódigoSituaciónAcción
10029820El estado actual no permite corregir: solo Rejeitada se puede corregirConfirme el estado con Consultar
10029821La corrección cambió valores o impuestosCambie solo lo que no afecta valores
10029817Solicitud inválidaCorrija según Detalhes
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
10029819La nota no existe en este equipoRevise el id
10029815Faltan la configuración local o los datos tributariosSincronice en línea una vez

También puede devolver los errores comunes.

Ejemplos

java
SituacaoNota original = nfce.consultar("PDV01-000131");
ResultadoEmissao r = nfce.substituir("PDV01-000131", corrigirNcm(original.getPedido()), null);
System.out.println(r.getStatus());

Cupom

Genera el cupón de una nota del equipo. El cupón de una nota offline sale con la marca de contingencia offline y el aviso de «pendiente de autorización», sin número de protocolo; la cantidad de copias la configura la plataforma. Los bytes ESC/POS se envían directo a la impresora térmica, y el PDF se entrega al driver de impresión de Windows. También funciona sin red.

Para ajustar las columnas por línea, la página de códigos, la forma de imprimir el código QR, el corte o la cantidad de copias, use la sobrecarga con parámetros de impresión; los parámetros están más abajo, en «Parámetros de impresión».

Red: No hace falta.

Firma

java
public byte[] cupom(String id, FormatoCupom formato);
public byte[] cupom(String id, FormatoCupom formato, String empresaId);
public byte[] cupom(String id, FormatoCupom formato, OpcoesCupom opcoes, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Identificador de la notaidSíEl id de la solicitud de emisión
FormatoformatoSíFormato del cupón. Valores en la tabla de abajo
Parámetros de impresiónopcoes (OpcoesCupom)NoParámetros de impresión del cupón. Solo en la sobrecarga con parámetros de impresión; se puede pasar null; campos más abajo, en «Parámetros de impresión»
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada
Java FormatoCupomContenido
ESCPOS_80Bytes ESC/POS para impresora térmica de 80 mm
ESCPOS_58Bytes ESC/POS para impresora térmica de 58 mm
TEXTOTexto plano UTF-8
HTMLHTML 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. Se entrega al driver de impresión de Windows, para impresoras que no aceptan ESC/POS directo; usa las fuentes monoespaciadas estándar de PDF, sin incrustar fuentes, y los acentos del portugués se ven correctamente; el código QR es una imagen en blanco y negro

Parámetros de impresión

Clase OpcoesCupom, con métodos encadenados. Las opciones no informadas usan el valor por defecto; fuera de rango devuelve 10029874, con Detalhes.campo en opcoes.

ParámetroJavaObligatorioDescripción
Columnas por líneacolunas(int)NoCaracteres por línea. 48, 42, 32; sin valor o con 0 depende del formato: 48 en 80 mm, 32 en 58 mm
Página de códigospaginaCodigo(String)NoPágina de códigos de la impresora. CP1252 (por defecto, Europa occidental), CP860 (portugués), CP850 (Europa occidental multilingüe), CP437 (inglés de EE. UU.); los caracteres que no existen en la página de códigos se imprimen sin acento
Forma del código QRmodoQrCode(OpcoesCupom.ModoQrCode)NoForma de imprimir el código QR. NATIVO (por defecto) usa el comando de QR propio de la impresora; IMAGEM imprime el código QR como mapa de bits, para impresoras sin comando de QR
Tamaño del módulo QRtamanhoModuloQr(int)NoPuntos por módulo del código QR. De 1 a 16; sin valor o con 0 es 4
Corte del papelcortar(boolean)NoInterruptor de corte del papel. Por defecto true: corta tras imprimir
Copiasvias(int)NoCantidad de copias. De 1 a 9; sin valor o con 0 sigue la configuración de la plataforma

Retorno

Bytes del cupón. Con PDF_80 es el contenido del archivo PDF.

Errores posibles

CódigoSituaciónAcción
10029819La nota no existe en este equipoRevise el id
10029874Formato con valor inválido, o parámetros de impresión fuera de rangoUse los valores de la tabla

También puede devolver los errores comunes.

Ejemplos

java
byte[] cupom = nfce.cupom("PDV01-000131", FormatoCupom.ESCPOS_80);
Files.write(Paths.get("PDV01-000131.escpos"), cupom);
// PDF de 80 mm para el driver de impresión de Windows
byte[] pdf = nfce.cupom("PDV01-000131", FormatoCupom.PDF_80, new OpcoesCupom().vias(1), null);
Files.write(Paths.get("PDV01-000131.pdf"), pdf);

QrCodePng

Genera la imagen PNG del código QR de una nota del equipo (blanco y negro, con zona de silencio). Úsela para armar su propio cupón o mostrar el código QR en pantalla; el contenido es el mismo que QrCode del resultado de la emisión. También funciona sin red.

Red: No hace falta.

Firma

java
public byte[] qrCodePng(String id, int tamanhoPx, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Identificador de la notaidSíEl id de la solicitud de emisión
Lado de la imagentamanhoPxNoLado de la imagen en píxeles. De 64 a 2048; debe pasarse explícitamente
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null

Retorno

Bytes de la imagen PNG.

Errores posibles

CódigoSituaciónAcción
10029819La nota no existe en este equipoRevise el id
10029817El lado de la imagen no está entre 64 y 2048Corrija el tamaño

También puede devolver los errores comunes.

Ejemplos

java
Files.write(Paths.get("PDV01-000131-qrcode.png"), nfce.qrCodePng("PDV01-000131", 240, null));

XmlAutorizado

Lee el texto original del XML autorizado de una nota (con el protocolo de autorización). Después de autorizar una nota en línea, o de autorizar una nota offline tras la transmisión, el núcleo descarga el XML autorizado al equipo; los días de retención los define la opción RetencaoXmlDias (90 días por defecto). Si no está en el equipo (aún no se descargó, o se borró al vencer el plazo de retención), el núcleo lo recupera de la plataforma por la red en el momento; el archivo de la plataforma es el original de referencia.

Si XmlAutorizadoDisponivel de Consultar es true, se lee directamente del equipo, sin red.

No lo llame en el hilo de la interfaz: si no está en el equipo hay que esperar la respuesta de la plataforma, hasta unos 120 segundos (si el tiempo límite por llamada configurado es mayor, vale ese); llámelo en un hilo de fondo.

Red: Posible. Si no está en el equipo, se recupera de la plataforma de forma síncrona, hasta unos 120 segundos; no lo llame en el hilo de la interfaz.

Firma

java
public byte[] xmlAutorizado(String id, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Identificador de la notaidSíEl id de la solicitud de emisión
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null

Retorno

Bytes UTF-8 del XML autorizado.

Errores posibles

CódigoSituaciónAcción
10029841XML autorizado no disponible: la nota aún no se autorizó, o no está en el equipo y no se pudo recuperar de la plataformaSi no está autorizada, espere el evento NOTA_AUTORIZADA y vuelva a pedirlo; si ya está autorizada, la plataforma todavía no la archivó o no está accesible en este momento; reintente más tarde
10029819La nota no existe en este equipoRevise el id

También puede devolver los errores comunes.

Ejemplos

java
// Puede recuperarse por la red: use un hilo de fondo
CompletableFuture.supplyAsync(() -> nfce.xmlAutorizado("PDV01-000131", null))
.thenAccept(xml -> gravar("PDV01-000131-nfce.xml", xml));

XmlCancelamento

Lee el texto original del XML de cancelación de una nota cancelada (evento de cancelación y su recibo). Los días de retención en el equipo son los mismos del XML autorizado, definidos por la opción RetencaoXmlDias (90 días por defecto); si no está en el equipo, el núcleo lo recupera de la plataforma por la red en el momento.

No lo llame en el hilo de la interfaz: si no está en el equipo hay que esperar la respuesta de la plataforma, hasta unos 120 segundos (si el tiempo límite por llamada configurado es mayor, vale ese).

Red: Posible. Si no está en el equipo, se recupera de la plataforma de forma síncrona, hasta unos 120 segundos; no lo llame en el hilo de la interfaz.

Firma

java
public byte[] xmlCancelamento(String id, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Identificador de la notaidSíEl id de la solicitud de emisión
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null

Retorno

Bytes UTF-8 del XML de cancelación.

Errores posibles

CódigoSituaciónAcción
10029843XML de cancelación no disponible: la nota no está cancelada, o no está en el equipo y no se pudo recuperar de la plataformaSi no está cancelada, espere el evento CANCELAMENTO_CONCLUIDO y vuelva a pedirlo; si ya está cancelada, la plataforma todavía no lo archivó o no está accesible en este momento; reintente más tarde
10029819La nota no existe en este equipoRevise el id

También puede devolver los errores comunes.

Ejemplos

java
CompletableFuture.supplyAsync(() -> nfce.xmlCancelamento("PDV01-000131", null))
.thenAccept(xml -> gravar("PDV01-000131-can.xml", xml));

ExportarXmls

Exporta a un directorio los XML autorizados y de cancelación de un período, según la fecha de emisión, para entregarlos mensualmente al contador o archivarlos. Las fechas usan la zona horaria del estado de la empresa, con ambas fechas incluidas. Los pasos están en Operación y tareas avanzadas: exportación mensual de XML para el contador.

  • Nombres de archivo: el XML autorizado es {chave}-nfe.xml y el XML de cancelación {chave}-can.xml ({chave} es la clave de acceso de 44 dígitos); los archivos con el mismo nombre se sobrescriben.
  • Los XML que no están en el equipo se recuperan primero de la plataforma por la red; los que aun así no se obtienen no interrumpen la exportación y se listan uno por uno en Falhas del resultado, con el motivo (incluido si se borraron al vencer el plazo de retención).
  • El período exportado debe quedar dentro del plazo de retención de la opción RetencaoXmlDias; los XML fuera de ese plazo hay que recuperarlos uno por uno de la plataforma, y los que no se obtienen van a Falhas.
  • Fin rápido sin red: si justo antes de empezar la exportación no se llega a la plataforma, o la primera vez que deja de llegar durante la exportación, el resto de las notas sin XML ya no se buscan en la red y van directamente a Falhas.
  • Solo lo que está en el equipo: con somenteLocal en true no se conecta en absoluto, solo escribe los XML que ya están en el equipo, y las notas que falten van a Falhas.

Red: Posible. Los XML que no están en el equipo se recuperan por la red, salvo con somenteLocal en true, que no se conecta. La espera máxima es de al menos 30 minutos, o el tiempo límite por llamada si se configuró uno mayor; no lo llame en el hilo de la interfaz. Si la espera se agota (10029833), el runtime puede seguir escribiendo archivos: no reintente enseguida con el mismo directorio; espere un momento y vuelva a exportar a un directorio nuevo.

Firma

java
public Resultados.ExportacaoXml exportarXmls(LocalDate de, LocalDate ate, Path diretorio, String empresaId);
public Resultados.ExportacaoXml exportarXmls(LocalDate de, LocalDate ate, Path diretorio, boolean somenteLocal,
String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
Fecha inicialdeSíInicio del período por fecha de emisión. Incluye ese día
Fecha finalateSíFin del período por fecha de emisión. Incluye ese día
Directorio de destinodiretorioSíDirectorio de exportación. Una ruta relativa se convierte en absoluta a partir del directorio actual del software de caja
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null
Solo el equiposomenteLocalNoIndicador de exportación local. true exporta solo los XML que ya están en el equipo, sin conexión; por defecto false, y los que no están en el equipo se recuperan primero por la red. En Java use la sobrecarga de cinco parámetros

Retorno

Resultado de la exportación, campos en Tipos de datos: Resultado de la exportación de XML.

Errores posibles

CódigoSituaciónAcción
10029874Fecha faltante o con formato inválido, con Detalhes.campo en de o ateCorrija la fecha
10029844Directorio sin permiso de escrituraCambie de directorio; revise el espacio en disco y los permisos
10029801 / 10029802Empresa no emparejada / varias empresas sin empresaIdEmpareje primero; informe empresaId

Que falte el XML de una nota no genera error; vea Falhas en el resultado.

También puede devolver los errores comunes.

Ejemplos

java
Resultados.ExportacaoXml r = nfce.exportarXmls(LocalDate.of(2026, 10, 1), LocalDate.of(2026, 10, 31),
Paths.get("C:/Exportacao/2026-10"), null);
System.out.println("exportadas " + r.getQuantidadeNotas() + " notas, " + r.getQuantidadeArquivos() + " arquivos, falhas "
+ r.getFalhas().size());

TrocarCertificado

Cuando el certificado A1 de la empresa se renueva o se cambia, reemplaza el certificado registrado en el núcleo por el nuevo. La identidad del dispositivo, la serie del dispositivo y la licencia no cambian y no hace falta emparejar de nuevo; el certificado nuevo se informa a la plataforma en el siguiente heartbeat. Antes del vencimiento el núcleo emite el evento CERTIFICADO_EXPIRANDO (una vez a los 30, 7 y 1 días), que puede usar para avisar al administrador.

Red: No hace falta.

Firma

java
public void trocarCertificado(Certificado certificado, String empresaId);

Parámetros

ParámetroJavaObligatorioDescripción
CertificadocertificadoSíCertificado A1 nuevo. Formas en Tipos de datos: origen del certificado; el CNPJ debe ser el de la empresa de la tienda
Identificador de la empresaempresaIdObligatorio con varias empresasEmpresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null

Retorno

Ninguno. Tras el cambio, CertificadoValidoAte de Situacao pasa a la fecha de vencimiento del certificado nuevo.

Errores posibles

CódigoSituaciónAcción
10029813Certificado no disponible: no encontrado, sin clave privada o con CNPJ distinto del de la empresaRevise el almacén de certificados y use el certificado de la empresa de la tienda
10029814Certificado vencidoUse un certificado vigente
10029874Parámetro de certificado inválido: la huella no tiene 40 dígitos hexadecimales o el PFX está vacíoCorrija el parámetro del certificado
10029801 / 10029802Empresa no emparejada / varias empresas sin empresaIdEmpareje primero; envíe empresaId

También puede devolver los errores comunes.

Ejemplos

java
nfce.trocarCertificado(Certificado.deArquivoPfx(Files.readAllBytes(Paths.get("C:/deploy/novo.pfx")), senha), null);

Situacao

Lee el estado general del núcleo: la versión del núcleo, los avisos del motor y, para cada empresa emparejada, la conexión, lo que queda de la licencia, las notas por transmitir, el plazo de transmisión, el vencimiento del certificado y el último error. Sirve para mostrar en el PDV avisos como «sin conexión», «N notas por transmitir» o «el certificado vence en 7 días»; se puede llamar periódicamente (por ejemplo cada 10 segundos), con costo mínimo.

Red: No hace falta.

Firma

java
public Resultados.Nucleo situacao();

Parámetros

Ninguno.

Retorno

Estado del núcleo; campos en Tipos de datos: estado del núcleo. El estado de cada empresa es una lista de pares clave-valor devuelta por getEmpresas().

Avisos sugeridos:

CondiciónAviso
Conectado en falseSin conexión; las notas se transmitirán al volver la red
PendentesTransmissao mayor que 0Cantidad por transmitir; muéstrela junto al plazo PrazoTransmissaoAte
OfflineAte cercaEl tiempo offline está por agotarse; conéctese cuanto antes
CertificadoValidoAte cercaEl certificado está por vencer; tras renovarlo llame TrocarCertificado
Situacao distinto de AtivoEl dispositivo ya no puede emitir notas nuevas; contacte al integrador
UltimoErro con valorMotivo del último fallo de sincronización; envíelo al soporte técnico al diagnosticar
Avisos no vacíoHay que ajustar el entorno de ejecución, por ejemplo falta el parámetro de inicio que exige la autenticación del proxy en el modo en proceso de Java; vea Proxy de salida. Muestre el texto original al personal técnico

Errores posibles

Solo los errores comunes.

Ejemplos

java
Resultados.Nucleo s = nfce.situacao();
for (Map<String, Object> empresa : s.getEmpresas()) {
System.out.println(empresa.get("empresaId") + " conectado=" + empresa.get("conectado"));
}
for (String aviso : s.getAvisos()) {
System.out.println("aviso: " + aviso);
}

SincronizarAgora

Dispara de inmediato una ronda de sincronización: heartbeat, renovación de la licencia, transmisión de las notas offline, envío de las cancelaciones en cola y descarga de los resultados de la plataforma. El núcleo ya sincroniza solo de forma periódica; este método sirve para acortar la espera, por ejemplo cuando el PDV detecta que volvió la red o antes del cambio de turno para terminar de transmitir.

La sincronización sigue en segundo plano; los resultados llegan por eventos, o se ven después con Consultar y Situacao. La llamada solo dispara la siguiente ronda de sincronización en segundo plano y retorna de inmediato, sin esperar el resultado, así que puede hacerse directamente en el hilo de la interfaz; si ya hay una ronda en curso para una empresa, no se ejecuta otra en paralelo y la sincronización sigue en cuanto esa ronda termina. Sin red no da error.

Red: Dispara la conexión, sin esperar el resultado de la sincronización; la llamada retorna de inmediato.

Firma

java
public void sincronizarAgora();

Parámetros

Ninguno.

Retorno

Ninguno.

Errores posibles

Solo los errores comunes.

Ejemplos

java
// Solo dispara la siguiente ronda en segundo plano y retorna de inmediato; puede llamarse directamente en el hilo de la interfaz
nfce.sincronizarAgora();

Backup

Hace una copia de seguridad cifrada de la base local en un archivo, para conservar copias periódicas o protegerla antes de cambiar el disco. La copia de seguridad toma una instantánea completa de un momento dado, y mientras tanto se puede seguir emitiendo con normalidad. La estrategia de copias y el flujo completo de recuperación de un equipo dañado están en Operación y tareas avanzadas: copia de seguridad y recuperación de un equipo dañado.

  • Cifrado: la clave se deriva de la contraseña con PBKDF2-SHA256 y toda la base se cifra con AES-256-GCM. Ni el SDK ni la plataforma guardan la contraseña: si se pierde la contraseña, la copia de seguridad no se puede restaurar. Guárdela separada del archivo de copia de seguridad.
  • Solo se puede restaurar en la misma computadora y con el mismo usuario de Windows: la clave del dispositivo en la base local está protegida a nivel de usuario de Windows; en otra computadora o con otro usuario de Windows la copia de seguridad no sirve, y hay que desactivar el dispositivo anterior y emparejar de nuevo.
  • Restauración: use RestaurarBackup. La versión del SDK y del runtime usada para restaurar no puede ser inferior a la de la copia de seguridad; VersaoBanco del resultado registra la versión de estructura de la base local.
  • Escritura: primero escribe un archivo temporal y luego lo renombra; si falla, no queda un archivo de copia de seguridad incompleto.

Red: No hace falta. La espera máxima es de al menos 30 minutos, o el tiempo límite por llamada si se configuró uno mayor; con una base local grande tarda varios minutos, no lo llame en el hilo de la interfaz. Si la espera se agota (10029833), el runtime puede seguir escribiendo el archivo: no reintente enseguida con el mismo nombre de archivo; espere un momento y use un nombre de archivo nuevo.

Firma

java
public Resultados.Backup backup(Path destino, String senha);

Parámetros

ParámetroJavaObligatorioDescripción
Archivo de copiadestinoSíRuta del archivo de copia. El archivo no debe existir; una ruta relativa se convierte en absoluta a partir del directorio actual del software de caja
ContraseñasenhaSíContraseña de la copia de seguridad. Al menos 8 caracteres; para restaurar hay que dar la misma contraseña; no se registra en el log

Retorno

Resultado de la copia, campos en Tipos de datos: Resultado de la copia de seguridad.

Errores posibles

CódigoSituaciónAcción
10029874Contraseña vacía, Detalhes.campo es senhaInforme la contraseña
10029817Contraseña de menos de 8 caracteresUse una contraseña más larga
10029844El archivo de destino ya existe, o el directorio no tiene permiso de escrituraCambie el nombre del archivo o el directorio; revise el espacio en disco y los permisos

También puede devolver los errores comunes.

Ejemplos

java
Resultados.Backup b = nfce.backup(Paths.get("D:/Backup/tffiscal-20261031.bak"), senhaBackup);
System.out.println(b.getArquivo() + " " + b.getBytes() + " sha256=" + b.getSha256());

RestaurarBackup

Vuelve a la base local de una copia de seguridad cifrada generada con Backup, para recuperarse después de perder o dañar la base local o de un error de operación. Es un método estático y se llama antes de Iniciar: no inicia el motor ni se conecta a la red; en el modo subproceso, el SDK levanta temporalmente un runtime que termina al completar la restauración. Al llamarlo no debe haber ninguna instancia en ejecución con este directorio de datos; si ya hay una instancia iniciada, primero llame Encerrar y, al terminar la restauración, Iniciar. Cuándo usar la copia de seguridad y cuándo exportar el paquete de pendientes está en Operación y tareas avanzadas: copia de seguridad y recuperación de un equipo dañado.

  • Solo se restaura en la computadora original: la clave del dispositivo incluida en la copia de seguridad está protegida por la protección de datos de Windows y solo puede usarse en la misma computadora y con el mismo usuario de Windows que generaron la copia. Al cambiar de computadora o de usuario de Windows no dependa de la copia de seguridad: exporte las notas pendientes de transmisión con ExportarPendentes, entréguelas a la plataforma y vuelva a emparejar la computadora nueva.
  • Base original guardada aparte: antes de restaurar, la base original del directorio de datos se renombra y se guarda aparte (el nombre empieza por nfce.db.antes-restauracao-), y CopiaAnterior del resultado da la ruta; si la restauración falla, la base original no se toca.
  • Versión: si la versión de estructura de la base local de la copia de seguridad es superior a la del SDK actual, se rechaza; si es inferior, se actualiza sola en el próximo Iniciar.
  • Protección después de restaurar: los números y las licencias de la copia de seguridad quedaron en el momento de la copia. Tras restaurar y llamar Iniciar, cada empresa primero pasa por un realineamiento: la emisión offline devuelve 10029811 y la emisión en línea se sincroniza una vez con la plataforma antes de tomar un número. Cuando llega una licencia nueva, la numeración de la serie del dispositivo salta 50 números hacia adelante, un único salto compartido por las notas en línea y offline; los números saltados se declaran inutilizados automáticamente ante la plataforma (el resultado llega por el evento NUMERO_INUTILIZADO) y luego la emisión en línea y offline siguen con normalidad. Hasta terminar el realineamiento no se puede emitir sin llegar a la plataforma. Aunque las notas emitidas después de la copia de seguridad ya se hayan entregado a los consumidores, no se repiten números.
  • Notas offline emitidas después de la copia de seguridad: no están en ella. Si la base anterior todavía inicia, antes de restaurar llame ExportarPendentes con la base anterior y entregue lo exportado a la plataforma; de lo contrario esas notas se pierden.

Red: No hace falta. La espera máxima es de al menos 30 minutos, o el tiempo límite por llamada si se configuró uno mayor; no lo llame en el hilo de la interfaz.

Firma

java
public static Resultados.Restauracao restaurarBackup(Configuracao config, Path origem, String senha);

Parámetros

ParámetroJavaObligatorioDescripción
ConfiguraciónconfigSíConfiguración de inicio. La misma que se usa en Iniciar; de ella se toman el directorio de datos y la ubicación del runtime; vea Configuración
Archivo de copiaorigemSíRuta del archivo de copia de seguridad. Una ruta relativa se convierte en absoluta a partir del directorio actual del software de caja
ContraseñasenhaSíContraseña de la copia de seguridad. La que se usó al generar la copia de seguridad

Retorno

Resultado de la restauración, campos en Tipos de datos: Resultado de la restauración.

Errores posibles

CódigoSituaciónAcción
10029846Contraseña incorrecta, o el archivo de copia de seguridad fue modificado, está dañado o no es una copia de seguridad de este SDK; no se distingue entre ambos casosVerifique la contraseña; use otra copia de seguridad íntegra. La base original no se modificó
10029842La copia de seguridad viene de una versión más nueva del SDKActualice el SDK y el runtime a una versión no inferior a la de la copia de seguridad
10029828Hay otro motor en ejecución sobre el directorio de datos, incluida una instancia de este mismo programa en la que todavía no se llamó Encerrar. El RestaurarBackup estático del SDK abre su propia conexión con el runtime en cada llamada, y este es el código que recibePrimero llame Encerrar en la instancia que usa este directorio de datos y luego restaure
10029875Se llamó al método de protocolo de restauración restaurarBackup en una conexión con el runtime que ya ejecutó Iniciar. El RestaurarBackup estático del SDK abre una conexión nueva en cada llamada y nunca recibe este código; solo aparece al integrarse directamente con el protocolo del runtimeLlame Encerrar y restaure por una conexión nueva, antes de Iniciar
10029817Contraseña de menos de 8 caracteresIngrese la contraseña usada al generar la copia de seguridad
10029874Archivo de copia de seguridad o contraseña vacíos, Detalhes.campo es origem o senhaComplete los parámetros
10029844Falla al leer o escribir archivosRevise la ruta del archivo de copia de seguridad y el espacio en disco y los permisos del directorio de datos

También puede devolver los errores comunes.

Ejemplos

java
nfce.encerrar();
Resultados.Restauracao r = TfFiscalNfce.restaurarBackup(config, Paths.get("D:/Backup/tffiscal-20261031.bak"), senhaBackup);
System.out.println("versao " + r.getVersaoBanco() + " anterior " + r.getCopiaAnterior());
nfce = TfFiscalNfce.iniciar(config);
// Sin licencia nueva la emisión offline queda suspendida; sincroniza una ronda de inmediato (ejecute este bloque en un hilo de fondo)
nfce.sincronizarAgora();

ExportarPendentes

Exporta las notas offline firmadas y aún no transmitidas de este equipo como un paquete de pendientes que la plataforma importa directamente. Sirve cuando la caja se dañó o no puede conectarse por mucho tiempo y no alcanza a transmitir desde este equipo. La exportación no cambia el estado del equipo: esas notas siguen en la cola de transmisión local. Los pasos completos ante un equipo dañado están en Operación y tareas avanzadas: copia de seguridad y recuperación de un equipo dañado.

Cada llamada crea en el directorio de destino un subdirectorio nuevo con el nombre del momento de la exportación (UTC), con un directorio por dispositivo y hasta 500 notas por paquete:

text
{diretorio}/pendentes-20261111-150000/{dispositivoId}/pacote-001/manifesto.json
/pacote-001/{chave}.xml
/pacote-002/…
  • {diretorio} es el directorio de destino pasado en la llamada, {dispositivoId} es el identificador del dispositivo y {chave} es la clave de acceso de 44 dígitos.
  • Cada manifiesto manifesto.json registra el dispositivo al que pertenece e incluye cada nota junto con su XML firmado, y puede entregarse directamente a la plataforma para importarlo; el {chave}.xml del mismo directorio es el mismo XML firmado, para consulta manual.
  • Para entregarlo a la plataforma, 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», sin descomprimirlo ni separarlo por paquete o por dispositivo. Con varias empresas, el zip contiene varios directorios de dispositivo; el equipo de operación filtra por dispositivo y los envía por tandas.
  • Si no hay notas pendientes de transmisión no da error: Quantidade es 0, Manifesto está vacío y Manifestos es un arreglo vacío.
  • El manifiesto se escribe primero en un archivo temporal y luego se renombra, por lo que un manifiesto leído siempre está completo.

Red: No hace falta. La espera máxima es de al menos 30 minutos, o el tiempo límite por llamada si se configuró uno mayor; no lo llame en el hilo de la interfaz. Si la espera se agota (10029833), el runtime puede seguir escribiendo archivos: no reintente enseguida con el mismo directorio; espere un momento y vuelva a exportar a un directorio nuevo.

Firma

java
public Resultados.ExportacaoPendentes exportarPendentes(Path diretorio);

Parámetros

ParámetroJavaObligatorioDescripción
Directorio de destinodiretorioSíDirectorio de exportación. Una ruta relativa se convierte en absoluta a partir del directorio actual del software de caja

Exporta las notas pendientes de todas las empresas emparejadas en este directorio de datos; el dispositivo de cada empresa tiene su propio directorio y sus propios manifiestos, y el manifiesto registra la empresa de cada nota.

Retorno

Resultado de la exportación, campos en Tipos de datos: Resultado de la exportación de pendientes.

Errores posibles

CódigoSituaciónAcción
10029844Directorio sin permiso de escrituraCambie de directorio; revise el espacio en disco y los permisos

También puede devolver los errores comunes.

Ejemplos

java
Resultados.ExportacaoPendentes p = nfce.exportarPendentes(Paths.get("E:/Pendentes"));
System.out.println(p.getQuantidade() + " notas, " + p.getManifestos().size() + " pacote(s)");

CriarTerminal

Emite, en el principal, el token de terminal de un secundario. El nombre es la identificación de la caja en las notas que emite ese secundario; use un número de caja que la tienda reconozca, por ejemplo Caixa 2. El token completo aparece una sola vez, en este retorno, y el principal guarda solo un resumen: configúrelo en el momento en TokenTerminal del secundario; si se pierde, revóquelo y emita otro. Solo en modo principal; el despliegue y la gestión de los secundarios están en Varias cajas (modo principal y secundario).

Red: No hace falta.

Firma

java
public Resultados.TerminalCriado criarTerminal(String nome);

Parámetros

ParámetroJavaObligatorioDescripción
Nombre del terminalnomeSíNombre de la caja. De 1 a 60 caracteres; no se puede repetir entre terminales activos, sin distinguir mayúsculas

Retorno

El terminal nuevo; campos en Tipos de datos: terminal secundario.

Errores posibles

CódigoSituaciónAcción
10029874Nombre vacío, con más de 60 caracteres, o repetido entre terminales activos (Detalhes.motivo es duplicado)Use otro nombre; para reutilizar un nombre antiguo, revoque antes el terminal antiguo
10029884No está en modo principalLlámelo solo en el principal

También puede devolver los errores comunes.

Ejemplos

java
Resultados.TerminalCriado t = principal.criarTerminal("Caixa 2");
// El token completo llega solo esta vez; configúrelo en la caja 2 en el momento
System.out.println(t.getId() + " " + t.getToken());

ListarTerminais

Lista, en el principal, los terminales secundarios, del más nuevo al más antiguo, sin los tokens. Por defecto oculta los terminales revocados hace más de 30 días; con todos en true lista todos. Los registros se conservan siempre. Solo en modo principal.

Red: No hace falta.

Firma

java
public List<Resultados.Terminal> listarTerminais(boolean todos);

Parámetros

ParámetroJavaObligatorioDescripción
Listar todostodosNoIncluye terminales revocados hace más de 30 días. Por defecto false

Retorno

Lista de terminales; campos en Tipos de datos: terminal secundario.

Errores posibles

CódigoSituaciónAcción
10029884No está en modo principalLlámelo solo en el principal

También puede devolver los errores comunes.

Ejemplos

java
for (Resultados.Terminal t : principal.listarTerminais(false)) {
System.out.println(t.getNome() + " " + t.getSituacao() + " " + t.getUltimoUsoEm());
}

RevogarTerminal

Revoca, en el principal, el token de terminal de un secundario, con efecto inmediato: las llamadas siguientes de ese secundario devuelven 10029882 y los eventos aún no entregados a él se descartan. Úselo cuando un secundario se pierda, se retire o se filtre su token. La revocación no se puede deshacer; emita otro token cuando haga falta. Solo en modo principal.

Red: No hace falta.

Firma

java
public void revogarTerminal(String id);

Parámetros

ParámetroJavaObligatorioDescripción
Identificador del terminalidSíEl id devuelto por CriarTerminal, empieza con trm_

Retorno

Ninguno.

Errores posibles

CódigoSituaciónAcción
10029888Terminal no encontradoRevise el id con ListarTerminais
10029884No está en modo principalLlámelo solo en el principal

También puede devolver los errores comunes.

Ejemplos

java
principal.revogarTerminal("trm_8Kq2Xc0vLm4R");

Encerrar

Cierra el SDK: detiene la sincronización en segundo plano, espera a que terminen las emisiones en curso (hasta 10 segundos), cierra la base local y termina el runtime (si a los 5 segundos sigue activo, lo fuerza a terminar). Todo el proceso dura como máximo unos 15 segundos. Llámelo antes de cerrar el PDV. Se puede llamar varias veces; después del cierre, cualquier otro método devuelve 10029834 y hay que llamar de nuevo Iniciar.

Mientras está cerrado no se transmite; tras el siguiente Iniciar se sincroniza de inmediato una ronda, y si aún hay notas por transmitir o eventos sin confirmar se emite PENDENCIAS_NA_INICIALIZACAO. Lo que hay que tener en cuenta al salir y reiniciar está en Operación y tareas avanzadas: cierre y reinicio.

Red: No hace falta.

Firma

java
public void encerrar();
public void close();

close equivale a Encerrar y funciona con try-with-resources.

Parámetros

Ninguno.

Retorno

Ninguno.

Errores posibles

No lanza errores y se puede llamar varias veces.

Ejemplos

java
Runtime.getRuntime().addShutdownHook(new Thread(nfce::encerrar));

Tipos de datos

Los objetos de resultado que devuelven los métodos, los valores de estado de los eventos y los parámetros del certificado. Las columnas de las tablas se leen así:

  • Nombre JSON: nombre del campo en el texto original de getJson().
  • Java: método de lectura; los campos marcados «por getCampos()» no tienen método propio y se leen con getCampos().get("nombre").
  • Los campos de fecha son texto ISO 8601 UTC.
  • Todos los resultados conservan el texto original (getJson()); los campos que agregue una versión nueva del runtime también se leen desde el original con un SDK antiguo.
  • Los campos con «Null» en «Sí» pueden venir en null.

Estado de la nota

Valores de Status en el resultado de la emisión, el estado de consulta y los eventos.

ValorSignificadoQué hace el PDV
AutorizadaAutorizadaImprime el cupón
ContingenciaPendenteFirmada offline en el equipo, pendiente de transmisiónImprime el cupón y lo entrega al consumidor; la transmisión es automática
AguardandoAutorizacaoAceptada en línea, la SEFAZ aún no respondióNo imprime todavía; espera el evento de autorización; si después se rechaza, llega NOTA_NEGADA
NegadaLa SEFAZ rechazó la nota enviada en línea, incluidas las que se rechazaron después de esperar autorización (evento NOTA_NEGADA)No admite corrección con el mismo número; corrige los datos de la venta y emite de nuevo con un id nuevo
RejeitadaLa SEFAZ rechazó la nota offline transmitida (evento NOTA_REJEITADA)Corrige con el mismo número usando Substituir; no se puede emitir otra
RecusadaLa plataforma no aceptó la nota offlineRequiere atención manual; contacte a la plataforma
CanceladaCanceladaNada

Resultado de la emisión

Retorno de Emitir y Substituir. Java ResultadoEmissao.

Nombre JSONJavaTipoNullDescripción
idgetId()TextoNoIdentificador de la nota. El id de la solicitud de emisión
statusgetStatus()TextoNoEstado de la nota. Valores arriba
emitidaEmContingenciaisEmitidaEmContingencia()BooleanoNoIndicador de firma offline. Sigue en true después de autorizada
chavegetChave()TextoSíClave de acceso. 44 dígitos
seriegetSerie() (Long)EnteroSíSerie
numerogetNumero() (Long)EnteroSíNúmero de la nota
dataEmissaogetDataEmissao()FechaSíFecha de emisión
protocologetProtocolo()TextoSíNúmero de protocolo de autorización. null mientras está pendiente de transmisión offline
qrCodegetQrCode()TextoSíContenido del QR Code. Codifíquelo como QR si arma el cupón por su cuenta
urlConsultagetUrlConsulta()TextoSíURL de consulta para el consumidor
motivogetMotivo()TextoSíDescripción del motivo. Viene de la SEFAZ o de la plataforma
cStatgetCStat() (Long)EnteroSíCódigo de resultado de la SEFAZ. null si no hay resultado de la SEFAZ
xMotivogetXMotivo()TextoSíMensaje de resultado de la SEFAZ. Viene junto con el código de resultado
tentativaOnlineisTentativaOnline()BooleanoNoIndicador de intento en línea. true si intentó en línea y pasó a offline con resultado incierto; esta nota usa el número siguiente al del intento en línea y, al transmitir, la plataforma resuelve ese número original; false para notas autorizadas en línea
respostaPlataformagetRespostaPlataforma()TextoSíRespuesta original de la plataforma. En la emisión en línea, el JSON devuelto por la plataforma, con la estructura de Consultar NFC-e; null en offline
terminalgetTerminal()TextoSíIdentificación de la caja. En las notas emitidas por un secundario en modo principal y secundario, el nombre del terminal; null en las notas emitidas por el propio principal o en modo independiente. Se envía a la plataforma junto con la nota; mismo valor que terminal en Consultar NFC-e y en los webhooks

Estado de consulta

Retorno de Consultar y elemento de la página de notas. Java SituacaoNota; incluye todos los campos del resultado de la emisión, más:

Nombre JSONJavaTipoNullDescripción
transmitidaisTransmitida()BooleanoNoIndicador de transmisión. La nota offline ya se transmitió a la plataforma
cancelamentoPendenteisCancelamentoPendente()BooleanoNoIndicador de cancelación pendiente. Hay una cancelación pendiente o en cola en el equipo
correcoesgetCorrecoes() (Long)EnteroNoCantidad de correcciones
atualizadoEmgetAtualizadoEm()FechaSíFecha de la última actualización
xmlAutorizadoDisponivelisXmlAutorizadoDisponivel()BooleanoNoIndicador de XML local listo. true cuando el XML autorizado ya está en el equipo y XmlAutorizado lo lee directamente; si la nota está autorizada pero vale false, la llamada lo recupera por la red
pedidogetPedido()TextoSíSolicitud de emisión. Texto JSON, base para la corrección con el mismo número; los ítems que referenciaban una clase de impuesto ya llevan los impostos expandidos por la plataforma, que se pueden guardar para enviar sin red

Página de notas

Retorno de ListarNotas. Java Resultados.PaginaNotas.

Nombre JSONJavaTipoNullDescripción
itensgetItens()ArrayNoNotas de la página. Los elementos son estado de consulta, de la emisión más reciente a la más antigua
paginagetPagina()EnteroNoNúmero de página. Empieza en 1
tamanhoPaginagetTamanhoPagina()EnteroNoNotas por página. Siempre 50
temMaisisTemMais()BooleanoNoIndicador de página siguiente. No se informa el total

Resultado de la vista previa

Retorno de Previsualizar. Java Resultados.PreVisualizacao.

Nombre JSONJavaTipoNullDescripción
validoisValido()BooleanoNoIndicador de validación aprobada
errosgetErros()Array de textoNoErrores de validación. Ya traducidos al idioma de errores; array vacío si pasa
pedidoNormalizadogetPedidoNormalizado()TextoSíSolicitud normalizada. Texto JSON, en general no se usa
valorTotalgetValorTotal() (BigDecimal)DecimalSíTotal de la nota
valorTributosgetValorTributos() (BigDecimal)DecimalSíTotal de impuestos

Resultado de la cancelación

Retorno de Cancelar y de CancelarPorSubstituicao. Java Resultados.Cancelamento.

Nombre JSONJavaTipoNullDescripción
situacaogetSituacao()TextoNoDestino de la solicitud. Valores abajo
motivogetMotivo()TextoSíDescripción
situacaoSignificado
SolicitadoNota autorizada; la cancelación ya se envió a la plataforma y el resultado llega por el evento CANCELAMENTO_CONCLUIDO o CANCELAMENTO_REJEITADO
AgendadoNota offline transmitida y aún no autorizada; la plataforma deja la cancelación pendiente y la ejecuta sola tras la autorización
EnfileiradoLocalCola local: sin red, o la nota offline / sustituta aún no se transmitió; se envía en la misma ronda justo después de la transmisión

Información del código de emparejamiento

Retorno de InspecionarCodigoAtivacao. Java Resultados.CodigoAtivacao.

Nombre JSONJavaTipoNullDescripción
ambientegetAmbiente() (Long)EnteroNoAmbiente de emisión. 1 producción, 2 pruebas
formasPermitidasgetFormasPermitidas() (Long)EnteroNoFormas permitidas. 0 cualquier forma, 1 solo el Asistente Fiscal, 2 solo el SDK embebido
expiraEmgetExpiraEm()FechaNoVencimiento del código de emparejamiento
plataformagetPlataforma()TextoNoDirección de la plataforma. Plataforma a la que apunta el código
seriegetSerie() (Long)EnteroSíSerie del dispositivo indicada. La serie que el integrador indicó al generar el código; null si no se indicó, y la plataforma asigna una en el emparejamiento
numeroInicialgetNumeroInicial() (Long)EnteroSíNúmero inicial indicado. Si solo se indicó la serie, el número que la plataforma calculó al generar el código; null si no se indicó, y la numeración empieza en 1

Resultado del emparejamiento

Retorno de Ativar. Java Resultados.Ativacao.

Nombre JSONJavaTipoNullDescripción
empresaIdgetEmpresaId()TextoNoIdentificador de la empresa. Es el empresaId de los demás métodos
dispositivoIdgetDispositivoId()TextoNoIdentificador del dispositivo
cnpjgetCnpj()TextoNoCNPJ de la empresa
ufpor getCampos()TextoNoEstado
ambientepor getCampos()EnteroNoAmbiente de emisión. 1 producción, 2 pruebas
serieOfflinegetSerieOffline() (Long)EnteroNoSerie del dispositivo. Exclusiva de este dispositivo, compartida por las notas en línea y offline con numeración continua; se mantuvo el nombre del campo
licencaExpiraEmgetLicencaExpiraEm()FechaSíVencimiento de la licencia
numeroInicialgetNumeroInicial() (Long)EnteroNoNúmero inicial. Número de la primera nota de este dispositivo; 1 si el código no lo indicó

Empresa emparejada

Elemento de Empresas. Java Resultados.EmpresaAtivada.

Nombre JSONJavaTipoNullDescripción
empresaIdgetEmpresaId()TextoNoIdentificador de la empresa
dispositivoIdgetDispositivoId()TextoNoIdentificador del dispositivo
cnpjgetCnpj()TextoNoCNPJ de la empresa
ufpor getCampos()TextoNoEstado
ambientepor getCampos()EnteroNoAmbiente de emisión. 1 producción, 2 pruebas
serieOfflinepor getCampos()EnteroNoSerie del dispositivo
situacaogetSituacao()TextoNoEstado del dispositivo. Valores abajo
situacaoSignificadoAcción
AtivoPuede emitirNada
DesativadoEl integrador desactivó el dispositivoIrreversible; para seguir usando la misma computadora hay que emparejarla de nuevo
RevogadoLa plataforma revocó el dispositivoContacte a la plataforma
EmpresaDesativadaLa emisión offline de la empresa está desactivadaContacte a la plataforma
AplicativoBloqueadoEl software de caja fue bloqueado por la plataformaContacte a la plataforma
VersaoBloqueadaLa versión del PDV está bloqueada o por debajo de la mínimaActualice el PDV

Salvo Ativo, ningún estado permite emitir notas nuevas; las notas offline ya emitidas se siguen transmitiendo.

Estado del núcleo

Retorno de Situacao. Java Resultados.Nucleo.

Nombre JSONJavaTipoDescripción
versaoNucleogetVersaoNucleo()TextoVersión del núcleo
empresasgetEmpresas() (elementos clave-valor)ArrayEstado de cada empresa emparejada, campos abajo
avisosgetAvisos()Array de textoAvisos del motor. Problemas del entorno de ejecución que debe resolver el anfitrión; array vacío si no hay. Por ejemplo, se configuró autenticación de proxy, pero en el modo en proceso de Java falta el parámetro de inicio de la JVM que exige la autenticación del proxy o la configuración no surtió efecto; vea Proxy de salida. El texto está en portugués y se puede mostrar tal cual

Elemento de empresas:

Nombre JSONTipoNullDescripción
empresaIdTextoNoIdentificador de la empresa
dispositivoIdTextoNoIdentificador del dispositivo
situacaoTextoNoEstado del dispositivo. Valores como en empresa emparejada
conectadoBooleanoNoIndicador de conexión. Si en este momento llega a la plataforma
ultimoContatoFechaSíÚltimo contacto
licencaExpiraEmFechaSíVencimiento de la licencia
offlineAteFechaSíPlazo de la emisión offline. El menor entre el vencimiento de la licencia y el del certificado
pendentesTransmissaoEnteroNoNotas por transmitir
pendenteMaisAntigaEmFechaSíPendiente más antigua. Fecha de emisión de la nota por transmitir más antigua
prazoTransmissaoAteFechaSíPlazo de transmisión. Plazo de la nota por transmitir más antigua; pasado ese momento el dispositivo no puede seguir emitiendo offline
certificadoValidoAteFechaSíVencimiento del certificado
ultimoErroTextoSíÚltimo error. Motivo del último fallo de sincronización
numerosNaoUtilizadosPendentesEnteroNoRangos pendientes de inutilización. Cantidad de rangos de números tomados y no usados que aún deben declararse como inutilizados ante la plataforma; si la declaración se rechaza sin ser un estado final, se reintenta sola; vea NUMERO_INUTILIZACAO_RECUSADA
restauradoPendenteSincronizacaoBooleanoNoRestauración pendiente de alineación. true tras restaurar una copia de seguridad y hasta recibir una licencia nueva; mientras tanto la emisión offline devuelve 10029811 y la en línea sincroniza antes con la plataforma; false tras la alineación. Úselo para pedir al cajero que se conecte; no interprete el texto del error

Resultado de la exportación de XML

Retorno de ExportarXmls. Java Resultados.ExportacaoXml.

Nombre JSONJavaTipoNullDescripción
quantidadeNotasgetQuantidadeNotas()EnteroNoNotas exportadas. Cantidad de notas con al menos un archivo escrito
quantidadeArquivosgetQuantidadeArquivos()EnteroNoCantidad de archivos. Total de archivos de XML autorizado y de XML de cancelación escritos; una nota cancelada con ambos XML escritos cuenta como dos
arquivosgetArquivos()Array de textoNoArchivos exportados. Rutas absolutas de los archivos escritos, un archivo para el XML autorizado y otro para el XML de cancelación
falhasgetFalhas() (elementos clave-valor)ArrayNoLista de faltantes. Notas del período cuyo XML no se obtuvo; array vacío si no hay; campos de los elementos abajo

Elemento de falhas:

Nombre JSONClave en JavaTipoDescripción
ididTextoIdentificador de la nota
chavechaveTextoClave de acceso
motivomotivoTextoMotivo de la falta. Incluye si se borró al vencer el plazo de retención

Resultado de la copia de seguridad

Retorno de Backup. Java Resultados.Backup.

Nombre JSONJavaTipoNullDescripción
arquivogetArquivo()TextoNoArchivo de copia. Ruta absoluta
bytesgetBytes()EnteroNoTamaño del archivo. En bytes
versaoBancogetVersaoBanco()EnteroNoVersión de estructura de la base local. Para restaurar, la versión del núcleo no puede ser inferior a esta
sha256getSha256()TextoNoResumen del archivo. SHA-256 del archivo de copia de seguridad cifrado, en hexadecimal minúscula

Resultado de la restauración

Retorno de RestaurarBackup. Java Resultados.Restauracao.

Nombre JSONJavaTipoNullDescripción
versaoBancogetVersaoBanco()EnteroNoVersión de estructura de la base local. Versión de la base restaurada; si es inferior a la del SDK actual, se actualiza sola en el próximo inicio
copiaAnteriorgetCopiaAnterior()TextoSíCopia de la base original. Ruta absoluta del archivo de la base original guardado aparte antes de restaurar; vacío si antes no había base

Resultado de la exportación de pendientes

Retorno de ExportarPendentes. Java Resultados.ExportacaoPendentes.

Nombre JSONJavaTipoNullDescripción
quantidadegetQuantidade()EnteroNoNotas exportadas
manifestogetManifesto()TextoSíPrimer manifiesto. Ruta absoluta del manifesto.json del primer paquete; vacío si no hay notas pendientes
manifestosgetManifestos()Array de textoNoTodos los manifiestos. Uno por cada pacote-NNN dentro de cada directorio de dispositivo, con hasta 500 notas por paquete; array vacío si no hay notas pendientes
arquivosgetArquivos()Array de textoNoArchivos XML firmados. Rutas absolutas

Origen del certificado

Parámetro de certificado de Ativar y TrocarCertificado.

OrigenJava
Certificado ya presente en el almacén de certificados de WindowsCertificado.doRepositorio(thumbprint, maquinaLocal)
Archivo PFXCertificado.deArquivoPfx(bytes, senha)
ParámetroDescripción
thumbprintHuella del certificado. SHA-1 en 40 dígitos hexadecimales; los espacios se ignoran; un formato inválido devuelve 10029874
maquinaLocalIndicador del almacén del equipo. true usa el almacén de certificados del equipo; false (por defecto) el del usuario de Windows actual
Bytes del PFX y senhaCertificado PFX y contraseña. El núcleo importa el certificado al almacén con la clave privada no exportable y después guarda solo la huella; la contraseña no se guarda

Al emparejar o cambiar el certificado con PFX (Certificado.deArquivoPfx), el núcleo importa el certificado al almacén "Usuario actual > Personal" del usuario de Windows que ejecuta el SDK, con la clave privada no exportable, y lo conserva allí de forma permanente: cada firma lo usa. No borre este certificado: sin él el dispositivo no puede firmar y la emisión devuelve 10029813.

Cuando el dispositivo deje de usarse, limpie en este orden:

  1. Confirme en el estado que pendentesTransmissao de cada empresa es 0, es decir, que todas las notas offline se transmitieron
  2. Desactive o revoque el dispositivo en la consola; si solo cambia el certificado, instale antes el nuevo con TrocarCertificado
  3. Con el mismo usuario de Windows, abra certmgr.msc y borre el certificado antiguo en "Personal > Certificados" por su huella, o ejecute en PowerShell Remove-Item Cert:\CurrentUser\My\<huella>

Terminal secundario

Retorno de CriarTerminal. Java Resultados.TerminalCriado.

Nombre JSONJavaTipoNullDescripción
idgetId()TextoNoIdentificador del terminal. Empieza con trm_, se usa para revocar
nomegetNome()TextoNoNombre del terminal. La identificación de la caja en las notas que emite ese secundario
tokengetToken()TextoNoToken del terminal. Empieza con tfl_, llega una sola vez; configúrelo en TokenTerminal del secundario

Elementos de ListarTerminais. Java Resultados.Terminal; sin el token.

Nombre JSONJavaTipoNullDescripción
idgetId()TextoNoIdentificador del terminal
nomegetNome()TextoNoNombre del terminal
situacaogetSituacao()TextoNoEstado del terminal. Ativo o Revogado
criadoEmgetCriadoEm()Fecha y horaNoMomento de emisión del token
ultimoUsoEmgetUltimoUsoEm()Fecha y horaSíÚltimo uso. null si nunca se usó
revogadoEmgetRevogadoEm()Fecha y horaSíMomento de la revocación. null en terminales activos

Excepción

Todos los fallos lanzan una excepción.

CampoJava TfFiscalExceptionDescripción
Código de errorgetCodigo()Entero. Decida por él, vea Códigos de error
Constante de errorgetTipo()Por ejemplo ENGINE_LICENSE_EXPIRED; en errores de la plataforma, el nombre de constante de la plataforma
MensajegetMessage()Traducido al idioma de errores configurado; se puede mostrar directamente
Información adicionalgetDetalhes(), getDetalhesJson()Por ejemplo erros con los motivos campo por campo en una solicitud inválida, o campo en un parámetro inválido

Constantes de códigos: TfFiscalErrorCodes registra los códigos habituales; los códigos no registrados aparecen igual, como número, en el campo de código de error.

Eventos

Eventos locales que el núcleo entrega al PDV cuando cambian el estado de las notas, la licencia, el certificado, la conexión y otros. Los webhooks que la plataforma envía al servidor del integrador son otro canal, vea Cómo llegan los resultados; qué eventos recibe un secundario en modo principal y secundario está en Varias cajas (modo principal y secundario).

Suscripción

Forma de suscripciónHilo del callback
aoReceberEvento(Consumer<EventoNfce>) en la configuración, o el método de instancia aoReceberEvento, cuyo retorno al cerrarse cancela la suscripciónEn modo subproceso, uno por vez en un hilo dedicado del SDK; en modo en proceso, llamada síncrona en el hilo de entrega del núcleo. Si el manejador lanza una excepción, no se confirma

Si conecta el manejador al inicio con aoReceberEvento en la configuración, no se pierden los eventos acumulados antes del inicio.

Entrega y confirmación

  • Al menos una vez y en orden: el evento se guarda en el equipo en la misma transacción que el cambio de estado que lo provoca, y después se entrega.
  • Confirmación: si el manejador retorna normalmente, el evento queda confirmado. Si lanza una excepción, no se confirma y unos 30 segundos después se reenvía a partir del evento más antiguo sin confirmar, con el mismo EventoId y Seq.
  • Deduplicación: el mismo evento puede llegar varias veces; deduplique por EventoId.
  • No bloquee el manejador mucho tiempo: registre el evento y haga el trabajo pesado de forma asíncrona, si no los eventos siguientes se acumulan.
  • Eventos locales del SDK: RUNTIME_FALHOU y RUNTIME_REINICIADO los genera el propio SDK, con Seq en 0; no necesitan confirmación ni se reenvían.

Campos comunes

Nombre JSONJavaTipoNullDescripción
eventoIdgetEventoId()TextoNoIdentificador del evento. Clave de deduplicación, no cambia en el reenvío
seqgetSeq() (long)EnteroNoSecuencia local. Creciente; 0 en los eventos locales del SDK
tipogetTipo()TextoNoTipo de evento. Vea cada sección abajo
ocorridoEmgetOcorridoEm()Texto de fechaNoFecha del evento. ISO 8601 UTC
empresaIdgetEmpresaId()TextoSíIdentificador de la empresa. null en los eventos locales del SDK
dispositivoIdpor getCampos()TextoSíIdentificador del dispositivo
idgetId()TextoSíIdentificador de la nota. Solo en eventos de nota
chavegetChave()TextoSíClave de acceso. Solo en eventos de nota
statusgetStatus()TextoSíEstado actual de la nota. Solo en eventos de nota; valores en Estado de la nota
dadosgetDados() (Map<String, Object>)ObjetoNoDatos del evento. Campos en cada sección abajo

NOTA_EMITIDA_OFFLINE

Firma offline exitosa. Evento de nota, con status en ContingenciaPendente.

Campo de dadosTipoDescripción
serieEnteroSerie del dispositivo
numeroEnteroNúmero de la nota
qrCodeTextoContenido del QR Code
tentativaOnlineBooleanoIndicador de intento en línea. true si intentó en línea y pasó a offline con resultado incierto; false para notas autorizadas en línea

Acción: marque la venta como «offline pendiente de transmisión». El mismo resultado ya llegó por Emitir en el momento de la emisión; este evento sirve sobre todo para completar el estado si el PDV se cayó y reinició.

NOTA_AUTORIZADA

Nota offline autorizada tras la transmisión, autorizada tras la corrección con el mismo número, o nota en línea pendiente que se autorizó. Evento de nota, con status en Autorizada.

Campo de dadosTipoDescripción
protocoloTextoNúmero de protocolo de autorización
dataAutorizacaoTexto de fecha, admite nullFecha de autorización
foraDoPrazoBooleanoIndicador de entrega fuera de plazo. true si llegó a la SEFAZ después de 24 horas; la nota sigue siendo válida
aposCorrecaoBooleanoIndicador de autorización tras corrección. true si se autorizó tras la corrección con el mismo número

Acción: marque la venta como autorizada y guarde el protocolo; en una nota en línea que estaba pendiente, ahora se puede imprimir el cupón.

NOTA_REJEITADA

La SEFAZ rechazó la nota offline transmitida. Evento de nota, con status en Rejeitada.

Campo de dadosTipoDescripción
cStatEnteroCódigo de resultado de la SEFAZ
motivoTextoMensaje de resultado de la SEFAZ

Acción: avise al administrador para corregir con el mismo número usando Substituir; no se puede emitir otra nota. La solicitud original está en Pedido de Consultar.

NOTA_NEGADA

Una nota enviada en línea que esperaba autorización (AguardandoAutorizacao) fue rechazada después por la SEFAZ. Evento de nota, con status en Negada. Cuando se rechaza la transmisión de una nota offline no se emite este evento, sino NOTA_REJEITADA.

Campo de dadosTipoDescripción
cStatEnteroCódigo de resultado de la SEFAZ
motivoTextoMensaje de resultado de la SEFAZ
numeroLiberadoBooleanoNúmero recuperado. Cuando es true, la SEFAZ no usó este número; el kernel lo reserva para la próxima nota emitida en línea, sin dejar saltos en la numeración

Acción: esta nota no admite corrección con el mismo número. Corrija los datos de la venta según el código y el mensaje de resultado y llame de nuevo Emitir con un id nuevo.

NOTA_RECUSADA_PLATAFORMA

La plataforma no aceptó la nota offline. Evento de nota, con status en Recusada.

Campo de dadosTipoDescripción
codigoEntero, admite nullCódigo de error de la plataforma
mensagemTextoMensaje de la plataforma

Acción: requiere atención manual; registre el código y el mensaje y contacte a la plataforma.

CANCELAMENTO_CONCLUIDO

Cancelación exitosa. Evento de nota, con status en Cancelada.

Campo de dadosTipoDescripción
cStatEntero, admite nullCódigo de resultado de la SEFAZ
motivoTextoMensaje del resultado
protocoloTexto, admite nullNúmero de protocolo de la cancelación

Acción: marque la venta como cancelada.

CANCELAMENTO_REJEITADO

Cancelación rechazada, por ejemplo por plazo vencido, o porque la plataforma rechazó la cancelación pendiente. Evento de nota, con status en el estado original de la nota.

Campo de dadosTipoDescripción
cStatEntero, admite nullCódigo de resultado de la SEFAZ
motivoTextoMotivo del rechazo
protocoloTexto, admite nullNúmero de protocolo

Acción: la nota sigue siendo válida. Avise al administrador para resolverlo según las reglas de Cancelar NFC-e.

NUMERO_INUTILIZADO

Los números de la serie del dispositivo tomados pero no firmados quedaron cerrados: inutilizados en la SEFAZ o, en estados que ya no aceptan la inutilización como AC, BA y SP, dispensados de declararse por norma. En ambos casos cuentan como usados y no se vuelven a emitir. No es un evento de nota.

Campo de dadosTipoDescripción
serieEnteroSerie del dispositivo
inicioEnteroNúmero inicial
fimEnteroNúmero final

Acción: no hace falta nada; puede registrarlo en el log para la conciliación.

NUMERO_INUTILIZACAO_RECUSADA

La plataforma rechazó la inutilización de números no usados. No es un evento de nota. Un rechazo que no es estado final se emite solo en el primer fallo, y luego el núcleo reintenta solo con espera progresiva; un rechazo en estado final requiere revisión manual.

Campo de dadosTipoDescripción
serieEnteroSerie del dispositivo
inicioEnteroNúmero inicial
fimEnteroNúmero final
codigoEnteroCódigo de error de la plataforma
mensagemTextoMensaje de la plataforma
definitivoBooleanoIndicador de estado final. true indica que no se reintentará, por ejemplo con un rango inválido o con notas ya emitidas en el rango; false indica que el núcleo reintenta solo

Acción: con definitivo en false basta registrarlo en el log; la cantidad de rangos pendientes de inutilización está en NumerosNaoUtilizadosPendentes de Situacao. Con true, registre el código y el mensaje de error; el administrador revisa ese rango de números y luego contacta a la plataforma.

DISPOSITIVO_DESATIVADO

Dispositivo desactivado o revocado, emisión offline de la empresa desactivada, o software de caja o versión bloqueados. A partir de ahí se rechazan las notas nuevas; las notas offline ya emitidas se siguen transmitiendo.

Campo de dadosTipoDescripción
situacaoTextoEstado del dispositivo. Valores en Empresa emparejada
motivoTextoMotivo. Puede venir como texto vacío

Acción: muestre en el PDV un aviso destacado «este equipo ya no puede emitir» y, según situacao, contacte al integrador o actualice el PDV.

LICENCA_EXPIRANDO

Quedan menos de 12 horas de licencia y no se pudo renovar, normalmente por una caída larga de la red. Como máximo una vez cada 6 horas.

Campo de dadosTipoDescripción
expiraEmTexto de fechaVencimiento de la licencia
offlineAteTexto de fechaPlazo de la emisión offline

Acción: avise al cajero para restablecer la red cuanto antes; con conexión se renueva sola.

LICENCA_EXPIRADA

La licencia venció: la emisión offline se rechaza, la emisión en línea no se ve afectada.

Campo de dadosTipoDescripción
expiradaEmTexto de fechaFecha de vencimiento

Acción: al restablecer la red se renueva sola.

PRAZO_TRANSMISSAO_PROXIMO

La nota por transmitir más antigua ya consumió el 80% del plazo de transmisión.

Campo de dadosTipoDescripción
pendenteMaisAntigaEmTexto de fechaFecha de emisión de la nota por transmitir más antigua
prazoAteTexto de fechaPlazo de transmisión

Acción: avise de forma destacada al cajero para restablecer la red de inmediato. Pasado el plazo, el equipo no puede seguir emitiendo offline.

CERTIFICADO_EXPIRANDO

El certificado de la empresa vence dentro de 30, 7 o 1 días; un aviso por cada uno.

Campo de dadosTipoDescripción
validoAteTexto de fechaVencimiento del certificado

Acción: avise al administrador para renovar el certificado y, tras renovarlo, llame TrocarCertificado.

CONEXAO_ALTERADA

Cambio entre en línea y offline.

Campo de dadosTipoDescripción
conectadoBooleanoIndicador de conexión. true indica que volvió la conexión

Acción: actualice el indicador en línea / offline del PDV.

PENDENCIAS_NA_INICIALIZACAO

Al iniciar, el equipo todavía tiene notas offline por transmitir o eventos sin confirmar.

Campo de dadosTipoDescripción
pendentesTransmissaoEnteroNotas por transmitir
eventosNaoEntreguesEnteroEventos sin confirmar

Acción: la pantalla del PDV puede avisar «N notas offline por transmitir» y verificar la red; los eventos sin confirmar se reenvían después, sin otra acción.

RUNTIME_FALHOU

Evento local del SDK: el proceso del runtime terminó inesperadamente. Seq en 0. Las llamadas en curso fallan con 10029832.

Campo de dadosTipoDescripción
codigoSaidaEnteroCódigo de salida del proceso
tentativaEnteroIntento de reinicio
proximaTentativaMsEnteroMilisegundos de espera hasta el próximo reinicio

Acción: con el reinicio automático activado no hace falta nada; regístrelo en el log y, si se repite a menudo, exporte los logs y contacte a la plataforma. Para las emisiones que fallaron, reenvíe con el mismo id; el núcleo es idempotente por id.

RUNTIME_REINICIADO

Evento local del SDK: el runtime se reinició solo y se volvió a inicializar. Seq en 0.

Campo de dadosTipoDescripción
tentativaEnteroNúmero de reinicio

Acción: no hace falta nada; los eventos sin confirmar antes del reinicio se reenvían.

Solicitud de emisión

La solicitud de emisión que reciben Emitir, Previsualizar y Substituir es el cuerpo de la interfaz Emitir NFC-e: mismos nombres de campo, mismos valores y mismas reglas de validación; el núcleo y la plataforma usan la misma normalización y validación; referenciar una clase de impuesto requiere conexión, vea la tabla de abajo. La descripción campo por campo, los valores enumerados y los ejemplos por escenario están directamente en Emitir NFC-e.

Hay tres diferencias:

CampoEn el SDK
modoRespostaNo hace falta enviarlo. El SDK siempre espera el resultado; si se envía, se ignora
ambienteEmissaoIgual al ambiente del dispositivo. El ambiente del dispositivo lo fija el código de emparejamiento, vea Generar código de emparejamiento
itens[].classeImpostoDisponible con conexión. La plataforma la expande antes de emitir, con el mismo resultado que la emisión en la nube; sin red o sin acceso a la plataforma devuelve 10029780, en cuyo caso se envía impostos. Vea Clases de impuesto y conexión

El id es la clave de idempotencia: llamar Emitir de nuevo con el mismo id devuelve la nota original; tras una caída, un reinicio o un tiempo agotado, reenvíe con el mismo id, no con uno nuevo.

Cómo se envía la solicitud

La solicitud de emisión se pasa como texto JSON. Con Java 21 o superior en el anfitrión hay además una entrada tipada TfFiscalNfceTipado, con los mismos tipos de solicitud que usa la plataforma; las reglas de classeImposto son las mismas.

Ejemplo de solicitud

Venta presencial, consumidor no identificado, pago en efectivo:

json
{
"id": "PDV01-000131",
"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" }
}
}
]
}

Códigos de error

El Asistente Fiscal y el SDK embebido comparten el núcleo de emisión offline. Sus errores llegan como excepción en el SDK (Codigo es el código y Tipo la constante) y como codigo en la interfaz local del Asistente Fiscal. 10029800 a 10029846 vienen del núcleo y 10029870 a 10029888 del wrapper del SDK, de la comunicación con el runtime y del modo principal y secundario; el resto del rango no está asignado. Los códigos que devuelve la plataforma se transmiten tal cual.

Errores comunes: cualquier método puede devolver 10029832 (el runtime terminó inesperadamente), 10029833 (tiempo de espera agotado), 10029834 (cerrado) y 10029836 (error interno del núcleo); en las operaciones en línea, los errores de negocio de la plataforma se transmiten tal cual. En «Errores posibles» de cada método solo figuran los códigos propios de ese método. Todos los códigos y la acción recomendada están en Códigos de error.

codigoConstanteEscenarioAcción
10029800ENGINE_NOT_STARTEDNo inicializadoNo ocurre en uso normal; si aparece, es un defecto del paquete SDK: inicialice de nuevo
10029801ENGINE_NOT_ACTIVATEDLa empresa no está emparejada en este equipo, o el equipo aún no emparejó ninguna empresaGuíe el emparejamiento; con varias empresas revise empresaId
10029802ENGINE_EMPRESA_REQUIREDHay varias empresas emparejadas y no se indicó empresaIdEnvíe empresaId
10029803ENGINE_LICENSE_MISSINGNo hay licencia para emisión offlineSincronice en línea una vez (SincronizarAgora)
10029804ENGINE_LICENSE_EXPIREDLicencia vencida; la emisión offline se rechaza, la emisión en línea sigue normalRestablezca la red; se renueva sola
10029805ENGINE_LICENSE_SIGNATURE_INVALIDFirma de la licencia inválidaAtención manual: contacte a la plataforma, la base local puede haber sido alterada
10029806ENGINE_LICENSE_NOT_FOR_DEVICELa licencia no pertenece a este dispositivoAtención manual: empareje de nuevo
10029807ENGINE_OFFLINE_WINDOW_CLOSEDPasó el plazo de emisión offlineEmita en línea cuando vuelva la red
10029808ENGINE_LICENSE_QUOTA_EXHAUSTEDLa 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
10029809ENGINE_CLOCK_ROLLBACKEl reloj del sistema retrocedióAtención manual: corrija la hora del sistema
10029810ENGINE_TRANSMISSION_DEADLINE_REACHEDLa nota pendiente más antigua superó el plazo de transmisiónAtención manual: restablezca la red cuanto antes para transmitir
10029811ENGINE_OFFLINE_NOT_ALLOWEDLa empresa o el estado no permite emisión offline; o se acaba de restaurar la copia de seguridad y aún no se obtuvo una licencia nuevaSolo 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
10029812ENGINE_OFFLINE_FUEL_NOT_SUPPORTEDLas notas con combustible no se emiten offlineEmita cuando vuelva la red
10029813ENGINE_CERTIFICATE_UNAVAILABLECertificado no encontrado, sin clave privada o con CNPJ distintoAtención manual: revise el almacén de certificados; si hace falta, TrocarCertificado
10029814ENGINE_CERTIFICATE_EXPIREDCertificado vencidoAtención manual: renueve y llame TrocarCertificado
10029815ENGINE_SNAPSHOT_MISSINGFaltan la configuración local o los datos tributarios, o no pasaron la verificaciónSincronice en línea; si persiste, contacte a la plataforma
10029816ENGINE_DEVICE_DEACTIVATEDDispositivo desactivadoAtención manual: contacte al integrador; las notas offline ya emitidas se siguen transmitiendo
10029817ENGINE_REQUEST_INVALIDSolicitud inválida; Detalhes lista los motivos campo por campoCorrija la solicitud; puede validarla antes con Previsualizar
10029780ENGINE_TAX_CLASS_REQUIRES_ONLINEUn í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
10029818ENGINE_DUPLICATE_ID_DIFFERENT_CONTENTEl mismo id ya se usó con contenido distintoVenta nueva con id nuevo; para reintentar, reenvíe la solicitud original y recupere la nota
10029819ENGINE_NOTE_NOT_FOUNDLa nota no existe en este equipoRevise id y empresaId
10029820ENGINE_NOTE_NOT_CORRECTABLEEl estado actual no permite corregirSolo Rejeitada admite Substituir
10029821ENGINE_CORRECTION_CHANGES_TOTALSLa corrección cambió valores o impuestosCambie solo lo que no afecta valores
10029822ENGINE_CANCEL_NOT_ALLOWEDEl estado actual no permite cancelarNo reintente
10029823ENGINE_SERIE_EXHAUSTEDNumeración de la serie del dispositivo agotadaDesactive 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
10029824ENGINE_PLATFORM_UNREACHABLEUna operación que requiere conexión (emparejamiento) no llega a la plataformaRevise la red y reintente
10029825ENGINE_ACTIVATION_CODE_INVALIDFormato, firma o vigencia del código de emparejamiento incorrectosAtención manual: genere un código nuevo
10029826ENGINE_ACTIVATION_HOST_UNTRUSTEDEl código de emparejamiento apunta a una dirección de plataforma no confiableAtención manual: confirme el origen del código y el ambiente del instalador (pruebas / producción)
10029827ENGINE_KEY_PROTECTION_FAILEDEl directorio de datos viene de otra computadora o de otro usuario de WindowsAtención manual: ejecute en la computadora y el usuario originales, o empareje de nuevo
10029828ENGINE_DATA_DIR_LOCKEDEl directorio de datos está en uso por otro proceso, incluida, al restaurar una copia de seguridad, una instancia de este programa en la que todavía no se llamó EncerrarCierre la otra instancia; antes de restaurar una copia de seguridad, llame Encerrar
10029829ENGINE_LOCAL_STORE_CORRUPTEDBase local inconsistenteAtención manual: no borre el directorio de datos, contacte a la plataforma
10029830ENGINE_PROTOCOL_VERSION_UNSUPPORTEDVersiones de SDK y runtime incompatiblesActualice el SDK y el runtime juntos
10029831ENGINE_RUNTIME_START_FAILEDFalló el inicio del runtimeRevise que el directorio del runtime esté completo y que el antivirus no lo bloquee
10029832ENGINE_RUNTIME_CRASHEDEl runtime terminó inesperadamenteSe puede reintentar; con reinicio automático el SDK se recupera solo, reenvíe la emisión con el mismo id
10029833ENGINE_TIMEOUTTiempo de espera agotadoReenvíe la emisión con el mismo id, o primero Consultar
10029834ENGINE_SHUTTING_DOWNCerrando o ya cerradoLlame de nuevo Iniciar
10029835ENGINE_IN_PROCESS_UNSUPPORTEDEl modo en proceso de Java exige Java 21 o superiorUse el modo subproceso
10029836ENGINE_INTERNAL_ERRORError interno del núcleo; el mensaje trae un número de referenciaContacte a la plataforma con el número de referencia y los logs
10029837ENGINE_ALREADY_ACTIVATEDLa empresa ya está emparejada en este directorio de datosNo hace falta emparejar de nuevo; para cambiar de equipo, desactive antes el dispositivo anterior
10029838ENGINE_PLATFORM_RESPONSE_UNTRUSTEDRespuesta de la plataforma rechazada en la verificación; se conservaron los datos anterioresSe reintenta sola; si persiste, revise si un proxy de red altera las respuestas
10029839ENGINE_ACTIVATION_PERSIST_FAILEDLa plataforma emparejó pero falló el guardado localEmpareje de nuevo con el mismo código de emparejamiento
10029840ENGINE_CONFIG_INVALIDConfiguración de inicio inválidaCorrija la configuración
10029841ENGINE_AUTHORIZED_XML_UNAVAILABLEXML autorizado no disponible: la nota aún no se autorizó, o no está en el equipo y no se pudo recuperar de la plataformaSi no está autorizada, espere el evento de autorización y vuelva a pedirlo; si ya está autorizada, la plataforma todavía no la archivó o no está accesible en este momento; reintente más tarde
10029842ENGINE_LOCAL_STORE_NEWER_VERSIONLa versión de la base local es superior a la del núcleo actual: el directorio de datos ya lo usó una versión más nueva del SDK y el inicio se rechazaActualice el SDK y el runtime a una versión no inferior a la última usada; nunca borre el directorio de datos
10029843ENGINE_CANCEL_XML_UNAVAILABLEXML de cancelación no disponible: la nota no está cancelada, o no está en el equipo y no se pudo recuperar de la plataformaSi no está cancelada, espere CANCELAMENTO_CONCLUIDO y vuelva a pedirlo; si ya está cancelada, reintente más tarde
10029844ENGINE_EXPORT_FAILEDFalla al escribir el archivo: el destino de la exportación o de la copia no tiene permiso de escritura, o el archivo de copia ya existeCambie de directorio o de nombre de archivo; revise el espacio en disco y los permisos
10029845ENGINE_SUBSTITUTE_KEY_INVALIDClave de la nota sustituta inválida en la cancelación por sustitución, o no es una nota offline de este equipo y de la misma empresa no rechazadaInforme la clave de acceso de 44 dígitos de la nota offline emitida en este equipo para la misma venta
10029846ENGINE_BACKUP_INVALIDLa copia de seguridad no se puede restaurar: contraseña incorrecta, o el archivo de copia de seguridad fue modificado, está dañado o no es una copia de seguridad de este SDKVerifique la contraseña; use otra copia de seguridad íntegra. La base original no se modificó
10029870ENGINE_PROTOCOL_INVALID_JSONEl runtime recibió un mensaje que no es JSON válidoDefecto del paquete SDK; actualice el SDK
10029871ENGINE_PROTOCOL_LINE_TOO_LONGUn mensaje superó 8 MBSolicitud demasiado grande; divida los ítems
10029872ENGINE_PROTOCOL_MESSAGE_INVALIDEstructura de mensaje inválidaDefecto del paquete SDK; actualice el SDK
10029873ENGINE_METHOD_UNKNOWNEl runtime no conoce el métodoEl SDK es más nuevo que el runtime; actualice el runtime
10029874ENGINE_PARAMS_INVALIDParámetro ausente o de tipo incorrecto; Detalhes.campo indica cuálCorrija el parámetro, por ejemplo solicitud que no es objeto JSON, formato de la huella del certificado o de la fecha
10029875ENGINE_ALREADY_STARTEDInicialización repetida, o el método de protocolo de restauración de la copia de seguridad llamado en una conexión con el runtime que ya ejecutó IniciarNo ocurre en el uso normal de los paquetes; si aparece, es un defecto del paquete SDK, actualice el SDK. Al integrarse directamente con el protocolo del runtime, llame Encerrar y restaure por una conexión nueva
10029876ENGINE_REQUEST_ID_DUPLICATEDLa misma llamada aún está en procesoDefecto del paquete SDK; actualice el SDK
10029877ENGINE_RUNTIME_NOT_FOUNDRuntime no encontradoRevise el instalador y el directorio del runtime
10029878ENGINE_TOO_MANY_PENDINGMás de 64 llamadas en espera al mismo tiempoReduzca la concurrencia
10029879ENGINE_RESPONSE_TOO_LARGEUna respuesta superó el límiteContacte a la plataforma
10029880ENGINE_PRINCIPAL_UNREACHABLEEl secundario no alcanza al principal; la solicitud no llegóReintente más tarde, o pase la caja a la máquina de respaldo
10029881ENGINE_PRINCIPAL_RESULT_UNKNOWNLa solicitud llegó al principal pero no volvió respuesta; resultado desconocidoCuando vuelva el principal, llame Consultar con el mismo id; reenviar Emitir con el mismo id y contenido no emite dos veces
10029882ENGINE_TERMINAL_TOKEN_INVALIDToken del terminal secundario inválido o revocadoLlame de nuevo CriarTerminal en el principal y actualice TokenTerminal del secundario
10029883ENGINE_PRINCIPAL_ADDRESS_INVALIDDirección del principal mal formada o fuera de la red local privadaCorrija EnderecoPrincipal
10029884ENGINE_MODE_METHOD_UNAVAILABLEEl modo actual no ofrece este métodoEmparejamiento, cambio de certificado, copia de seguridad y exportación se hacen en el principal; la gestión de terminales solo en el principal
10029885ENGINE_PRINCIPAL_REJECTEDEl principal rechazó el origen de la solicitud, por ejemplo un secundario fuera de las redes permitidasRevise RedesPermitidas del principal y la red
10029886ENGINE_PRINCIPAL_RATE_LIMITEDDemasiados fallos de autenticación; limitado por el principalRevise el token y reintente tras 1 minuto
10029887ENGINE_PRINCIPAL_LISTEN_FAILEDNo se puede escuchar en el puerto de red local del principalCambie PortaPrincipal o libere el puerto
10029888ENGINE_TERMINAL_NOT_FOUNDEl terminal a revocar no existeRevise el id del terminal con ListarTerminais

Todos los códigos, incluidos los del Asistente Fiscal, están en Códigos de error.