TF Fiscal
Documentação

NFC-e offline

Referência do SDK

Referência do SDK embarcado de NFC-e offline: configuração, assinatura e erros de cada método, tipos de dados, eventos e códigos de erro.

Manual de consulta do SDK embarcado, dividido em configuração, métodos, tipos de dados, eventos, requisição de emissão e códigos de erro; cada seção pode ser consultada sozinha. Os nomes dos métodos estão em português; os títulos e o texto desta página usam a forma com inicial maiúscula (como Emitir), e no código Java a inicial é minúscula (como emitir). Na primeira integração, comece pelo tutorial do SDK embarcado.

Configuração

A configuração é passada de uma vez ao chamar Iniciar e não pode ser alterada depois da inicialização; para trocar a configuração, chame Encerrar e depois Iniciar de novo. A configuração é montada com Configuracao.builder() ... .build(), de forma encadeada.

As cinco últimas linhas da tabela (papel principal ou secundário, porta do principal, redes permitidas, endereço do principal, token do terminal) só se aplicam à implantação principal e secundário, em que vários caixas da mesma loja usam uma só série do dispositivo. A divisão de papéis, os passos de implantação e os métodos disponíveis no secundário estão em Vários caixas (modo principal e secundário).

ItemJavaObrigatórioDescrição
Diretório de dadosdiretorioDados(Path)SimDiretório da base local. Um por caixa, aberto por um único processo de cada vez; antes da transmissão, os arquivos assinados das notas offline só existem aqui, não apague. Veja SDK embarcado
Diretório do runtimediretorioRuntime(Path)Obrigatório no modo subprocessoDiretório de instalação do runtime. Deve conter tffiscal-nfce.exe; se não for encontrado, devolve 10029877
Nome do PDVnomeAplicativo(String)SimNome do software do PDV. A plataforma reconhece o software por ele; use o mesmo nome em todos os caixas que rodam o mesmo software; se faltar, volta 10029874
Versão do PDVversaoAplicativo(String)SimNúmero de versão do PDV. A plataforma usa para controlar versão mínima e versões bloqueadas, por exemplo 3.2.1
Idioma das mensagensidioma(String)NãoIdioma das descrições de exceção. pt-BR (padrão), en, zh-CN, es; vale só a parte do idioma, por exemplo en-US é inglês, e outros idiomas caem para português. Erros devolvidos pela plataforma e repassados pelo SDK (como classe de imposto inexistente ou incompatível com o regime) também vêm neste idioma
Tempo limite da chamadatempoLimitePadraoMs(long)NãoEspera máxima de cada chamada. Padrão de 30 segundos; ao estourar devolve 10029833 e o resultado atrasado é descartado. Pareamento e obtenção do XML de autorização ou de cancelamento esperam pelo menos 120 segundos; ExportarXmls, ExportarPendentes, Backup e RestaurarBackup esperam pelo menos 30 minutos; se este item for configurado com valor maior, vale este item
Tempo limite da partidatempoLimiteInicioMs(long)NãoEspera máxima até o runtime ficar pronto. Padrão de 5 segundos; ao estourar devolve 10029831
Reinício automáticoreiniciarAutomaticamente(boolean)NãoReinício automático do runtime após saída inesperada. Ligado por padrão, com intervalos de 1, 2, 4 segundos até 60 segundos
Encaminhamento de logencaminharLog(boolean)NãoLog do núcleo enviado ao PDV. Desligado por padrão; ligado, vai para java.util.logging
Proxy de saídaproxy(String)NãoEndereço do proxy manual. No formato host:porta; sem configuração, não usa proxy e conecta direto; formato inválido devolve 10029874. Veja Proxy de saída
Autenticação no proxyproxyAutenticacao(String, String)NãoUsuário e senha do proxy. Valem tanto para o proxy manual quanto para o do sistema; a senha só passa ao runtime em memória, não vai para o disco nem para o log; autenticação sem endereço de proxy e sem proxy do sistema devolve 10029874
Usar proxy do sistemausarProxyDoSistema(boolean)NãoUso do proxy do sistema. Desligado por padrão; ligado, usa a configuração de proxy do Windows e prevalece sobre Proxy; script PAC de proxy automático não é suportado
Dias de retenção do XMLretencaoXmlDias(int)NãoDias de retenção do XML no computador. Número de dias que o XML autorizado e o XML de cancelamento ficam no computador, de 1 a 3650; sem configuração ou com 0, 90 dias; fora da faixa devolve 10029874. XML apagado ao fim da retenção é buscado na plataforma automaticamente na leitura; na exportação mensal de XML, o período exportado deve ficar dentro da retenção
Modo de execuçãomodo(Modo)NãoModo de execução do Java. SUBPROCESSO (padrão) ou EM_PROCESSO, veja abaixo
Ouvinte de eventosaoReceberEvento(Consumer<EventoNfce>)NãoTratador de eventos registrado na partida. Eventos acumulados antes da partida não se perdem; veja Eventos
Comando do runtimecomandoRuntime(String)NãoItem avançado. Caminho completo do executável do runtime, só para desenvolvimento e testes
Parâmetros do runtimeargumentosRuntime(List<String>)NãoItem avançado. Parâmetros de partida do runtime, padrão --stdio; só para desenvolvimento e testes
Motor simuladomotorSimulado(boolean)NãoMotor substituto para testes. Só para exemplos e testes automatizados, não gera notas válidas; não ligue em produção
Papel principal ou secundáriomodoOperacao(ModoOperacao)NãoPapel deste caixa quando vários caixas usam uma só série. Independente (padrão), principal ou secundário, com os valores INDEPENDENTE / PRINCIPAL / SECUNDARIO; veja Vários caixas (modo principal e secundário)
Porta do principalportaPrincipal(int)NãoPorta de rede local do principal. Só no principal; sem valor ou 0 é 8786; com a porta ocupada, Iniciar devolve 10029887
Redes permitidasredesPermitidas(List<String>)NãoRedes dos secundários aceitas pelo principal. Só no principal; notação CIDR, por exemplo 192.168.0.0/24; sem valor é a rede /24 do principal; só aceita endereços privados de rede local; formato inválido devolve 10029874
Endereço do principalenderecoPrincipal(String)Obrigatório no secundárioEndereço do principal ao qual o secundário se conecta. Forma host:porta, por exemplo 192.168.0.10:8786; precisa ser endereço privado de rede local, senão 10029883
Token do terminaltokenTerminal(String)Obrigatório no secundárioToken do terminal secundário. Emitido por CriarTerminal no principal, começa com tfl_; só vai para o runtime em memória, nunca para disco ou log; inválido ou revogado, Iniciar devolve 10029882

Modo de execução no Java

ModoSignificadoRequisitos
SUBPROCESSOPadrão. O SDK inicia o runtime como subprocessoHost com Java 8 ou superior; é preciso distribuir o runtime e definir diretorioRuntime
EM_PROCESSOO núcleo roda direto na JVM do PDV, sem subprocessoHost com Java 21 ou superior e os jars do runtime e do núcleo no classpath; abaixo do Java 21 a partida devolve 10029835. Com autenticação no proxy, os parâmetros de partida da JVM precisam incluir -Djdk.http.auth.tunneling.disabledSchemes=, veja Proxy de saída

Proxy de saída

O núcleo decide se usa proxy para acessar a plataforma conforme a tabela abaixo:

ConfiguraçãoForma de proxy
UsarProxyDoSistema ligadoProxy do sistema. Lê primeiro a configuração de proxy WinHTTP do computador no Windows e, se não houver, a configuração de proxy das Opções da Internet do usuário atual do Windows; com Proxy também configurado, vale o proxy do sistema
Só Proxy configuradoProxy manual. Usa o endereço informado em Proxy
Nada configuradoConexão direta
  • Script PAC de proxy automático não suportado: se o Windows só tiver script de proxy automático, sem endereço de proxy fixo, o núcleo registra um aviso no log e conecta direto. Nessa rede, configure Proxy manualmente.
  • Autenticação no proxy: proxyAutenticacao vale tanto para o proxy manual quanto para o do sistema.
  • Parâmetro de partida no modo em processo do Java: a autenticação Basic do proxy no túnel HTTPS depende da propriedade de sistema da JVM jdk.http.auth.tunneling.disabledSchemes, que a JVM lê uma única vez, no primeiro uso do cliente HTTP embutido; mudanças posteriores não têm efeito. No modo em processo do Java (EM_PROCESSO) com autenticação no proxy, o host precisa acrescentar -Djdk.http.auth.tunneling.disabledSchemes= aos parâmetros de partida da JVM (vazio depois do sinal de igual). Ao carregar, o núcleo também esvazia a propriedade o mais cedo possível quando o host não a definiu, e verifica se isso surtiu efeito: se o host desativou Basic explicitamente, se já usou antes o cliente HTTP embutido da JVM, ou se não dá para saber, Avisos em Situacao informa que a autenticação do proxy pode não funcionar, e um aviso é gravado no log. No modo subprocesso do Java, o subprocesso do runtime define isso na partida, e o host não precisa fazer nada.

Abaixo, o exemplo mostra o proxy manual com autenticação.

java
Configuracao configuracao = Configuracao.builder()
// Demais itens de configuração como acima
.proxy("10.0.0.5:3128")
.proxyAutenticacao("caixa01", senhaProxy)
.build();

Exemplo de configuração

Uma configuração básica comum; os itens não listados ficam com o valor padrão.

java
Configuracao configuracao = Configuracao.builder()
.diretorioDados(Paths.get("C:/ProgramData/MinhaLoja/TFFiscal"))
.diretorioRuntime(Paths.get("C:/Program Files/MinhaLoja/tffiscal-runtime"))
.nomeAplicativo("Caixa Exemplo")
.versaoAplicativo("1.0.0")
.idioma("pt-BR")
.tempoLimitePadraoMs(30_000)
.build();

Métodos

Cada método segue a mesma ordem: para que serve e se usa a rede, assinatura, parâmetros, retorno, erros possíveis e exemplos. Além dos erros listados em cada método, qualquer método pode devolver os erros gerais; veja o início de Códigos de erro.

Iniciar

Inicia o SDK: sobe o runtime (modo subprocesso) ou carrega o núcleo (modo em processo do Java), abre o diretório de dados, retoma o que ficou incompleto da última vez e começa em segundo plano o heartbeat, a transmissão e a busca de resultados. Os demais métodos só podem ser chamados depois de Iniciar dar certo; um diretório de dados só pode ter uma instância por vez.

Rede: não precisa. Inicia mesmo sem rede e, quando houver rede, começa a sincronizar.

Assinatura

java
public static TfFiscalNfce iniciar(Configuracao config);

Parâmetros

ParâmetroJavaObrigatórioDescrição
ConfiguraçãoconfigSimConfiguração de inicialização. Campos em Configuração

Retorno

A instância do SDK pronta, TfFiscalNfce. Ao terminar, chame Encerrar; também dá para fechar automaticamente com try-with-resources.

Erros possíveis

Código de erroSituaçãoAção
10029877Runtime não encontradoConfira se o diretório do runtime e tffiscal-nfce.exe vão no instalador
10029831O runtime não iniciou ou não ficou pronto dentro do tempo limite da partidaVeja o log; em computador lento, aumente o tempo limite da partida
10029830Versões do SDK e do runtime incompatíveisDistribua runtime e SDK da mesma versão
10029835Modo em processo do Java com host abaixo do Java 21Use o modo subprocesso ou atualize o Java
10029828Diretório de dados já aberto por outro processoAbra uma única instância por diretório; verifique processos remanescentes
10029827A chave local não pode ser aberta: o diretório de dados veio de outro computador ou de outro usuário do WindowsRode com o usuário Windows original; para trocar de computador, desative o dispositivo antigo e pareie de novo
10029829Base local inconsistenteNão apague o diretório de dados; fale com a plataforma
10029842Base local de versão mais nova que o núcleo atual: o diretório de dados já foi usado por uma versão mais nova do SDK e a partida é recusadaAtualize o SDK e o runtime para uma versão não inferior à última usada; nunca apague o diretório de dados, os originais das notas offline não transmitidas estão nele
10029840Configuração inválidaCorrija o item de configuração conforme Message
10029874Valor de configuração inválido: nome ou versão do PDV ausente, endereço de proxy com formato inválido, só autenticação no proxy, dias de retenção do XML fora da faixaCorrija o item de configuração conforme Detalhes.campo
10029882Token do terminal secundário inválido ou revogadoEmita outro token no principal e atualize TokenTerminal
10029883Endereço do principal mal formatado ou fora da rede local privadaCorrija EnderecoPrincipal
10029887Não foi possível escutar na porta de rede local do principalTroque PortaPrincipal ou libere a porta

Também pode devolver os erros gerais.

Exemplos

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

Ativado / Empresas

  • Ativado: indica se este diretório de dados já tem pelo menos uma empresa pareada. Ao iniciar, o PDV usa isso para decidir se entra no fluxo de pareamento.
  • Empresas: lista das empresas pareadas. Quando um diretório de dados pareia várias empresas (vários CNPJ), use para achar o empresaId de cada uma.

Os dois consultam o núcleo a cada chamada, sem cache: depois que o dispositivo é desativado pela plataforma, a situação aparece fielmente no campo Situacao.

Rede: não precisa.

Assinatura

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

Parâmetros

Nenhum.

Retorno

Ativado devolve um booleano. Empresas devolve a lista de empresas pareadas; campos dos itens em Tipos de dados: empresa pareada.

