TF Fiscal
Documentação

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:

text
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 eventos
Rotina: 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:

http
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:

json
{ "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):

xml
<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:

text
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 empresaId dos 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 com ExportarPendentes e 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 com InspecionarCodigoAtivacao, 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.

java
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ódigo
System.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 exibida
System.out.println("Erro " + c + " " + e.getTipo() + ": " + e.getMessage());
}
return false;
}
}
}

Se o pareamento ou a partida falhar, trate pelo código de erro:

CategoriaCódigo de erroTratamento
Dá para repetir10029824 (sem conexão com a plataforma), 10029833 (tempo esgotado)Confira a rede e tente de novo
Dá para repetir10029839 (a plataforma pareou mas o computador não gravou)Pareie de novo com o mesmo código
Exige outro código10029825, 10029205 a 10029209, 10029219, 10029221 a 10029225Peça ao integrador um novo código de pareamento
Exige outro certificado10029813, 10029814, 10029213, 10029214Use um certificado válido da empresa
Falha logo na partida10029842 (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:

FormaComo configurarObservação
DiretaNenhum item de proxy configuradoForma padrão
Proxy manualProxy com host:porta, por exemplo 10.0.0.1:3128Formato inválido devolve 10029874
Proxy do sistemaUsarProxyDoSistema igual a trueLê 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 devolve 10029874.
  • 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, Avisos em 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:

java
// Acrescente à cadeia Configuracao.builder() de 2.1: acesso à internet por proxy manual com autenticaçã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")
.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.

json
{
"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.

json
{
"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" }
}
}
]
}
CampoPreenchimentoDescrição
idObrigatórioNú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
ambienteEmissaoObrigatórioAmbiente de emissão. Igual ao ambiente em que o dispositivo foi pareado
modoRespostaNão enviarO SDK sempre espera o resultado
pedido.presencaConsumidorObrigatórioPresença do consumidor. Na loja é OperacaoPresencial
pedido.pagamento.formasObrigatórioFormas de pagamento. tipo e valor de cada uma; a soma precisa cobrir o total da nota
pedido.pagamento.trocoOpcionalTroco. Quando o dinheiro passa do total; a soma dos pagamentos menos o troco é igual ao total da nota
clienteOpcionalConsumidor. 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 / valorUnitarioObrigatórioDados básicos do item
itens[].ean / cest / valorDescontoOpcionalCódigo de barras, CEST, desconto do item
itens[].impostos.icms.situacaoTributariaObrigatórioCódigo de tributação do ICMS. No Simples Nacional, por exemplo 102; no regime normal, por exemplo 00
itens[].impostos.icms.aliquotaOpcionalAlíquota do ICMS. Percentual
itens[].impostos.pis / cofinsObrigatórioCódigo de PIS / COFINS, por exemplo 49 no Simples Nacional e 07 no regime normal
itens[].classeImpostoOpcionalCó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.

java
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ática
return 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 novo
System.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 exibida
System.out.println("Erro " + e.getCodigo() + " " + e.getTipo() + ": " + e.getMessage() + " " + e.getDetalhesJson());
return false;
}
}
}

3.3 Situações devolvidas

StatusO que aconteceuTela do caixa
AutorizadaAutorizada onlineImprime o cupom e conclui a venda
ContingenciaPendenteSem conexão com a plataforma; emitida offline no próprio computadorImprime e entrega normalmente ao consumidor; o cupom já sai com a marca de contingência; pode mostrar «emissão offline» num canto da tela
AguardandoAutorizacaoA plataforma aceitou, a SEFAZ ainda não respondeu e naquele momento não dava para assinar offlineNã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
NegadaRejeitada pela SEFAZMostra o código e a mensagem de resultado da SEFAZ; corrige e emite de novo com outro id
ExceçãoRequisiçã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:

