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).
| Item | Java | Obrigatório | Descrição |
|---|---|---|---|
| Diretório de dados | diretorioDados(Path) | Sim | Diretó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 runtime | diretorioRuntime(Path) | Obrigatório no modo subprocesso | Diretório de instalação do runtime. Deve conter tffiscal-nfce.exe; se não for encontrado, devolve 10029877 |
| Nome do PDV | nomeAplicativo(String) | Sim | Nome 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 PDV | versaoAplicativo(String) | Sim | Nú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 mensagens | idioma(String) | Não | Idioma 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 chamada | tempoLimitePadraoMs(long) | Não | Espera 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 partida | tempoLimiteInicioMs(long) | Não | Espera máxima até o runtime ficar pronto. Padrão de 5 segundos; ao estourar devolve 10029831 |
| Reinício automático | reiniciarAutomaticamente(boolean) | Não | Reiní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 log | encaminharLog(boolean) | Não | Log do núcleo enviado ao PDV. Desligado por padrão; ligado, vai para java.util.logging |
| Proxy de saída | proxy(String) | Não | Endereç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 proxy | proxyAutenticacao(String, String) | Não | Usuá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 sistema | usarProxyDoSistema(boolean) | Não | Uso 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 XML | retencaoXmlDias(int) | Não | Dias 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ção | modo(Modo) | Não | Modo de execução do Java. SUBPROCESSO (padrão) ou EM_PROCESSO, veja abaixo |
| Ouvinte de eventos | aoReceberEvento(Consumer<EventoNfce>) | Não | Tratador de eventos registrado na partida. Eventos acumulados antes da partida não se perdem; veja Eventos |
| Comando do runtime | comandoRuntime(String) | Não | Item avançado. Caminho completo do executável do runtime, só para desenvolvimento e testes |
| Parâmetros do runtime | argumentosRuntime(List<String>) | Não | Item avançado. Parâmetros de partida do runtime, padrão --stdio; só para desenvolvimento e testes |
| Motor simulado | motorSimulado(boolean) | Não | Motor 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ário | modoOperacao(ModoOperacao) | Não | Papel 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 principal | portaPrincipal(int) | Não | Porta de rede local do principal. Só no principal; sem valor ou 0 é 8786; com a porta ocupada, Iniciar devolve 10029887 |
| Redes permitidas | redesPermitidas(List<String>) | Não | Redes 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 principal | enderecoPrincipal(String) | Obrigatório no secundário | Endereç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 terminal | tokenTerminal(String) | Obrigatório no secundário | Token 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
Modo | Significado | Requisitos |
|---|---|---|
SUBPROCESSO | Padrão. O SDK inicia o runtime como subprocesso | Host com Java 8 ou superior; é preciso distribuir o runtime e definir diretorioRuntime |
EM_PROCESSO | O núcleo roda direto na JVM do PDV, sem subprocesso | Host 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ção | Forma de proxy |
|---|---|
UsarProxyDoSistema ligado | Proxy 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 configurado | Proxy manual. Usa o endereço informado em Proxy |
| Nada configurado | Conexã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
Proxymanualmente. - Autenticação no proxy:
proxyAutenticacaovale 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,Avisosem 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.
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.
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
public static TfFiscalNfce iniciar(Configuracao config);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Configuração | config | Sim | Configuraçã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 erro | Situação | Ação |
|---|---|---|
| 10029877 | Runtime não encontrado | Confira se o diretório do runtime e tffiscal-nfce.exe vão no instalador |
| 10029831 | O runtime não iniciou ou não ficou pronto dentro do tempo limite da partida | Veja o log; em computador lento, aumente o tempo limite da partida |
| 10029830 | Versões do SDK e do runtime incompatíveis | Distribua runtime e SDK da mesma versão |
| 10029835 | Modo em processo do Java com host abaixo do Java 21 | Use o modo subprocesso ou atualize o Java |
| 10029828 | Diretório de dados já aberto por outro processo | Abra uma única instância por diretório; verifique processos remanescentes |
| 10029827 | A chave local não pode ser aberta: o diretório de dados veio de outro computador ou de outro usuário do Windows | Rode com o usuário Windows original; para trocar de computador, desative o dispositivo antigo e pareie de novo |
| 10029829 | Base local inconsistente | Não apague o diretório de dados; fale com a plataforma |
| 10029842 | Base 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 é recusada | Atualize 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 |
| 10029840 | Configuração inválida | Corrija o item de configuração conforme Message |
| 10029874 | Valor 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 faixa | Corrija o item de configuração conforme Detalhes.campo |
| 10029882 | Token do terminal secundário inválido ou revogado | Emita outro token no principal e atualize TokenTerminal |
| 10029883 | Endereço do principal mal formatado ou fora da rede local privada | Corrija EnderecoPrincipal |
| 10029887 | Não foi possível escutar na porta de rede local do principal | Troque PortaPrincipal ou libere a porta |
Também pode devolver os erros gerais.
Exemplos
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 oempresaIdde 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
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
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
public Resultados.CodigoAtivacao inspecionarCodigoAtivacao(String codigo);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Código de pareamento | codigo | Sim | Texto 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 erro | Situação | Ação |
|---|---|---|
| 10029825 | Formato, assinatura ou validade do código incorretos | Confira se copiou o código inteiro; se venceu, peça ao integrador para gerar outro |
| 10029826 | O código aponta para um endereço de plataforma não confiável | O 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
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
public Resultados.Ativacao ativar(String codigoAtivacao, Certificado certificado);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Código de pareamento | codigoAtivacao | Sim | Texto completo do código de pareamento. Começa com TFA1., de uso único, válido por 72 horas |
| Certificado | certificado | Sim | Certificado 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 erro | Situação | Ação |
|---|---|---|
| 10029825 / 10029826 | Falha na verificação local do código / plataforma não confiável | Veja InspecionarCodigoAtivacao |
| 10029824 | Sem conexão com a plataforma | Conecte e tente de novo |
| 10029837 | Empresa já pareada neste diretório de dados | Não precisa parear de novo |
| 10029813 / 10029814 | Certificado não encontrado, sem chave privada, CNPJ divergente / vencido | Use um certificado A1 válido da empresa |
| 10029839 | Pareada na plataforma, mas a gravação local falhou | Chame Ativar de novo com o mesmo código de pareamento |
| 10029806 | A licença não pertence a este dispositivo | Pareie de novo; se continuar, fale com a plataforma |
| 10029874 | Parâmetro de certificado inválido: impressão digital sem 40 dígitos hexadecimais, ou PFX vazio | Corrija o parâmetro do certificado |
| 10029205 a 10029208 | Devolvido pela plataforma: código inválido / vencido / já usado / revogado | Gere outro código de pareamento |
| 10029209 | Devolvido pela plataforma: o código não permite a forma SDK | Gere de novo com Sdk ou Qualquer |
| 10029210 / 10029211 | Devolvido pela plataforma: falta o nome do PDV / versão do PDV bloqueada ou abaixo da mínima | Configure o nome do PDV; atualize o PDV |
| 10029213 / 10029214 | Devolvido pela plataforma: CNPJ do certificado difere da empresa / certificado vencido | Use um certificado válido da empresa |
| 10029219 | Devolvido pela plataforma: ambiente do código diferente do ambiente atual da empresa | Gere um novo código no ambiente atual da empresa |
| 10029221 a 10029225 | Devolvido pela plataforma: a série do dispositivo indicada no código não está mais disponível | O integrador gera um novo código com outra série ou outro número inicial |
Também pode devolver os erros gerais.
Exemplos
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:
- Busca local por
id: se o mesmoidjá foi emitido, devolve a nota original sem tomar outro número; conteúdo diferente devolve10029818. - Se uma linha de item referencia classe de imposto (
classeImposto), a requisição vai antes à plataforma, que a expande emimpostoscompletos: exige conexão, e sem acesso à plataforma devolve10029780sem 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. - Normalização e validação, com as mesmas regras da nuvem; se não passar, devolve
10029817, comDetalheslistando os motivos campo a campo. - 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. - 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, devolveAguardandoAutorizacaoe 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
public ResultadoEmissao emitir(String pedidoJson);public ResultadoEmissao emitir(String pedidoJson, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Requisição de emissão | pedidoJson | Sim | Requisiçã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 empresa | empresaId | Obrigatório com várias empresas | Empresa 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.
Status | O que o PDV faz |
|---|---|
Autorizada | Imprime o cupom |
ContingenciaPendente | Assinada offline: imprime o cupom com Cupom e entrega ao consumidor; a transmissão é automática |
AguardandoAutorizacao | Aceita 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 |
Negada | Emissã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 erro | Situação | Ação |
|---|---|---|
| 10029817 | Falha na validação da requisição | Corrija conforme Detalhes |
| 10029780 | Linha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumido | Reenvie com o mesmo id quando a rede voltar; sem rede, envie impostos nas linhas de item |
| 10029818 | O mesmo id já foi usado em nota de conteúdo diferente | Venda nova com id novo; para repetir, use a requisição original |
| 10029801 / 10029802 | Empresa não pareada / várias empresas sem empresaId | Pareie primeiro; informe empresaId |
| 10029816 | Dispositivo desativado | Fale com o integrador |
| 10029805 / 10029806 | Assinatura da licença inválida / licença de outro dispositivo | Fale com a plataforma; se preciso, pareie de novo |
| 10029874 | A requisição não é um objeto JSON | Envie o texto de um objeto JSON |
| 10029803 / 10029804 / 10029807 | Sem rede e sem licença / licença vencida / prazo offline encerrado | Restaure a rede; depois da renovação volta sozinho |
| 10029808 | A série do dispositivo chegou ao número 999999999 | Desative 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 |
| 10029809 | O relógio do sistema foi atrasado | Corrija a hora do sistema |
| 10029810 | A nota pendente mais antiga passou do prazo de transmissão | Restaure a rede para transmitir |
| 10029811 / 10029812 | Empresa ou estado não permite offline / nota com combustível | Só é possível emitir online |
| 10029813 / 10029814 | Certificado indisponível / vencido | Confira o certificado; se preciso, TrocarCertificado |
| 10029815 | Faltam a configuração local ou os dados fiscais | Sincronize uma vez com rede |
| 10029823 | Numeração da série do dispositivo esgotada | Desative 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 |
| 10029307 | Devolvido pela plataforma: ambiente do dispositivo diferente do ambiente atual da empresa | Pareie um dispositivo novo no ambiente atual da empresa |
| 10029424 | Devolvido 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 divergem | Não tente com outro número; exporte os logs e fale com a plataforma |
| 10029426 | Devolvido pela plataforma: o mesmo id já tem uma nota não rejeitada na plataforma, por exemplo emitida pela API em nuvem ou por outro dispositivo | Confira a nota original em Consultar NFC-e; use um id novo para uma venda nova |
| Outros códigos da plataforma | Erro de negócio devolvido pela plataforma na emissão online, como 10022004 | Trate conforme os erros de Emitir NFC-e |
Também pode devolver os erros gerais.
Exemplos
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
public Resultados.PreVisualizacao previsualizar(String pedidoJson, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Requisição de emissão | pedidoJson | Sim | Requisição a validar. Mesma estrutura de Emitir; o id pode ficar para depois |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa 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
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
public SituacaoNota consultar(String id);public SituacaoNota consultar(String id, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Identificador da nota | id | Sim | O id da requisição de emissão |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa 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 erro | Situação | Ação |
|---|---|---|
| 10029819 | A nota não existe neste computador | Confira id e empresaId; se a nota não foi emitida neste computador, use a consulta em nuvem |
| 10029801 / 10029802 | Empresa não pareada / várias empresas sem empresaId | Pareie primeiro; informe empresaId |
Também pode devolver os erros gerais.
Exemplos
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
public Resultados.PaginaNotas listarNotas(LocalDate data, String status, int pagina, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Data de emissão | data | Não | Filtro 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ção | status | Não | Filtro por situação. Valores em Tipos de dados: situação da nota; sem ele não há limite |
| Página | pagina | Não | Número da página. Começa em 1, padrão 1 |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa 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 erro | Situação | Ação |
|---|---|---|
| 10029874 | Data fora do formato yyyy-mm-dd, situação com valor inválido, ou página menor que 1 | Informe conforme a tabela de valores |
| 10029801 / 10029802 | Empresa não pareada / várias empresas sem empresaId | Pareie primeiro; informe empresaId |
Também pode devolver os erros gerais.
Exemplos
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:
| Caso | Destino Situacao | Depois |
|---|---|---|
| Nota autorizada e com rede | Solicitado | Enviado à plataforma; o resultado chega pelos eventos CANCELAMENTO_CONCLUIDO ou CANCELAMENTO_REJEITADO |
| Nota offline transmitida e ainda não autorizada | Agendado | A 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 transmitida | EnfileiradoLocal | Fica 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
public Resultados.Cancelamento cancelar(String id, String justificativa, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Identificador da nota | id | Sim | O id da requisição de emissão |
| Justificativa | justificativa | Sim | Motivo do cancelamento. De 15 a 255 caracteres |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa 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 erro | Situação | Ação |
|---|---|---|
| 10029822 | A 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 detalhes | Não tente de novo; confira a situação com Consultar |
| 10029819 | A nota não existe neste computador | Confira o id |
| 10029817 | Justificativa fora de 15 a 255 caracteres | Corrija a justificativa |
| Outros códigos da plataforma | Erro devolvido pela plataforma no envio, como prazo de cancelamento vencido 10022007 | Trate conforme Cancelar NFC-e |
Também pode devolver os erros gerais.
Exemplos
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:
| Objeto | Precisa atender | Se não atender |
|---|---|---|
| Nota original | Nota normal emitida online, encaminhada pela plataforma: não é offline, não está cancelada e não tem cancelamento pendente | 10029822 |
| Nota substituta | Nota 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 original | 10029845 |
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
public Resultados.Cancelamento cancelarPorSubstituicao(String id, String chaveSubstituta, String justificativa,String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Identificador da nota | id | Sim | O id da nota original que é substituída |
| Chave da substituta | chaveSubstituta | Sim | Chave de acesso da nota substituta. 44 dígitos, obtidos em Chave do resultado da emissão da substituta |
| Justificativa | justificativa | Sim | Motivo do cancelamento. De 15 a 255 caracteres |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa 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 erro | Situação | Ação |
|---|---|---|
| 10029822 | A original não é nota normal emitida online: é offline, já está cancelada ou tem cancelamento pendente | Não tente de novo; para nota offline use Cancelar |
| 10029845 | Chave da substituta inválida, ou não é nota offline deste computador e desta empresa não recusada | Informe a chave de acesso de 44 dígitos da nota offline emitida neste computador para a mesma venda |
| 10029819 | A nota original não existe neste computador | Confira o id |
| 10029817 | Justificativa fora de 15 a 255 caracteres | Corrija a justificativa |
| Outros códigos da plataforma | Erro devolvido pela plataforma no envio, como prazo de cancelamento vencido 10022007 | Trate conforme Cancelar NFC-e |
Também pode devolver os erros gerais.
Exemplos
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
public ResultadoEmissao substituir(String id, String pedidoJsonCorrigido, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Identificador da nota | id | Sim | O id da nota rejeitada |
| Requisição corrigida | pedidoJsonCorrigido | Sim | Requisiçã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 empresa | empresaId | Obrigatório com várias empresas | Empresa 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 erro | Situação | Ação |
|---|---|---|
| 10029820 | A situação atual não permite correção: só Rejeitada pode ser corrigida | Confira a situação com Consultar |
| 10029821 | A correção alterou valores ou tributos | Altere só o que não envolve valores |
| 10029817 | Falha na validação da requisição | Corrija conforme Detalhes |
| 10029780 | Linha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumido | Reenvie com o mesmo id quando a rede voltar; sem rede, envie impostos nas linhas de item |
| 10029819 | A nota não existe neste computador | Confira o id |
| 10029815 | Faltam a configuração local ou os dados fiscais | Sincronize uma vez com rede |
Também pode devolver os erros gerais.
Exemplos
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
public byte[] cupom(String id, FormatoCupom formato);public byte[] cupom(String id, FormatoCupom formato, String empresaId);public byte[] cupom(String id, FormatoCupom formato, OpcoesCupom opcoes, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Identificador da nota | id | Sim | O id da requisição de emissão |
| Formato | formato | Sim | Formato do cupom. Valores na tabela abaixo |
| Parâmetros de impressão | opcoes (OpcoesCupom) | Não | Parâ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 empresa | empresaId | Obrigatório com várias empresas | Empresa emitente. Pode ser omitido quando só uma empresa está pareada |
Java FormatoCupom | Conteúdo |
|---|---|
ESCPOS_80 | Bytes ESC/POS para impressora térmica de 80 mm |
ESCPOS_58 | Bytes ESC/POS para impressora térmica de 58 mm |
TEXTO | Texto puro em UTF-8 |
HTML | HTML em UTF-8, para pré-visualização na tela ou impressão pelo navegador |
PDF_80 | PDF 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âmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Colunas por linha | colunas(int) | Não | Caracteres 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ódigo | paginaCodigo(String) | Não | Pá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 Code | modoQrCode(OpcoesCupom.ModoQrCode) | Não | Forma 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 Code | tamanhoModuloQr(int) | Não | Pontos por módulo do QR Code. De 1 a 16; sem configuração ou com 0, vale 4 |
| Corte do papel | cortar(boolean) | Não | Corte do papel. Padrão true, corta depois de imprimir |
| Vias | vias(int) | Não | Nú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 erro | Situação | Ação |
|---|---|---|
| 10029819 | A nota não existe neste computador | Confira o id |
| 10029874 | Valor de formato inválido, ou parâmetros de impressão fora da faixa | Use os valores da tabela acima |
Também pode devolver os erros gerais.
Exemplos
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 Windowsbyte[] 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
public byte[] qrCodePng(String id, int tamanhoPx, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Identificador da nota | id | Sim | O id da requisição de emissão |
| Lado da imagem | tamanhoPx | Não | Lado da imagem em pixels. De 64 a 2048, informe explicitamente |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa 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 erro | Situação | Ação |
|---|---|---|
| 10029819 | A nota não existe neste computador | Confira o id |
| 10029817 | Lado da imagem fora de 64 a 2048 | Corrija o lado da imagem |
Também pode devolver os erros gerais.
Exemplos
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
public byte[] xmlAutorizado(String id, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Identificador da nota | id | Sim | O id da requisição de emissão |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa 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 erro | Situação | Ação |
|---|---|---|
| 10029841 | XML autorizado indisponível: ainda não autorizada, ou não está no computador e não foi possível buscar na plataforma | Se 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 |
| 10029819 | A nota não existe neste computador | Confira o id |
Também pode devolver os erros gerais.
Exemplos
// Pode buscar na plataforma; use uma thread de segundo planoCompletableFuture.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
public byte[] xmlCancelamento(String id, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Identificador da nota | id | Sim | O id da requisição de emissão |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa 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 erro | Situação | Ação |
|---|---|---|
| 10029843 | XML de cancelamento indisponível: a nota não foi cancelada, ou não está no computador e não foi possível buscar na plataforma | Se 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 |
| 10029819 | A nota não existe neste computador | Confira o id |
Também pode devolver os erros gerais.
Exemplos
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
Falhasdo 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 emFalhas. - 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
somenteLocaligual atrue, não há nenhum acesso à rede; só os XML já presentes no computador são gravados, e as notas faltantes entram emFalhas.
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
public Resultados.ExportacaoXml exportarXmls(LocalDate de, LocalDate ate, Path diretorio, String empresaId);public Resultados.ExportacaoXml exportarXmls(LocalDate de, LocalDate ate, Path diretorio, boolean somenteLocal,String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Data inicial | de | Sim | Início do período pela data de emissão. Inclui o dia |
| Data final | ate | Sim | Fim do período pela data de emissão. Inclui o dia |
| Diretório de destino | diretorio | Sim | Diretório da exportação. Caminho relativo é convertido em absoluto a partir do diretório atual do PDV |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa emitente. Pode ser omitido quando só uma empresa está pareada; no Java passe null |
| Só do computador | somenteLocal | Não | Indicador 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 erro | Situação | Ação |
|---|---|---|
| 10029874 | Data ausente ou com formato inválido; Detalhes.campo é de ou ate | Corrija a data |
| 10029844 | Diretório sem permissão de gravação | Troque de diretório; confira espaço em disco e permissões |
| 10029801 / 10029802 | Empresa não pareada / várias empresas sem empresaId | Pareie 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
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
public void trocarCertificado(Certificado certificado, String empresaId);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Certificado | certificado | Sim | Novo certificado A1. Formas em Tipos de dados: origem do certificado; o CNPJ deve ser o da empresa da loja |
| Identificador da empresa | empresaId | Obrigatório com várias empresas | Empresa 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 erro | Situação | Ação |
|---|---|---|
| 10029813 | Certificado indisponível: não encontrado, sem chave privada, ou CNPJ diferente da empresa | Confira o repositório de certificados e use o certificado da empresa |
| 10029814 | Certificado vencido | Use um certificado válido |
| 10029874 | Parâmetro de certificado inválido: impressão digital sem 40 dígitos hexadecimais, ou PFX vazio | Corrija o parâmetro do certificado |
| 10029801 / 10029802 | Empresa não pareada / várias empresas sem empresaId | Pareie primeiro; informe empresaId |
Também pode devolver os erros gerais.
Exemplos
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
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ção | Aviso |
|---|---|
Conectado é false | Offline; as notas serão transmitidas quando a rede voltar |
PendentesTransmissao maior que 0 | Quantidade a transmitir; junto com PrazoTransmissaoAte, mostre o prazo de transmissão |
OfflineAte próximo | O tempo offline está acabando; conecte o quanto antes |
CertificadoValidoAte próximo | O certificado está para vencer; depois de renovar, chame TrocarCertificado |
Situacao diferente de Ativo | O dispositivo não emite mais notas novas; fale com o integrador |
UltimoErro preenchido | Motivo da última falha de sincronização; informe ao suporte técnico no diagnóstico |
Avisos não vazio | O 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
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
public void sincronizarAgora();
Parâmetros
Nenhum.
Retorno
Nenhum.
Erros possíveis
Só os erros gerais.
Exemplos
// Só dispara a próxima rodada em segundo plano e retorna na hora; pode chamar direto na thread da interfacenfce.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;
VersaoBancono 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
public Resultados.Backup backup(Path destino, String senha);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Arquivo de backup | destino | Sim | Caminho do arquivo de backup. O arquivo não pode existir; caminho relativo é convertido em absoluto a partir do diretório atual do PDV |
| Senha | senha | Sim | Senha 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 erro | Situação | Ação |
|---|---|---|
| 10029874 | Senha vazia; Detalhes.campo é senha | Informe a senha |
| 10029817 | Senha com menos de 8 caracteres | Use uma senha mais longa |
| 10029844 | O arquivo de destino já existe, ou o diretório não tem permissão de gravação | Troque o nome do arquivo ou o diretório; confira espaço em disco e permissões |
Também pode devolver os erros gerais.
Exemplos
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-), eCopiaAnteriorno 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 devolve10029811e 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
public static Resultados.Restauracao restaurarBackup(Configuracao config, Path origem, String senha);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Configuração | config | Sim | Configuraçã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 backup | origem | Sim | Caminho do arquivo de backup. Caminho relativo é convertido em absoluto a partir do diretório atual do PDV |
| Senha | senha | Sim | Senha 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 erro | Situação | Ação |
|---|---|---|
| 10029846 | Senha errada, ou arquivo de backup alterado, corrompido ou que não é backup deste SDK; os dois casos não são distinguidos | Confira a senha; use outro backup íntegro. A base original não foi alterada |
| 10029842 | Backup gerado por uma versão mais nova do SDK | Atualize o SDK e o runtime para uma versão não inferior à do backup |
| 10029828 | Outro 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 recebe | Chame antes Encerrar na instância que usa este diretório de dados e depois restaure |
| 10029875 | O 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 runtime | Chame Encerrar e restaure por uma conexão nova, antes de Iniciar |
| 10029817 | Senha com menos de 8 caracteres | Informe a senha usada ao gerar o backup |
| 10029874 | Arquivo de backup ou senha vazio; Detalhes.campo é origem ou senha | Complete os parâmetros |
| 10029844 | Falha ao ler ou gravar arquivo | Confira 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
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:
{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.jsonregistra 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}.xmlno 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,Manifestovem vazio eManifestosé 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
public Resultados.ExportacaoPendentes exportarPendentes(Path diretorio);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Diretório de destino | diretorio | Sim | Diretó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 erro | Situação | Ação |
|---|---|---|
| 10029844 | Diretório sem permissão de gravação | Troque de diretório; confira espaço em disco e permissões |
Também pode devolver os erros gerais.
Exemplos
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
public Resultados.TerminalCriado criarTerminal(String nome);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Nome do terminal | nome | Sim | Nome 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 erro | Situação | Ação |
|---|---|---|
| 10029874 | Nome 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 |
| 10029884 | Não está em modo principal | Chame só no principal |
Também pode devolver os erros gerais.
Exemplos
Resultados.TerminalCriado t = principal.criarTerminal("Caixa 2");// O token completo vem só esta vez; configure no caixa 2 na horaSystem.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
public List<Resultados.Terminal> listarTerminais(boolean todos);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Listar todos | todos | Não | Inclui 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 erro | Situação | Ação |
|---|---|---|
| 10029884 | Não está em modo principal | Chame só no principal |
Também pode devolver os erros gerais.
Exemplos
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
public void revogarTerminal(String id);
Parâmetros
| Parâmetro | Java | Obrigatório | Descrição |
|---|---|---|---|
| Identificador do terminal | id | Sim | O id devolvido por CriarTerminal, começa com trm_ |
Retorno
Nenhum.
Erros possíveis
| Código de erro | Situação | Ação |
|---|---|---|
| 10029888 | Terminal não encontrado | Confira o id com ListarTerminais |
| 10029884 | Não está em modo principal | Chame só no principal |
Também pode devolver os erros gerais.
Exemplos
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
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
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 comgetCampos().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.
| Valor | Significado | O que o PDV faz |
|---|---|---|
Autorizada | Autorizada | Imprime o cupom |
ContingenciaPendente | Assinada offline neste computador, aguardando transmissão | Imprime o cupom e entrega ao consumidor; a transmissão é automática |
AguardandoAutorizacao | Aceita online, a SEFAZ ainda não respondeu | Não imprime ainda; aguarda o evento de autorização; se for negada depois, chega NOTA_NEGADA |
Negada | Nota 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 |
Rejeitada | Nota offline rejeitada pela SEFAZ na transmissão (evento NOTA_REJEITADA) | Corrige com o mesmo número usando Substituir; não pode emitir outra |
Recusada | A plataforma recusou esta nota offline | Exige ação manual; fale com a plataforma |
Cancelada | Cancelada | Nada |
Resultado da emissão
Retorno de Emitir e de Substituir. Java ResultadoEmissao.
| Nome JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
id | getId() | Texto | Não | Identificador da nota. O id da requisição de emissão |
status | getStatus() | Texto | Não | Situação da nota. Valores acima |
emitidaEmContingencia | isEmitidaEmContingencia() | Booleano | Não | Indicador de emissão offline. Continua true depois da autorização |
chave | getChave() | Texto | Sim | Chave de acesso. 44 dígitos |
serie | getSerie() (Long) | Inteiro | Sim | Série |
numero | getNumero() (Long) | Inteiro | Sim | Número da nota |
dataEmissao | getDataEmissao() | Data e hora | Sim | Data de emissão |
protocolo | getProtocolo() | Texto | Sim | Protocolo de autorização. null enquanto a nota offline aguarda transmissão |
qrCode | getQrCode() | Texto | Sim | Conteúdo do QR Code. Codifique em QR ao montar o próprio cupom |
urlConsulta | getUrlConsulta() | Texto | Sim | URL de consulta do consumidor |
motivo | getMotivo() | Texto | Sim | Descrição do motivo. Vem da SEFAZ ou da plataforma |
cStat | getCStat() (Long) | Inteiro | Sim | Código de resultado da SEFAZ. null quando não há resultado da SEFAZ |
xMotivo | getXMotivo() | Texto | Sim | Mensagem de resultado da SEFAZ. Vem junto com o código de resultado |
tentativaOnline | isTentativaOnline() | Booleano | Não | Indicador 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 |
respostaPlataforma | getRespostaPlataforma() | Texto | Sim | Texto original da resposta da plataforma. Na emissão online é o JSON devolvido pela plataforma, com a estrutura de Consultar NFC-e; offline é null |
terminal | getTerminal() | Texto | Sim | Identificaçã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 JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
transmitida | isTransmitida() | Booleano | Não | Indicador de transmissão. A nota offline já foi transmitida à plataforma |
cancelamentoPendente | isCancelamentoPendente() | Booleano | Não | Indicador de cancelamento pendente. Há cancelamento agendado ou na fila local |
correcoes | getCorrecoes() (Long) | Inteiro | Não | Quantidade de correções |
atualizadoEm | getAtualizadoEm() | Data e hora | Sim | Última atualização |
xmlAutorizadoDisponivel | isXmlAutorizadoDisponivel() | Booleano | Não | Indicador 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 |
pedido | getPedido() | Texto | Sim | Requisiçã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 JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
itens | getItens() | Lista | Não | Notas da página. Itens são situação consultada, em ordem decrescente de emissão |
pagina | getPagina() | Inteiro | Não | Número da página. Começa em 1 |
tamanhoPagina | getTamanhoPagina() | Inteiro | Não | Notas por página. Fixo em 50 |
temMais | isTemMais() | Booleano | Não | Indicador de próxima página. Não há total |
Resultado da prévia
Retorno de Previsualizar. Java Resultados.PreVisualizacao.
| Nome JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
valido | isValido() | Booleano | Não | Indicador de validação aprovada |
erros | getErros() | Lista de textos | Não | Erros de validação. Já traduzidos conforme o idioma das mensagens; lista vazia quando passa |
pedidoNormalizado | getPedidoNormalizado() | Texto | Sim | Requisição normalizada. Texto JSON, normalmente não usado |
valorTotal | getValorTotal() (BigDecimal) | Decimal | Sim | Total da nota |
valorTributos | getValorTributos() (BigDecimal) | Decimal | Sim | Total de tributos |
Resultado do cancelamento
Retorno de Cancelar e de CancelarPorSubstituicao. Java Resultados.Cancelamento.
| Nome JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
situacao | getSituacao() | Texto | Não | Destino do pedido. Valores abaixo |
motivo | getMotivo() | Texto | Sim | Descrição |
situacao | Significado |
|---|---|
Solicitado | Nota autorizada, cancelamento enviado à plataforma; o resultado chega pelos eventos CANCELAMENTO_CONCLUIDO ou CANCELAMENTO_REJEITADO |
Agendado | Nota offline transmitida e ainda não autorizada; a plataforma agenda o cancelamento e o dispara depois da autorização |
EnfileiradoLocal | Fila 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 JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
ambiente | getAmbiente() (Long) | Inteiro | Não | Ambiente de emissão. 1 produção, 2 homologação |
formasPermitidas | getFormasPermitidas() (Long) | Inteiro | Não | Formas permitidas. 0 qualquer forma, 1 só o Assistente Fiscal, 2 só o SDK embarcado |
expiraEm | getExpiraEm() | Data e hora | Não | Vencimento do código de pareamento |
plataforma | getPlataforma() | Texto | Não | Endereço da plataforma. Plataforma para a qual o código aponta |
serie | getSerie() (Long) | Inteiro | Sim | Sé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 |
numeroInicial | getNumeroInicial() (Long) | Inteiro | Sim | Nú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 JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
empresaId | getEmpresaId() | Texto | Não | Identificador da empresa. O empresaId dos demais métodos |
dispositivoId | getDispositivoId() | Texto | Não | Identificador do dispositivo |
cnpj | getCnpj() | Texto | Não | CNPJ da empresa |
uf | via getCampos() | Texto | Não | Estado |
ambiente | via getCampos() | Inteiro | Não | Ambiente de emissão. 1 produção, 2 homologação |
serieOffline | getSerieOffline() (Long) | Inteiro | Não | Série do dispositivo. Exclusiva deste dispositivo, compartilhada pelas notas online e offline com numeração contínua; o nome do campo foi mantido |
licencaExpiraEm | getLicencaExpiraEm() | Data e hora | Sim | Vencimento da licença |
numeroInicial | getNumeroInicial() (Long) | Inteiro | Não | Nú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 JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
empresaId | getEmpresaId() | Texto | Não | Identificador da empresa |
dispositivoId | getDispositivoId() | Texto | Não | Identificador do dispositivo |
cnpj | getCnpj() | Texto | Não | CNPJ da empresa |
uf | via getCampos() | Texto | Não | Estado |
ambiente | via getCampos() | Inteiro | Não | Ambiente de emissão. 1 produção, 2 homologação |
serieOffline | via getCampos() | Inteiro | Não | Série do dispositivo |
situacao | getSituacao() | Texto | Não | Situação do dispositivo. Valores abaixo |
situacao | Significado | Ação |
|---|---|---|
Ativo | Pode emitir | Nada |
Desativado | O integrador desativou o dispositivo | Não volta; para continuar usando o mesmo computador, pareie de novo |
Revogado | A plataforma revogou o dispositivo | Fale com a plataforma |
EmpresaDesativada | Emissão offline da empresa desativada | Fale com a plataforma |
AplicativoBloqueado | Software do PDV bloqueado pela plataforma | Fale com a plataforma |
VersaoBloqueada | A versão do PDV foi bloqueada ou está abaixo da mínima | Atualize 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 JSON | Java | Tipo | Descrição |
|---|---|---|---|
versaoNucleo | getVersaoNucleo() | Texto | Versão do núcleo |
empresas | getEmpresas() (itens são mapas) | Lista | Situação de cada empresa pareada, campos abaixo |
avisos | getAvisos() | Lista de texto | Avisos 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 JSON | Tipo | Nulo | Descrição |
|---|---|---|---|
empresaId | Texto | Não | Identificador da empresa |
dispositivoId | Texto | Não | Identificador do dispositivo |
situacao | Texto | Não | Situação do dispositivo. Valores iguais aos de empresa pareada |
conectado | Booleano | Não | Indicador de conexão. Se agora consegue falar com a plataforma |
ultimoContato | Data e hora | Sim | Último contato |
licencaExpiraEm | Data e hora | Sim | Vencimento da licença |
offlineAte | Data e hora | Sim | Prazo da emissão offline. O que vier primeiro entre o vencimento da licença e o do certificado |
pendentesTransmissao | Inteiro | Não | Notas a transmitir |
pendenteMaisAntigaEm | Data e hora | Sim | Pendente mais antiga. Data de emissão da nota mais antiga a transmitir |
prazoTransmissaoAte | Data e hora | Sim | Prazo de transmissão. Prazo da nota mais antiga a transmitir; depois dele o dispositivo não emite mais offline |
certificadoValidoAte | Data e hora | Sim | Vencimento do certificado |
ultimoErro | Texto | Sim | Último erro. Motivo da última falha de sincronização |
numerosNaoUtilizadosPendentes | Inteiro | Não | Faixas 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 |
restauradoPendenteSincronizacao | Booleano | Não | Restauraçã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 JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
quantidadeNotas | getQuantidadeNotas() | Inteiro | Não | Notas exportadas. Número de notas com pelo menos um arquivo gravado |
quantidadeArquivos | getQuantidadeArquivos() | Inteiro | Não | Quantidade de arquivos. Total de arquivos de XML autorizado e de cancelamento gravados; uma nota cancelada com os dois XML gravados conta como dois |
arquivos | getArquivos() | Lista de texto | Não | Arquivos exportados. Caminhos absolutos dos arquivos gravados, um arquivo para o XML autorizado e outro para o de cancelamento |
falhas | getFalhas() (itens são mapas) | Lista | Não | Lista 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 JSON | Chave no Java | Tipo | Descrição |
|---|---|---|---|
id | id | Texto | Identificador da nota |
chave | chave | Texto | Chave de acesso |
motivo | motivo | Texto | Motivo da falta. Inclui se foi apagado ao fim da retenção |
Resultado do backup
Retorno de Backup. Java Resultados.Backup.
| Nome JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
arquivo | getArquivo() | Texto | Não | Arquivo de backup. Caminho absoluto |
bytes | getBytes() | Inteiro | Não | Tamanho do arquivo. Em bytes |
versaoBanco | getVersaoBanco() | Inteiro | Não | Versão da estrutura da base local. Na restauração, a versão do núcleo não pode ser inferior a ela |
sha256 | getSha256() | Texto | Não | Resumo do arquivo. SHA-256 do arquivo de backup criptografado, em hexadecimal minúsculo |
Resultado da restauração
Retorno de RestaurarBackup. Java Resultados.Restauracao.
| Nome JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
versaoBanco | getVersaoBanco() | Inteiro | Não | Versão da estrutura da base local. Versão da base restaurada; se for inferior à do SDK atual, é atualizada automaticamente na próxima partida |
copiaAnterior | getCopiaAnterior() | Texto | Sim | Có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 JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
quantidade | getQuantidade() | Inteiro | Não | Notas exportadas |
manifesto | getManifesto() | Texto | Sim | Primeiro manifesto. Caminho absoluto do manifesto.json do primeiro pacote; vazio quando não há notas pendentes |
manifestos | getManifestos() | Lista de texto | Não | Todos 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 |
arquivos | getArquivos() | Lista de texto | Não | Arquivos XML assinados. Caminhos absolutos |
Origem do certificado
Parâmetro de certificado de Ativar e TrocarCertificado.
| Origem | Java |
|---|---|
| Certificado já presente no repositório de certificados do Windows | Certificado.doRepositorio(thumbprint, maquinaLocal) |
| Arquivo PFX | Certificado.deArquivoPfx(bytes, senha) |
| Parâmetro | Descrição |
|---|---|
thumbprint | Impressão digital do certificado. SHA-1 com 40 dígitos hexadecimais, espaços são ignorados; formato errado devolve 10029874 |
maquinaLocal | Indicador 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 senha | Certificado 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:
- Confirme na situação que
pendentesTransmissaode cada empresa é 0, ou seja, todas as notas offline foram transmitidas - Desative ou revogue o dispositivo no console; se for só troca de certificado, instale antes o novo com TrocarCertificado
- Com o mesmo usuário Windows, abra
certmgr.msce apague o certificado antigo em "Pessoal > Certificados" pela impressão digital, ou execute no PowerShellRemove-Item Cert:\CurrentUser\My\<impressão digital>
Terminal secundário
Retorno de CriarTerminal. Java Resultados.TerminalCriado.
| Nome JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
id | getId() | Texto | Não | Identificador do terminal. Começa com trm_, usado para revogar |
nome | getNome() | Texto | Não | Nome do terminal. A identificação do caixa nas notas que esse secundário emite |
token | getToken() | Texto | Não | Token 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 JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
id | getId() | Texto | Não | Identificador do terminal |
nome | getNome() | Texto | Não | Nome do terminal |
situacao | getSituacao() | Texto | Não | Situação do terminal. Ativo ou Revogado |
criadoEm | getCriadoEm() | Data e hora | Não | Momento da emissão do token |
ultimoUsoEm | getUltimoUsoEm() | Data e hora | Sim | Último uso. null se nunca foi usado |
revogadoEm | getRevogadoEm() | Data e hora | Sim | Momento da revogação. null em terminal ativo |
Exceção
Toda falha lança uma exceção.
| Campo | Java TfFiscalException | Descrição |
|---|---|---|
| Código de erro | getCodigo() | Inteiro. Decida por ele; veja Códigos de erro |
| Constante de erro | getTipo() | Por exemplo ENGINE_LICENSE_EXPIRED; erros da plataforma trazem a constante da plataforma |
| Descrição | getMessage() | Traduzida conforme o idioma das mensagens configurado, pronta para mostrar |
| Informações adicionais | getDetalhes(), 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 assinar | Thread do callback |
|---|---|
aoReceberEvento(Consumer<EventoNfce>) na configuração, ou o método de instância aoReceberEvento, cujo retorno cancela a assinatura ao ser fechado | No 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
EventoIdeSeqiguais. - 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_FALHOUeRUNTIME_REINICIADOsão gerados pelo próprio SDK, têmSeq0, não precisam de confirmação e não são reenviados.
Campos comuns
| Nome JSON | Java | Tipo | Nulo | Descrição |
|---|---|---|---|---|
eventoId | getEventoId() | Texto | Não | Identificador do evento. Chave de deduplicação, igual nos reenvios |
seq | getSeq() (long) | Inteiro | Não | Sequência local. Crescente; 0 nos eventos locais do SDK |
tipo | getTipo() | Texto | Não | Tipo do evento. Veja as seções abaixo |
ocorridoEm | getOcorridoEm() | Texto de data e hora | Não | Momento do evento. ISO 8601 UTC |
empresaId | getEmpresaId() | Texto | Sim | Identificador da empresa. null nos eventos locais do SDK |
dispositivoId | via getCampos() | Texto | Sim | Identificador do dispositivo |
id | getId() | Texto | Sim | Identificador da nota. Só nos eventos de nota |
chave | getChave() | Texto | Sim | Chave de acesso. Só nos eventos de nota |
status | getStatus() | Texto | Sim | Situação atual da nota. Só nos eventos de nota; valores em Situação da nota |
dados | getDados() (Map<String, Object>) | Objeto | Não | Dados do evento. Campos nas seções abaixo |
NOTA_EMITIDA_OFFLINE
Assinatura offline concluída. Evento de nota, com status ContingenciaPendente.
Campo de dados | Tipo | Descrição |
|---|---|---|
serie | Inteiro | Série do dispositivo |
numero | Inteiro | Número da nota |
qrCode | Texto | Conteúdo do QR Code |
tentativaOnline | Booleano | Indicador 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 dados | Tipo | Descrição |
|---|---|---|
protocolo | Texto | Protocolo de autorização |
dataAutorizacao | Texto de data e hora, pode ser nulo | Data da autorização |
foraDoPrazo | Booleano | Indicador de entrega fora do prazo. true quando chegou à SEFAZ depois de 24 horas; a nota continua válida |
aposCorrecao | Booleano | Indicador 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 dados | Tipo | Descrição |
|---|---|---|
cStat | Inteiro | Código de resultado da SEFAZ |
motivo | Texto | Mensagem 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 dados | Tipo | Descrição |
|---|---|---|
cStat | Inteiro | Código de resultado da SEFAZ |
motivo | Texto | Mensagem de resultado da SEFAZ |
numeroLiberado | Booleano | Nú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 dados | Tipo | Descrição |
|---|---|---|
codigo | Inteiro, pode ser nulo | Código de erro da plataforma |
mensagem | Texto | Descriçã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 dados | Tipo | Descrição |
|---|---|---|
cStat | Inteiro, pode ser nulo | Código de resultado da SEFAZ |
motivo | Texto | Descrição do resultado |
protocolo | Texto, pode ser nulo | Protocolo 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 dados | Tipo | Descrição |
|---|---|---|
cStat | Inteiro, pode ser nulo | Código de resultado da SEFAZ |
motivo | Texto | Motivo da recusa |
protocolo | Texto, pode ser nulo | Protocolo |
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 dados | Tipo | Descrição |
|---|---|---|
serie | Inteiro | Série do dispositivo |
inicio | Inteiro | Número inicial |
fim | Inteiro | Nú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 dados | Tipo | Descrição |
|---|---|---|
serie | Inteiro | Série do dispositivo |
inicio | Inteiro | Número inicial |
fim | Inteiro | Número final |
codigo | Inteiro | Código de erro da plataforma |
mensagem | Texto | Mensagem da plataforma |
definitivo | Booleano | Indicador 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 dados | Tipo | Descrição |
|---|---|---|
situacao | Texto | Situação do dispositivo. Valores em Empresa pareada |
motivo | Texto | Motivo. 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 dados | Tipo | Descrição |
|---|---|---|
expiraEm | Texto de data e hora | Vencimento da licença |
offlineAte | Texto de data e hora | Prazo 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 dados | Tipo | Descrição |
|---|---|---|
expiradaEm | Texto de data e hora | Momento 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 dados | Tipo | Descrição |
|---|---|---|
pendenteMaisAntigaEm | Texto de data e hora | Data de emissão da nota mais antiga a transmitir |
prazoAte | Texto de data e hora | Prazo 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 dados | Tipo | Descrição |
|---|---|---|
validoAte | Texto de data e hora | Vencimento 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 dados | Tipo | Descrição |
|---|---|---|
conectado | Booleano | Indicador 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 dados | Tipo | Descrição |
|---|---|---|
pendentesTransmissao | Inteiro | Notas a transmitir |
eventosNaoEntregues | Inteiro | Eventos 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 dados | Tipo | Descrição |
|---|---|---|
codigoSaida | Inteiro | Código de saída do processo |
tentativa | Inteiro | Número de tentativas de reinício |
proximaTentativaMs | Inteiro | Milissegundos 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 dados | Tipo | Descrição |
|---|---|---|
tentativa | Inteiro | Nú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:
| Campo | No SDK |
|---|---|
modoResposta | Não precisa enviar. O SDK sempre espera o resultado; se enviar, é ignorado |
ambienteEmissao | Mantenha igual ao ambiente do dispositivo. O ambiente do dispositivo é definido pelo código de pareamento; veja Gerar código de pareamento |
itens[].classeImposto | Disponí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:
{"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 erro | Constante | Cenário | Ação |
|---|---|---|---|
| 10029800 | ENGINE_NOT_STARTED | Não inicializado | No uso normal não acontece; se acontecer, há defeito no pacote do SDK; inicialize de novo |
| 10029801 | ENGINE_NOT_ACTIVATED | Empresa não pareada neste computador, ou nenhuma empresa pareada ainda | Conduza o pareamento; com várias empresas, confira empresaId |
| 10029802 | ENGINE_EMPRESA_REQUIRED | Várias empresas pareadas, mas empresaId não informado | Informe empresaId |
| 10029803 | ENGINE_LICENSE_MISSING | Não há licença para emissão offline | Sincronize uma vez com rede (SincronizarAgora) |
| 10029804 | ENGINE_LICENSE_EXPIRED | Licença vencida; a emissão offline é recusada e a online segue normal | Restaure a rede; a renovação é automática |
| 10029805 | ENGINE_LICENSE_SIGNATURE_INVALID | Assinatura da licença inválida | Ação manual: fale com a plataforma, a base local pode ter sido adulterada |
| 10029806 | ENGINE_LICENSE_NOT_FOR_DEVICE | A licença não pertence a este dispositivo | Ação manual: pareie de novo |
| 10029807 | ENGINE_OFFLINE_WINDOW_CLOSED | O prazo da emissão offline terminou | Restaure a rede e emita online |
| 10029808 | ENGINE_LICENSE_QUOTA_EXHAUSTED | A série do dispositivo chegou ao número 999999999 | Desative 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 |
| 10029809 | ENGINE_CLOCK_ROLLBACK | O relógio do sistema foi atrasado | Ação manual: corrija a hora do sistema |
| 10029810 | ENGINE_TRANSMISSION_DEADLINE_REACHED | A nota pendente mais antiga passou do prazo de transmissão | Ação manual: restaure a rede e transmita o quanto antes |
| 10029811 | ENGINE_OFFLINE_NOT_ALLOWED | A 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ça | Só é possível emitir online; depois de restaurar, a emissão offline volta sozinha após uma sincronização com a plataforma |
| 10029812 | ENGINE_OFFLINE_FUEL_NOT_SUPPORTED | Nota com combustível não pode ser emitida offline | Emita quando a rede voltar |
| 10029813 | ENGINE_CERTIFICATE_UNAVAILABLE | Certificado não encontrado, sem chave privada ou com CNPJ divergente | Ação manual: confira o repositório de certificados; se preciso, TrocarCertificado |
| 10029814 | ENGINE_CERTIFICATE_EXPIRED | Certificado vencido | Ação manual: renove e chame TrocarCertificado |
| 10029815 | ENGINE_SNAPSHOT_MISSING | Configuração local ou dados fiscais ausentes ou com falha de verificação | Sincronize com rede; se persistir, fale com a plataforma |
| 10029816 | ENGINE_DEVICE_DEACTIVATED | Dispositivo desativado | Ação manual: fale com o integrador; as notas offline já emitidas seguem sendo transmitidas |
| 10029817 | ENGINE_REQUEST_INVALID | Falha na validação da requisição; Detalhes lista os motivos campo a campo | Corrija a requisição; dá para validar antes com Previsualizar |
| 10029780 | ENGINE_TAX_CLASS_REQUIRES_ONLINE | Linha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumido | Reenvie com o mesmo id quando a rede voltar; sem rede, envie impostos nas linhas de item |
| 10029818 | ENGINE_DUPLICATE_ID_DIFFERENT_CONTENT | O mesmo id já foi usado em nota de conteúdo diferente | Venda nova com id novo; para repetir, use a requisição original e recupere a nota original |
| 10029819 | ENGINE_NOTE_NOT_FOUND | A nota não existe neste computador | Confira id e empresaId |
| 10029820 | ENGINE_NOTE_NOT_CORRECTABLE | A situação atual não permite correção | Só Rejeitada pode usar Substituir |
| 10029821 | ENGINE_CORRECTION_CHANGES_TOTALS | A correção alterou valores ou tributos | Altere só o que não envolve valores |
| 10029822 | ENGINE_CANCEL_NOT_ALLOWED | A situação atual não permite cancelar | Não tente de novo |
| 10029823 | ENGINE_SERIE_EXHAUSTED | Numeração da série do dispositivo esgotada | Desative 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 |
| 10029824 | ENGINE_PLATFORM_UNREACHABLE | Operação que exige rede (pareamento) sem conexão com a plataforma | Confira a rede e tente de novo |
| 10029825 | ENGINE_ACTIVATION_CODE_INVALID | Formato, assinatura ou validade do código de pareamento incorretos | Ação manual: gere outro código de pareamento |
| 10029826 | ENGINE_ACTIVATION_HOST_UNTRUSTED | O código de pareamento aponta para um endereço de plataforma não confiável | Ação manual: confirme a origem do código e o ambiente do instalador (homologação / produção) |
| 10029827 | ENGINE_KEY_PROTECTION_FAILED | O diretório de dados veio de outro computador ou de outro usuário do Windows | Ação manual: rode no computador e com o usuário originais, ou pareie de novo |
| 10029828 | ENGINE_DATA_DIR_LOCKED | Diretó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 Encerrar | Feche a outra instância; antes de restaurar um backup, chame Encerrar |
| 10029829 | ENGINE_LOCAL_STORE_CORRUPTED | Base local inconsistente | Ação manual: não apague o diretório de dados, fale com a plataforma |
| 10029830 | ENGINE_PROTOCOL_VERSION_UNSUPPORTED | Versões do SDK e do runtime incompatíveis | Atualize SDK e runtime juntos |
| 10029831 | ENGINE_RUNTIME_START_FAILED | O runtime não iniciou | Confira se o diretório do runtime está completo e se o antivírus está bloqueando |
| 10029832 | ENGINE_RUNTIME_CRASHED | O runtime saiu inesperadamente | Pode tentar de novo; com reinício automático o SDK se recupera sozinho; reenvie a emissão com o mesmo id |
| 10029833 | ENGINE_TIMEOUT | Tempo de espera esgotado | Reenvie a emissão com o mesmo id, ou faça Consultar antes |
| 10029834 | ENGINE_SHUTTING_DOWN | Encerrando ou já encerrado | Chame Iniciar de novo |
| 10029835 | ENGINE_IN_PROCESS_UNSUPPORTED | O modo em processo do Java exige Java 21 ou superior | Use o modo subprocesso |
| 10029836 | ENGINE_INTERNAL_ERROR | Erro interno do núcleo; a descrição traz um número de referência | Fale com a plataforma informando o número de referência e o log |
| 10029837 | ENGINE_ALREADY_ACTIVATED | Empresa já pareada neste diretório de dados | Não precisa parear de novo; para trocar de dispositivo, desative o antigo antes |
| 10029838 | ENGINE_PLATFORM_RESPONSE_UNTRUSTED | Falha na verificação da resposta da plataforma; os dados anteriores foram mantidos | Nova tentativa automática depois; se persistir, verifique se um proxy de rede alterou a resposta |
| 10029839 | ENGINE_ACTIVATION_PERSIST_FAILED | Pareada na plataforma, mas a gravação local falhou | Pareie de novo com o mesmo código de pareamento |
| 10029840 | ENGINE_CONFIG_INVALID | Configuração de inicialização inválida | Corrija a configuração |
| 10029841 | ENGINE_AUTHORIZED_XML_UNAVAILABLE | XML autorizado indisponível: ainda não autorizada, ou não está no computador e não foi possível buscar na plataforma | Se 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 |
| 10029842 | ENGINE_LOCAL_STORE_NEWER_VERSION | Base 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 é recusada | Atualize o SDK e o runtime para uma versão não inferior à última usada; nunca apague o diretório de dados |
| 10029843 | ENGINE_CANCEL_XML_UNAVAILABLE | XML de cancelamento indisponível: a nota não foi cancelada, ou não está no computador e não foi possível buscar na plataforma | Se ainda não cancelada, aguarde CANCELAMENTO_CONCLUIDO e leia depois; se já cancelada, tente mais tarde |
| 10029844 | ENGINE_EXPORT_FAILED | Falha ao gravar arquivo: destino da exportação ou do backup sem permissão de gravação, ou arquivo de backup já existente | Troque de diretório ou de nome; confira espaço em disco e permissões |
| 10029845 | ENGINE_SUBSTITUTE_KEY_INVALID | Chave da nota substituta do cancelamento por substituição inválida, ou não é nota offline deste computador e desta empresa não recusada | Informe a chave de acesso de 44 dígitos da nota offline emitida neste computador para a mesma venda |
| 10029846 | ENGINE_BACKUP_INVALID | O backup não pode ser restaurado: senha errada, ou o arquivo de backup foi alterado, está corrompido ou não é backup deste SDK | Confira a senha; use outro backup íntegro. A base original não foi alterada |
| 10029870 | ENGINE_PROTOCOL_INVALID_JSON | A mensagem recebida pelo runtime não é JSON válido | Defeito no pacote do SDK; atualize o SDK |
| 10029871 | ENGINE_PROTOCOL_LINE_TOO_LONG | Mensagem acima de 8 MB | Requisição grande demais; divida os itens |
| 10029872 | ENGINE_PROTOCOL_MESSAGE_INVALID | Estrutura da mensagem inválida | Defeito no pacote do SDK; atualize o SDK |
| 10029873 | ENGINE_METHOD_UNKNOWN | O runtime não reconhece o método | O SDK é mais novo que o runtime; atualize o runtime |
| 10029874 | ENGINE_PARAMS_INVALID | Parâmetro ausente ou de tipo errado; Detalhes.campo indica o parâmetro | Corrija o parâmetro, por exemplo requisição que não é objeto JSON, formato da impressão digital do certificado ou formato de data |
| 10029875 | ENGINE_ALREADY_STARTED | Inicialização repetida, ou o método de protocolo de restauração de backup chamado numa conexão com o runtime que já executou Iniciar | No 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 |
| 10029876 | ENGINE_REQUEST_ID_DUPLICATED | A mesma chamada ainda está em processamento | Defeito no pacote do SDK; atualize o SDK |
| 10029877 | ENGINE_RUNTIME_NOT_FOUND | Runtime não encontrado | Confira o instalador e o diretório do runtime |
| 10029878 | ENGINE_TOO_MANY_PENDING | Mais de 64 chamadas aguardando ao mesmo tempo | Reduza a concorrência |
| 10029879 | ENGINE_RESPONSE_TOO_LARGE | Resposta acima do limite | Fale com a plataforma |
| 10029880 | ENGINE_PRINCIPAL_UNREACHABLE | O secundário não alcança o principal; o pedido não chegou | Tente depois, ou passe o caixa para a máquina reserva |
| 10029881 | ENGINE_PRINCIPAL_RESULT_UNKNOWN | O pedido chegou ao principal, mas a resposta não voltou; resultado desconhecido | Com o principal de volta, chame Consultar com o mesmo id; reenviar Emitir com o mesmo id e conteúdo não emite duas vezes |
| 10029882 | ENGINE_TERMINAL_TOKEN_INVALID | Token do terminal secundário inválido ou revogado | Chame CriarTerminal de novo no principal e atualize TokenTerminal do secundário |
| 10029883 | ENGINE_PRINCIPAL_ADDRESS_INVALID | Endereço do principal mal formatado ou fora da rede local privada | Corrija EnderecoPrincipal |
| 10029884 | ENGINE_MODE_METHOD_UNAVAILABLE | O modo atual não oferece esse método | Pareamento, troca de certificado, backup e exportação são feitos no principal; gestão de terminais só no principal |
| 10029885 | ENGINE_PRINCIPAL_REJECTED | O principal recusou a origem do pedido, por exemplo um secundário fora das redes permitidas | Confira RedesPermitidas do principal e a rede |
| 10029886 | ENGINE_PRINCIPAL_RATE_LIMITED | Falhas de autenticação demais; limitado pelo principal | Confira o token e tente após 1 minuto |
| 10029887 | ENGINE_PRINCIPAL_LISTEN_FAILED | Não foi possível escutar na porta de rede local do principal | Troque PortaPrincipal ou libere a porta |
| 10029888 | ENGINE_TERMINAL_NOT_FOUND | O terminal a revogar não existe | Confira o id do terminal com ListarTerminais |
Todos os códigos, inclusive os do Assistente Fiscal, estão em Códigos de erro.