Erros possíveis

Só os erros gerais.

Exemplos

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

InspecionarCodigoAtivacao

Confere no próprio computador o formato, a assinatura da plataforma, a validade e o endereço da plataforma do código de pareamento, e lê a empresa, o ambiente e as formas permitidas. Não usa rede e não consome o código. Serve para mostrar ao caixa, antes do pareamento, algo como "código de homologação, válido por 72 horas", ou para barrar antes códigos com formato errado, vencidos ou de forma incompatível.

Rede: não precisa. Código válido não garante pareamento bem-sucedido: código já usado ou revogado e casos semelhantes só a plataforma consegue julgar em Ativar.

Assinatura

java
public Resultados.CodigoAtivacao inspecionarCodigoAtivacao(String codigo);

Parâmetros

ParâmetroJavaObrigatórioDescrição
Código de pareamentocodigoSimTexto completo do código de pareamento. Começa com TFA1.; o conteúdo do arquivo .tfa é o próprio código, e espaços no início e no fim são removidos

Retorno

Informações do código de pareamento; campos em Tipos de dados: informações do código de pareamento.

Erros possíveis

Código de erroSituaçãoAção
10029825Formato, assinatura ou validade do código incorretosConfira se copiou o código inteiro; se venceu, peça ao integrador para gerar outro
10029826O código aponta para um endereço de plataforma não confiávelO código não foi emitido por esta plataforma, ou a versão do runtime não corresponde ao ambiente; fale com o integrador

Também pode devolver os erros gerais.

Exemplos

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

Ativar

Com o código de pareamento gerado pelo integrador e o certificado A1 da empresa, pareia este computador como um dispositivo da empresa. No pareamento o núcleo gera as chaves do dispositivo, vincula o certificado e se registra na plataforma; em caso de sucesso recebe a série do dispositivo e a primeira licença, e a plataforma envia nfce.device.activated (veja Como os resultados chegam). Cada empresa é pareada uma única vez num diretório de dados; o mesmo diretório pode parear outras empresas.

Rede: precisa. Sem conexão com a plataforma devolve 10029824, e o código de pareamento não é consumido.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Código de pareamentocodigoAtivacaoSimTexto completo do código de pareamento. Começa com TFA1., de uso único, válido por 72 horas
CertificadocertificadoSimCertificado A1 da empresa. Formas de informar em Tipos de dados: origem do certificado; o CNPJ do certificado deve ser o da empresa da loja

Retorno

Resultado do pareamento; campos em Tipos de dados: resultado do pareamento.

Erros possíveis

Código de erroSituaçãoAção
10029825 / 10029826Falha na verificação local do código / plataforma não confiávelVeja InspecionarCodigoAtivacao
10029824Sem conexão com a plataformaConecte e tente de novo
10029837Empresa já pareada neste diretório de dadosNão precisa parear de novo
10029813 / 10029814Certificado não encontrado, sem chave privada, CNPJ divergente / vencidoUse um certificado A1 válido da empresa
10029839Pareada na plataforma, mas a gravação local falhouChame Ativar de novo com o mesmo código de pareamento
10029806A licença não pertence a este dispositivoPareie de novo; se continuar, fale com a plataforma
10029874Parâmetro de certificado inválido: impressão digital sem 40 dígitos hexadecimais, ou PFX vazioCorrija o parâmetro do certificado
10029205 a 10029208Devolvido pela plataforma: código inválido / vencido / já usado / revogadoGere outro código de pareamento
10029209Devolvido pela plataforma: o código não permite a forma SDKGere de novo com Sdk ou Qualquer
10029210 / 10029211Devolvido pela plataforma: falta o nome do PDV / versão do PDV bloqueada ou abaixo da mínimaConfigure o nome do PDV; atualize o PDV
10029213 / 10029214Devolvido pela plataforma: CNPJ do certificado difere da empresa / certificado vencidoUse um certificado válido da empresa
10029219Devolvido pela plataforma: ambiente do código diferente do ambiente atual da empresaGere um novo código no ambiente atual da empresa
10029221 a 10029225Devolvido pela plataforma: a série do dispositivo indicada no código não está mais disponívelO integrador gera um novo código com outra série ou outro número inicial

Também pode devolver os erros gerais.

Exemplos

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

Emitir

Emite uma NFC-e. O núcleo pega o próximo número da série do dispositivo, assina a nota e primeiro a entrega à plataforma para autorização online; sem conexão com a plataforma, com tempo esgotado ou resultado incerto, assina a nota offline no próprio computador e devolve na hora uma nota offline pronta para imprimir. O corpo da requisição é exatamente o da API de emissão em nuvem; veja Requisição de emissão.

Ordem de processamento:

  1. Busca local por id: se o mesmo id já foi emitido, devolve a nota original sem tomar outro número; conteúdo diferente devolve 10029818.
  2. Se uma linha de item referencia classe de imposto (classeImposto), a requisição vai antes à plataforma, que a expande em impostos completos: exige conexão, e sem acesso à plataforma devolve 10029780 sem consumir número; classe de imposto recusada (inexistente, incompatível com o regime etc.) devolve o código e a mensagem da plataforma sem alteração.
  3. Normalização e validação, com as mesmas regras da nuvem; se não passar, devolve 10029817, com Detalhes listando os motivos campo a campo.
  4. Pega um número da série do dispositivo, assina e envia online, com resultado igual ao da emissão síncrona em nuvem; erro de negócio devolvido pela plataforma volta sem alteração, não vira offline e o número fica para a nota seguinte. A única exceção é a plataforma informar o número como já usado (10029424): o núcleo descarta esse número, sincroniza uma vez com a plataforma para atualizar o número confirmado e tenta de novo uma única vez; um segundo conflito volta sem alteração, sem ficar testando número após número e travando o caixa.
  5. Falha ou tempo esgotado online: confere licença, prazo de transmissão, permissão offline e demais condições, assina offline e devolve ContingenciaPendente. Com resultado incerto, o número original não é reaproveitado: a nota offline recebe o número seguinte e a plataforma resolve o original, cancelando por substituição se foi autorizado ou inutilizando se não (veja Números que a plataforma trata por você); se não dá para assinar offline naquele momento, devolve AguardandoAutorizacao e depois reenvia o número original sem alteração. Se a última tentativa de rede acabou de falhar, pula o passo 4 e assina offline direto.

As emissões da mesma empresa rodam em ordem dentro do núcleo, garantindo numeração contínua na série do dispositivo, entre notas online e offline; empresas diferentes podem rodar em paralelo.

Rede: opcional. Com rede emite online; sem rede assina offline.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Requisição de emissãopedidoJsonSimRequisição de emissão. Texto JSON; mesma estrutura da API de emissão em nuvem, sem precisar de modoResposta. As linhas de item podem trazer impostos ou referenciar uma classe de imposto com classeImposto (exige conexão)
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; com várias e sem informar, devolve 10029802

Retorno

Resultado da emissão; campos e situações em Tipos de dados: resultado da emissão.

StatusO que o PDV faz
AutorizadaImprime o cupom
ContingenciaPendenteAssinada offline: imprime o cupom com Cupom e entrega ao consumidor; a transmissão é automática
AguardandoAutorizacaoAceita online, mas a SEFAZ ainda não respondeu, e naquele momento não dava para assinar offline: não imprima ainda; aguarde o evento NOTA_AUTORIZADA ou consulte depois; se a SEFAZ negar depois, chega NOTA_NEGADA
NegadaEmissão online negada pela SEFAZ: não admite correção com o mesmo número; corrija os dados da venda conforme o código e a mensagem de resultado da SEFAZ e emita de novo com um id novo

Erros possíveis

Código de erroSituaçãoAção
10029817Falha na validação da requisiçãoCorrija conforme Detalhes
10029780Linha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumidoReenvie com o mesmo id quando a rede voltar; sem rede, envie impostos nas linhas de item
10029818O mesmo id já foi usado em nota de conteúdo diferenteVenda nova com id novo; para repetir, use a requisição original
10029801 / 10029802Empresa não pareada / várias empresas sem empresaIdPareie primeiro; informe empresaId
10029816Dispositivo desativadoFale com o integrador
10029805 / 10029806Assinatura da licença inválida / licença de outro dispositivoFale com a plataforma; se preciso, pareie de novo
10029874A requisição não é um objeto JSONEnvie o texto de um objeto JSON
10029803 / 10029804 / 10029807Sem rede e sem licença / licença vencida / prazo offline encerradoRestaure a rede; depois da renovação volta sozinho
10029808A série do dispositivo chegou ao número 999999999Desative o dispositivo e pareie-o de novo com um código de pareamento novo que informe outra série em serie; a plataforma não troca a série sozinha
10029809O relógio do sistema foi atrasadoCorrija a hora do sistema
10029810A nota pendente mais antiga passou do prazo de transmissãoRestaure a rede para transmitir
10029811 / 10029812Empresa ou estado não permite offline / nota com combustívelSó é possível emitir online
10029813 / 10029814Certificado indisponível / vencidoConfira o certificado; se preciso, TrocarCertificado
10029815Faltam a configuração local ou os dados fiscaisSincronize uma vez com rede
10029823Numeração da série do dispositivo esgotadaDesative o dispositivo e pareie-o de novo com um código de pareamento novo que informe outra série em serie; a plataforma não troca a série sozinha
10029307Devolvido pela plataforma: ambiente do dispositivo diferente do ambiente atual da empresaPareie um dispositivo novo no ambiente atual da empresa
10029424Devolvido pela plataforma: número já usado. O núcleo já descartou o número e tentou de novo uma vez; se o conflito se repete, o banco local e os registros da plataforma divergemNão tente com outro número; exporte os logs e fale com a plataforma
10029426Devolvido pela plataforma: o mesmo id já tem uma nota não rejeitada na plataforma, por exemplo emitida pela API em nuvem ou por outro dispositivoConfira a nota original em Consultar NFC-e; use um id novo para uma venda nova
Outros códigos da plataformaErro de negócio devolvido pela plataforma na emissão online, como 10022004Trate conforme os erros de Emitir NFC-e

Também pode devolver os erros gerais.

Exemplos

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

Previsualizar

Verifica uma requisição de emissão com a mesma normalização, validação e cálculo de tributos de Emitir e devolve se passou, as mensagens de erro campo a campo, o total da nota e o total de tributos. Não toma número, não assina, não grava e não usa rede. Serve para validar enquanto o caixa digita: se a validação não passar, não lança exceção e devolve Valido = false.

Rede: não precisa.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Requisição de emissãopedidoJsonSimRequisição a validar. Mesma estrutura de Emitir; o id pode ficar para depois
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. No Java, passe null quando só uma empresa está pareada

Retorno

Resultado da prévia; campos em Tipos de dados: resultado da prévia. Erros já vem traduzido conforme o idioma das mensagens configurado e pode ser mostrado direto ao caixa.

Erros possíveis

Validação que não passa não lança erro. Além dos erros gerais, só há erros ligados à empresa: 10029801 (empresa não pareada), 10029802 (várias empresas sem empresaId) e 10029815 (faltam os dados fiscais locais; sincronize uma vez com rede).

Também pode devolver os erros gerais.

Exemplos

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

Recomenda-se chamar depois de uma pausa de cerca de 300 milissegundos na digitação, e não a cada tecla.

Consultar

Consulta, pelo id usado na emissão, a situação atual de uma nota local: se já foi autorizada, se já foi transmitida, se há cancelamento pendente, quantas correções teve, se o XML autorizado já foi baixado e a requisição de emissão original. Notas online e offline ficam no computador, e a nota offline pode ser consultada antes da transmissão. Depois de uma queda e reinício do PDV, use para recuperar as notas emitidas antes da queda.

Rede: não precisa. O retorno é o registro local; os resultados de transmissão e autorização são atualizados pela sincronização em segundo plano. Para ter o resultado mais recente o quanto antes, chame SincronizarAgora primeiro.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Identificador da notaidSimO id da requisição de emissão
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada

Retorno

Situação consultada; campos em Tipos de dados: situação consultada.

Erros possíveis

Código de erroSituaçãoAção
10029819A nota não existe neste computadorConfira id e empresaId; se a nota não foi emitida neste computador, use a consulta em nuvem
10029801 / 10029802Empresa não pareada / várias empresas sem empresaIdPareie primeiro; informe empresaId

Também pode devolver os erros gerais.

Exemplos

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

ListarNotas

Lista as notas locais em páginas (online e offline juntas), em ordem decrescente de emissão, 50 por página. Serve para a tela de "Notas do dia" e para conferir notas pendentes de transmissão na troca de turno. Para não contar a tabela inteira, o resultado não traz total, só se há próxima página.

Rede: não precisa.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Data de emissãodataNãoFiltro pelo dia da emissão. A data segue o fuso do estado da empresa; sem ela não há limite de data, então numa lista do dia informe sempre
SituaçãostatusNãoFiltro por situação. Valores em Tipos de dados: situação da nota; sem ele não há limite
PáginapaginaNãoNúmero da página. Começa em 1, padrão 1
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null

Retorno

Página de notas; campos em Tipos de dados: página de notas. A paginação na tela tem só "anterior / próxima"; desabilite "próxima" quando TemMais for false.

Erros possíveis