FormatoSignificado
ESCPOS_80Comandos ESC/POS para impressora térmica de 80 mm
ESCPOS_58Comandos ESC/POS para impressora térmica de 58 mm
TEXTOTexto puro em UTF-8
HTMLPágina HTML em UTF-8, para pré-visualização na tela ou impressão pelo navegador
PDF_80PDF com 80 mm de largura, uma página por via, impresso pelo driver de impressão do Windows; 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.
java
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âmetroValoresPadrão
ColunasCaracteres por linha. 48, 42 ou 32Pelo formato: 48 em 80 mm, 32 em 58 mm
PaginaCodigoPá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 acentoCP1252
ModoQrCodeForma 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 nativoNATIVO
TamanhoModuloQrTamanho do módulo do QR Code. De 1 a 16 pontos4
CortarCorte do papel ao final. true corta, false não corta (impressora sem guilhotina)true
ViasNúmero de vias. De 1 a 9Configurado 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).

java
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.

EventoO que o PDV faz
NOTA_AUTORIZADAMarca a venda como autorizada; a nota online que aguardava autorização (AguardandoAutorizacao) é impressa agora
NOTA_NEGADAA 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_REJEITADANota 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_PLATAFORMANota offline recusada pela plataforma; registra e fala com a plataforma
CANCELAMENTO_CONCLUIDO / CANCELAMENTO_REJEITADOAtualiza o resultado do cancelamento; recusado, a nota continua válida
NUMERO_INUTILIZACAO_RECUSADAA 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_DESATIVADOAvisa com destaque «este caixa não emite mais»
LICENCA_EXPIRANDO / PRAZO_TRANSMISSAO_PROXIMOPede para restabelecer a rede o quanto antes
CERTIFICADO_EXPIRANDOPede 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:

