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ón | Java | Obligatorio | Descripción |
|---|---|---|---|
| Directorio de datos | diretorioDados(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 runtime | diretorioRuntime(Path) | Obligatorio en modo subproceso | Directorio de instalación del runtime. Debe contener tffiscal-nfce.exe; si no lo encuentra devuelve 10029877 |
| Nombre del software de caja | nomeAplicativo(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 PDV | versaoAplicativo(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 errores | idioma(String) | No | Idioma 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 llamada | tempoLimitePadraoMs(long) | No | Espera 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 inicio | tempoLimiteInicioMs(long) | No | Espera máxima hasta que el runtime esté listo. Por defecto 5 segundos; al agotarse devuelve 10029831 |
| Reinicio automático | reiniciarAutomaticamente(boolean) | No | Reinicio automático del runtime si termina inesperadamente. Activado por defecto, con intervalos de 1, 2, 4 segundos hasta 60 |
| Reenvío de logs | encaminharLog(boolean) | No | Envío de los logs del núcleo al PDV. Desactivado por defecto; al activarlo se escriben en java.util.logging |
| Proxy de salida | proxy(String) | No | Direcció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 proxy | proxyAutenticacao(String, String) | No | Usuario 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 sistema | usarProxyDoSistema(boolean) | No | Interruptor 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 XML | retencaoXmlDias(int) | No | Dí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ón | modo(Modo) | No | Modo de ejecución en Java. SUBPROCESSO (por defecto) o EM_PROCESSO, vea abajo |
| Oyente de eventos | aoReceberEvento(Consumer<EventoNfce>) | No | Manejador conectado al inicio. Así no se pierden los eventos acumulados antes del inicio, vea Eventos |
| Comando del runtime | comandoRuntime(String) | No | Opción avanzada. Ruta completa del ejecutable del runtime, solo para desarrollo y pruebas |
| Argumentos del runtime | argumentosRuntime(List<String>) | No | Opción avanzada. Argumentos de inicio del runtime, por defecto --stdio; solo para desarrollo y pruebas |
| Motor simulado | motorSimulado(boolean) | No | Motor sustituto para pruebas. Solo para ejemplos y pruebas automatizadas, no genera notas válidas; no lo active en producción |
| Rol principal o secundario | modoOperacao(ModoOperacao) | No | Rol 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 principal | portaPrincipal(int) | No | Puerto de red local del principal. Solo en el principal; sin valor o 0 es 8786; si el puerto está ocupado, Iniciar devuelve 10029887 |
| Redes permitidas | redesPermitidas(List<String>) | No | Redes 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 principal | enderecoPrincipal(String) | Obligatorio en el secundario | Direcció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 terminal | tokenTerminal(String) | Obligatorio en el secundario | Token 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
Modo | Significado | Requisitos |
|---|---|---|
SUBPROCESSO | Por defecto. El SDK inicia el runtime como subproceso | Java 8 o superior en el anfitrión; hay que distribuir el runtime y configurar diretorioRuntime |
EM_PROCESSO | El núcleo corre dentro de la JVM del PDV, sin subproceso | Java 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ón | Forma de proxy |
|---|---|
UsarProxyDoSistema activado | Proxy 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 Proxy | Proxy manual. Usa la dirección informada en Proxy |
| Ninguna | Directa |
- 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
Proxymanualmente. - Autenticación del proxy:
proxyAutenticacaovale 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,Avisosde 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.
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.
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
public static TfFiscalNfce iniciar(Configuracao config);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Configuración | config | Sí | 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ódigo | Situación | Acción |
|---|---|---|
| 10029877 | Runtime no encontrado | Revise que el directorio del runtime y tffiscal-nfce.exe se distribuyan con el instalador |
| 10029831 | El runtime no inició o no estuvo listo dentro del tiempo límite de inicio | Revise los logs; en computadoras lentas aumente el tiempo límite de inicio |
| 10029830 | Versiones de SDK y runtime incompatibles | Distribuya el runtime y el SDK de la misma versión |
| 10029835 | Modo en proceso de Java con anfitrión por debajo de Java 21 | Use el modo subproceso o actualice Java |
| 10029828 | El directorio de datos ya está abierto por otro proceso | Una sola instancia por directorio; revise si quedó algún proceso |
| 10029827 | No se puede abrir la clave local: el directorio de datos viene de otra computadora o de otro usuario de Windows | Ejecute con el usuario de Windows original; para cambiar de computadora, desactive el dispositivo anterior y empareje de nuevo |
| 10029829 | Base local inconsistente | No borre el directorio de datos; contacte a la plataforma |
| 10029842 | La 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 rechaza | Actualice 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 |
| 10029840 | Configuración inválida | Corrija la configuración según Message |
| 10029874 | Valor 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 rango | Corrija la configuración según Detalhes.campo |
| 10029882 | Token del terminal secundario inválido o revocado | Emita otro token en el principal y actualice TokenTerminal |
| 10029883 | Dirección del principal mal formada o fuera de la red local privada | Corrija EnderecoPrincipal |
| 10029887 | No se puede escuchar en el puerto de red local del principal | Cambie PortaPrincipal o libere el puerto |
También puede devolver los errores comunes.
Ejemplos
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 elempresaIdde 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
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
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
public Resultados.CodigoAtivacao inspecionarCodigoAtivacao(String codigo);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Código de emparejamiento | codigo | Sí | 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ódigo | Situación | Acción |
|---|---|---|
| 10029825 | Formato, firma o vigencia del código incorrectos | Confirme que se copió completo; si venció, pida al integrador uno nuevo |
| 10029826 | El código apunta a una dirección de plataforma no confiable | El 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
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
public Resultados.Ativacao ativar(String codigoAtivacao, Certificado certificado);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Código de emparejamiento | codigoAtivacao | Sí | Texto completo del código de emparejamiento. Empieza con TFA1., es de un solo uso y vale 72 horas |
| Certificado | certificado | Sí | 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ódigo | Situación | Acción |
|---|---|---|
| 10029825 / 10029826 | El código no pasó la verificación local / apunta a una plataforma no confiable | Vea InspecionarCodigoAtivacao |
| 10029824 | No llega a la plataforma | Reintente con conexión |
| 10029837 | La empresa ya está emparejada en este directorio de datos | No hace falta emparejar de nuevo |
| 10029813 / 10029814 | Certificado no encontrado, sin clave privada o con CNPJ distinto / vencido | Use un certificado A1 vigente de la empresa |
| 10029839 | La plataforma emparejó pero falló el guardado local | Llame de nuevo Ativar con el mismo código de emparejamiento |
| 10029806 | La licencia no pertenece a este dispositivo | Empareje de nuevo; si persiste, contacte a la plataforma |
| 10029874 | Parámetro de certificado inválido: la huella no tiene 40 dígitos hexadecimales o el PFX está vacío | Corrija el parámetro del certificado |
| 10029205 a 10029208 | De la plataforma: código inválido / vencido / ya usado / anulado | Genere un código nuevo |
| 10029209 | De la plataforma: el código no permite la forma SDK | Genere otro con Sdk o Qualquer |
| 10029210 / 10029211 | De la plataforma: falta el nombre del software de caja / versión del PDV bloqueada o muy antigua | Configure el nombre del software de caja; actualice el PDV |
| 10029213 / 10029214 | De la plataforma: CNPJ del certificado distinto del de la empresa / certificado vencido | Use un certificado vigente de la empresa |
| 10029219 | De la plataforma: el ambiente del código difiere del ambiente actual de la empresa | Genere un código nuevo en el ambiente actual de la empresa |
| 10029221 a 10029225 | De la plataforma: la serie del dispositivo indicada en el código ya no está disponible | El integrador genera un código nuevo con otra serie u otro número inicial |
También puede devolver los errores comunes.
Ejemplos
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:
- Busca el
iden el equipo: si ya emitió el mismoid, devuelve la nota original sin tomar otro número; si el contenido es distinto, devuelve10029818. - Si un ítem referencia una clase de impuesto (
classeImposto), la solicitud va primero a la plataforma, que la expande enimpostoscompletos: requiere conexión, y sin acceso a la plataforma devuelve10029780sin 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. - Normaliza y valida con las mismas reglas de la nube; si no pasa, devuelve
10029817yDetalheslista los motivos campo por campo. - 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. - 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, devuelveAguardandoAutorizacaoy 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
public ResultadoEmissao emitir(String pedidoJson);public ResultadoEmissao emitir(String pedidoJson, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Solicitud de emisión | pedidoJson | Sí | 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 empresa | empresaId | Obligatorio con varias empresas | Empresa 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.
Status | Qué hace el PDV |
|---|---|
Autorizada | Imprime el cupón |
ContingenciaPendente | Firma offline: imprima el cupón con Cupom y entréguelo al consumidor; la transmisión es automática |
AguardandoAutorizacao | Aceptada 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 |
Negada | La 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ódigo | Situación | Acción |
|---|---|---|
| 10029817 | Solicitud inválida | Corrija según Detalhes |
| 10029780 | Un ítem referencia una clase de impuesto, pero no se pudo acceder a la plataforma para expandirla; no se consumió ningún número | Reenvíe con el mismo id cuando vuelva la red; sin red, envíe impostos en los ítems |
| 10029818 | El mismo id ya se usó con contenido distinto | Venta nueva con id nuevo; para reintentar, use la solicitud original |
| 10029801 / 10029802 | Empresa no emparejada / varias empresas sin empresaId | Empareje primero; envíe empresaId |
| 10029816 | Dispositivo desactivado | Contacte al integrador |
| 10029805 / 10029806 | Firma de la licencia inválida / licencia de otro dispositivo | Contacte a la plataforma; si hace falta, empareje de nuevo |
| 10029874 | La solicitud no es un objeto JSON | Envíe el texto de un objeto JSON |
| 10029803 / 10029804 / 10029807 | Sin red y sin licencia / licencia vencida / pasó el plazo offline | Restablezca la red; tras renovar se recupera solo |
| 10029808 | La serie del dispositivo llegó al número 999999999 | Desactive el dispositivo y emparéjelo de nuevo con un código de emparejamiento nuevo que indique otra serie en serie; la plataforma no cambia la serie por sí sola |
| 10029809 | El reloj del sistema retrocedió | Corrija la hora del sistema |
| 10029810 | La nota pendiente más antigua superó el plazo de transmisión | Restablezca la red para transmitir |
| 10029811 / 10029812 | La empresa o el estado no permite offline / nota con combustible | Solo emisión en línea |
| 10029813 / 10029814 | Certificado no disponible / vencido | Revise el certificado; si hace falta, TrocarCertificado |
| 10029815 | Faltan la configuración local o los datos tributarios | Sincronice en línea una vez |
| 10029823 | Numeración de la serie del dispositivo agotada | Desactive el dispositivo y emparéjelo de nuevo con un código de emparejamiento nuevo que indique otra serie en serie; la plataforma no cambia la serie por sí sola |
| 10029307 | De la plataforma: el ambiente del dispositivo difiere del ambiente actual de la empresa | Empareje un dispositivo nuevo en el ambiente actual de la empresa |
| 10029424 | De 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 coinciden | No reintente con otro número; exporte los registros y contacte a la plataforma |
| 10029426 | De 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 dispositivo | Verifique la nota original en Consultar NFC-e; use un id nuevo para una venta nueva |
| Otros códigos de la plataforma | Error de negocio devuelto por la plataforma en la emisión en línea, como 10022004 | Trátelo según la descripción de errores de Emitir NFC-e |
También puede devolver los errores comunes.
Ejemplos
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
public Resultados.PreVisualizacao previsualizar(String pedidoJson, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Solicitud de emisión | pedidoJson | Sí | Solicitud a validar. Misma estructura que Emitir; el id puede faltar todavía |
| Identificador de la empresa | empresaId | Obligatorio con varias empresas | Empresa 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
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
public SituacaoNota consultar(String id);public SituacaoNota consultar(String id, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Identificador de la nota | id | Sí | El id de la solicitud de emisión |
| Identificador de la empresa | empresaId | Obligatorio con varias empresas | Empresa 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ódigo | Situación | Acción |
|---|---|---|
| 10029819 | La nota no existe en este equipo | Revise id y empresaId; si la nota no se emitió en este equipo, use la consulta en la nube |
| 10029801 / 10029802 | Empresa no emparejada / varias empresas sin empresaId | Empareje primero; envíe empresaId |
También puede devolver los errores comunes.
Ejemplos
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
public Resultados.PaginaNotas listarNotas(LocalDate data, String status, int pagina, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Fecha de emisión | data | No | Filtro 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 |
| Estado | status | No | Filtro por estado. Valores en Tipos de datos: estado de la nota; sin él no se filtra |
| Página | pagina | No | Número de página. Empieza en 1, por defecto 1 |
| Identificador de la empresa | empresaId | Obligatorio con varias empresas | Empresa 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ódigo | Situación | Acción |
|---|---|---|
| 10029874 | Fecha que no es yyyy-mm-dd, estado con valor inválido, o página menor que 1 | Use los valores de la tabla |
| 10029801 / 10029802 | Empresa no emparejada / varias empresas sin empresaId | Empareje primero; envíe empresaId |
También puede devolver los errores comunes.
Ejemplos
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ón | Destino Situacao | Después |
|---|---|---|
| Nota autorizada y con conexión | Solicitado | Ya se envió a la plataforma; el resultado llega por el evento CANCELAMENTO_CONCLUIDO o CANCELAMENTO_REJEITADO |
| Nota offline transmitida y aún no autorizada | Agendado | La 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 transmitida | EnfileiradoLocal | Queda 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
public Resultados.Cancelamento cancelar(String id, String justificativa, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Identificador de la nota | id | Sí | El id de la solicitud de emisión |
| Motivo de la cancelación | justificativa | Sí | Motivo de la cancelación. De 15 a 255 caracteres |
| Identificador de la empresa | empresaId | Obligatorio con varias empresas | Empresa 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ódigo | Situación | Acción |
|---|---|---|
| 10029822 | El 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 detalhes | No reintente; confirme el estado con Consultar |
| 10029819 | La nota no existe en este equipo | Revise el id |
| 10029817 | El motivo no tiene de 15 a 255 caracteres | Corrija el motivo |
| Otros códigos de la plataforma | Error de la plataforma al enviar en línea, como plazo de cancelación vencido 10022007 | Trátelo según Cancelar NFC-e |
También puede devolver los errores comunes.
Ejemplos
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:
| Objeto | Debe cumplir | Si no se cumple |
|---|---|---|
| Nota original | Nota normal emitida en línea por la plataforma: no es offline, no está cancelada y no tiene una cancelación pendiente | 10029822 |
| Nota sustituta | Nota 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 original | 10029845 |
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
public Resultados.Cancelamento cancelarPorSubstituicao(String id, String chaveSubstituta, String justificativa,String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Identificador de la nota | id | Sí | El id de la nota original sustituida |
| Clave de la nota sustituta | chaveSubstituta | Sí | 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ón | justificativa | Sí | Motivo de la cancelación. De 15 a 255 caracteres |
| Identificador de la empresa | empresaId | Obligatorio con varias empresas | Empresa 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ódigo | Situación | Acción |
|---|---|---|
| 10029822 | La nota original no es una nota normal emitida en línea: es offline, ya está cancelada o tiene una cancelación pendiente | No reintente; para notas offline use Cancelar |
| 10029845 | Clave de la nota sustituta inválida, o no es una nota offline de este equipo y de la misma empresa no rechazada | Informe la clave de acceso de 44 dígitos de la nota offline emitida en este equipo para la misma venta |
| 10029819 | La nota original no existe en este equipo | Revise el id |
| 10029817 | El motivo no tiene entre 15 y 255 caracteres | Corrija el motivo |
| Otros códigos de la plataforma | Error devuelto por la plataforma al enviar, por ejemplo plazo de cancelación superado 10022007 | Trátelo según Cancelar NFC-e |
También puede devolver los errores comunes.
Ejemplos
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
public ResultadoEmissao substituir(String id, String pedidoJsonCorrigido, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Identificador de la nota | id | Sí | El id de la nota rechazada |
| Solicitud corregida | pedidoJsonCorrigido | Sí | 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 empresa | empresaId | Obligatorio con varias empresas | Empresa 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ódigo | Situación | Acción |
|---|---|---|
| 10029820 | El estado actual no permite corregir: solo Rejeitada se puede corregir | Confirme el estado con Consultar |
| 10029821 | La corrección cambió valores o impuestos | Cambie solo lo que no afecta valores |
| 10029817 | Solicitud inválida | Corrija según Detalhes |
| 10029780 | Un ítem referencia una clase de impuesto, pero no se pudo acceder a la plataforma para expandirla; no se consumió ningún número | Reenvíe con el mismo id cuando vuelva la red; sin red, envíe impostos en los ítems |
| 10029819 | La nota no existe en este equipo | Revise el id |
| 10029815 | Faltan la configuración local o los datos tributarios | Sincronice en línea una vez |
También puede devolver los errores comunes.
Ejemplos
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
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ámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Identificador de la nota | id | Sí | El id de la solicitud de emisión |
| Formato | formato | Sí | Formato del cupón. Valores en la tabla de abajo |
| Parámetros de impresión | opcoes (OpcoesCupom) | No | Pará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 empresa | empresaId | Obligatorio con varias empresas | Empresa emisora. Se puede omitir si solo hay una empresa emparejada |
Java FormatoCupom | Contenido |
|---|---|
ESCPOS_80 | Bytes ESC/POS para impresora térmica de 80 mm |
ESCPOS_58 | Bytes ESC/POS para impresora térmica de 58 mm |
TEXTO | Texto plano UTF-8 |
HTML | HTML UTF-8, para vista previa en pantalla o impresión desde el navegador |
PDF_80 | PDF de 80 mm de ancho, una página por copia. 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ámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Columnas por línea | colunas(int) | No | Caracteres 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ódigos | paginaCodigo(String) | No | Pá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 QR | modoQrCode(OpcoesCupom.ModoQrCode) | No | Forma 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 QR | tamanhoModuloQr(int) | No | Puntos por módulo del código QR. De 1 a 16; sin valor o con 0 es 4 |
| Corte del papel | cortar(boolean) | No | Interruptor de corte del papel. Por defecto true: corta tras imprimir |
| Copias | vias(int) | No | Cantidad 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ódigo | Situación | Acción |
|---|---|---|
| 10029819 | La nota no existe en este equipo | Revise el id |
| 10029874 | Formato con valor inválido, o parámetros de impresión fuera de rango | Use los valores de la tabla |
También puede devolver los errores comunes.
Ejemplos
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 Windowsbyte[] 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
public byte[] qrCodePng(String id, int tamanhoPx, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Identificador de la nota | id | Sí | El id de la solicitud de emisión |
| Lado de la imagen | tamanhoPx | No | Lado de la imagen en píxeles. De 64 a 2048; debe pasarse explícitamente |
| Identificador de la empresa | empresaId | Obligatorio con varias empresas | Empresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null |
Retorno
Bytes de la imagen PNG.
Errores posibles
| Código | Situación | Acción |
|---|---|---|
| 10029819 | La nota no existe en este equipo | Revise el id |
| 10029817 | El lado de la imagen no está entre 64 y 2048 | Corrija el tamaño |
También puede devolver los errores comunes.
Ejemplos
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
public byte[] xmlAutorizado(String id, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Identificador de la nota | id | Sí | El id de la solicitud de emisión |
| Identificador de la empresa | empresaId | Obligatorio con varias empresas | Empresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null |
Retorno
Bytes UTF-8 del XML autorizado.
Errores posibles
| Código | Situación | Acción |
|---|---|---|
| 10029841 | XML autorizado no disponible: la nota aún no se autorizó, o no está en el equipo y no se pudo recuperar de la plataforma | Si 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 |
| 10029819 | La nota no existe en este equipo | Revise el id |
También puede devolver los errores comunes.
Ejemplos
// Puede recuperarse por la red: use un hilo de fondoCompletableFuture.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
public byte[] xmlCancelamento(String id, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Identificador de la nota | id | Sí | El id de la solicitud de emisión |
| Identificador de la empresa | empresaId | Obligatorio con varias empresas | Empresa 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ódigo | Situación | Acción |
|---|---|---|
| 10029843 | XML de cancelación no disponible: la nota no está cancelada, o no está en el equipo y no se pudo recuperar de la plataforma | Si 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 |
| 10029819 | La nota no existe en este equipo | Revise el id |
También puede devolver los errores comunes.
Ejemplos
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.xmly 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
Falhasdel 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 aFalhas. - 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
somenteLocalentrueno se conecta en absoluto, solo escribe los XML que ya están en el equipo, y las notas que falten van aFalhas.
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
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ámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Fecha inicial | de | Sí | Inicio del período por fecha de emisión. Incluye ese día |
| Fecha final | ate | Sí | Fin del período por fecha de emisión. Incluye ese día |
| Directorio de destino | diretorio | Sí | Directorio de exportación. Una ruta relativa se convierte en absoluta a partir del directorio actual del software de caja |
| Identificador de la empresa | empresaId | Obligatorio con varias empresas | Empresa emisora. Se puede omitir si solo hay una empresa emparejada; en Java pase null |
| Solo el equipo | somenteLocal | No | Indicador 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ódigo | Situación | Acción |
|---|---|---|
| 10029874 | Fecha faltante o con formato inválido, con Detalhes.campo en de o ate | Corrija la fecha |
| 10029844 | Directorio sin permiso de escritura | Cambie de directorio; revise el espacio en disco y los permisos |
| 10029801 / 10029802 | Empresa no emparejada / varias empresas sin empresaId | Empareje 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
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
public void trocarCertificado(Certificado certificado, String empresaId);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Certificado | certificado | Sí | 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 empresa | empresaId | Obligatorio con varias empresas | Empresa 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ódigo | Situación | Acción |
|---|---|---|
| 10029813 | Certificado no disponible: no encontrado, sin clave privada o con CNPJ distinto del de la empresa | Revise el almacén de certificados y use el certificado de la empresa de la tienda |
| 10029814 | Certificado vencido | Use un certificado vigente |
| 10029874 | Parámetro de certificado inválido: la huella no tiene 40 dígitos hexadecimales o el PFX está vacío | Corrija el parámetro del certificado |
| 10029801 / 10029802 | Empresa no emparejada / varias empresas sin empresaId | Empareje primero; envíe empresaId |
También puede devolver los errores comunes.
Ejemplos
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
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ón | Aviso |
|---|---|
Conectado en false | Sin conexión; las notas se transmitirán al volver la red |
PendentesTransmissao mayor que 0 | Cantidad por transmitir; muéstrela junto al plazo PrazoTransmissaoAte |
OfflineAte cerca | El tiempo offline está por agotarse; conéctese cuanto antes |
CertificadoValidoAte cerca | El certificado está por vencer; tras renovarlo llame TrocarCertificado |
Situacao distinto de Ativo | El dispositivo ya no puede emitir notas nuevas; contacte al integrador |
UltimoErro con valor | Motivo del último fallo de sincronización; envíelo al soporte técnico al diagnosticar |
Avisos no vacío | Hay 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
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
public void sincronizarAgora();
Parámetros
Ninguno.
Retorno
Ninguno.
Errores posibles
Solo los errores comunes.
Ejemplos
// Solo dispara la siguiente ronda en segundo plano y retorna de inmediato; puede llamarse directamente en el hilo de la interfaznfce.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;
VersaoBancodel 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
public Resultados.Backup backup(Path destino, String senha);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Archivo de copia | destino | Sí | 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ña | senha | Sí | 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ódigo | Situación | Acción |
|---|---|---|
| 10029874 | Contraseña vacía, Detalhes.campo es senha | Informe la contraseña |
| 10029817 | Contraseña de menos de 8 caracteres | Use una contraseña más larga |
| 10029844 | El archivo de destino ya existe, o el directorio no tiene permiso de escritura | Cambie el nombre del archivo o el directorio; revise el espacio en disco y los permisos |
También puede devolver los errores comunes.
Ejemplos
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-), yCopiaAnteriordel 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 devuelve10029811y 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
public static Resultados.Restauracao restaurarBackup(Configuracao config, Path origem, String senha);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Configuración | config | Sí | 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 copia | origem | Sí | Ruta del archivo de copia de seguridad. Una ruta relativa se convierte en absoluta a partir del directorio actual del software de caja |
| Contraseña | senha | Sí | 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ódigo | Situación | Acción |
|---|---|---|
| 10029846 | Contraseñ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 casos | Verifique la contraseña; use otra copia de seguridad íntegra. La base original no se modificó |
| 10029842 | La copia de seguridad viene de una versión más nueva del SDK | Actualice el SDK y el runtime a una versión no inferior a la de la copia de seguridad |
| 10029828 | Hay 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 recibe | Primero llame Encerrar en la instancia que usa este directorio de datos y luego restaure |
| 10029875 | Se 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 runtime | Llame Encerrar y restaure por una conexión nueva, antes de Iniciar |
| 10029817 | Contraseña de menos de 8 caracteres | Ingrese la contraseña usada al generar la copia de seguridad |
| 10029874 | Archivo de copia de seguridad o contraseña vacíos, Detalhes.campo es origem o senha | Complete los parámetros |
| 10029844 | Falla al leer o escribir archivos | Revise 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
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:
{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.jsonregistra 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}.xmldel 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:
Quantidadees 0,Manifestoestá vacío yManifestoses 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
public Resultados.ExportacaoPendentes exportarPendentes(Path diretorio);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Directorio de destino | diretorio | Sí | 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ódigo | Situación | Acción |
|---|---|---|
| 10029844 | Directorio sin permiso de escritura | Cambie de directorio; revise el espacio en disco y los permisos |
También puede devolver los errores comunes.
Ejemplos
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
public Resultados.TerminalCriado criarTerminal(String nome);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Nombre del terminal | nome | Sí | 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ódigo | Situación | Acción |
|---|---|---|
| 10029874 | Nombre 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 |
| 10029884 | No está en modo principal | Llámelo solo en el principal |
También puede devolver los errores comunes.
Ejemplos
Resultados.TerminalCriado t = principal.criarTerminal("Caixa 2");// El token completo llega solo esta vez; configúrelo en la caja 2 en el momentoSystem.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
public List<Resultados.Terminal> listarTerminais(boolean todos);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Listar todos | todos | No | Incluye 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ódigo | Situación | Acción |
|---|---|---|
| 10029884 | No está en modo principal | Llámelo solo en el principal |
También puede devolver los errores comunes.
Ejemplos
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
public void revogarTerminal(String id);
Parámetros
| Parámetro | Java | Obligatorio | Descripción |
|---|---|---|---|
| Identificador del terminal | id | Sí | El id devuelto por CriarTerminal, empieza con trm_ |
Retorno
Ninguno.
Errores posibles
| Código | Situación | Acción |
|---|---|---|
| 10029888 | Terminal no encontrado | Revise el id con ListarTerminais |
| 10029884 | No está en modo principal | Llámelo solo en el principal |
También puede devolver los errores comunes.
Ejemplos
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
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
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 congetCampos().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.
| Valor | Significado | Qué hace el PDV |
|---|---|---|
Autorizada | Autorizada | Imprime el cupón |
ContingenciaPendente | Firmada offline en el equipo, pendiente de transmisión | Imprime el cupón y lo entrega al consumidor; la transmisión es automática |
AguardandoAutorizacao | Aceptada 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 |
Negada | La 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 |
Rejeitada | La SEFAZ rechazó la nota offline transmitida (evento NOTA_REJEITADA) | Corrige con el mismo número usando Substituir; no se puede emitir otra |
Recusada | La plataforma no aceptó la nota offline | Requiere atención manual; contacte a la plataforma |
Cancelada | Cancelada | Nada |
Resultado de la emisión
Retorno de Emitir y Substituir. Java ResultadoEmissao.
| Nombre JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
id | getId() | Texto | No | Identificador de la nota. El id de la solicitud de emisión |
status | getStatus() | Texto | No | Estado de la nota. Valores arriba |
emitidaEmContingencia | isEmitidaEmContingencia() | Booleano | No | Indicador de firma offline. Sigue en true después de autorizada |
chave | getChave() | Texto | Sí | Clave de acceso. 44 dígitos |
serie | getSerie() (Long) | Entero | Sí | Serie |
numero | getNumero() (Long) | Entero | Sí | Número de la nota |
dataEmissao | getDataEmissao() | Fecha | Sí | Fecha de emisión |
protocolo | getProtocolo() | Texto | Sí | Número de protocolo de autorización. null mientras está pendiente de transmisión offline |
qrCode | getQrCode() | Texto | Sí | Contenido del QR Code. Codifíquelo como QR si arma el cupón por su cuenta |
urlConsulta | getUrlConsulta() | Texto | Sí | URL de consulta para el consumidor |
motivo | getMotivo() | Texto | Sí | Descripción del motivo. Viene de la SEFAZ o de la plataforma |
cStat | getCStat() (Long) | Entero | Sí | Código de resultado de la SEFAZ. null si no hay resultado de la SEFAZ |
xMotivo | getXMotivo() | Texto | Sí | Mensaje de resultado de la SEFAZ. Viene junto con el código de resultado |
tentativaOnline | isTentativaOnline() | Booleano | No | Indicador 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 |
respostaPlataforma | getRespostaPlataforma() | Texto | Sí | 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 |
terminal | getTerminal() | Texto | Sí | 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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
transmitida | isTransmitida() | Booleano | No | Indicador de transmisión. La nota offline ya se transmitió a la plataforma |
cancelamentoPendente | isCancelamentoPendente() | Booleano | No | Indicador de cancelación pendiente. Hay una cancelación pendiente o en cola en el equipo |
correcoes | getCorrecoes() (Long) | Entero | No | Cantidad de correcciones |
atualizadoEm | getAtualizadoEm() | Fecha | Sí | Fecha de la última actualización |
xmlAutorizadoDisponivel | isXmlAutorizadoDisponivel() | Booleano | No | Indicador 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 |
pedido | getPedido() | Texto | Sí | 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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
itens | getItens() | Array | No | Notas de la página. Los elementos son estado de consulta, de la emisión más reciente a la más antigua |
pagina | getPagina() | Entero | No | Número de página. Empieza en 1 |
tamanhoPagina | getTamanhoPagina() | Entero | No | Notas por página. Siempre 50 |
temMais | isTemMais() | Booleano | No | Indicador de página siguiente. No se informa el total |
Resultado de la vista previa
Retorno de Previsualizar. Java Resultados.PreVisualizacao.
| Nombre JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
valido | isValido() | Booleano | No | Indicador de validación aprobada |
erros | getErros() | Array de texto | No | Errores de validación. Ya traducidos al idioma de errores; array vacío si pasa |
pedidoNormalizado | getPedidoNormalizado() | Texto | Sí | Solicitud normalizada. Texto JSON, en general no se usa |
valorTotal | getValorTotal() (BigDecimal) | Decimal | Sí | Total de la nota |
valorTributos | getValorTributos() (BigDecimal) | Decimal | Sí | Total de impuestos |
Resultado de la cancelación
Retorno de Cancelar y de CancelarPorSubstituicao. Java Resultados.Cancelamento.
| Nombre JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
situacao | getSituacao() | Texto | No | Destino de la solicitud. Valores abajo |
motivo | getMotivo() | Texto | Sí | Descripción |
situacao | Significado |
|---|---|
Solicitado | Nota autorizada; la cancelación ya se envió a la plataforma y el resultado llega por el evento CANCELAMENTO_CONCLUIDO o CANCELAMENTO_REJEITADO |
Agendado | Nota offline transmitida y aún no autorizada; la plataforma deja la cancelación pendiente y la ejecuta sola tras la autorización |
EnfileiradoLocal | Cola 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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
ambiente | getAmbiente() (Long) | Entero | No | Ambiente de emisión. 1 producción, 2 pruebas |
formasPermitidas | getFormasPermitidas() (Long) | Entero | No | Formas permitidas. 0 cualquier forma, 1 solo el Asistente Fiscal, 2 solo el SDK embebido |
expiraEm | getExpiraEm() | Fecha | No | Vencimiento del código de emparejamiento |
plataforma | getPlataforma() | Texto | No | Dirección de la plataforma. Plataforma a la que apunta el código |
serie | getSerie() (Long) | Entero | Sí | 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 |
numeroInicial | getNumeroInicial() (Long) | Entero | Sí | 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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
empresaId | getEmpresaId() | Texto | No | Identificador de la empresa. Es el empresaId de los demás métodos |
dispositivoId | getDispositivoId() | Texto | No | Identificador del dispositivo |
cnpj | getCnpj() | Texto | No | CNPJ de la empresa |
uf | por getCampos() | Texto | No | Estado |
ambiente | por getCampos() | Entero | No | Ambiente de emisión. 1 producción, 2 pruebas |
serieOffline | getSerieOffline() (Long) | Entero | No | Serie 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 |
licencaExpiraEm | getLicencaExpiraEm() | Fecha | Sí | Vencimiento de la licencia |
numeroInicial | getNumeroInicial() (Long) | Entero | No | Nú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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
empresaId | getEmpresaId() | Texto | No | Identificador de la empresa |
dispositivoId | getDispositivoId() | Texto | No | Identificador del dispositivo |
cnpj | getCnpj() | Texto | No | CNPJ de la empresa |
uf | por getCampos() | Texto | No | Estado |
ambiente | por getCampos() | Entero | No | Ambiente de emisión. 1 producción, 2 pruebas |
serieOffline | por getCampos() | Entero | No | Serie del dispositivo |
situacao | getSituacao() | Texto | No | Estado del dispositivo. Valores abajo |
situacao | Significado | Acción |
|---|---|---|
Ativo | Puede emitir | Nada |
Desativado | El integrador desactivó el dispositivo | Irreversible; para seguir usando la misma computadora hay que emparejarla de nuevo |
Revogado | La plataforma revocó el dispositivo | Contacte a la plataforma |
EmpresaDesativada | La emisión offline de la empresa está desactivada | Contacte a la plataforma |
AplicativoBloqueado | El software de caja fue bloqueado por la plataforma | Contacte a la plataforma |
VersaoBloqueada | La versión del PDV está bloqueada o por debajo de la mínima | Actualice 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 JSON | Java | Tipo | Descripción |
|---|---|---|---|
versaoNucleo | getVersaoNucleo() | Texto | Versión del núcleo |
empresas | getEmpresas() (elementos clave-valor) | Array | Estado de cada empresa emparejada, campos abajo |
avisos | getAvisos() | Array de texto | Avisos 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 JSON | Tipo | Null | Descripción |
|---|---|---|---|
empresaId | Texto | No | Identificador de la empresa |
dispositivoId | Texto | No | Identificador del dispositivo |
situacao | Texto | No | Estado del dispositivo. Valores como en empresa emparejada |
conectado | Booleano | No | Indicador de conexión. Si en este momento llega a la plataforma |
ultimoContato | Fecha | Sí | Último contacto |
licencaExpiraEm | Fecha | Sí | Vencimiento de la licencia |
offlineAte | Fecha | Sí | Plazo de la emisión offline. El menor entre el vencimiento de la licencia y el del certificado |
pendentesTransmissao | Entero | No | Notas por transmitir |
pendenteMaisAntigaEm | Fecha | Sí | Pendiente más antigua. Fecha de emisión de la nota por transmitir más antigua |
prazoTransmissaoAte | Fecha | Sí | Plazo de transmisión. Plazo de la nota por transmitir más antigua; pasado ese momento el dispositivo no puede seguir emitiendo offline |
certificadoValidoAte | Fecha | Sí | Vencimiento del certificado |
ultimoErro | Texto | Sí | Último error. Motivo del último fallo de sincronización |
numerosNaoUtilizadosPendentes | Entero | No | Rangos 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 |
restauradoPendenteSincronizacao | Booleano | No | Restauració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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
quantidadeNotas | getQuantidadeNotas() | Entero | No | Notas exportadas. Cantidad de notas con al menos un archivo escrito |
quantidadeArquivos | getQuantidadeArquivos() | Entero | No | Cantidad 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 |
arquivos | getArquivos() | Array de texto | No | Archivos exportados. Rutas absolutas de los archivos escritos, un archivo para el XML autorizado y otro para el XML de cancelación |
falhas | getFalhas() (elementos clave-valor) | Array | No | Lista 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 JSON | Clave en Java | Tipo | Descripción |
|---|---|---|---|
id | id | Texto | Identificador de la nota |
chave | chave | Texto | Clave de acceso |
motivo | motivo | Texto | Motivo 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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
arquivo | getArquivo() | Texto | No | Archivo de copia. Ruta absoluta |
bytes | getBytes() | Entero | No | Tamaño del archivo. En bytes |
versaoBanco | getVersaoBanco() | Entero | No | Versión de estructura de la base local. Para restaurar, la versión del núcleo no puede ser inferior a esta |
sha256 | getSha256() | Texto | No | Resumen 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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
versaoBanco | getVersaoBanco() | Entero | No | Versió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 |
copiaAnterior | getCopiaAnterior() | Texto | Sí | 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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
quantidade | getQuantidade() | Entero | No | Notas exportadas |
manifesto | getManifesto() | Texto | Sí | Primer manifiesto. Ruta absoluta del manifesto.json del primer paquete; vacío si no hay notas pendientes |
manifestos | getManifestos() | Array de texto | No | Todos 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 |
arquivos | getArquivos() | Array de texto | No | Archivos XML firmados. Rutas absolutas |
Origen del certificado
Parámetro de certificado de Ativar y TrocarCertificado.
| Origen | Java |
|---|---|
| Certificado ya presente en el almacén de certificados de Windows | Certificado.doRepositorio(thumbprint, maquinaLocal) |
| Archivo PFX | Certificado.deArquivoPfx(bytes, senha) |
| Parámetro | Descripción |
|---|---|
thumbprint | Huella del certificado. SHA-1 en 40 dígitos hexadecimales; los espacios se ignoran; un formato inválido devuelve 10029874 |
maquinaLocal | Indicador 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 senha | Certificado 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:
- Confirme en el estado que
pendentesTransmissaode cada empresa es 0, es decir, que todas las notas offline se transmitieron - Desactive o revoque el dispositivo en la consola; si solo cambia el certificado, instale antes el nuevo con TrocarCertificado
- Con el mismo usuario de Windows, abra
certmgr.mscy borre el certificado antiguo en "Personal > Certificados" por su huella, o ejecute en PowerShellRemove-Item Cert:\CurrentUser\My\<huella>
Terminal secundario
Retorno de CriarTerminal. Java Resultados.TerminalCriado.
| Nombre JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
id | getId() | Texto | No | Identificador del terminal. Empieza con trm_, se usa para revocar |
nome | getNome() | Texto | No | Nombre del terminal. La identificación de la caja en las notas que emite ese secundario |
token | getToken() | Texto | No | Token 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 JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
id | getId() | Texto | No | Identificador del terminal |
nome | getNome() | Texto | No | Nombre del terminal |
situacao | getSituacao() | Texto | No | Estado del terminal. Ativo o Revogado |
criadoEm | getCriadoEm() | Fecha y hora | No | Momento de emisión del token |
ultimoUsoEm | getUltimoUsoEm() | Fecha y hora | Sí | Último uso. null si nunca se usó |
revogadoEm | getRevogadoEm() | Fecha y hora | Sí | Momento de la revocación. null en terminales activos |
Excepción
Todos los fallos lanzan una excepción.
| Campo | Java TfFiscalException | Descripción |
|---|---|---|
| Código de error | getCodigo() | Entero. Decida por él, vea Códigos de error |
| Constante de error | getTipo() | Por ejemplo ENGINE_LICENSE_EXPIRED; en errores de la plataforma, el nombre de constante de la plataforma |
| Mensaje | getMessage() | Traducido al idioma de errores configurado; se puede mostrar directamente |
| Información adicional | getDetalhes(), 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ón | Hilo del callback |
|---|---|
aoReceberEvento(Consumer<EventoNfce>) en la configuración, o el método de instancia aoReceberEvento, cuyo retorno al cerrarse cancela la suscripción | En 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
EventoIdySeq. - 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_FALHOUyRUNTIME_REINICIADOlos genera el propio SDK, conSeqen 0; no necesitan confirmación ni se reenvían.
Campos comunes
| Nombre JSON | Java | Tipo | Null | Descripción |
|---|---|---|---|---|
eventoId | getEventoId() | Texto | No | Identificador del evento. Clave de deduplicación, no cambia en el reenvío |
seq | getSeq() (long) | Entero | No | Secuencia local. Creciente; 0 en los eventos locales del SDK |
tipo | getTipo() | Texto | No | Tipo de evento. Vea cada sección abajo |
ocorridoEm | getOcorridoEm() | Texto de fecha | No | Fecha del evento. ISO 8601 UTC |
empresaId | getEmpresaId() | Texto | Sí | Identificador de la empresa. null en los eventos locales del SDK |
dispositivoId | por getCampos() | Texto | Sí | Identificador del dispositivo |
id | getId() | Texto | Sí | Identificador de la nota. Solo en eventos de nota |
chave | getChave() | Texto | Sí | Clave de acceso. Solo en eventos de nota |
status | getStatus() | Texto | Sí | Estado actual de la nota. Solo en eventos de nota; valores en Estado de la nota |
dados | getDados() (Map<String, Object>) | Objeto | No | Datos del evento. Campos en cada sección abajo |
NOTA_EMITIDA_OFFLINE
Firma offline exitosa. Evento de nota, con status en ContingenciaPendente.
Campo de dados | Tipo | Descripción |
|---|---|---|
serie | Entero | Serie del dispositivo |
numero | Entero | Número de la nota |
qrCode | Texto | Contenido del QR Code |
tentativaOnline | Booleano | Indicador 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 dados | Tipo | Descripción |
|---|---|---|
protocolo | Texto | Número de protocolo de autorización |
dataAutorizacao | Texto de fecha, admite null | Fecha de autorización |
foraDoPrazo | Booleano | Indicador de entrega fuera de plazo. true si llegó a la SEFAZ después de 24 horas; la nota sigue siendo válida |
aposCorrecao | Booleano | Indicador 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 dados | Tipo | Descripción |
|---|---|---|
cStat | Entero | Código de resultado de la SEFAZ |
motivo | Texto | Mensaje 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 dados | Tipo | Descripción |
|---|---|---|
cStat | Entero | Código de resultado de la SEFAZ |
motivo | Texto | Mensaje de resultado de la SEFAZ |
numeroLiberado | Booleano | Nú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 dados | Tipo | Descripción |
|---|---|---|
codigo | Entero, admite null | Código de error de la plataforma |
mensagem | Texto | Mensaje 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 dados | Tipo | Descripción |
|---|---|---|
cStat | Entero, admite null | Código de resultado de la SEFAZ |
motivo | Texto | Mensaje del resultado |
protocolo | Texto, admite null | Nú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 dados | Tipo | Descripción |
|---|---|---|
cStat | Entero, admite null | Código de resultado de la SEFAZ |
motivo | Texto | Motivo del rechazo |
protocolo | Texto, admite null | Nú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 dados | Tipo | Descripción |
|---|---|---|
serie | Entero | Serie del dispositivo |
inicio | Entero | Número inicial |
fim | Entero | Nú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 dados | Tipo | Descripción |
|---|---|---|
serie | Entero | Serie del dispositivo |
inicio | Entero | Número inicial |
fim | Entero | Número final |
codigo | Entero | Código de error de la plataforma |
mensagem | Texto | Mensaje de la plataforma |
definitivo | Booleano | Indicador 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 dados | Tipo | Descripción |
|---|---|---|
situacao | Texto | Estado del dispositivo. Valores en Empresa emparejada |
motivo | Texto | Motivo. 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 dados | Tipo | Descripción |
|---|---|---|
expiraEm | Texto de fecha | Vencimiento de la licencia |
offlineAte | Texto de fecha | Plazo 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 dados | Tipo | Descripción |
|---|---|---|
expiradaEm | Texto de fecha | Fecha 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 dados | Tipo | Descripción |
|---|---|---|
pendenteMaisAntigaEm | Texto de fecha | Fecha de emisión de la nota por transmitir más antigua |
prazoAte | Texto de fecha | Plazo 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 dados | Tipo | Descripción |
|---|---|---|
validoAte | Texto de fecha | Vencimiento 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 dados | Tipo | Descripción |
|---|---|---|
conectado | Booleano | Indicador 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 dados | Tipo | Descripción |
|---|---|---|
pendentesTransmissao | Entero | Notas por transmitir |
eventosNaoEntregues | Entero | Eventos 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 dados | Tipo | Descripción |
|---|---|---|
codigoSaida | Entero | Código de salida del proceso |
tentativa | Entero | Intento de reinicio |
proximaTentativaMs | Entero | Milisegundos 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 dados | Tipo | Descripción |
|---|---|---|
tentativa | Entero | Nú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:
| Campo | En el SDK |
|---|---|
modoResposta | No hace falta enviarlo. El SDK siempre espera el resultado; si se envía, se ignora |
ambienteEmissao | Igual al ambiente del dispositivo. El ambiente del dispositivo lo fija el código de emparejamiento, vea Generar código de emparejamiento |
itens[].classeImposto | Disponible 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:
{"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.
| codigo | Constante | Escenario | Acción |
|---|---|---|---|
| 10029800 | ENGINE_NOT_STARTED | No inicializado | No ocurre en uso normal; si aparece, es un defecto del paquete SDK: inicialice de nuevo |
| 10029801 | ENGINE_NOT_ACTIVATED | La empresa no está emparejada en este equipo, o el equipo aún no emparejó ninguna empresa | Guíe el emparejamiento; con varias empresas revise empresaId |
| 10029802 | ENGINE_EMPRESA_REQUIRED | Hay varias empresas emparejadas y no se indicó empresaId | Envíe empresaId |
| 10029803 | ENGINE_LICENSE_MISSING | No hay licencia para emisión offline | Sincronice en línea una vez (SincronizarAgora) |
| 10029804 | ENGINE_LICENSE_EXPIRED | Licencia vencida; la emisión offline se rechaza, la emisión en línea sigue normal | Restablezca la red; se renueva sola |
| 10029805 | ENGINE_LICENSE_SIGNATURE_INVALID | Firma de la licencia inválida | Atención manual: contacte a la plataforma, la base local puede haber sido alterada |
| 10029806 | ENGINE_LICENSE_NOT_FOR_DEVICE | La licencia no pertenece a este dispositivo | Atención manual: empareje de nuevo |
| 10029807 | ENGINE_OFFLINE_WINDOW_CLOSED | Pasó el plazo de emisión offline | Emita en línea cuando vuelva la red |
| 10029808 | ENGINE_LICENSE_QUOTA_EXHAUSTED | La serie del dispositivo llegó al número 999999999 | Desactive el dispositivo y emparéjelo de nuevo con un código de emparejamiento nuevo que indique otra serie en serie; la plataforma no cambia la serie por sí sola |
| 10029809 | ENGINE_CLOCK_ROLLBACK | El reloj del sistema retrocedió | Atención manual: corrija la hora del sistema |
| 10029810 | ENGINE_TRANSMISSION_DEADLINE_REACHED | La nota pendiente más antigua superó el plazo de transmisión | Atención manual: restablezca la red cuanto antes para transmitir |
| 10029811 | ENGINE_OFFLINE_NOT_ALLOWED | La 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 nueva | Solo emisión en línea; tras una restauración reciente, la emisión offline vuelve sola después de una sincronización en línea |
| 10029812 | ENGINE_OFFLINE_FUEL_NOT_SUPPORTED | Las notas con combustible no se emiten offline | Emita cuando vuelva la red |
| 10029813 | ENGINE_CERTIFICATE_UNAVAILABLE | Certificado no encontrado, sin clave privada o con CNPJ distinto | Atención manual: revise el almacén de certificados; si hace falta, TrocarCertificado |
| 10029814 | ENGINE_CERTIFICATE_EXPIRED | Certificado vencido | Atención manual: renueve y llame TrocarCertificado |
| 10029815 | ENGINE_SNAPSHOT_MISSING | Faltan la configuración local o los datos tributarios, o no pasaron la verificación | Sincronice en línea; si persiste, contacte a la plataforma |
| 10029816 | ENGINE_DEVICE_DEACTIVATED | Dispositivo desactivado | Atención manual: contacte al integrador; las notas offline ya emitidas se siguen transmitiendo |
| 10029817 | ENGINE_REQUEST_INVALID | Solicitud inválida; Detalhes lista los motivos campo por campo | Corrija la solicitud; puede validarla antes con Previsualizar |
| 10029780 | ENGINE_TAX_CLASS_REQUIRES_ONLINE | Un ítem referencia una clase de impuesto, pero no se pudo acceder a la plataforma para expandirla; no se consumió ningún número | Reenvíe con el mismo id cuando vuelva la red; sin red, envíe impostos en los ítems |
| 10029818 | ENGINE_DUPLICATE_ID_DIFFERENT_CONTENT | El mismo id ya se usó con contenido distinto | Venta nueva con id nuevo; para reintentar, reenvíe la solicitud original y recupere la nota |
| 10029819 | ENGINE_NOTE_NOT_FOUND | La nota no existe en este equipo | Revise id y empresaId |
| 10029820 | ENGINE_NOTE_NOT_CORRECTABLE | El estado actual no permite corregir | Solo Rejeitada admite Substituir |
| 10029821 | ENGINE_CORRECTION_CHANGES_TOTALS | La corrección cambió valores o impuestos | Cambie solo lo que no afecta valores |
| 10029822 | ENGINE_CANCEL_NOT_ALLOWED | El estado actual no permite cancelar | No reintente |
| 10029823 | ENGINE_SERIE_EXHAUSTED | Numeración de la serie del dispositivo agotada | Desactive el dispositivo y emparéjelo de nuevo con un código de emparejamiento nuevo que indique otra serie en serie; la plataforma no cambia la serie por sí sola |
| 10029824 | ENGINE_PLATFORM_UNREACHABLE | Una operación que requiere conexión (emparejamiento) no llega a la plataforma | Revise la red y reintente |
| 10029825 | ENGINE_ACTIVATION_CODE_INVALID | Formato, firma o vigencia del código de emparejamiento incorrectos | Atención manual: genere un código nuevo |
| 10029826 | ENGINE_ACTIVATION_HOST_UNTRUSTED | El código de emparejamiento apunta a una dirección de plataforma no confiable | Atención manual: confirme el origen del código y el ambiente del instalador (pruebas / producción) |
| 10029827 | ENGINE_KEY_PROTECTION_FAILED | El directorio de datos viene de otra computadora o de otro usuario de Windows | Atención manual: ejecute en la computadora y el usuario originales, o empareje de nuevo |
| 10029828 | ENGINE_DATA_DIR_LOCKED | El 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ó Encerrar | Cierre la otra instancia; antes de restaurar una copia de seguridad, llame Encerrar |
| 10029829 | ENGINE_LOCAL_STORE_CORRUPTED | Base local inconsistente | Atención manual: no borre el directorio de datos, contacte a la plataforma |
| 10029830 | ENGINE_PROTOCOL_VERSION_UNSUPPORTED | Versiones de SDK y runtime incompatibles | Actualice el SDK y el runtime juntos |
| 10029831 | ENGINE_RUNTIME_START_FAILED | Falló el inicio del runtime | Revise que el directorio del runtime esté completo y que el antivirus no lo bloquee |
| 10029832 | ENGINE_RUNTIME_CRASHED | El runtime terminó inesperadamente | Se puede reintentar; con reinicio automático el SDK se recupera solo, reenvíe la emisión con el mismo id |
| 10029833 | ENGINE_TIMEOUT | Tiempo de espera agotado | Reenvíe la emisión con el mismo id, o primero Consultar |
| 10029834 | ENGINE_SHUTTING_DOWN | Cerrando o ya cerrado | Llame de nuevo Iniciar |
| 10029835 | ENGINE_IN_PROCESS_UNSUPPORTED | El modo en proceso de Java exige Java 21 o superior | Use el modo subproceso |
| 10029836 | ENGINE_INTERNAL_ERROR | Error interno del núcleo; el mensaje trae un número de referencia | Contacte a la plataforma con el número de referencia y los logs |
| 10029837 | ENGINE_ALREADY_ACTIVATED | La empresa ya está emparejada en este directorio de datos | No hace falta emparejar de nuevo; para cambiar de equipo, desactive antes el dispositivo anterior |
| 10029838 | ENGINE_PLATFORM_RESPONSE_UNTRUSTED | Respuesta de la plataforma rechazada en la verificación; se conservaron los datos anteriores | Se reintenta sola; si persiste, revise si un proxy de red altera las respuestas |
| 10029839 | ENGINE_ACTIVATION_PERSIST_FAILED | La plataforma emparejó pero falló el guardado local | Empareje de nuevo con el mismo código de emparejamiento |
| 10029840 | ENGINE_CONFIG_INVALID | Configuración de inicio inválida | Corrija la configuración |
| 10029841 | ENGINE_AUTHORIZED_XML_UNAVAILABLE | XML autorizado no disponible: la nota aún no se autorizó, o no está en el equipo y no se pudo recuperar de la plataforma | Si 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 |
| 10029842 | ENGINE_LOCAL_STORE_NEWER_VERSION | La 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 rechaza | Actualice el SDK y el runtime a una versión no inferior a la última usada; nunca borre el directorio de datos |
| 10029843 | ENGINE_CANCEL_XML_UNAVAILABLE | XML de cancelación no disponible: la nota no está cancelada, o no está en el equipo y no se pudo recuperar de la plataforma | Si no está cancelada, espere CANCELAMENTO_CONCLUIDO y vuelva a pedirlo; si ya está cancelada, reintente más tarde |
| 10029844 | ENGINE_EXPORT_FAILED | Falla 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 existe | Cambie de directorio o de nombre de archivo; revise el espacio en disco y los permisos |
| 10029845 | ENGINE_SUBSTITUTE_KEY_INVALID | Clave 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 rechazada | Informe la clave de acceso de 44 dígitos de la nota offline emitida en este equipo para la misma venta |
| 10029846 | ENGINE_BACKUP_INVALID | La 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 SDK | Verifique la contraseña; use otra copia de seguridad íntegra. La base original no se modificó |
| 10029870 | ENGINE_PROTOCOL_INVALID_JSON | El runtime recibió un mensaje que no es JSON válido | Defecto del paquete SDK; actualice el SDK |
| 10029871 | ENGINE_PROTOCOL_LINE_TOO_LONG | Un mensaje superó 8 MB | Solicitud demasiado grande; divida los ítems |
| 10029872 | ENGINE_PROTOCOL_MESSAGE_INVALID | Estructura de mensaje inválida | Defecto del paquete SDK; actualice el SDK |
| 10029873 | ENGINE_METHOD_UNKNOWN | El runtime no conoce el método | El SDK es más nuevo que el runtime; actualice el runtime |
| 10029874 | ENGINE_PARAMS_INVALID | Parámetro ausente o de tipo incorrecto; Detalhes.campo indica cuál | Corrija el parámetro, por ejemplo solicitud que no es objeto JSON, formato de la huella del certificado o de la fecha |
| 10029875 | ENGINE_ALREADY_STARTED | Inicializació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ó Iniciar | No 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 |
| 10029876 | ENGINE_REQUEST_ID_DUPLICATED | La misma llamada aún está en proceso | Defecto del paquete SDK; actualice el SDK |
| 10029877 | ENGINE_RUNTIME_NOT_FOUND | Runtime no encontrado | Revise el instalador y el directorio del runtime |
| 10029878 | ENGINE_TOO_MANY_PENDING | Más de 64 llamadas en espera al mismo tiempo | Reduzca la concurrencia |
| 10029879 | ENGINE_RESPONSE_TOO_LARGE | Una respuesta superó el límite | Contacte a la plataforma |
| 10029880 | ENGINE_PRINCIPAL_UNREACHABLE | El secundario no alcanza al principal; la solicitud no llegó | Reintente más tarde, o pase la caja a la máquina de respaldo |
| 10029881 | ENGINE_PRINCIPAL_RESULT_UNKNOWN | La solicitud llegó al principal pero no volvió respuesta; resultado desconocido | Cuando vuelva el principal, llame Consultar con el mismo id; reenviar Emitir con el mismo id y contenido no emite dos veces |
| 10029882 | ENGINE_TERMINAL_TOKEN_INVALID | Token del terminal secundario inválido o revocado | Llame de nuevo CriarTerminal en el principal y actualice TokenTerminal del secundario |
| 10029883 | ENGINE_PRINCIPAL_ADDRESS_INVALID | Dirección del principal mal formada o fuera de la red local privada | Corrija EnderecoPrincipal |
| 10029884 | ENGINE_MODE_METHOD_UNAVAILABLE | El modo actual no ofrece este método | Emparejamiento, cambio de certificado, copia de seguridad y exportación se hacen en el principal; la gestión de terminales solo en el principal |
| 10029885 | ENGINE_PRINCIPAL_REJECTED | El principal rechazó el origen de la solicitud, por ejemplo un secundario fuera de las redes permitidas | Revise RedesPermitidas del principal y la red |
| 10029886 | ENGINE_PRINCIPAL_RATE_LIMITED | Demasiados fallos de autenticación; limitado por el principal | Revise el token y reintente tras 1 minuto |
| 10029887 | ENGINE_PRINCIPAL_LISTEN_FAILED | No se puede escuchar en el puerto de red local del principal | Cambie PortaPrincipal o libere el puerto |
| 10029888 | ENGINE_TERMINAL_NOT_FOUND | El terminal a revocar no existe | Revise el id del terminal con ListarTerminais |
Todos los códigos, incluidos los del Asistente Fiscal, están en Códigos de error.