Código de erroSituaçãoAção
10029874Data fora do formato yyyy-mm-dd, situação com valor inválido, ou página menor que 1Informe conforme a tabela de valores
10029801 / 10029802Empresa não pareada / várias empresas sem empresaIdPareie primeiro; informe empresaId

Também pode devolver os erros gerais.

Exemplos

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

Cancelar

Cancela uma NFC-e já emitida. Conforme a situação da nota e a rede, há três destinos:

CasoDestino SituacaoDepois
Nota autorizada e com redeSolicitadoEnviado à plataforma; o resultado chega pelos eventos CANCELAMENTO_CONCLUIDO ou CANCELAMENTO_REJEITADO
Nota offline transmitida e ainda não autorizadaAgendadoA plataforma agenda o cancelamento e o dispara no momento da autorização, sem exigir que o PDV esteja aberto
Sem rede no momento, ou nota offline ainda não transmitidaEnfileiradoLocalFica na fila local; logo após a transmissão, é enviado na mesma rodada; motivo diz a causa

O prazo de cancelamento é o mesmo da nuvem; veja Cancelar NFC-e. O uso no fluxo do caixa está em Operação e recursos avançados: cancelamento.

Rede: opcional. Sem rede entra na fila local.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Identificador da notaidSimO id da requisição de emissão
JustificativajustificativaSimMotivo do cancelamento. De 15 a 255 caracteres
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null

Retorno

Resultado do cancelamento; campos em Tipos de dados: resultado do cancelamento. Aceite não significa cancelado; o resultado final está nos eventos ou no Status de Consultar.

Erros possíveis

Código de erroSituaçãoAção
10029822A situação atual não permite cancelar: já cancelada, já há cancelamento pendente, ou não está autorizada nem aguardando autorização; também quando a situação local ainda não foi sincronizada e a plataforma recusa o cancelamento (por exemplo, nota já rejeitada), com o motivo da plataforma em detalhesNão tente de novo; confira a situação com Consultar
10029819A nota não existe neste computadorConfira o id
10029817Justificativa fora de 15 a 255 caracteresCorrija a justificativa
Outros códigos da plataformaErro devolvido pela plataforma no envio, como prazo de cancelamento vencido 10022007Trate conforme Cancelar NFC-e

Também pode devolver os erros gerais.

Exemplos

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

CancelarPorSubstituicao

Cancelamento por substituição: quando uma nota emitida online é substituída por uma nota de contingência offline emitida depois neste computador (nova emissão para a mesma venda), cancela a nota original informando no cancelamento a chave de acesso da nota substituta.

Requisitos:

ObjetoPrecisa atenderSe não atender
Nota originalNota normal emitida online, encaminhada pela plataforma: não é offline, não está cancelada e não tem cancelamento pendente10029822
Nota substitutaNota offline emitida neste computador, para esta empresa, não recusada pela plataforma; chave de acesso de 44 dígitos, modelo 65, dígito verificador correto, mesmo CNPJ da original e diferente da chave da original10029845

Se a substituta ainda não foi transmitida, devolve EnfileiradoLocal: o cancelamento fica na fila do computador e só é enviado depois que a substituta for transmitida com sucesso. O resultado final chega pelos eventos CANCELAMENTO_CONCLUIDO ou CANCELAMENTO_REJEITADO. O prazo de cancelamento é o mesmo da nuvem; veja Cancelar NFC-e. O fluxo completo de nova emissão e cancelamento por substituição está em Operação e recursos avançados: cancelamento por substituição.

Rede: opcional. Sem rede, ou com a substituta ainda não transmitida, entra na fila do computador e é enviado sozinho quando as condições forem atendidas.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Identificador da notaidSimO id da nota original que é substituída
Chave da substitutachaveSubstitutaSimChave de acesso da nota substituta. 44 dígitos, obtidos em Chave do resultado da emissão da substituta
JustificativajustificativaSimMotivo do cancelamento. De 15 a 255 caracteres
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null

Retorno

Resultado do cancelamento; campos em Tipos de dados: resultado do cancelamento. Aceite não significa cancelado; o resultado final está nos eventos ou no Status de Consultar.

Erros possíveis

Código de erroSituaçãoAção
10029822A original não é nota normal emitida online: é offline, já está cancelada ou tem cancelamento pendenteNão tente de novo; para nota offline use Cancelar
10029845Chave da substituta inválida, ou não é nota offline deste computador e desta empresa não recusadaInforme a chave de acesso de 44 dígitos da nota offline emitida neste computador para a mesma venda
10029819A nota original não existe neste computadorConfira o id
10029817Justificativa fora de 15 a 255 caracteresCorrija a justificativa
Outros códigos da plataformaErro devolvido pela plataforma no envio, como prazo de cancelamento vencido 10022007Trate conforme Cancelar NFC-e

Também pode devolver os erros gerais.

Exemplos

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

Substituir

Quando a nota offline é rejeitada pela SEFAZ depois da transmissão (situação Rejeitada, evento NOTA_REJEITADA), ela já foi entregue ao consumidor e não pode ser trocada por outra nota; só pode ser corrigida com o mesmo número e transmitida de novo. Substituir monta e assina de novo com a requisição corrigida, mantendo número, série, chave de acesso e data de emissão, e devolve a nota à fila de transmissão; o núcleo transmite sozinho na próxima sincronização. As regras de transmissão e de rejeição estão em Notas offline e transmissão.

Só pode mudar o que não afeta valores nem tributos, como NCM do produto, CFOP e documento do consumidor; mudança no total da nota ou no tributo de qualquer item é recusada.

Rede: não precisa. A correção é feita no computador e a transmissão ocorre em segundo plano.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Identificador da notaidSimO id da nota rejeitada
Requisição corrigidapedidoJsonCorrigidoSimRequisição de emissão completa. Altere a partir da requisição original, obtida em Pedido de Consultar; o id é o mesmo da original
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null

Retorno

Resultado da emissão, com a mesma estrutura de Emitir; o Status volta a ContingenciaPendente. Ao ser autorizada na nova transmissão chega NOTA_AUTORIZADA, com Dados.aposCorrecao = true.

Erros possíveis

Código de erroSituaçãoAção
10029820A situação atual não permite correção: só Rejeitada pode ser corrigidaConfira a situação com Consultar
10029821A correção alterou valores ou tributosAltere só o que não envolve valores
10029817Falha na validação da requisiçãoCorrija conforme Detalhes
10029780Linha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumidoReenvie com o mesmo id quando a rede voltar; sem rede, envie impostos nas linhas de item
10029819A nota não existe neste computadorConfira o id
10029815Faltam a configuração local ou os dados fiscaisSincronize uma vez com rede

Também pode devolver os erros gerais.

Exemplos

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

Cupom

Gera o cupom de uma nota local. O cupom da nota offline sai automaticamente com a marca de contingência e o aviso de "pendente de autorização", sem protocolo; o número de vias é configurado pela plataforma. Os bytes ESC/POS vão direto para a impressora térmica, e o PDF pode ser impresso pelo driver de impressão do Windows. Funciona também sem rede.

Para ajustar colunas por linha, página de código, forma do QR Code, corte do papel ou número de vias, use a sobrecarga com parâmetros de impressão; parâmetros em «Parâmetros de impressão» abaixo.

Rede: não precisa.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Identificador da notaidSimO id da requisição de emissão
FormatoformatoSimFormato do cupom. Valores na tabela abaixo
Parâmetros de impressãoopcoes (OpcoesCupom)NãoParâmetros de impressão do cupom. Só existem na sobrecarga com parâmetros de impressão, e pode passar null; campos em «Parâmetros de impressão» abaixo
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada
Java FormatoCupomConteúdo
ESCPOS_80Bytes ESC/POS para impressora térmica de 80 mm
ESCPOS_58Bytes ESC/POS para impressora térmica de 58 mm
TEXTOTexto puro em UTF-8
HTMLHTML em UTF-8, para pré-visualização na tela ou impressão pelo navegador
PDF_80PDF com 80 mm de largura, uma página por via. Impresso pelo driver de impressão do Windows, para impressoras que não recebem ESC/POS direto; usa as fontes monoespaçadas padrão do PDF, sem fontes embutidas, e os acentos do português saem corretos; QR Code como imagem em preto e branco

Parâmetros de impressão

Classe OpcoesCupom, com configuração encadeada. Itens não definidos usam o padrão; valor fora da faixa devolve 10029874, com Detalhes.campo igual a opcoes.

ParâmetroJavaObrigatórioDescrição
Colunas por linhacolunas(int)NãoCaracteres por linha. 48, 42, 32; sem configuração ou com 0, vale o formato: 48 em 80 mm, 32 em 58 mm
Página de códigopaginaCodigo(String)NãoPágina de código da impressora. CP1252 (padrão, Europa ocidental), CP860 (português), CP850 (multilíngue Europa ocidental), CP437 (inglês dos EUA); caracteres que não existem na página de código são impressos sem acento
Forma do QR CodemodoQrCode(OpcoesCupom.ModoQrCode)NãoForma de impressão do QR Code. NATIVO (padrão) usa o comando de QR Code da própria impressora; IMAGEM imprime o QR Code como bitmap, para impressoras sem comando de QR Code
Tamanho do módulo do QR CodetamanhoModuloQr(int)NãoPontos por módulo do QR Code. De 1 a 16; sem configuração ou com 0, vale 4
Corte do papelcortar(boolean)NãoCorte do papel. Padrão true, corta depois de imprimir
Viasvias(int)NãoNúmero de vias. De 1 a 9; sem configuração ou com 0, vale a configuração da plataforma

Retorno

Bytes do cupom. Com PDF_80, é o conteúdo do arquivo PDF.

Erros possíveis

Código de erroSituaçãoAção
10029819A nota não existe neste computadorConfira o id
10029874Valor de formato inválido, ou parâmetros de impressão fora da faixaUse os valores da tabela acima

Também pode devolver os erros gerais.

Exemplos

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

QrCodePng

Gera a imagem PNG do QR Code de uma nota local (preto e branco, com zona de silêncio). Use ao montar o próprio cupom ou mostrar o QR Code na tela; o conteúdo é o mesmo de QrCode no resultado da emissão. Funciona também sem rede.

Rede: não precisa.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Identificador da notaidSimO id da requisição de emissão
Lado da imagemtamanhoPxNãoLado da imagem em pixels. De 64 a 2048, informe explicitamente
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null

Retorno

Bytes da imagem PNG.

Erros possíveis

Código de erroSituaçãoAção
10029819A nota não existe neste computadorConfira o id
10029817Lado da imagem fora de 64 a 2048Corrija o lado da imagem

Também pode devolver os erros gerais.

Exemplos

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

XmlAutorizado

Lê o XML autorizado original de uma nota (com o protocolo de autorização). Depois da autorização da nota online, ou da autorização da nota offline após a transmissão, o núcleo baixa o XML autorizado para o computador sozinho; os dias de retenção vêm do item de configuração RetencaoXmlDias (padrão 90). Se não estiver no computador (ainda não baixado, ou apagado ao fim da retenção), o núcleo busca na plataforma na hora; o original é o arquivo da plataforma.

Com XmlAutorizadoDisponivel de Consultar igual a true, a leitura é feita no computador, sem rede.

Não chame na thread da interface: se não estiver no computador, é preciso esperar a resposta da plataforma, até cerca de 120 segundos (se o tempo limite da chamada for maior, vale o tempo limite da chamada); use uma thread de segundo plano.

Rede: possível. Se não estiver no computador, busca na plataforma de forma síncrona, até cerca de 120 segundos; não chame na thread da interface.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Identificador da notaidSimO id da requisição de emissão
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null

Retorno

Bytes UTF-8 do XML autorizado.

Erros possíveis

Código de erroSituaçãoAção
10029841XML autorizado indisponível: ainda não autorizada, ou não está no computador e não foi possível buscar na plataformaSe ainda não autorizada, aguarde o evento NOTA_AUTORIZADA e leia depois; se já autorizada, a plataforma ainda não arquivou ou está inacessível no momento; tente mais tarde
10029819A nota não existe neste computadorConfira o id

Também pode devolver os erros gerais.

Exemplos

java
// Pode buscar na plataforma; use uma thread de segundo plano
CompletableFuture.supplyAsync(() -> nfce.xmlAutorizado("PDV01-000131", null))
.thenAccept(xml -> gravar("PDV01-000131-nfce.xml", xml));

XmlCancelamento

Lê o XML de cancelamento original de uma nota cancelada (evento de cancelamento e seu retorno). A retenção no computador é a mesma do XML autorizado, definida pelo item de configuração RetencaoXmlDias (padrão 90 dias); se não estiver no computador, o núcleo busca na plataforma na hora.

Não chame na thread da interface: se não estiver no computador, é preciso esperar a resposta da plataforma, até cerca de 120 segundos (se o tempo limite da chamada for maior, vale o tempo limite da chamada).

Rede: possível. Se não estiver no computador, busca na plataforma de forma síncrona, até cerca de 120 segundos; não chame na thread da interface.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Identificador da notaidSimO id da requisição de emissão
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null

Retorno

Bytes UTF-8 do XML de cancelamento.

Erros possíveis

Código de erroSituaçãoAção
10029843XML de cancelamento indisponível: a nota não foi cancelada, ou não está no computador e não foi possível buscar na plataformaSe ainda não cancelada, aguarde o evento CANCELAMENTO_CONCLUIDO e leia depois; se já cancelada, a plataforma ainda não arquivou ou está inacessível no momento; tente mais tarde
10029819A nota não existe neste computadorConfira o id

