NFC-e offline
Tutorial do SDK embarcado
Primeiros passos do SDK embarcado: gerar o código de pareamento, adicionar o SDK, inicialização e pareamento, emitir a primeira nota, imprimir o cupom, receber os resultados, o comportamento sem rede e o checklist antes da produção, com exemplos completos em Java.
Esta página mostra como integrar o SDK embarcado no seu PDV: com rede, o SDK pega um número da série do dispositivo, assina a nota e a autoriza online pela plataforma; sem rede, a nota de contingência offline é emitida no próprio computador e impressa na hora, e a transmissão acontece sozinha quando a rede volta. Ao terminar, você terá pareado um caixa, emitido e impresso a primeira nota e recebido os resultados da transmissão e do cancelamento. Pré-requisitos: poder chamar a API aberta da plataforma para gerar o código de pareamento e um PDV que roda no Windows; a requisição de emissão é a mesma do endpoint de emissão na nuvem, e linhas de item que referenciam classe de imposto exigem conexão.
Você só fala com o SDK, que roda o núcleo de emissão offline em segundo plano. A integração inteira fica assim:
Preparar: gerar o código de pareamento, incluir o SDK, distribuir o runtime│▼Iniciar ──► Não pareado? ──► Ativar (só na primeira vez, com internet)│▼Emitir ──► Tratar pelo status ──► Imprimir o cupom│└─ Em segundo plano: sem rede emite offline, com rede transmite sozinho, resultados chegam como eventosRotina: cancelar e consultar, obter o XML autorizado, cancelamento por substituição, exportação mensal de XML, backup e recuperação de computador com defeito
Cada passo traz o código em Java. A descrição completa de métodos e tipos está na Referência do SDK; termos como série do dispositivo, nota de contingência offline e transmissão estão em Números e série.
1 Preparação
1.1 Gerar o código de pareamento
Cada caixa é pareado uma vez; o integrador gera o código chamando a plataforma. Este é o endpoint que gera o código de pareamento:
POST /openapi/v2/empresas/{empresaId}/nfce-offline/codigos-ativacao
O corpo pode ser vazio; para dar nome ao caixa e permitir só o pareamento pelo SDK:
{ "nomeDispositivo": "Caixa 01", "formaPermitida": "Sdk" }
A primeira chamada habilita a emissão offline da empresa; não há etapa separada. Campos e erros em Gerar código de pareamento. O codigoAtivacao da resposta (começa com TFA1.) é o código de pareamento:
- O texto completo só vem nesta resposta; entregue-o na hora ao responsável pelo caixa da loja. Vale 72 horas e só pode ser usado uma vez.
- Pode ser entregue como texto ou salvo num arquivo
.tfa(UTF-8, uma linha, com o código inteiro). - Sem
ambiente, vale o ambiente atual da empresa; depois de pareado, o dispositivo emite sempre nesse ambiente.
O PDV não precisa ser cadastrado antes na plataforma: na inicialização ele informa o nome e a versão do software, e a plataforma o reconhece sozinha.
1.2 Adicionar o SDK
O SDK e o runtime são obtidos na aba "Downloads" da página "Emissão offline → Emissão offline" do menu lateral do console: basta estar logado, e a tabela mostra o tamanho e o SHA-256 de cada versão; confira o SHA-256 depois de baixar.
O SDK é distribuído como artefato Maven com.tffiscal:tffiscal-nfce-sdk-java e suporta Java 8 ou superior. Abaixo, a dependência no pom.xml (em version, a versão publicada):
<dependency><groupId>com.tffiscal</groupId><artifactId>tffiscal-nfce-sdk-java</artifactId><version>VERSAO_PUBLICADA</version></dependency>
Os exemplos desta página são os mesmos do projeto de exemplo Java do pacote do SDK (cinco cenários: primeiros passos, sem rede e transmissão, tratamento de eventos, cancelamento, consulta e XML, arquivos e impressão).
1.3 Distribuir o runtime com o instalador
O SDK inicia um processo de runtime em segundo plano, que roda o núcleo de emissão offline. Coloque a pasta tffiscal-runtime inteira no instalador do PDV (cerca de 60 MB), com esta estrutura:
tffiscal-runtime/├── tffiscal-nfce.exe├── app/├── runtime/└── VERSION
Na inicialização, aponte o diretório do runtime para ela; se não for encontrada, volta 10029877. Distribua o SDK e o runtime sempre na mesma versão. Um PDV Java rodando em Java 21 ou superior também pode usar o modo em processo e dispensar o runtime; veja a Referência do SDK.
1.4 Diretório de dados
Um diretório de dados por caixa, por exemplo C:\ProgramData\MinhaLoja\TFFiscal:
- Antes da transmissão, o arquivo assinado da nota offline só existe aqui e é o único original legal. Não apague ao desinstalar ou atualizar o PDV.
- A chave do dispositivo é cifrada para o usuário do Windows atual: rode o PDV sempre com o mesmo usuário; o diretório não funciona copiado para outro computador ou outro usuário (
10029827). - Só um processo por vez abre o diretório (
10029828). Se o computador tiver dois PDVs, use dois diretórios e pareie dois dispositivos. - Um diretório pode parear várias empresas (vários CNPJ). Com uma só, o
empresaIddos métodos pode ser omitido; com várias, é obrigatório. - O XML autorizado e o XML de cancelamento são baixados para cá automaticamente depois da autorização; o número de dias de retenção vem da configuração
RetencaoXmlDias(veja 2.2). Os vencidos são apagados sozinhos e, ao ler de novo, são buscados automaticamente na plataforma. - Faça backup periódico com
Backup; se o computador quebrar antes da transmissão, exporte comExportarPendentese entregue à plataforma, veja Backup e recuperação de computador com defeito.
2 Inicialização e pareamento
Inicialize uma vez quando o PDV abrir e use a mesma instância durante toda a execução; na primeira execução no computador, pareie também uma vez.
2.1 Inicialização e pareamento
A inicialização exige o nome e a versão do PDV: com isso a plataforma reconhece o seu software sozinha e pode controlar versões; se faltarem, volta 10029874.
Na primeira execução no computador, Ativado é false: pareie com o código de pareamento e o certificado A1 da empresa.
- Código de pareamento: o caixa cola o texto ou escolhe o arquivo
.tfa. Confira antes comInspecionarCodigoAtivacao, que valida no próprio computador e mostra ambiente e validade para o caixa confirmar, sem rede e sem consumir o código. - Certificado: um certificado já no repositório de certificados do Windows (pela impressão digital), ou um arquivo PFX com senha. Importado o PFX, a chave privada fica não exportável e a senha não é guardada; o certificado fica em "Usuário atual > Pessoal" para uso permanente e, se for apagado, o dispositivo não consegue assinar. Desativação e limpeza em Origem do certificado.
O código abaixo inicia o SDK, registra o tratador de eventos e, se ainda não pareado, confere o código de pareamento e pareia. Se a loja acessa a internet por proxy, ou se for preciso ajustar os dias de retenção do XML, acrescente na mesma configuração os itens de 2.2.
import com.tffiscal.nfce.sdk.Certificado;import com.tffiscal.nfce.sdk.Configuracao;import com.tffiscal.nfce.sdk.EventoNfce;import com.tffiscal.nfce.sdk.Resultados;import com.tffiscal.nfce.sdk.TfFiscalException;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.io.IOException;import java.nio.charset.StandardCharsets;import java.nio.file.Files;import java.nio.file.Path;import java.nio.file.Paths;import java.util.function.Consumer;public final class NfceInicio {private NfceInicio() {}/** Inicia o SDK; o ouvinte é ligado na partida, então eventos acumulados antes não se perdem. */public static TfFiscalNfce iniciar(Consumer<EventoNfce> aoEvento) {Configuracao configuracao = Configuracao.builder().diretorioDados(Paths.get("C:/ProgramData/MinhaLoja/TFFiscal")).diretorioRuntime(Paths.get("C:/Program Files/MinhaLoja/tffiscal-runtime")).nomeAplicativo("Caixa Exemplo").versaoAplicativo("1.0.0").idioma("pt-BR").aoReceberEvento(aoEvento).build();return TfFiscalNfce.iniciar(configuracao);}/** Pareia se ainda não estiver pareado. codigoOuArquivo pode ser o texto do código ou o caminho de um arquivo .tfa; com senhaPfx null usa o certificado do repositório pela impressão digital. */public static boolean ativarSeNecessario(TfFiscalNfce nfce, String codigoOuArquivo, String thumbprintOuPfx, String senhaPfx)throws IOException {if (nfce.isAtivado()) {return true;}Path arquivo = Paths.get(codigoOuArquivo);String codigo = Files.isRegularFile(arquivo)? new String(Files.readAllBytes(arquivo), StandardCharsets.UTF_8): codigoOuArquivo;codigo = codigo.replace("\uFEFF", "").trim();Certificado certificado = senhaPfx == null? Certificado.doRepositorio(thumbprintOuPfx, false): Certificado.deArquivoPfx(Files.readAllBytes(Paths.get(thumbprintOuPfx)), senhaPfx);try {Resultados.CodigoAtivacao info = nfce.inspecionarCodigoAtivacao(codigo);System.out.println("Codigo de pareamento: ambiente " + info.getAmbiente() + ", expira em " + info.getExpiraEm());Resultados.Ativacao a = nfce.ativar(codigo, certificado);System.out.println("Pareado: empresa " + a.getEmpresaId() + ", CNPJ " + a.getCnpj() + ", serie do dispositivo " + a.getSerieOffline());return true;} catch (TfFiscalException e) {int c = e.getCodigo();if (c == 10029824 || c == 10029833 || c == 10029839) {// Pode repetir: confira a rede e tente de novo com o mesmo códigoSystem.out.println("Tente de novo: " + e.getMessage());} else {// Precisa de código novo ou de outro certificado: getMessage() já vem traduzida conforme idioma e pode ser exibidaSystem.out.println("Erro " + c + " " + e.getTipo() + ": " + e.getMessage());}return false;}}}
Se o pareamento ou a partida falhar, trate pelo código de erro:
| Categoria | Código de erro | Tratamento |
|---|---|---|
| Dá para repetir | 10029824 (sem conexão com a plataforma), 10029833 (tempo esgotado) | Confira a rede e tente de novo |
| Dá para repetir | 10029839 (a plataforma pareou mas o computador não gravou) | Pareie de novo com o mesmo código |
| Exige outro código | 10029825, 10029205 a 10029209, 10029219, 10029221 a 10029225 | Peça ao integrador um novo código de pareamento |
| Exige outro certificado | 10029813, 10029814, 10029213, 10029214 | Use um certificado válido da empresa |
| Falha logo na partida | 10029842 (o diretório de dados foi usado por uma versão mais nova do SDK; a base local é mais nova que o programa atual e a partida é recusada) | Basta atualizar o SDK e o runtime para uma versão não inferior à última usada; nunca apague o diretório de dados |
2.2 Proxy e dias de retenção do XML
Proxy de saída: configure quando a rede da loja só sai para a internet por proxy; sem nenhuma configuração, a conexão é direta. Há três formas:
| Forma | Como configurar | Observação |
|---|---|---|
| Direta | Nenhum item de proxy configurado | Forma padrão |
| Proxy manual | Proxy com host:porta, por exemplo 10.0.0.1:3128 | Formato inválido devolve 10029874 |
| Proxy do sistema | UsarProxyDoSistema igual a true | Lê a configuração de proxy do Windows: primeiro a do computador, depois a do navegador do usuário atual do Windows; configurado junto com Proxy, o proxy do sistema prevalece |
- Autenticação no proxy: definida com
proxyAutenticacao(usuario, senha), válida tanto para o proxy manual quanto para o do sistema. A senha só passa ao runtime em memória na partida, não vai para o disco nem para o log; se o PDV guardar a senha, guarde-a cifrada. Autenticação configurada sem endereço de proxy e sem proxy do sistema devolve10029874. - Script de proxy automático não suportado: se o Windows só tiver um script PAC de proxy automático, o SDK conecta direto e registra um aviso no log. Nessa rede, use o proxy manual ou configure um proxy fixo no Windows.
- Parâmetro de partida no modo em processo do Java: no acesso à plataforma por HTTPS, a autenticação Basic do proxy exige que a JVM permita Basic no túnel, e a JVM lê essa configuração 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, acrescente-Djdk.http.auth.tunneling.disabledSchemes=(vazio depois do sinal de igual) aos parâmetros de partida da JVM do software do PDV. O núcleo também tenta esvaziá-la o mais cedo possível ao carregar, mas isso não vale se o software do PDV já usou antes o cliente HTTP embutido da JVM ou se ele mesmo definiu essa propriedade para desativar Basic; nesse caso,Avisosem Situacao traz um aviso e a autenticação do proxy pode falhar. No modo subprocesso do Java o runtime cuida disso sozinho, e não é preciso acrescentar parâmetros.
Dias de retenção do XML: RetencaoXmlDias é o número de dias que o XML autorizado e o XML de cancelamento ficam no computador, de 1 a 3650; sem configuração, 90 dias; fora da faixa devolve 10029874. Os vencidos são apagados sozinhos e, ao ler de novo, são buscados automaticamente na plataforma (veja Obter o XML). Na exportação mensal para o contador, prefira um período dentro da retenção, veja Exportação mensal de XML para o contador.
Abaixo, a configuração de 2.1 recebe o proxy manual, a autenticação no proxy e a retenção do XML por 180 dias:
// Acrescente à cadeia Configuracao.builder() de 2.1: acesso à internet por proxy manual com autenticaçãoConfiguracao configuracao = Configuracao.builder().diretorioDados(Paths.get("C:/ProgramData/MinhaLoja/TFFiscal")).diretorioRuntime(Paths.get("C:/Program Files/MinhaLoja/tffiscal-runtime")).nomeAplicativo("Caixa Exemplo").versaoAplicativo("1.0.0").proxy("10.0.0.1:3128").proxyAutenticacao("caixa01", senhaProxy)// Ou use o proxy do sistema do Windows (prevalece sobre proxy): .usarProxyDoSistema(true)// XML autorizado e de cancelamento retidos por 180 dias no computador.retencaoXmlDias(180).aoReceberEvento(aoEvento).build();
3 Emitir a primeira nota
3.1 Requisição de emissão
O corpo é o mesmo de Emitir NFC-e; a descrição dos campos, as regras de cada estado e outros cenários seguem aquela página. No SDK não precisa enviar modoResposta. Classe de imposto exige conexão: as linhas de item podem referenciar uma classe de imposto com classeImposto, que a plataforma expande antes da emissão no dispositivo; sem rede ou sem acesso à plataforma, devolve 10029780, indicando enviar impostos, sem consumir número, veja Classe de imposto e conexão. Os códigos de tributação precisam combinar com o regime da empresa: no Simples Nacional, CSOSN de três dígitos; no regime normal, CST de dois dígitos. As duas requisições abaixo são iguais a pedido-exemplo.json e pedido-exemplo-regime-normal.json do pacote do SDK.
Simples Nacional: venda presencial, consumidor não identificado, pagamento em dinheiro.
{"id": "EXEMPLO-0001","ambienteEmissao": "Homologacao","pedido": {"presencaConsumidor": "OperacaoPresencial","pagamento": {"formas": [{ "tipo": "Dinheiro", "valor": 50.30 }]}},"itens": [{"cfop": "5102","codigo": "7891000100101","descricao": "ARROZ BRANCO TIPO 1 5KG","ncm": "10063021","quantidade": 2,"unidadeMedida": "UN","valorUnitario": 25.15,"impostos": {"icms": { "situacaoTributaria": "102" },"pis": { "situacaoTributaria": "49" },"cofins": { "situacaoTributaria": "49" }}}]}
Regime normal: a mesma venda, só mudam os códigos de tributação.
{"id": "EXEMPLO-RN-0001","ambienteEmissao": "Homologacao","pedido": {"presencaConsumidor": "OperacaoPresencial","pagamento": {"formas": [{ "tipo": "Dinheiro", "valor": 50.30 }]}},"itens": [{"cfop": "5102","codigo": "7891000100101","descricao": "ARROZ BRANCO TIPO 1 5KG","ncm": "10063021","quantidade": 2,"unidadeMedida": "UN","valorUnitario": 25.15,"impostos": {"icms": { "situacaoTributaria": "00" },"pis": { "situacaoTributaria": "07" },"cofins": { "situacaoTributaria": "07" }}}]}
| Campo | Preenchimento | Descrição |
|---|---|---|
id | Obrigatório | Número da venda no PDV. Até 64 caracteres; é a chave de idempotência: cada venda usa um id novo, e a repetição da mesma venda usa o mesmo id |
ambienteEmissao | Obrigatório | Ambiente de emissão. Igual ao ambiente em que o dispositivo foi pareado |
modoResposta | Não enviar | O SDK sempre espera o resultado |
pedido.presencaConsumidor | Obrigatório | Presença do consumidor. Na loja é OperacaoPresencial |
pedido.pagamento.formas | Obrigatório | Formas de pagamento. tipo e valor de cada uma; a soma precisa cobrir o total da nota |
pedido.pagamento.troco | Opcional | Troco. Quando o dinheiro passa do total; a soma dos pagamentos menos o troco é igual ao total da nota |
cliente | Opcional | Consumidor. Sem identificação, não envie o grupo; com CPF, só tipoPessoa e cpfCnpj; acima do limite de identificação do estado é obrigatório |
itens[].cfop / codigo / descricao / ncm / quantidade / unidadeMedida / valorUnitario | Obrigatório | Dados básicos do item |
itens[].ean / cest / valorDesconto | Opcional | Código de barras, CEST, desconto do item |
itens[].impostos.icms.situacaoTributaria | Obrigatório | Código de tributação do ICMS. No Simples Nacional, por exemplo 102; no regime normal, por exemplo 00 |
itens[].impostos.icms.aliquota | Opcional | Alíquota do ICMS. Percentual |
itens[].impostos.pis / cofins | Obrigatório | Código de PIS / COFINS, por exemplo 49 no Simples Nacional e 07 no regime normal |
itens[].classeImposto | Opcional | Código da classe de imposto. Enviado, cfop e impostos podem ser omitidos; exige conexão e, sem rede, devolve 10029780, quando então se envia impostos |
Todos os campos em Emitir NFC-e.
3.2 Montar a requisição e emitir
O código abaixo lê a requisição do arquivo JSON acima, troca o id e emite; depois decide pelo status se imprime. O seu PDV pode montar o mesmo JSON do jeito que preferir.
import com.tffiscal.nfce.sdk.ResultadoEmissao;import com.tffiscal.nfce.sdk.TfFiscalException;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.io.IOException;import java.nio.charset.StandardCharsets;import java.nio.file.Files;import java.nio.file.Paths;public final class NfceVenda {private NfceVenda() {}/** Lê o arquivo da requisição e troca o id (um id novo por venda). */public static String lerPedido(String arquivo, String id) throws IOException {String json = new String(Files.readAllBytes(Paths.get(arquivo)), StandardCharsets.UTF_8);return json.replaceFirst("\"id\"\\s*:\\s*\"[^\"]*\"", "\"id\": \"" + id + "\"");}/** Emite e trata pelo status; devolve se o cupom pode ser impresso. */public static boolean vender(TfFiscalNfce nfce, String pedidoJson) {try {ResultadoEmissao r = nfce.emitir(pedidoJson);System.out.println("Nota " + r.getId() + ": " + r.getStatus() + " | serie " + r.getSerie() + " n. "+ r.getNumero() + " | chave " + r.getChave() + " | protocolo " + r.getProtocolo());switch (r.getStatus()) {case "Autorizada":case "ContingenciaPendente":// A nota emitida offline é impressa e entregue normalmente; a transmissão é automáticareturn true;case "AguardandoAutorizacao":// Aceita online, mas a SEFAZ ainda não respondeu: não imprima ainda, espere o evento NOTA_AUTORIZADA (autorizada) ou NOTA_NEGADA (negada)return false;default:// Negada: corrija conforme o resultado da SEFAZ e emita de novo com um id novoSystem.out.println("Rejeitada: " + r.getCStat() + " " + r.getXMotivo());return false;}} catch (TfFiscalException e) {// Requisição inválida, condições offline não atendidas etc.: getMessage() já vem traduzida e pode ser exibidaSystem.out.println("Erro " + e.getCodigo() + " " + e.getTipo() + ": " + e.getMessage() + " " + e.getDetalhesJson());return false;}}}
3.3 Situações devolvidas
Status | O que aconteceu | Tela do caixa |
|---|---|---|
Autorizada | Autorizada online | Imprime o cupom e conclui a venda |
ContingenciaPendente | Sem conexão com a plataforma; emitida offline no próprio computador | Imprime e entrega normalmente ao consumidor; o cupom já sai com a marca de contingência; pode mostrar «emissão offline» num canto da tela |
AguardandoAutorizacao | A plataforma aceitou, a SEFAZ ainda não respondeu e naquele momento não dava para assinar offline | Não imprime ainda; mostra «aguardando autorização» e imprime ao receber o evento NOTA_AUTORIZADA. Receber NOTA_NEGADA significa que a SEFAZ negou em definitivo: esta nota não admite correção com o mesmo número; corrija os dados da venda e emita de novo com um id novo |
Negada | Rejeitada pela SEFAZ | Mostra o código e a mensagem de resultado da SEFAZ; corrige e emite de novo com outro id |
| Exceção | Requisição inválida, condições do offline não atendidas etc. | Mostra a mensagem da exceção; veja Erros comuns |
Chamar Emitir de novo com o mesmo id não emite outra nota: devolve a nota original. Depois de tempo esgotado ou queda do programa, reenvie com o mesmo id para recuperar o resultado.
4 Imprimir o cupom
4.1 Imprimir o cupom
Cupom(id, formato) devolve os bytes do cupom; mande para a impressora como estão. A nota offline já vem com a marca de contingência, e o número de vias é configurado pela plataforma. Valores de formato:
| Formato | Significado |
|---|---|
ESCPOS_80 | Comandos ESC/POS para impressora térmica de 80 mm |
ESCPOS_58 | Comandos ESC/POS para impressora térmica de 58 mm |
TEXTO | Texto puro em UTF-8 |
HTML | Página 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; serve para impressoras que não aceitam ESC/POS direto, veja 4.2 |
O código abaixo obtém o cupom ESC/POS e manda para a impressora:
- O exemplo envia os bytes para a porta 9100 de uma impressora térmica de rede.
- Para impressora USB, compartilhe-a no Windows e grave no caminho compartilhado; para impressora serial, grave os mesmos bytes com uma biblioteca de porta serial.
import com.tffiscal.nfce.sdk.FormatoCupom;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.io.IOException;import java.io.OutputStream;import java.net.Socket;public final class NfceImpressao {private NfceImpressao() {}/** Envia o cupom ESC/POS para a impressora de rede. */public static void imprimir(TfFiscalNfce nfce, String id, String ipImpressora) throws IOException {byte[] cupom = nfce.cupom(id, FormatoCupom.ESCPOS_80);try (Socket socket = new Socket(ipImpressora, 9100); OutputStream saida = socket.getOutputStream()) {saida.write(cupom);}}}
4.2 Cupom em PDF, parâmetros de impressão e imagem do QR Code
Cupom em PDF: quando a impressora só tem driver do Windows e não recebe comandos ESC/POS direto, use PDF_80 para obter o PDF de 80 mm e imprima pelo programa de PDF associado no sistema, via driver de impressão. O PDF usa as fontes padrão do próprio leitor, e os acentos do português saem corretos.
Parâmetros de impressão: para adaptar o mesmo formato a impressoras diferentes, use a sobrecarga com parâmetros de impressão cupom(id, formato, OpcoesCupom, empresaId). Itens não definidos usam o padrão; valor fora da faixa devolve 10029874.
| Parâmetro | Valores | Padrão |
|---|---|---|
Colunas | Caracteres por linha. 48, 42 ou 32 | Pelo formato: 48 em 80 mm, 32 em 58 mm |
PaginaCodigo | Página de código da impressora. CP1252, CP860 (comum em impressoras brasileiras), CP850 ou CP437; caracteres que não existem na página de código são impressos sem acento | CP1252 |
ModoQrCode | Forma de imprimir o QR Code. NATIVO: usa o comando de QR Code da própria impressora; IMAGEM: imprime como bitmap, para impressoras sem QR Code nativo | NATIVO |
TamanhoModuloQr | Tamanho do módulo do QR Code. De 1 a 16 pontos | 4 |
Cortar | Corte do papel ao final. true corta, false não corta (impressora sem guilhotina) | true |
Vias | Número de vias. De 1 a 9 | Configurado pela plataforma |
Imagem do QR Code: QrCodePng(id, pixels) devolve um PNG em preto e branco, com margem, de 64 a 2048 pixels, informados explicitamente; fora da faixa devolve 10029817. Use quando o PDV monta o próprio documento (por exemplo um recibo A4).
O código abaixo é igual ao cenário 05 do projeto de exemplo: grava em arquivo o cupom em PDF e a imagem do QR Code e manda para a impressora padrão; depois obtém o cupom ESC/POS com os parâmetros de uma impressora de 58 mm (32 colunas, CP850, QR Code em bitmap, módulo de 6 pontos, duas vias, sem corte).
import com.tffiscal.nfce.sdk.FormatoCupom;import com.tffiscal.nfce.sdk.OpcoesCupom;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.awt.Desktop;import java.io.IOException;import java.nio.file.Files;import java.nio.file.Path;public final class NfceImpressaoArquivos {private NfceImpressaoArquivos() {}/** Grava em arquivo o cupom PDF de 80 mm e o PNG do QR Code e manda para a impressora padrão. */public static void pdfEQrCode(TfFiscalNfce nfce, String id, Path pasta) throws IOException {Path pdf = pasta.resolve(id + ".pdf");Files.write(pdf, nfce.cupom(id, FormatoCupom.PDF_80, null, null));Path png = pasta.resolve(id + "-qrcode.png");Files.write(png, nfce.qrCodePng(id, 300, null));// O PDF é impresso na impressora padrão pelo programa de PDF associado no sistema (via driver de impressão)if (Desktop.isDesktopSupported() && Desktop.getDesktop().isSupported(Desktop.Action.PRINT)) {Desktop.getDesktop().print(pdf.toFile());}}/** Impressora de 58 mm: 32 colunas, CP850, QR Code em bitmap, módulo de 6 pontos, duas vias, sem corte. */public static byte[] cupom58mm(TfFiscalNfce nfce, String id) {OpcoesCupom opcoes = new OpcoesCupom().colunas(32).paginaCodigo("CP850").modoQrCode(OpcoesCupom.ModoQrCode.IMAGEM).tamanhoModuloQr(6).vias(2).cortar(false);return nfce.cupom(id, FormatoCupom.ESCPOS_58, opcoes, null);}}
5 Receber os resultados
Resultados da transmissão, do cancelamento, desativação do dispositivo e avisos de licença e certificado chegam ao PDV como eventos. A entrega é pelo menos uma vez e em ordem: o tratador que retorna normalmente confirma o evento; se lançar exceção, o evento volta em cerca de 30 segundos. Deduplique por EventoId (o exemplo usa um conjunto em memória; em produção, grave no banco do PDV). O servidor do integrador também pode receber os resultados por webhook, veja Como os resultados chegam.
| Evento | O que o PDV faz |
|---|---|
NOTA_AUTORIZADA | Marca a venda como autorizada; a nota online que aguardava autorização (AguardandoAutorizacao) é impressa agora |
NOTA_NEGADA | A nota aceita online e aguardando autorização foi negada depois pela SEFAZ. Marca a venda como negada e avisa o caixa; esta nota não admite correção com o mesmo número: corrija os dados da venda e emita de novo com um id novo |
NOTA_REJEITADA | Nota offline rejeitada pela SEFAZ na transmissão. Avisa o gerente e corrige com Substituir no mesmo número; não emite outra nota |
NOTA_RECUSADA_PLATAFORMA | Nota offline recusada pela plataforma; registra e fala com a plataforma |
CANCELAMENTO_CONCLUIDO / CANCELAMENTO_REJEITADO | Atualiza o resultado do cancelamento; recusado, a nota continua válida |
NUMERO_INUTILIZACAO_RECUSADA | A plataforma recusou a inutilização de números não usados. Com definitivo igual a false, o núcleo tenta de novo sozinho; basta registrar. Com true, é definitivo (faixa de números inválida ou com notas já emitidas na faixa) e é preciso conferir manualmente essa faixa com o integrador |
DISPOSITIVO_DESATIVADO | Avisa com destaque «este caixa não emite mais» |
LICENCA_EXPIRANDO / PRAZO_TRANSMISSAO_PROXIMO | Pede para restabelecer a rede o quanto antes |
CERTIFICADO_EXPIRANDO | Pede para renovar o certificado e, depois, chama TrocarCertificado |
Todos os eventos e campos estão na Referência do SDK.
A thread em que os eventos chegam: no modo subprocesso, callback em série numa thread de segundo plano exclusiva do wrapper; no modo em processo, callback síncrono na thread de entrega do núcleo. Em interface Swing, volte à thread da interface com SwingUtilities.invokeLater.
No tratador, só registre; não chame métodos do SDK: coloque numa fila o que precisa ser tratado depois (por exemplo o id rejeitado na transmissão), e o fluxo principal do PDV retira e trata.
O código abaixo deduplica por EventoId, trata cada tipo de evento e coloca na fila as notas rejeitadas na transmissão, que o fluxo principal corrige com o mesmo número usando Substituir:
import com.tffiscal.nfce.sdk.EventoNfce;import com.tffiscal.nfce.sdk.ResultadoEmissao;import com.tffiscal.nfce.sdk.SituacaoNota;import com.tffiscal.nfce.sdk.TfFiscalNfce;import java.util.Map;import java.util.Queue;import java.util.Set;import java.util.concurrent.ConcurrentHashMap;import java.util.concurrent.ConcurrentLinkedQueue;public final class NfceEventos {private final Set<String> vistos = ConcurrentHashMap.newKeySet();private final Queue<String> rejeitadas = new ConcurrentLinkedQueue<>();/** Ouvinte de eventos: passe para Configuracao.Builder.aoReceberEvento. Retornar normalmente confirma; lançar exceção faz o evento ser reenviado. */public void aoReceber(EventoNfce e) {// Entrega pelo menos uma vez: o mesmo evento pode chegar mais de uma vez; deduplique pelo eventoId (em produção grave os eventoId tratados no banco de dados)if (!vistos.add(e.getEventoId())) {return;}Map<String, Object> d = e.getDados();switch (e.getTipo()) {case "NOTA_AUTORIZADA":System.out.println("Nota " + e.getId() + " autorizada, protocolo " + d.get("protocolo")+ (Boolean.TRUE.equals(d.get("aposCorrecao")) ? " (apos correcao)" : ""));break;case "NOTA_NEGADA":// Nota online que aguardava autorização foi negada depois pela SEFAZ: não admite correção com o mesmo número; corrija os dados da venda e emita de novo com um id novoSystem.out.println("Nota " + e.getId() + " negada pela SEFAZ: " + d.get("cStat") + " " + d.get("motivo")+ " - corrija a venda e emita de novo com um novo id");break;case "NOTA_REJEITADA":// Nota offline rejeitada na transmissão: entra na fila e o fluxo principal corrige com substituir no mesmo númeroSystem.out.println("Nota " + e.getId() + " rejeitada pela SEFAZ: " + d.get("cStat") + " " + d.get("motivo"));rejeitadas.add(e.getId());break;case "NOTA_RECUSADA_PLATAFORMA":System.out.println("Nota " + e.getId() + " recusada pela plataforma: " + d.get("codigo") + " " + d.get("mensagem"));break;case "CANCELAMENTO_CONCLUIDO":case "CANCELAMENTO_REJEITADO":System.out.println("Cancelamento da nota " + e.getId() + ": " + e.getTipo() + " " + d.get("cStat") + " " + d.get("motivo"));break;case "NUMERO_INUTILIZACAO_RECUSADA":// definitivo=true: faixa inválida ou com notas já emitidas na faixa, exige conferência manual; false: o núcleo tenta de novo sozinhoSystem.out.println("Inutilizacao recusada: serie " + d.get("serie") + " " + d.get("inicio") + "-" + d.get("fim")+ ": " + d.get("mensagem") + (Boolean.TRUE.equals(d.get("definitivo")) ? " - verificar manualmente" : ""));break;case "DISPOSITIVO_DESATIVADO":System.out.println("Este caixa nao emite mais: " + d.get("situacao") + " " + d.get("motivo"));break;case "LICENCA_EXPIRANDO":case "PRAZO_TRANSMISSAO_PROXIMO":System.out.println("Restabeleca a internet o quanto antes");break;case "CERTIFICADO_EXPIRANDO":System.out.println("Certificado A1 valido ate " + d.get("validoAte") + "; troque com trocarCertificado");break;default:// Tipos de evento novos podem ser ignorados com segurançabreak;}}/** Chamado periodicamente pelo fluxo principal: corrige com o mesmo número as notas rejeitadas na transmissão. */public void corrigirRejeitadas(TfFiscalNfce nfce) {String id;while ((id = rejeitadas.poll()) != null) {SituacaoNota original = nfce.consultar(id);// Corrija o campo que não afeta valores (como NCM ou CFOP) conforme cStat / motivo de NOTA_REJEITADA; valores e tributos não podem mudarString corrigido = original.getPedido();ResultadoEmissao r = nfce.substituir(id, corrigido, null);System.out.println("Substituir " + r.getId() + ": " + r.getStatus() + ", numero " + r.getNumero() + " (mesmo numero)");}}}
A correção com o mesmo número só pode mudar conteúdo que não afeta valores e tributos (por exemplo NCM, CFOP, documento do consumidor); número, chave de acesso e data de emissão não mudam; mudança de valor ou tributo devolve 10029821. No NOTA_AUTORIZADA recebido depois da correção e da nova transmissão, aposCorrecao vem true.
6 O que acontece sem rede
Sem rede, o caixa emite normalmente e o PDV não precisa de nenhum desvio no código. As regras da transmissão em si (situação pendente de transmissão, transmissão automática, correção com o mesmo número após rejeição, prazo de transmissão, notas que não podem ser emitidas offline) estão em Notas offline e transmissão; aqui fica só o comportamento do lado do SDK:
Emitirtenta online primeiro; com tempo esgotado ou sem conexão com a plataforma, emite a nota de contingência offline no próprio computador e devolveContingenciaPendente. Se a última tentativa de conexão acabou de falhar, emite offline direto, sem esperar.- O cupom sai normalmente, com a marca de contingência e o aviso «pendente de autorização», sem protocolo.
- Quando a rede volta, o núcleo transmite sozinho, sem nenhuma chamada; para transmitir na hora, chame
SincronizarAgora, por exemplo ao detectar a volta da rede; ele só dispara a próxima rodada de sincronização em segundo plano e retorna na hora, e pode ser chamado na thread da interface. - Autorizada na transmissão, chega o evento
NOTA_AUTORIZADA; nota offline rejeitada pela SEFAZ na transmissão, chegaNOTA_REJEITADAe a correção é com o mesmo número usandoSubstituir, veja a seção 5.
Quando não dá para emitir offline, Emitir lança exceção:
| Código de erro | Situação | Como resolver |
|---|---|---|
10029804 / 10029807 / 10029810 | Licença vencida / prazo offline encerrado / nota pendente mais antiga além do prazo de transmissão | Some sozinho com a volta da rede |
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 |
10029811 | O estado ou a empresa não permite offline | Só é possível emitir online |
10029812 | Nota com combustível | Não pode ser emitida offline; só é possível emitir online |
Recomenda-se que a tela do caixa leia Situacao de tempos em tempos (por exemplo a cada 10 segundos) para avisar o caixa:
Campo de Situacao | Aviso na tela |
|---|---|
Conectado igual a false | «Offline; as notas serão transmitidas quando a rede voltar» |
PendentesTransmissao | «N notas a transmitir» |
PrazoTransmissaoAte | «Restabeleça a rede até tal hora», com destaque quando estiver perto |
OfflineAte | Quando o tempo offline estiver acabando, peça para conectar logo |
Avisos não vazio | O ambiente de execução precisa de ajuste por um técnico; registre o texto original no log ou mostre ao suporte técnico |
7 Checklist antes da produção
- Em homologação, cubra: pareamento, emissão com rede (
Autorizada), emissão sem rede (ContingenciaPendente) e, com a rede de volta, o eventoNOTA_AUTORIZADA. - Reenviar o mesmo
idnão emite outra nota; depois de uma queda,Consultarrecupera o resultado. - Eventos deduplicados por
EventoId, com o registro de deduplicação gravado;NOTA_NEGADA(emitir de novo comidnovo) eNOTA_REJEITADA(correção com o mesmo número) tratados separadamente. - O cupom sai legível na impressora usada na loja, com QR Code legível; impressoras sem ESC/POS direto testadas com
PDF_80. - O instalador leva o diretório do runtime; atualizar e desinstalar não apagam o diretório de dados; o PDV roda sempre com o mesmo usuário do Windows.
- A tela do caixa mostra o estado offline, as notas a transmitir e o prazo de transmissão.
- Certificado vencendo e dispositivo desativado têm aviso em destaque.
XmlAutorizado,XmlCancelamento,ExportarXmls,Backup,RestaurarBackupeExportarPendenteschamados em thread de segundo plano, sem travar a interface;SincronizarAgoraretorna na hora e pode ser chamado direto.- Se a loja acessa a internet por proxy, pareamento e emissão testados na rede real.
- Backup criptografado periódico configurado, com a senha guardada separada do arquivo de backup e fora do programa; restauração do backup antes de
Iniciarjá ensaiada; a equipe da loja sabe exportar o pacote de pendentes e entregá-lo à plataforma se o computador quebrar, veja Backup e recuperação de computador com defeito. - Quando a empresa passar para produção, gere códigos em produção, pareie dispositivos novos e desative os de homologação.
- Quem usa o modo principal e secundário ensaiou o principal fora do ar (o secundário devolve
10029880e o caixa passa para a máquina reserva) e a revogação de um secundário (que passa a devolver10029882).
Próximos passos
- Operação e recursos avançados: cancelamento, cancelamento por substituição, consulta e reimpressão do cupom, obtenção e exportação mensal do XML, backup e recuperação de computador com defeito, fechar e reiniciar.
- Vários caixas (modo principal e secundário): vários caixas da mesma loja com uma só série de dispositivo.
- Referência do SDK: configuração, cada método, tipos de dados, eventos e códigos de erro.
Erros comuns e como tratar
| Código de erro | Situação | Tratamento |
|---|---|---|
| 10029801 / 10029802 | Empresa não pareada neste computador / várias empresas pareadas e empresaId não informado | Pareie primeiro; informe empresaId |
| 10029804 / 10029807 | Sem rede e licença vencida / prazo offline encerrado | Restabeleça a rede; a renovação é automática |
| 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 | Relógio do sistema voltou para trás | Corrija a hora do sistema |
| 10029810 | A nota pendente mais antiga passou do prazo de transmissão | Restabeleça a rede o quanto antes para transmitir |
| 10029811 / 10029812 | Offline não permitido, ou base recém-restaurada de backup ainda sem nova licença / nota com combustível | Só é possível emitir online; depois de restaurar, a emissão offline volta sozinha após uma sincronização com a plataforma |
| 10029813 / 10029814 | Certificado indisponível / vencido | Confira o certificado; renovado, chame TrocarCertificado |
| 10029816 | Dispositivo desativado | Fale com o integrador |
| 10029817 | Requisição inválida: campo obrigatório ausente, valor inválido ou campo que não existe no contrato (cada um com o caminho do campo) | Corrija conforme Detalhes; valide antes com Previsualizar |
| 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 com conteúdo diferente | Use outro id na venda nova |
| 10029819 | Não existe neste computador nota com este id | Confira id e empresaId |
| 10029822 | A situação atual não permite cancelar | Já cancelada ou com cancelamento em andamento: não tente de novo; no cancelamento por substituição, a original precisa ser nota normal emitida online |
| 10029827 | Diretório de dados vindo de outro computador ou outro usuário do Windows | Rode com o usuário original; para trocar de computador, desative o dispositivo antigo e pareie de novo |
| 10029828 | Diretório de dados em uso por outro processo | Abra uma única instância; a restauração do backup é feita antes de Iniciar, e numa instância já iniciada chame antes Encerrar |
| 10029832 / 10029833 | Runtime terminou inesperadamente / tempo esgotado | Repita com o mesmo id |
| 10029841 | XML autorizado ainda não disponível | Se ainda não autorizada, aguarde NOTA_AUTORIZADA; se já autorizada e o erro continua, a plataforma não arquivou ou está inacessível no momento; tente mais tarde |
| 10029842 | Base local mais nova que o programa | O diretório de dados 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 | XML de cancelamento ainda não disponível | Se o cancelamento ainda não foi concluído, aguarde CANCELAMENTO_CONCLUIDO; se já cancelada e o erro continua, a plataforma não arquivou ou está inacessível no momento; tente mais tarde |
| 10029844 | Falha ao gravar arquivo | Diretório de exportação ou backup sem permissão de gravação, ou arquivo de backup já existente: troque de diretório ou de nome e confira espaço em disco e permissões |
| 10029845 | Chave da nota substituta inválida | Informe a chave de 44 dígitos da nota offline substituta emitida neste computador, com o mesmo CNPJ e não recusada pela plataforma |
| 10029846 | O backup não pode ser restaurado | Senha errada ou arquivo de backup alterado ou corrompido: confira a senha e use outro backup íntegro; a base original não foi alterada |
| 10029874 | Parâmetro inválido, por exemplo nome ou versão do PDV ausente na inicialização, proxy com formato inválido, parâmetros de impressão ou datas de exportação fora da faixa | Complete ou corrija os parâmetros conforme Detalhes |
| 10029877 | Runtime não encontrado | Confira o diretório do runtime no instalador |
| 10029880 / 10029881 | O secundário não alcança o principal / o pedido foi enviado mas a resposta do principal não voltou | Tente depois ou passe para a máquina reserva; com resultado desconhecido, chame Consultar com o mesmo id quando o principal voltar |
| 10029882 | Token do terminal secundário inválido ou revogado | Emita outro token no principal e atualize TokenTerminal |
| 10029884 | O secundário chamou um método só do principal | Faça pareamento, troca de certificado, backup e exportação no principal |
| 10029307 | Ambiente do dispositivo diferente do ambiente atual da empresa | Gere um código no ambiente atual da empresa e pareie um dispositivo novo |
Todos os códigos e o tratamento sugerido estão na Referência do SDK e em Códigos de erro.
Por que a emissão sem rede demora um pouco?
O núcleo tenta online primeiro e só emite offline depois do tempo de espera; o resultado traz TentativaOnline igual a true; esta nota offline usa o número seguinte, e a plataforma resolve o número da tentativa online sem que você precise fazer nada. Se a última tentativa de conexão acabou de falhar, emite offline direto, sem esperar.
Como testar a emissão offline?
Pareie um computador de testes em homologação e desconecte a rede dele para emitir; notas de homologação não têm valor fiscal.
Como trocar o computador do caixa?
Deixe o computador antigo transmitir com rede todas as notas offline, desative o dispositivo antigo e gere um código novo para parear o computador novo. Não copie o diretório de dados.
O computador antigo quebrou e as notas offline ainda não foram transmitidas. E agora?
Se o computador ainda liga, exporte as notas pendentes com ExportarPendentes, 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» (a exportação já vem dividida por dispositivo, com até 500 notas por pacote, sem precisar descompactar nem dividir de novo); depois desative o dispositivo antigo e pareie o computador novo, veja o caminho 1 de Backup e recuperação de computador com defeito. O backup criptografado só pode ser restaurado no computador original e não ajuda na troca de computador. Se o computador não liga mais, fale com a plataforma.
Qual a diferença entre a nota online negada (NOTA_NEGADA) e a nota offline rejeitada na transmissão (NOTA_REJEITADA)?
A nota online negada não pode ser corrigida: corrija os dados da venda e emita de novo com um id novo. A nota offline já foi impressa e entregue ao consumidor; rejeitada na transmissão, ela é corrigida com o mesmo número usando Substituir, e o número e a chave de acesso não mudam.