java
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 novo
System.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úmero
System.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 sozinho
System.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ça
break;
}
}
/** 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 mudar
String 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:

  1. Emitir tenta online primeiro; com tempo esgotado ou sem conexão com a plataforma, emite a nota de contingência offline no próprio computador e devolve ContingenciaPendente. Se a última tentativa de conexão acabou de falhar, emite offline direto, sem esperar.
  2. O cupom sai normalmente, com a marca de contingência e o aviso «pendente de autorização», sem protocolo.
  3. 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.
  4. Autorizada na transmissão, chega o evento NOTA_AUTORIZADA; nota offline rejeitada pela SEFAZ na transmissão, chega NOTA_REJEITADA e a correção é com o mesmo número usando Substituir, veja a seção 5.

Quando não dá para emitir offline, Emitir lança exceção:

Código de erroSituaçãoComo resolver
10029804 / 10029807 / 10029810Licença vencida / prazo offline encerrado / nota pendente mais antiga além do prazo de transmissãoSome sozinho com a volta da rede
10029808A série do dispositivo chegou ao número 999999999Desative o dispositivo e pareie-o de novo com um código de pareamento novo que informe outra série em serie; a plataforma não troca a série sozinha
10029811O estado ou a empresa não permite offlineSó é possível emitir online
10029812Nota com combustívelNã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 SituacaoAviso 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
OfflineAteQuando o tempo offline estiver acabando, peça para conectar logo
Avisos não vazioO 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

  1. Em homologação, cubra: pareamento, emissão com rede (Autorizada), emissão sem rede (ContingenciaPendente) e, com a rede de volta, o evento NOTA_AUTORIZADA.
  2. Reenviar o mesmo id não emite outra nota; depois de uma queda, Consultar recupera o resultado.
  3. Eventos deduplicados por EventoId, com o registro de deduplicação gravado; NOTA_NEGADA (emitir de novo com id novo) e NOTA_REJEITADA (correção com o mesmo número) tratados separadamente.
  4. O cupom sai legível na impressora usada na loja, com QR Code legível; impressoras sem ESC/POS direto testadas com PDF_80.
  5. 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.
  6. A tela do caixa mostra o estado offline, as notas a transmitir e o prazo de transmissão.
  7. Certificado vencendo e dispositivo desativado têm aviso em destaque.
  8. XmlAutorizado, XmlCancelamento, ExportarXmls, Backup, RestaurarBackup e ExportarPendentes chamados em thread de segundo plano, sem travar a interface; SincronizarAgora retorna na hora e pode ser chamado direto.
  9. Se a loja acessa a internet por proxy, pareamento e emissão testados na rede real.
  10. Backup criptografado periódico configurado, com a senha guardada separada do arquivo de backup e fora do programa; restauração do backup antes de Iniciar já 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.
  11. Quando a empresa passar para produção, gere códigos em produção, pareie dispositivos novos e desative os de homologação.
  12. Quem usa o modo principal e secundário ensaiou o principal fora do ar (o secundário devolve 10029880 e o caixa passa para a máquina reserva) e a revogação de um secundário (que passa a devolver 10029882).

Próximos passos

Erros comuns e como tratar

Código de erroSituaçãoTratamento
10029801 / 10029802Empresa não pareada neste computador / várias empresas pareadas e empresaId não informadoPareie primeiro; informe empresaId
10029804 / 10029807Sem rede e licença vencida / prazo offline encerradoRestabeleça a rede; a renovação é automática
10029808A série do dispositivo chegou ao número 999999999Desative o dispositivo e pareie-o de novo com um código de pareamento novo que informe outra série em serie; a plataforma não troca a série sozinha
10029809Relógio do sistema voltou para trásCorrija a hora do sistema
10029810A nota pendente mais antiga passou do prazo de transmissãoRestabeleça a rede o quanto antes para transmitir
10029811 / 10029812Offline não permitido, ou base recém-restaurada de backup ainda sem nova licença / nota com combustívelSó é possível emitir online; depois de restaurar, a emissão offline volta sozinha após uma sincronização com a plataforma
10029813 / 10029814Certificado indisponível / vencidoConfira o certificado; renovado, chame TrocarCertificado
10029816Dispositivo desativadoFale com o integrador
10029817Requisiçã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
10029780Linha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumidoReenvie com o mesmo id quando a rede voltar; sem rede, envie impostos nas linhas de item
10029818O mesmo id já foi usado com conteúdo diferenteUse outro id na venda nova
10029819Não existe neste computador nota com este idConfira id e empresaId
10029822A situação atual não permite cancelarJá cancelada ou com cancelamento em andamento: não tente de novo; no cancelamento por substituição, a original precisa ser nota normal emitida online
10029827Diretório de dados vindo de outro computador ou outro usuário do WindowsRode com o usuário original; para trocar de computador, desative o dispositivo antigo e pareie de novo
10029828Diretório de dados em uso por outro processoAbra uma única instância; a restauração do backup é feita antes de Iniciar, e numa instância já iniciada chame antes Encerrar
10029832 / 10029833Runtime terminou inesperadamente / tempo esgotadoRepita com o mesmo id
10029841XML autorizado ainda não disponívelSe 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
10029842Base local mais nova que o programaO 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
10029843XML de cancelamento ainda não disponívelSe 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
10029844Falha ao gravar arquivoDiretó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
10029845Chave da nota substituta inválidaInforme a chave de 44 dígitos da nota offline substituta emitida neste computador, com o mesmo CNPJ e não recusada pela plataforma
10029846O backup não pode ser restauradoSenha errada ou arquivo de backup alterado ou corrompido: confira a senha e use outro backup íntegro; a base original não foi alterada
10029874Parâ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 faixaComplete ou corrija os parâmetros conforme Detalhes
10029877Runtime não encontradoConfira o diretório do runtime no instalador
10029880 / 10029881O secundário não alcança o principal / o pedido foi enviado mas a resposta do principal não voltouTente depois ou passe para a máquina reserva; com resultado desconhecido, chame Consultar com o mesmo id quando o principal voltar
10029882Token do terminal secundário inválido ou revogadoEmita outro token no principal e atualize TokenTerminal
10029884O secundário chamou um método só do principalFaça pareamento, troca de certificado, backup e exportação no principal
10029307Ambiente do dispositivo diferente do ambiente atual da empresaGere 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.