Também pode devolver os erros gerais.

Exemplos

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

ExportarXmls

Exporta para um diretório os XML autorizados e de cancelamento de um período, pela data de emissão, para entregar ao contador todo mês ou arquivar. As datas seguem o fuso do estado da empresa, incluindo a data inicial e a final. O passo a passo está em Operação e recursos avançados: exportação mensal de XML para o contador.

  • Nomes de arquivo: XML autorizado em {chave}-nfe.xml, XML de cancelamento em {chave}-can.xml ({chave} é a chave de acesso de 44 dígitos); arquivos com o mesmo nome são sobrescritos.
  • XML que não está no computador é buscado primeiro na plataforma; o que mesmo assim não vier não interrompe a exportação e é listado nota a nota em Falhas do resultado, com o motivo (inclusive se foi apagado ao fim da retenção).
  • O período exportado deve ficar dentro da retenção do item de configuração RetencaoXmlDias; XML fora da retenção precisa ser buscado nota a nota na plataforma, e o que não vier entra em Falhas.
  • Fim rápido sem rede: se a plataforma estava inacessível logo antes do início da exportação, ou ficar inacessível pela primeira vez durante ela, as demais notas sem XML não tentam mais a rede e entram direto em Falhas.
  • Só o que está no computador: com somenteLocal igual a true, não há nenhum acesso à rede; só os XML já presentes no computador são gravados, e as notas faltantes entram em Falhas.

Rede: possível. XML que não está no computador é buscado na plataforma; com somenteLocal igual a true, não acessa a rede. Espera máxima de pelo menos 30 minutos, e se o tempo limite da chamada for maior, vale o tempo limite da chamada; não chame na thread da interface. Ao estourar a espera (10029833), o runtime pode ainda estar gravando arquivos: não repita logo no mesmo diretório; espere um pouco e exporte de novo para um diretório novo.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Data inicialdeSimInício do período pela data de emissão. Inclui o dia
Data finalateSimFim do período pela data de emissão. Inclui o dia
Diretório de destinodiretorioSimDiretório da exportação. Caminho relativo é convertido em absoluto a partir do diretório atual do PDV
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null
Só do computadorsomenteLocalNãoIndicador de exportação local. true exporta só os XML já presentes no computador, sem acessar a rede; padrão false, em que o que não está no computador é buscado primeiro na plataforma. No Java, use a sobrecarga de cinco parâmetros

Retorno

Resultado da exportação; campos em Tipos de dados: resultado da exportação de XML.

Erros possíveis

Código de erroSituaçãoAção
10029874Data ausente ou com formato inválido; Detalhes.campo é de ou ateCorrija a data
10029844Diretório sem permissão de gravaçãoTroque de diretório; confira espaço em disco e permissões
10029801 / 10029802Empresa não pareada / várias empresas sem empresaIdPareie primeiro; informe empresaId

A falta de XML de uma nota não gera erro; veja Falhas no resultado.

Também pode devolver os erros gerais.

Exemplos

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

TrocarCertificado

Depois da renovação ou troca do certificado A1 da empresa, substitui o certificado registrado no núcleo pelo novo. Identidade do dispositivo, série do dispositivo e licença não mudam, sem precisar parear de novo; o novo certificado é informado à plataforma no próximo heartbeat. Antes do vencimento do certificado o núcleo emite o evento CERTIFICADO_EXPIRANDO (uma vez a 30, 7 e 1 dia), que pode ser usado para avisar o gerente.

Rede: não precisa.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
CertificadocertificadoSimNovo certificado A1. Formas em Tipos de dados: origem do certificado; o CNPJ deve ser o da empresa da loja
Identificador da empresaempresaIdObrigatório com várias empresasEmpresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null

Retorno

Nenhum. Em caso de sucesso, CertificadoValidoAte de Situacao passa a mostrar o vencimento do novo certificado.

Erros possíveis

Código de erroSituaçãoAção
10029813Certificado indisponível: não encontrado, sem chave privada, ou CNPJ diferente da empresaConfira o repositório de certificados e use o certificado da empresa
10029814Certificado vencidoUse um certificado válido
10029874Parâmetro de certificado inválido: impressão digital sem 40 dígitos hexadecimais, ou PFX vazioCorrija o parâmetro do certificado
10029801 / 10029802Empresa não pareada / várias empresas sem empresaIdPareie primeiro; informe empresaId

Também pode devolver os erros gerais.

Exemplos

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

Situacao

Lê a situação geral do núcleo: a versão do núcleo, os avisos do núcleo e, para cada empresa pareada, a conexão, o que resta da licença, as notas a transmitir, o prazo de transmissão, o vencimento do certificado e o último erro. Serve para mostrar na tela do caixa avisos como "offline", "N notas a transmitir", "certificado vence em 7 dias"; pode ser chamado periodicamente (por exemplo a cada 10 segundos), com custo muito baixo.

Rede: não precisa.

Assinatura

java
public Resultados.Nucleo situacao();

Parâmetros

Nenhum.

Retorno

Situação do núcleo; campos em Tipos de dados: situação do núcleo.; a situação de cada empresa é a lista de mapas devolvida por getEmpresas().

Avisos sugeridos na tela:

CondiçãoAviso
Conectado é falseOffline; as notas serão transmitidas quando a rede voltar
PendentesTransmissao maior que 0Quantidade a transmitir; junto com PrazoTransmissaoAte, mostre o prazo de transmissão
OfflineAte próximoO tempo offline está acabando; conecte o quanto antes
CertificadoValidoAte próximoO certificado está para vencer; depois de renovar, chame TrocarCertificado
Situacao diferente de AtivoO dispositivo não emite mais notas novas; fale com o integrador
UltimoErro preenchidoMotivo da última falha de sincronização; informe ao suporte técnico no diagnóstico
Avisos não vazioO ambiente de execução precisa de ajuste, por exemplo falta no modo em processo do Java o parâmetro de partida exigido pela autenticação do proxy, veja Proxy de saída; mostre o texto original ao técnico

Erros possíveis

Só os erros gerais.

Exemplos

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

SincronizarAgora

Dispara na hora uma rodada de sincronização: heartbeat, renovação da licença, transmissão das notas offline, envio dos cancelamentos em fila e busca dos resultados da plataforma. O núcleo já sincroniza sozinho periodicamente; este método serve para encurtar a espera, por exemplo quando o PDV detecta que a rede voltou ou quando se quer transmitir tudo antes da troca de turno.

A sincronização segue em segundo plano; o resultado chega pelos eventos, ou veja depois com Consultar e Situacao. A chamada só dispara a próxima rodada de sincronização em segundo plano e retorna na hora, sem esperar o resultado, e pode ser feita direto na thread da interface; se uma rodada de uma empresa já estiver em andamento, não roda outra em paralelo e a sincronização continua assim que essa rodada termina. Chamar sem rede não dá erro.

Rede: dispara o uso da rede, sem esperar o resultado da sincronização; a chamada retorna na hora.

Assinatura

java
public void sincronizarAgora();

Parâmetros

Nenhum.

Retorno

Nenhum.

Erros possíveis

Só os erros gerais.

Exemplos

java
// Só dispara a próxima rodada em segundo plano e retorna na hora; pode chamar direto na thread da interface
nfce.sincronizarAgora();

Backup

Faz um backup criptografado da base local num único arquivo, para guardar periodicamente ou proteger antes de trocar o disco. O backup é uma cópia completa de um único instante, e a emissão continua normalmente enquanto isso. A estratégia de backup e o processo completo de recuperação estão em Operação e recursos avançados: backup e recuperação de computador com defeito.

  • Criptografia: a chave é derivada da senha com PBKDF2-SHA256, e a base inteira é criptografada com AES-256-GCM. Nem o SDK nem a plataforma guardam a senha: sem a senha, o backup não pode ser restaurado. Guarde-a separada do arquivo de backup.
  • Só pode ser restaurado no mesmo computador e com o mesmo usuário do Windows: a chave do dispositivo na base local é protegida no nível do usuário do Windows; em outro computador ou com outro usuário do Windows o backup não serve, e é preciso desativar o dispositivo antigo e parear de novo.
  • Restauração: use RestaurarBackup. A versão do SDK e do runtime usada na restauração não pode ser inferior à do backup; VersaoBanco no resultado registra a versão da estrutura da base local.
  • Gravação: grava primeiro um arquivo temporário e depois o renomeia; uma falha não deixa arquivo de backup incompleto.

Rede: não precisa. Espera máxima de pelo menos 30 minutos, e se o tempo limite da chamada for maior, vale o tempo limite da chamada; com base local grande leva alguns minutos, não chame na thread da interface. Ao estourar a espera (10029833), o runtime pode ainda estar gravando o arquivo: não repita logo com o mesmo nome de arquivo; espere um pouco e use um nome de arquivo novo.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Arquivo de backupdestinoSimCaminho do arquivo de backup. O arquivo não pode existir; caminho relativo é convertido em absoluto a partir do diretório atual do PDV
SenhasenhaSimSenha do backup. Pelo menos 8 caracteres; a restauração exige a mesma senha, que não vai para o log

Retorno

Resultado do backup; campos em Tipos de dados: resultado do backup.

Erros possíveis

Código de erroSituaçãoAção
10029874Senha vazia; Detalhes.campo é senhaInforme a senha
10029817Senha com menos de 8 caracteresUse uma senha mais longa
10029844O arquivo de destino já existe, ou o diretório não tem permissão de gravaçãoTroque o nome do arquivo ou o diretório; confira espaço em disco e permissões

Também pode devolver os erros gerais.

Exemplos

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

RestaurarBackup

Substitui a base local pelo backup criptografado gerado por Backup, para recuperar a base local depois de perda, corrupção ou erro de operação. É um método estático, chamado antes de Iniciar: não inicia o motor nem acessa a rede; no modo subprocesso, o SDK sobe um runtime temporário que sai ao terminar a restauração. Na chamada, nenhuma instância pode estar rodando neste diretório de dados; numa instância já iniciada, chame antes Encerrar e, depois da restauração, Iniciar. Quando usar o backup e quando exportar o pacote de pendentes: veja Operação e recursos avançados: backup e recuperação de computador com defeito.

  • Só restaura no computador original: a chave do dispositivo no backup é protegida pela proteção de dados do Windows e só pode ser usada no mesmo computador e no mesmo usuário do Windows que geraram o backup. Ao trocar de computador ou de usuário do Windows, não conte com o backup: exporte as notas pendentes com ExportarPendentes, entregue à plataforma e pareie de novo o computador novo.
  • Cópia da base original: antes de restaurar, a base original no diretório de dados é renomeada e guardada (nome do arquivo começando com nfce.db.antes-restauracao-), e CopiaAnterior no resultado traz o caminho; se a restauração falhar, a base original não é tocada.
  • Versão: backup com versão da estrutura da base local acima da do SDK atual é recusado; abaixo dela, a base é atualizada automaticamente no próximo Iniciar.
  • Proteção depois da restauração: a numeração e a licença do backup param no momento do backup. Depois de restaurar e chamar Iniciar, cada empresa primeiro passa por um realinhamento: a emissão offline devolve 10029811 e a emissão online sincroniza uma vez com a plataforma antes de pegar um número. Quando chega uma nova licença, a numeração da série do dispositivo pula 50 números para a frente, um único salto compartilhado pelas notas online e offline; os números pulados são inutilizados automaticamente junto à plataforma (o resultado chega pelo evento NUMERO_INUTILIZADO) e depois a emissão online e offline segue normal. Até o realinhamento terminar não dá para emitir sem alcançar a plataforma. Não há números repetidos, mesmo que notas emitidas depois do backup já tenham sido entregues ao consumidor.
  • Notas offline emitidas depois do backup: não estão no backup. Se a base antiga ainda dá partida, antes de restaurar exporte essas notas com ExportarPendentes na base antiga e entregue à plataforma; do contrário, elas se perdem.

Rede: não precisa. Espera máxima de pelo menos 30 minutos, e se o tempo limite da chamada for maior, vale o tempo limite da chamada; não chame na thread da interface.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
ConfiguraçãoconfigSimConfiguração de inicialização. A mesma usada em Iniciar, de onde vêm o diretório de dados e o local do runtime; veja Configuração
Arquivo de backuporigemSimCaminho do arquivo de backup. Caminho relativo é convertido em absoluto a partir do diretório atual do PDV
SenhasenhaSimSenha do backup. A senha usada ao gerar o backup

Retorno

Resultado da restauração; campos em Tipos de dados: resultado da restauração.

Erros possíveis

Código de erroSituaçãoAção
10029846Senha errada, ou arquivo de backup alterado, corrompido ou que não é backup deste SDK; os dois casos não são distinguidosConfira a senha; use outro backup íntegro. A base original não foi alterada
10029842Backup gerado por uma versão mais nova do SDKAtualize o SDK e o runtime para uma versão não inferior à do backup
10029828Outro motor está rodando sobre o diretório de dados, inclusive uma instância deste programa em que ainda não se chamou Encerrar. O RestaurarBackup estático do SDK abre uma conexão própria com o runtime a cada chamada, e é este o código que ele recebeChame antes Encerrar na instância que usa este diretório de dados e depois restaure
10029875O método de protocolo de restauração restaurarBackup foi chamado numa conexão com o runtime que já executou Iniciar. O RestaurarBackup estático do SDK abre uma conexão nova a cada chamada e não recebe este código; ele só aparece para quem integra direto com o protocolo do runtimeChame Encerrar e restaure por uma conexão nova, antes de Iniciar
10029817Senha com menos de 8 caracteresInforme a senha usada ao gerar o backup
10029874Arquivo de backup ou senha vazio; Detalhes.campo é origem ou senhaComplete os parâmetros
10029844Falha ao ler ou gravar arquivoConfira o caminho do arquivo de backup, o espaço em disco e as permissões do diretório de dados

Também pode devolver os erros gerais.

Exemplos

java
nfce.encerrar();
Resultados.Restauracao r = TfFiscalNfce.restaurarBackup(config, Paths.get("D:/Backup/tffiscal-20261031.bak"), senhaBackup);
System.out.println("versao " + r.getVersaoBanco() + " anterior " + r.getCopiaAnterior());
nfce = TfFiscalNfce.iniciar(config);
// Até obter a nova licença a emissão offline fica suspensa; sincronize uma rodada logo (execute este trecho numa thread em segundo plano)
nfce.sincronizarAgora();

ExportarPendentes

Exporta as notas offline assinadas e ainda não transmitidas deste computador num pacote de pendentes que a plataforma importa diretamente. Serve quando o caixa quebrou ou ficou muito tempo sem rede e não dá mais para transmitir pelo próprio computador. A exportação não muda o estado do computador: as notas continuam na fila de transmissão local. O procedimento completo para computador com defeito está em Operação e recursos avançados: backup e recuperação de computador com defeito.

Cada chamada cria, no diretório de destino, um subdiretório com o nome do momento da exportação (UTC), dividido em diretórios por dispositivo, com até 500 notas por pacote:

text
{diretorio}/pendentes-20261111-150000/{dispositivoId}/pacote-001/manifesto.json
/pacote-001/{chave}.xml
/pacote-002/…
  • {diretorio} é o diretório de destino informado na chamada, {dispositivoId} é o identificador do dispositivo e {chave} é a chave de acesso de 44 dígitos.
  • Cada manifesto manifesto.json registra o dispositivo a que pertence, e cada nota fica no manifesto junto com o XML assinado, podendo ser entregue direto à plataforma para importação; o {chave}.xml no mesmo diretório é o mesmo XML assinado, para conferência manual.
  • Na entrega à plataforma, compacte num único zip o subdiretório pendentes-… inteiro desta exportação e entregue à operação da plataforma, que o envia direto em «Importar pacote de pendentes», sem descompactar nem separar por pacote ou por dispositivo. Com várias empresas, o zip tem vários diretórios de dispositivo; a operação filtra por dispositivo e envia em lotes.
  • Sem notas pendentes não há erro: Quantidade é 0, Manifesto vem vazio e Manifestos é um array vazio.
  • O manifesto é gravado primeiro num arquivo temporário e depois renomeado; o manifesto lido está sempre completo.

Rede: não precisa. Espera máxima de pelo menos 30 minutos, e se o tempo limite da chamada for maior, vale o tempo limite da chamada; não chame na thread da interface. Ao estourar a espera (10029833), o runtime pode ainda estar gravando arquivos: não repita logo no mesmo diretório; espere um pouco e exporte de novo para um diretório novo.

Assinatura

java
public Resultados.ExportacaoPendentes exportarPendentes(Path diretorio);

Parâmetros

ParâmetroJavaObrigatórioDescrição
Diretório de destinodiretorioSimDiretório da exportação. Caminho relativo é convertido em absoluto a partir do diretório atual do PDV

Exporta as notas pendentes de todas as empresas pareadas neste diretório de dados, com um diretório e manifestos próprios para o dispositivo de cada empresa; o manifesto registra a empresa de cada nota.

Retorno

Resultado da exportação; campos em Tipos de dados: resultado da exportação de pendentes.

Erros possíveis

Código de erroSituaçãoAção
10029844Diretório sem permissão de gravaçãoTroque de diretório; confira espaço em disco e permissões

Também pode devolver os erros gerais.

Exemplos

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

CriarTerminal

Emite, no principal, o token de terminal de um secundário. O nome é a identificação do caixa nas notas que esse secundário emite; use um número de caixa que a loja reconheça, por exemplo Caixa 2. O token completo aparece só uma vez, neste retorno, e o principal guarda só um resumo: configure-o na hora em TokenTerminal do secundário; se perder, revogue e emita outro. Só no modo principal; a implantação e o gerenciamento dos secundários estão em Vários caixas (modo principal e secundário).

Rede: não precisa.

Assinatura

java
public Resultados.TerminalCriado criarTerminal(String nome);

Parâmetros

ParâmetroJavaObrigatórioDescrição
Nome do terminalnomeSimNome do caixa. De 1 a 60 caracteres; não pode repetir entre terminais ativos, sem diferenciar maiúsculas

Retorno

O terminal novo; campos em Tipos de dados: terminal secundário.

Erros possíveis

Código de erroSituaçãoAção
10029874Nome vazio, com mais de 60 caracteres, ou repetido entre terminais ativos (Detalhes.motivo é duplicado)Use outro nome; para reaproveitar um nome antigo, revogue antes o terminal antigo
10029884Não está em modo principalChame só no principal

Também pode devolver os erros gerais.

Exemplos

java
Resultados.TerminalCriado t = principal.criarTerminal("Caixa 2");
// O token completo vem só esta vez; configure no caixa 2 na hora
System.out.println(t.getId() + " " + t.getToken());

ListarTerminais

Lista, no principal, os terminais secundários, do mais novo para o mais antigo, sem os tokens. Por padrão oculta os terminais revogados há mais de 30 dias; com todos em true lista todos. Os registros são sempre mantidos. Só no modo principal.

Rede: não precisa.

Assinatura

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

Parâmetros

ParâmetroJavaObrigatórioDescrição
Listar todostodosNãoInclui terminais revogados há mais de 30 dias. Padrão false

Retorno

Lista de terminais; campos em Tipos de dados: terminal secundário.

Erros possíveis

Código de erroSituaçãoAção
10029884Não está em modo principalChame só no principal

Também pode devolver os erros gerais.

Exemplos

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

RevogarTerminal

Revoga, no principal, o token de terminal de um secundário, com efeito imediato: as chamadas seguintes desse secundário devolvem 10029882 e os eventos ainda não entregues a ele são descartados. Use quando um secundário for perdido, desativado ou o token vazar. A revogação não pode ser desfeita; emita outro token quando precisar. Só no modo principal.

Rede: não precisa.

Assinatura

java
public void revogarTerminal(String id);

Parâmetros

ParâmetroJavaObrigatórioDescrição
Identificador do terminalidSimO id devolvido por CriarTerminal, começa com trm_

Retorno

Nenhum.

Erros possíveis

Código de erroSituaçãoAção
10029888Terminal não encontradoConfira o id com ListarTerminais
10029884Não está em modo principalChame só no principal

Também pode devolver os erros gerais.

Exemplos

java
principal.revogarTerminal("trm_8Kq2Xc0vLm4R");

Encerrar

Fecha o SDK: para a sincronização em segundo plano, espera a emissão em andamento terminar (até 10 segundos), fecha a base local e encerra o runtime (se não sair em mais 5 segundos, é encerrado à força). O processo inteiro leva no máximo cerca de 15 segundos. Chame antes de o PDV sair. Pode ser chamado várias vezes; depois de fechado, chamar outro método devolve 10029834 e é preciso Iniciar de novo.

Enquanto está fechado não há transmissão; depois do próximo Iniciar sincroniza uma rodada na hora e, se ainda houver notas a transmitir ou eventos não confirmados, emite PENDENCIAS_NA_INICIALIZACAO. Cuidados ao sair e reiniciar: veja Operação e recursos avançados: fechar e reiniciar.

Rede: não precisa.

Assinatura

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

close equivale a Encerrar e funciona com try-with-resources.

Parâmetros

Nenhum.

Retorno

Nenhum.

Erros possíveis

Não lança erro e pode ser chamado várias vezes.

Exemplos

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

Tipos de dados

Objetos de resultado devolvidos pelos métodos, valores de situação nos eventos e parâmetros de certificado. Como ler as colunas das tabelas:

  • Nome JSON: nome do campo no texto original de getJson().
  • Java: método de leitura; campos marcados "via getCampos()" não têm método próprio e são lidos com getCampos().get("nome").
  • Campos de data e hora em texto ISO 8601 UTC.
  • Todo resultado guarda o texto original (getJson()); campos acrescentados por versões novas do runtime também podem ser lidos desse texto por versões antigas do SDK.
  • Campos com "Nulo" = "Sim" podem vir null.

Situação da nota

Valores de Status no resultado da emissão, na situação consultada e nos eventos.

ValorSignificadoO que o PDV faz
AutorizadaAutorizadaImprime o cupom
ContingenciaPendenteAssinada offline neste computador, aguardando transmissãoImprime o cupom e entrega ao consumidor; a transmissão é automática
AguardandoAutorizacaoAceita online, a SEFAZ ainda não respondeuNão imprime ainda; aguarda o evento de autorização; se for negada depois, chega NOTA_NEGADA
NegadaNota encaminhada online negada pela SEFAZ, inclusive a negada depois de aguardar autorização (evento NOTA_NEGADA)Não admite correção com o mesmo número; corrige os dados da venda e emite de novo com id novo
RejeitadaNota offline rejeitada pela SEFAZ na transmissão (evento NOTA_REJEITADA)Corrige com o mesmo número usando Substituir; não pode emitir outra
RecusadaA plataforma recusou esta nota offlineExige ação manual; fale com a plataforma
CanceladaCanceladaNada

Resultado da emissão

Retorno de Emitir e de Substituir. Java ResultadoEmissao.

Nome JSONJavaTipoNuloDescrição
idgetId()TextoNãoIdentificador da nota. O id da requisição de emissão
statusgetStatus()TextoNãoSituação da nota. Valores acima
emitidaEmContingenciaisEmitidaEmContingencia()BooleanoNãoIndicador de emissão offline. Continua true depois da autorização
chavegetChave()TextoSimChave de acesso. 44 dígitos
seriegetSerie() (Long)InteiroSimSérie
numerogetNumero() (Long)InteiroSimNúmero da nota
dataEmissaogetDataEmissao()Data e horaSimData de emissão
protocologetProtocolo()TextoSimProtocolo de autorização. null enquanto a nota offline aguarda transmissão
qrCodegetQrCode()TextoSimConteúdo do QR Code. Codifique em QR ao montar o próprio cupom
urlConsultagetUrlConsulta()TextoSimURL de consulta do consumidor
motivogetMotivo()TextoSimDescrição do motivo. Vem da SEFAZ ou da plataforma
cStatgetCStat() (Long)InteiroSimCódigo de resultado da SEFAZ. null quando não há resultado da SEFAZ
xMotivogetXMotivo()TextoSimMensagem de resultado da SEFAZ. Vem junto com o código de resultado
tentativaOnlineisTentativaOnline()BooleanoNãoIndicador de tentativa online. true quando tentou online, ficou sem resultado e passou para offline; esta nota usa o número seguinte ao da tentativa online e, na transmissão, a plataforma resolve esse número original; false para nota autorizada online
respostaPlataformagetRespostaPlataforma()TextoSimTexto original da resposta da plataforma. Na emissão online é o JSON devolvido pela plataforma, com a estrutura de Consultar NFC-e; offline é null
terminalgetTerminal()TextoSimIdentificação do caixa. Nas notas emitidas por um secundário no modo principal e secundário, o nome do terminal; null nas notas emitidas pelo próprio principal ou em modo independente. Vai para a plataforma junto com a nota; mesmo valor de terminal em Consultar NFC-e e nos webhooks

Situação consultada

Retorno de Consultar e item da página de notas. Java SituacaoNota; traz todos os campos do resultado da emissão e mais:

Nome JSONJavaTipoNuloDescrição
transmitidaisTransmitida()BooleanoNãoIndicador de transmissão. A nota offline já foi transmitida à plataforma
cancelamentoPendenteisCancelamentoPendente()BooleanoNãoIndicador de cancelamento pendente. Há cancelamento agendado ou na fila local
correcoesgetCorrecoes() (Long)InteiroNãoQuantidade de correções
atualizadoEmgetAtualizadoEm()Data e horaSimÚltima atualização
xmlAutorizadoDisponivelisXmlAutorizadoDisponivel()BooleanoNãoIndicador de XML no computador. true quando o XML autorizado já está no computador, e XmlAutorizado lê direto dele; autorizada mas com false, a chamada busca na plataforma
pedidogetPedido()TextoSimRequisição de emissão. Texto JSON, base para a correção com o mesmo número; linhas de item que referenciavam classe de imposto já trazem os impostos expandidos pela plataforma, que podem ser guardados para enviar sem rede

Página de notas

Retorno de ListarNotas. Java Resultados.PaginaNotas.

Nome JSONJavaTipoNuloDescrição
itensgetItens()ListaNãoNotas da página. Itens são situação consultada, em ordem decrescente de emissão
paginagetPagina()InteiroNãoNúmero da página. Começa em 1
tamanhoPaginagetTamanhoPagina()InteiroNãoNotas por página. Fixo em 50
temMaisisTemMais()BooleanoNãoIndicador de próxima página. Não há total

Resultado da prévia

Retorno de Previsualizar. Java Resultados.PreVisualizacao.

Nome JSONJavaTipoNuloDescrição
validoisValido()BooleanoNãoIndicador de validação aprovada
errosgetErros()Lista de textosNãoErros de validação. Já traduzidos conforme o idioma das mensagens; lista vazia quando passa
pedidoNormalizadogetPedidoNormalizado()TextoSimRequisição normalizada. Texto JSON, normalmente não usado
valorTotalgetValorTotal() (BigDecimal)DecimalSimTotal da nota
valorTributosgetValorTributos() (BigDecimal)DecimalSimTotal de tributos

Resultado do cancelamento

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

Nome JSONJavaTipoNuloDescrição
situacaogetSituacao()TextoNãoDestino do pedido. Valores abaixo
motivogetMotivo()TextoSimDescrição
situacaoSignificado
SolicitadoNota autorizada, cancelamento enviado à plataforma; o resultado chega pelos eventos CANCELAMENTO_CONCLUIDO ou CANCELAMENTO_REJEITADO
AgendadoNota offline transmitida e ainda não autorizada; a plataforma agenda o cancelamento e o dispara depois da autorização
EnfileiradoLocalFila local: sem rede, ou a nota offline / substituta ainda não foi transmitida; logo após a transmissão, é enviado na mesma rodada

Informações do código de pareamento

Retorno de InspecionarCodigoAtivacao. Java Resultados.CodigoAtivacao.

Nome JSONJavaTipoNuloDescrição
ambientegetAmbiente() (Long)InteiroNãoAmbiente de emissão. 1 produção, 2 homologação
formasPermitidasgetFormasPermitidas() (Long)InteiroNãoFormas permitidas. 0 qualquer forma, 1 só o Assistente Fiscal, 2 só o SDK embarcado
expiraEmgetExpiraEm()Data e horaNãoVencimento do código de pareamento
plataformagetPlataforma()TextoNãoEndereço da plataforma. Plataforma para a qual o código aponta
seriegetSerie() (Long)InteiroSimSérie do dispositivo indicada. A série que o integrador indicou ao gerar o código; null se não indicada, e a plataforma atribui uma no pareamento
numeroInicialgetNumeroInicial() (Long)InteiroSimNúmero inicial indicado. Se só a série foi indicada, o número que a plataforma calculou ao gerar o código; null se não indicado, e a numeração começa em 1

Resultado do pareamento

Retorno de Ativar. Java Resultados.Ativacao.

Nome JSONJavaTipoNuloDescrição
empresaIdgetEmpresaId()TextoNãoIdentificador da empresa. O empresaId dos demais métodos
dispositivoIdgetDispositivoId()TextoNãoIdentificador do dispositivo
cnpjgetCnpj()TextoNãoCNPJ da empresa
ufvia getCampos()TextoNãoEstado
ambientevia getCampos()InteiroNãoAmbiente de emissão. 1 produção, 2 homologação
serieOfflinegetSerieOffline() (Long)InteiroNãoSérie do dispositivo. Exclusiva deste dispositivo, compartilhada pelas notas online e offline com numeração contínua; o nome do campo foi mantido
licencaExpiraEmgetLicencaExpiraEm()Data e horaSimVencimento da licença
numeroInicialgetNumeroInicial() (Long)InteiroNãoNúmero inicial. Número da primeira nota deste dispositivo; 1 se o código não indicou

Empresa pareada

Item de Empresas. Java Resultados.EmpresaAtivada.

Nome JSONJavaTipoNuloDescrição
empresaIdgetEmpresaId()TextoNãoIdentificador da empresa
dispositivoIdgetDispositivoId()TextoNãoIdentificador do dispositivo
cnpjgetCnpj()TextoNãoCNPJ da empresa
ufvia getCampos()TextoNãoEstado
ambientevia getCampos()InteiroNãoAmbiente de emissão. 1 produção, 2 homologação
serieOfflinevia getCampos()InteiroNãoSérie do dispositivo
situacaogetSituacao()TextoNãoSituação do dispositivo. Valores abaixo
situacaoSignificadoAção
AtivoPode emitirNada
DesativadoO integrador desativou o dispositivoNão volta; para continuar usando o mesmo computador, pareie de novo
RevogadoA plataforma revogou o dispositivoFale com a plataforma
EmpresaDesativadaEmissão offline da empresa desativadaFale com a plataforma
AplicativoBloqueadoSoftware do PDV bloqueado pela plataformaFale com a plataforma
VersaoBloqueadaA versão do PDV foi bloqueada ou está abaixo da mínimaAtualize o PDV

Fora Ativo, nenhuma situação emite notas novas; as notas offline já emitidas seguem sendo transmitidas.

Situação do núcleo

Retorno de Situacao. Java Resultados.Nucleo.

Nome JSONJavaTipoDescrição
versaoNucleogetVersaoNucleo()TextoVersão do núcleo
empresasgetEmpresas() (itens são mapas)ListaSituação de cada empresa pareada, campos abaixo
avisosgetAvisos()Lista de textoAvisos do núcleo. Problemas do ambiente de execução que o host precisa tratar; lista vazia se não houver. Por exemplo, a autenticação do proxy foi configurada, mas no modo em processo do Java falta o parâmetro de partida da JVM exigido pela autenticação do proxy, ou a configuração não surtiu efeito; veja Proxy de saída. O texto vem em português e pode ser mostrado direto

Itens de empresas:

Nome JSONTipoNuloDescrição
empresaIdTextoNãoIdentificador da empresa
dispositivoIdTextoNãoIdentificador do dispositivo
situacaoTextoNãoSituação do dispositivo. Valores iguais aos de empresa pareada
conectadoBooleanoNãoIndicador de conexão. Se agora consegue falar com a plataforma
ultimoContatoData e horaSimÚltimo contato
licencaExpiraEmData e horaSimVencimento da licença
offlineAteData e horaSimPrazo da emissão offline. O que vier primeiro entre o vencimento da licença e o do certificado
pendentesTransmissaoInteiroNãoNotas a transmitir
pendenteMaisAntigaEmData e horaSimPendente mais antiga. Data de emissão da nota mais antiga a transmitir
prazoTransmissaoAteData e horaSimPrazo de transmissão. Prazo da nota mais antiga a transmitir; depois dele o dispositivo não emite mais offline
certificadoValidoAteData e horaSimVencimento do certificado
ultimoErroTextoSimÚltimo erro. Motivo da última falha de sincronização
numerosNaoUtilizadosPendentesInteiroNãoFaixas a inutilizar. Número de faixas de números tomados e não usados que ainda aguardam a inutilização na plataforma; recusa não definitiva é repetida sozinha, veja NUMERO_INUTILIZACAO_RECUSADA
restauradoPendenteSincronizacaoBooleanoNãoRestauração pendente de alinhamento. true depois de restaurar um backup e até chegar uma licença nova; nesse intervalo a emissão offline devolve 10029811 e a online sincroniza antes com a plataforma; false depois do alinhamento. Use para pedir ao caixa que se conecte; não interprete o texto do erro

Resultado da exportação de XML

Retorno de ExportarXmls. Java Resultados.ExportacaoXml.

Nome JSONJavaTipoNuloDescrição
quantidadeNotasgetQuantidadeNotas()InteiroNãoNotas exportadas. Número de notas com pelo menos um arquivo gravado
quantidadeArquivosgetQuantidadeArquivos()InteiroNãoQuantidade de arquivos. Total de arquivos de XML autorizado e de cancelamento gravados; uma nota cancelada com os dois XML gravados conta como dois
arquivosgetArquivos()Lista de textoNãoArquivos exportados. Caminhos absolutos dos arquivos gravados, um arquivo para o XML autorizado e outro para o de cancelamento
falhasgetFalhas() (itens são mapas)ListaNãoLista de faltas. Notas do período cujo XML não foi obtido; lista vazia se não houver; campos dos itens abaixo

Itens de falhas:

Nome JSONChave no JavaTipoDescrição
ididTextoIdentificador da nota
chavechaveTextoChave de acesso
motivomotivoTextoMotivo da falta. Inclui se foi apagado ao fim da retenção

Resultado do backup

Retorno de Backup. Java Resultados.Backup.

Nome JSONJavaTipoNuloDescrição
arquivogetArquivo()TextoNãoArquivo de backup. Caminho absoluto
bytesgetBytes()InteiroNãoTamanho do arquivo. Em bytes
versaoBancogetVersaoBanco()InteiroNãoVersão da estrutura da base local. Na restauração, a versão do núcleo não pode ser inferior a ela
sha256getSha256()TextoNãoResumo do arquivo. SHA-256 do arquivo de backup criptografado, em hexadecimal minúsculo

Resultado da restauração

Retorno de RestaurarBackup. Java Resultados.Restauracao.

Nome JSONJavaTipoNuloDescrição
versaoBancogetVersaoBanco()InteiroNãoVersão da estrutura da base local. Versão da base restaurada; se for inferior à do SDK atual, é atualizada automaticamente na próxima partida
copiaAnteriorgetCopiaAnterior()TextoSimCópia da base original. Caminho absoluto do arquivo da base original guardado antes da restauração; vazio quando não havia base

Resultado da exportação de pendentes

Retorno de ExportarPendentes. Java Resultados.ExportacaoPendentes.

Nome JSONJavaTipoNuloDescrição
quantidadegetQuantidade()InteiroNãoNotas exportadas
manifestogetManifesto()TextoSimPrimeiro manifesto. Caminho absoluto do manifesto.json do primeiro pacote; vazio quando não há notas pendentes
manifestosgetManifestos()Lista de textoNãoTodos os manifestos. Um por pacote-NNN em cada diretório de dispositivo, com até 500 notas por pacote; lista vazia quando não há notas pendentes
arquivosgetArquivos()Lista de textoNãoArquivos XML assinados. Caminhos absolutos

Origem do certificado

Parâmetro de certificado de Ativar e TrocarCertificado.

OrigemJava
Certificado já presente no repositório de certificados do WindowsCertificado.doRepositorio(thumbprint, maquinaLocal)
Arquivo PFXCertificado.deArquivoPfx(bytes, senha)
ParâmetroDescrição
thumbprintImpressão digital do certificado. SHA-1 com 40 dígitos hexadecimais, espaços são ignorados; formato errado devolve 10029874
maquinaLocalIndicador do repositório da máquina. true usa o repositório da máquina local, false (padrão) usa o repositório do usuário Windows atual
Bytes do PFX e senhaCertificado PFX e senha. O núcleo importa o certificado para o repositório com a chave privada não exportável e depois guarda só a impressão digital; a senha não é gravada

Ao parear ou trocar o certificado com PFX (Certificado.deArquivoPfx), o núcleo importa o certificado para o repositório "Usuário atual > Pessoal" do usuário Windows que executa o SDK, com a chave privada não exportável, e o mantém lá de forma permanente: toda assinatura usa esse certificado. Não apague esse certificado: sem ele o dispositivo não consegue assinar e a emissão devolve 10029813.

Quando o dispositivo deixar de ser usado, faça a limpeza nesta ordem:

  1. Confirme na situação que pendentesTransmissao de cada empresa é 0, ou seja, todas as notas offline foram transmitidas
  2. Desative ou revogue o dispositivo no console; se for só troca de certificado, instale antes o novo com TrocarCertificado
  3. Com o mesmo usuário Windows, abra certmgr.msc e apague o certificado antigo em "Pessoal > Certificados" pela impressão digital, ou execute no PowerShell Remove-Item Cert:\CurrentUser\My\<impressão digital>

Terminal secundário

Retorno de CriarTerminal. Java Resultados.TerminalCriado.

Nome JSONJavaTipoNuloDescrição
idgetId()TextoNãoIdentificador do terminal. Começa com trm_, usado para revogar
nomegetNome()TextoNãoNome do terminal. A identificação do caixa nas notas que esse secundário emite
tokengetToken()TextoNãoToken do terminal. Começa com tfl_, vem só uma vez; configure em TokenTerminal do secundário

Itens de ListarTerminais. Java Resultados.Terminal; sem o token.

Nome JSONJavaTipoNuloDescrição
idgetId()TextoNãoIdentificador do terminal
nomegetNome()TextoNãoNome do terminal
situacaogetSituacao()TextoNãoSituação do terminal. Ativo ou Revogado
criadoEmgetCriadoEm()Data e horaNãoMomento da emissão do token
ultimoUsoEmgetUltimoUsoEm()Data e horaSimÚltimo uso. null se nunca foi usado
revogadoEmgetRevogadoEm()Data e horaSimMomento da revogação. null em terminal ativo

Exceção

Toda falha lança uma exceção.

CampoJava TfFiscalExceptionDescrição
Código de errogetCodigo()Inteiro. Decida por ele; veja Códigos de erro
Constante de errogetTipo()Por exemplo ENGINE_LICENSE_EXPIRED; erros da plataforma trazem a constante da plataforma
DescriçãogetMessage()Traduzida conforme o idioma das mensagens configurado, pronta para mostrar
Informações adicionaisgetDetalhes(), getDetalhesJson()Por exemplo erros com os motivos campo a campo na falha de validação, ou campo no erro de parâmetro

Constantes de erro: os códigos mais comuns estão registrados em TfFiscalErrorCodes; códigos não registrados aparecem igualmente como número no campo de código de erro.

Eventos

Eventos locais que o núcleo entrega ao PDV quando mudam a situação das notas, a licença, o certificado, a conexão e afins. Os webhooks que a plataforma envia ao servidor do integrador são outro canal; veja Como os resultados chegam. Quais eventos o secundário recebe no modo principal e secundário: veja Vários caixas (modo principal e secundário).

Assinatura

Como assinarThread do callback
aoReceberEvento(Consumer<EventoNfce>) na configuração, ou o método de instância aoReceberEvento, cujo retorno cancela a assinatura ao ser fechadoNo modo subprocesso, callback um a um numa thread dedicada do SDK; no modo em processo, callback síncrono na thread de entrega do núcleo. Se o tratador lançar exceção, o evento não é confirmado

Ao registrar o tratador na partida com aoReceberEvento na configuração, os eventos acumulados antes da partida não se perdem.

Entrega e confirmação

  • Pelo menos uma vez, em ordem: o evento é gravado no computador na mesma transação da mudança de situação que o gerou, e depois entregue.
  • Confirmação: o tratador retornar normalmente confirma o evento. Se o tratador lançar exceção, o evento não é confirmado e cerca de 30 segundos depois é entregue de novo a partir do evento não confirmado mais antigo, com EventoId e Seq iguais.
  • Deduplicação: o mesmo evento pode chegar mais de uma vez; deduplique por EventoId.
  • Não bloqueie o tratador por muito tempo: para tratamentos demorados, registre o evento e processe de forma assíncrona; senão os eventos seguintes se acumulam.
  • Eventos locais do SDK: RUNTIME_FALHOU e RUNTIME_REINICIADO são gerados pelo próprio SDK, têm Seq 0, não precisam de confirmação e não são reenviados.

Campos comuns

Nome JSONJavaTipoNuloDescrição
eventoIdgetEventoId()TextoNãoIdentificador do evento. Chave de deduplicação, igual nos reenvios
seqgetSeq() (long)InteiroNãoSequência local. Crescente; 0 nos eventos locais do SDK
tipogetTipo()TextoNãoTipo do evento. Veja as seções abaixo
ocorridoEmgetOcorridoEm()Texto de data e horaNãoMomento do evento. ISO 8601 UTC
empresaIdgetEmpresaId()TextoSimIdentificador da empresa. null nos eventos locais do SDK
dispositivoIdvia getCampos()TextoSimIdentificador do dispositivo
idgetId()TextoSimIdentificador da nota. Só nos eventos de nota
chavegetChave()TextoSimChave de acesso. Só nos eventos de nota
statusgetStatus()TextoSimSituação atual da nota. Só nos eventos de nota; valores em Situação da nota
dadosgetDados() (Map<String, Object>)ObjetoNãoDados do evento. Campos nas seções abaixo

NOTA_EMITIDA_OFFLINE

Assinatura offline concluída. Evento de nota, com status ContingenciaPendente.

Campo de dadosTipoDescrição
serieInteiroSérie do dispositivo
numeroInteiroNúmero da nota
qrCodeTextoConteúdo do QR Code
tentativaOnlineBooleanoIndicador de tentativa online. true quando tentou online, ficou sem resultado e passou para offline; false para nota autorizada online

Tratamento: marque a venda como "offline aguardando transmissão". O mesmo resultado já veio de Emitir na hora da emissão; este evento serve principalmente para completar a situação depois de uma queda e reinício do PDV.

NOTA_AUTORIZADA

Nota offline autorizada depois da transmissão, autorizada depois da correção com o mesmo número, ou nota online pendente que foi autorizada. Evento de nota, com status Autorizada.

Campo de dadosTipoDescrição
protocoloTextoProtocolo de autorização
dataAutorizacaoTexto de data e hora, pode ser nuloData da autorização
foraDoPrazoBooleanoIndicador de entrega fora do prazo. true quando chegou à SEFAZ depois de 24 horas; a nota continua válida
aposCorrecaoBooleanoIndicador de autorização após correção. true quando autorizada depois da correção com o mesmo número

Tratamento: marque a venda como autorizada e registre o protocolo; a nota online pendente já pode ter o cupom impresso.

NOTA_REJEITADA

Nota offline rejeitada pela SEFAZ na transmissão. Evento de nota, com status Rejeitada.

Campo de dadosTipoDescrição
cStatInteiroCódigo de resultado da SEFAZ
motivoTextoMensagem de resultado da SEFAZ

Tratamento: avise o gerente para corrigir com Substituir usando o mesmo número; não pode emitir outra nota. A requisição original vem em Pedido de Consultar.

NOTA_NEGADA

Nota encaminhada online que estava aguardando autorização (AguardandoAutorizacao) e depois foi negada pela SEFAZ. Evento de nota, com status Negada. Nota offline rejeitada na transmissão não gera este evento, e sim NOTA_REJEITADA.

Campo de dadosTipoDescrição
cStatInteiroCódigo de resultado da SEFAZ
motivoTextoMensagem de resultado da SEFAZ
numeroLiberadoBooleanoNúmero reaproveitado. Quando true, a SEFAZ não usou este número; o kernel o reserva para a próxima nota emitida online, sem deixar quebra na numeração

Tratamento: esta nota não admite correção com o mesmo número. Corrija os dados da venda conforme o código e a mensagem de resultado e emita de novo com um id novo chamando Emitir.

NOTA_RECUSADA_PLATAFORMA

A plataforma recusou esta nota offline. Evento de nota, com status Recusada.

Campo de dadosTipoDescrição
codigoInteiro, pode ser nuloCódigo de erro da plataforma
mensagemTextoDescrição da plataforma

Tratamento: exige ação manual; registre o código e a descrição e fale com a plataforma.

CANCELAMENTO_CONCLUIDO

Cancelamento concluído. Evento de nota, com status Cancelada.

Campo de dadosTipoDescrição
cStatInteiro, pode ser nuloCódigo de resultado da SEFAZ
motivoTextoDescrição do resultado
protocoloTexto, pode ser nuloProtocolo do cancelamento

Tratamento: marque a venda como cancelada.

CANCELAMENTO_REJEITADO

Cancelamento recusado, por exemplo fora do prazo de cancelamento ou com a plataforma recusando o cancelamento agendado. Evento de nota, com status igual à situação anterior da nota.

Campo de dadosTipoDescrição
cStatInteiro, pode ser nuloCódigo de resultado da SEFAZ
motivoTextoMotivo da recusa
protocoloTexto, pode ser nuloProtocolo

Tratamento: a nota continua válida. Avise o gerente para tratar conforme as regras de Cancelar NFC-e.

NUMERO_INUTILIZADO

Números da série do dispositivo tomados e não usados numa assinatura foram encerrados: inutilizados na SEFAZ ou, em estados que não aceitam mais a inutilização, como AC, BA e SP, dispensados de declaração por norma. Nos dois casos contam como usados e não são mais emitidos. Não é evento de nota.

Campo de dadosTipoDescrição
serieInteiroSérie do dispositivo
inicioInteiroNúmero inicial
fimInteiroNúmero final

Tratamento: nenhuma ação; pode registrar no log para conciliação.

NUMERO_INUTILIZACAO_RECUSADA

A plataforma recusou a inutilização de números não usados. Não é evento de nota. A recusa não definitiva só é enviada uma vez, na primeira falha, e o núcleo depois tenta de novo sozinho com espera crescente; a recusa definitiva exige conferência manual.

Campo de dadosTipoDescrição
serieInteiroSérie do dispositivo
inicioInteiroNúmero inicial
fimInteiroNúmero final
codigoInteiroCódigo de erro da plataforma
mensagemTextoMensagem da plataforma
definitivoBooleanoIndicador de recusa definitiva. true quando não haverá nova tentativa, por exemplo faixa inválida ou com notas já emitidas na faixa; false quando o núcleo vai tentar de novo sozinho

Tratamento: com definitivo igual a false, basta registrar no log; o número de faixas a inutilizar está em NumerosNaoUtilizadosPendentes de Situacao. Com true, registre o código e a mensagem; o gerente confere a faixa de números e fala com a plataforma.

DISPOSITIVO_DESATIVADO

Dispositivo desativado ou revogado, emissão offline da empresa desativada, ou software do PDV ou sua versão bloqueados. Depois disso, novas emissões são recusadas e as notas offline já emitidas seguem sendo transmitidas.

Campo de dadosTipoDescrição
situacaoTextoSituação do dispositivo. Valores em Empresa pareada
motivoTextoMotivo. Pode ser texto vazio

Tratamento: mostre com destaque na tela do caixa "este computador não emite mais notas" e, conforme situacao, oriente a falar com o integrador ou atualizar o PDV.

LICENCA_EXPIRANDO

Faltam menos de 12 horas para a licença vencer e ela não pôde ser renovada, normalmente por muito tempo sem rede. No máximo uma vez a cada 6 horas.

Campo de dadosTipoDescrição
expiraEmTexto de data e horaVencimento da licença
offlineAteTexto de data e horaPrazo da emissão offline

Tratamento: avise o caixa para restaurar a rede o quanto antes; com rede a licença é renovada sozinha.

LICENCA_EXPIRADA

A licença venceu; a emissão offline é recusada e a emissão online não é afetada.

Campo de dadosTipoDescrição
expiradaEmTexto de data e horaMomento do vencimento

Tratamento: depois que a rede voltar, a licença é renovada sozinha.

PRAZO_TRANSMISSAO_PROXIMO

A nota mais antiga a transmitir já passou de 80% do prazo de transmissão.

Campo de dadosTipoDescrição
pendenteMaisAntigaEmTexto de data e horaData de emissão da nota mais antiga a transmitir
prazoAteTexto de data e horaPrazo de transmissão

Tratamento: avise com destaque para o caixa restaurar a rede imediatamente. Depois do prazo, este computador não emite mais offline.

CERTIFICADO_EXPIRANDO

O certificado da empresa vence em 30, 7 ou 1 dia; um aviso de cada.

Campo de dadosTipoDescrição
validoAteTexto de data e horaVencimento do certificado

Tratamento: avise o gerente para renovar o certificado e, depois da renovação, chame TrocarCertificado.

CONEXAO_ALTERADA

Mudança entre online e offline.

Campo de dadosTipoDescrição
conectadoBooleanoIndicador de conexão. true quando a conexão voltou

Tratamento: atualize o indicador online / offline na tela do caixa.

PENDENCIAS_NA_INICIALIZACAO

Na inicialização ainda há notas offline a transmitir ou eventos não confirmados no computador.

Campo de dadosTipoDescrição
pendentesTransmissaoInteiroNotas a transmitir
eventosNaoEntreguesInteiroEventos não confirmados

Tratamento: a tela do PDV pode avisar «N notas offline a transmitir» e conferir a rede; os eventos não confirmados são reenviados em seguida, sem outra ação.

RUNTIME_FALHOU

Evento local do SDK: o processo do runtime saiu inesperadamente. Seq é 0. As chamadas em andamento falham com 10029832.

Campo de dadosTipoDescrição
codigoSaidaInteiroCódigo de saída do processo
tentativaInteiroNúmero de tentativas de reinício
proximaTentativaMsInteiroMilissegundos até o próximo reinício

Tratamento: com o reinício automático ligado, nenhuma ação; registre no log e, se for frequente, exporte o log e fale com a plataforma. Emissões que falharam podem ser reenviadas com o mesmo id, pois o núcleo é idempotente por id.

RUNTIME_REINICIADO

Evento local do SDK: o runtime foi reiniciado e inicializado de novo automaticamente. Seq é 0.

Campo de dadosTipoDescrição
tentativaInteiroNúmero do reinício

Tratamento: nenhuma ação; os eventos não confirmados antes do reinício são reenviados.

Requisição de emissão

A requisição de emissão recebida por Emitir, Previsualizar e Substituir é o corpo da API Emitir NFC-e: nomes de campo, valores e regras de validação são iguais, e o núcleo e a plataforma usam a mesma normalização e validação; referenciar classe de imposto exige conexão, veja a tabela abaixo. A descrição campo a campo, as enumerações e os exemplos de cada cenário estão em Emitir NFC-e.

Há três diferenças:

CampoNo SDK
modoRespostaNão precisa enviar. O SDK sempre espera o resultado; se enviar, é ignorado
ambienteEmissaoMantenha igual ao ambiente do dispositivo. O ambiente do dispositivo é definido pelo código de pareamento; veja Gerar código de pareamento
itens[].classeImpostoDisponível com conexão. Expandida pela plataforma antes da emissão, com o mesmo resultado da emissão em nuvem; sem rede ou sem acesso à plataforma devolve 10029780, quando então se envia impostos. Veja Classe de imposto e conexão

O id é a chave de idempotência: chamar Emitir de novo com o mesmo id devolve a nota original; depois de queda, reinício ou tempo esgotado, reenvie com o mesmo id, sem trocar por um novo.

Como passar a requisição

A requisição de emissão é passada como texto JSON. Com host em Java 21 ou superior há também a entrada tipada TfFiscalNfceTipado, cujo tipo de requisição é o mesmo da plataforma; as regras de classeImposto são as mesmas.

Exemplo de requisição

Venda presencial, consumidor não identificado, pagamento em dinheiro:

json
{
"id": "PDV01-000131",
"ambienteEmissao": "Homologacao",
"pedido": {
"presencaConsumidor": "OperacaoPresencial",
"pagamento": { "formas": [ { "tipo": "Dinheiro", "valor": 50.30 } ] }
},
"itens": [
{
"cfop": "5102",
"codigo": "7891000100101",
"descricao": "ARROZ BRANCO TIPO 1 5KG",
"ncm": "10063021",
"quantidade": 2,
"unidadeMedida": "UN",
"valorUnitario": 25.15,
"impostos": {
"icms": { "situacaoTributaria": "102" },
"pis": { "situacaoTributaria": "49" },
"cofins": { "situacaoTributaria": "49" }
}
}
]
}

Códigos de erro

O Assistente Fiscal e o SDK embarcado usam o mesmo núcleo de emissão offline. No SDK os erros do núcleo são lançados como exceção (Codigo é o código de erro e Tipo a constante); na interface local do Assistente vêm em codigo. De 10029800 a 10029846 vêm do núcleo, de 10029870 a 10029888 do pacote do SDK, da comunicação com o runtime e do modo principal e secundário; as demais faixas não estão atribuídas. Códigos de erro devolvidos pela plataforma são repassados sem alteração.

Erros gerais: qualquer método pode devolver 10029832 (saída inesperada do runtime), 10029833 (tempo de espera esgotado), 10029834 (encerrado) e 10029836 (erro interno do núcleo); em operações com rede, erros de negócio devolvidos pela plataforma são repassados sem alteração. A seção "Erros possíveis" de cada método lista só os códigos próprios daquele método. Todos os códigos de erro e ações recomendadas em Códigos de erro.

Código de erroConstanteCenárioAção
10029800ENGINE_NOT_STARTEDNão inicializadoNo uso normal não acontece; se acontecer, há defeito no pacote do SDK; inicialize de novo
10029801ENGINE_NOT_ACTIVATEDEmpresa não pareada neste computador, ou nenhuma empresa pareada aindaConduza o pareamento; com várias empresas, confira empresaId
10029802ENGINE_EMPRESA_REQUIREDVárias empresas pareadas, mas empresaId não informadoInforme empresaId
10029803ENGINE_LICENSE_MISSINGNão há licença para emissão offlineSincronize uma vez com rede (SincronizarAgora)
10029804ENGINE_LICENSE_EXPIREDLicença vencida; a emissão offline é recusada e a online segue normalRestaure a rede; a renovação é automática
10029805ENGINE_LICENSE_SIGNATURE_INVALIDAssinatura da licença inválidaAção manual: fale com a plataforma, a base local pode ter sido adulterada
10029806ENGINE_LICENSE_NOT_FOR_DEVICEA licença não pertence a este dispositivoAção manual: pareie de novo
10029807ENGINE_OFFLINE_WINDOW_CLOSEDO prazo da emissão offline terminouRestaure a rede e emita online
10029808ENGINE_LICENSE_QUOTA_EXHAUSTEDA série do dispositivo chegou ao número 999999999Desative o dispositivo e pareie-o de novo com um código de pareamento novo que informe outra série em serie; a plataforma não troca a série sozinha
10029809ENGINE_CLOCK_ROLLBACKO relógio do sistema foi atrasadoAção manual: corrija a hora do sistema
10029810ENGINE_TRANSMISSION_DEADLINE_REACHEDA nota pendente mais antiga passou do prazo de transmissãoAção manual: restaure a rede e transmita o quanto antes
10029811ENGINE_OFFLINE_NOT_ALLOWEDA empresa ou o estado não permite emissão offline; ou a base acabou de ser restaurada de um backup e ainda não recebeu uma nova licençaSó é possível emitir online; depois de restaurar, a emissão offline volta sozinha após uma sincronização com a plataforma
10029812ENGINE_OFFLINE_FUEL_NOT_SUPPORTEDNota com combustível não pode ser emitida offlineEmita quando a rede voltar
10029813ENGINE_CERTIFICATE_UNAVAILABLECertificado não encontrado, sem chave privada ou com CNPJ divergenteAção manual: confira o repositório de certificados; se preciso, TrocarCertificado
10029814ENGINE_CERTIFICATE_EXPIREDCertificado vencidoAção manual: renove e chame TrocarCertificado
10029815ENGINE_SNAPSHOT_MISSINGConfiguração local ou dados fiscais ausentes ou com falha de verificaçãoSincronize com rede; se persistir, fale com a plataforma
10029816ENGINE_DEVICE_DEACTIVATEDDispositivo desativadoAção manual: fale com o integrador; as notas offline já emitidas seguem sendo transmitidas
10029817ENGINE_REQUEST_INVALIDFalha na validação da requisição; Detalhes lista os motivos campo a campoCorrija a requisição; dá para validar antes com Previsualizar
10029780ENGINE_TAX_CLASS_REQUIRES_ONLINELinha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumidoReenvie com o mesmo id quando a rede voltar; sem rede, envie impostos nas linhas de item
10029818ENGINE_DUPLICATE_ID_DIFFERENT_CONTENTO mesmo id já foi usado em nota de conteúdo diferenteVenda nova com id novo; para repetir, use a requisição original e recupere a nota original
10029819ENGINE_NOTE_NOT_FOUNDA nota não existe neste computadorConfira id e empresaId
10029820ENGINE_NOTE_NOT_CORRECTABLEA situação atual não permite correçãoSó Rejeitada pode usar Substituir
10029821ENGINE_CORRECTION_CHANGES_TOTALSA correção alterou valores ou tributosAltere só o que não envolve valores
10029822ENGINE_CANCEL_NOT_ALLOWEDA situação atual não permite cancelarNão tente de novo
10029823ENGINE_SERIE_EXHAUSTEDNumeração da série do dispositivo esgotadaDesative o dispositivo e pareie-o de novo com um código de pareamento novo que informe outra série em serie; a plataforma não troca a série sozinha
10029824ENGINE_PLATFORM_UNREACHABLEOperação que exige rede (pareamento) sem conexão com a plataformaConfira a rede e tente de novo
10029825ENGINE_ACTIVATION_CODE_INVALIDFormato, assinatura ou validade do código de pareamento incorretosAção manual: gere outro código de pareamento
10029826ENGINE_ACTIVATION_HOST_UNTRUSTEDO código de pareamento aponta para um endereço de plataforma não confiávelAção manual: confirme a origem do código e o ambiente do instalador (homologação / produção)
10029827ENGINE_KEY_PROTECTION_FAILEDO diretório de dados veio de outro computador ou de outro usuário do WindowsAção manual: rode no computador e com o usuário originais, ou pareie de novo
10029828ENGINE_DATA_DIR_LOCKEDDiretório de dados em uso por outro processo, inclusive, ao restaurar um backup, uma instância deste programa em que ainda não se chamou EncerrarFeche a outra instância; antes de restaurar um backup, chame Encerrar
10029829ENGINE_LOCAL_STORE_CORRUPTEDBase local inconsistenteAção manual: não apague o diretório de dados, fale com a plataforma
10029830ENGINE_PROTOCOL_VERSION_UNSUPPORTEDVersões do SDK e do runtime incompatíveisAtualize SDK e runtime juntos
10029831ENGINE_RUNTIME_START_FAILEDO runtime não iniciouConfira se o diretório do runtime está completo e se o antivírus está bloqueando
10029832ENGINE_RUNTIME_CRASHEDO runtime saiu inesperadamentePode tentar de novo; com reinício automático o SDK se recupera sozinho; reenvie a emissão com o mesmo id
10029833ENGINE_TIMEOUTTempo de espera esgotadoReenvie a emissão com o mesmo id, ou faça Consultar antes
10029834ENGINE_SHUTTING_DOWNEncerrando ou já encerradoChame Iniciar de novo
10029835ENGINE_IN_PROCESS_UNSUPPORTEDO modo em processo do Java exige Java 21 ou superiorUse o modo subprocesso
10029836ENGINE_INTERNAL_ERRORErro interno do núcleo; a descrição traz um número de referênciaFale com a plataforma informando o número de referência e o log
10029837ENGINE_ALREADY_ACTIVATEDEmpresa já pareada neste diretório de dadosNão precisa parear de novo; para trocar de dispositivo, desative o antigo antes
10029838ENGINE_PLATFORM_RESPONSE_UNTRUSTEDFalha na verificação da resposta da plataforma; os dados anteriores foram mantidosNova tentativa automática depois; se persistir, verifique se um proxy de rede alterou a resposta
10029839ENGINE_ACTIVATION_PERSIST_FAILEDPareada na plataforma, mas a gravação local falhouPareie de novo com o mesmo código de pareamento
10029840ENGINE_CONFIG_INVALIDConfiguração de inicialização inválidaCorrija a configuração
10029841ENGINE_AUTHORIZED_XML_UNAVAILABLEXML autorizado indisponível: ainda não autorizada, ou não está no computador e não foi possível buscar na plataformaSe ainda não autorizada, aguarde o evento de autorização e leia depois; se já autorizada, a plataforma ainda não arquivou ou está inacessível no momento; tente mais tarde
10029842ENGINE_LOCAL_STORE_NEWER_VERSIONBase local de versão mais nova que o núcleo atual: o diretório de dados já foi usado por uma versão mais nova do SDK e a partida é recusadaAtualize o SDK e o runtime para uma versão não inferior à última usada; nunca apague o diretório de dados
10029843ENGINE_CANCEL_XML_UNAVAILABLEXML de cancelamento indisponível: a nota não foi cancelada, ou não está no computador e não foi possível buscar na plataformaSe ainda não cancelada, aguarde CANCELAMENTO_CONCLUIDO e leia depois; se já cancelada, tente mais tarde
10029844ENGINE_EXPORT_FAILEDFalha ao gravar arquivo: destino da exportação ou do backup sem permissão de gravação, ou arquivo de backup já existenteTroque de diretório ou de nome; confira espaço em disco e permissões
10029845ENGINE_SUBSTITUTE_KEY_INVALIDChave da nota substituta do cancelamento por substituição inválida, ou não é nota offline deste computador e desta empresa não recusadaInforme a chave de acesso de 44 dígitos da nota offline emitida neste computador para a mesma venda
10029846ENGINE_BACKUP_INVALIDO backup não pode ser restaurado: senha errada, ou o arquivo de backup foi alterado, está corrompido ou não é backup deste SDKConfira a senha; use outro backup íntegro. A base original não foi alterada
10029870ENGINE_PROTOCOL_INVALID_JSONA mensagem recebida pelo runtime não é JSON válidoDefeito no pacote do SDK; atualize o SDK
10029871ENGINE_PROTOCOL_LINE_TOO_LONGMensagem acima de 8 MBRequisição grande demais; divida os itens
10029872ENGINE_PROTOCOL_MESSAGE_INVALIDEstrutura da mensagem inválidaDefeito no pacote do SDK; atualize o SDK
10029873ENGINE_METHOD_UNKNOWNO runtime não reconhece o métodoO SDK é mais novo que o runtime; atualize o runtime
10029874ENGINE_PARAMS_INVALIDParâmetro ausente ou de tipo errado; Detalhes.campo indica o parâmetroCorrija o parâmetro, por exemplo requisição que não é objeto JSON, formato da impressão digital do certificado ou formato de data
10029875ENGINE_ALREADY_STARTEDInicialização repetida, ou o método de protocolo de restauração de backup chamado numa conexão com o runtime que já executou IniciarNo uso normal dos pacotes não acontece; se aparecer, é defeito no pacote do SDK, atualize o SDK. Quem integra direto com o protocolo do runtime chama Encerrar e restaura por uma conexão nova
10029876ENGINE_REQUEST_ID_DUPLICATEDA mesma chamada ainda está em processamentoDefeito no pacote do SDK; atualize o SDK
10029877ENGINE_RUNTIME_NOT_FOUNDRuntime não encontradoConfira o instalador e o diretório do runtime
10029878ENGINE_TOO_MANY_PENDINGMais de 64 chamadas aguardando ao mesmo tempoReduza a concorrência
10029879ENGINE_RESPONSE_TOO_LARGEResposta acima do limiteFale com a plataforma
10029880ENGINE_PRINCIPAL_UNREACHABLEO secundário não alcança o principal; o pedido não chegouTente depois, ou passe o caixa para a máquina reserva
10029881ENGINE_PRINCIPAL_RESULT_UNKNOWNO pedido chegou ao principal, mas a resposta não voltou; resultado desconhecidoCom o principal de volta, chame Consultar com o mesmo id; reenviar Emitir com o mesmo id e conteúdo não emite duas vezes
10029882ENGINE_TERMINAL_TOKEN_INVALIDToken do terminal secundário inválido ou revogadoChame CriarTerminal de novo no principal e atualize TokenTerminal do secundário
10029883ENGINE_PRINCIPAL_ADDRESS_INVALIDEndereço do principal mal formatado ou fora da rede local privadaCorrija EnderecoPrincipal
10029884ENGINE_MODE_METHOD_UNAVAILABLEO modo atual não oferece esse métodoPareamento, troca de certificado, backup e exportação são feitos no principal; gestão de terminais só no principal
10029885ENGINE_PRINCIPAL_REJECTEDO principal recusou a origem do pedido, por exemplo um secundário fora das redes permitidasConfira RedesPermitidas do principal e a rede
10029886ENGINE_PRINCIPAL_RATE_LIMITEDFalhas de autenticação demais; limitado pelo principalConfira o token e tente após 1 minuto
10029887ENGINE_PRINCIPAL_LISTEN_FAILEDNão foi possível escutar na porta de rede local do principalTroque PortaPrincipal ou libere a porta
10029888ENGINE_TERMINAL_NOT_FOUNDO terminal a revogar não existeConfira o id do terminal com ListarTerminais

Todos os códigos, inclusive os do Assistente Fiscal, estão em Códigos de erro.