TF Fiscal
Documentação

NFC-e offline

Tutorial do Assistente Fiscal

Tutorial do Assistente Fiscal: instalar e parear o Assistente no computador Windows da loja, o PDV emite com ou sem rede pela interface local com o mesmo caminho da NFC-e em nuvem, recebe os resultados por callback local ou consulta periódica, além de implantação e operação, emissão simples e perguntas frequentes.

O TF Fiscal Assistente Fiscal (aqui chamado Assistente Fiscal) é um programa instalado no computador Windows da loja, formado por um serviço em segundo plano e uma interface de desktop. O serviço traz o núcleo de emissão offline e oferece no próprio computador uma interface com o mesmo caminho e a mesma estrutura de corpo da emissão de NFC-e em nuvem (classe de imposto exige conexão); basta o PDV trocar o endereço da chamada para o endereço local e passa a ter emissão online e emissão offline sem rede. Ao final desta página você terá concluído a instalação, a integração e o recebimento dos resultados. Antes de começar, o integrador chama Gerar código de pareamento para este computador de caixa (formaPermitida igual a Assistente ou Qualquer) e entrega o código à loja.

text
1 Instalar e parear o assistente ──► 2 O PDV emite pela interface local ──► 3 Receber os resultados (callback local ou consulta)

1 Instalação e pareamento

Preparação

ItemDescrição
ComputadorWindows, o mesmo do PDV; para um Assistente atender vários caixas veja Modo rede local
PermissãoA instalação exige permissão de administrador
InstaladorTfFiscalAssistente-{versao}-Setup.exe ({versao} é o número da versão), obtido na aba "Downloads" da página "Emissão offline → Emissão offline" do menu lateral do console (basta estar logado; a tabela traz o tamanho e o SHA-256 do arquivo); se faltar o runtime WebView2 no computador ele é instalado automaticamente, e nesse caso é preciso internet
Código de pareamentoGerado pelo integrador em Gerar código de pareamento, com formaPermitida Assistente ou Qualquer; vale como texto ou arquivo .tfa
CertificadoCertificado A1 da empresa: já no repositório de certificados do Windows, ou arquivo PFX com senha

Depois da instalação aparecem o atalho «Assistente Fiscal» no menu Iniciar «TF Fiscal» e na área de trabalho, e o serviço inicia junto com o Windows. A interface de desktop é usada pelo gerente e pelos caixas: Visão geral, Emitir, Notas do dia, Detalhes da nota, Produtos, Integração com PDV, Configurações, Sobre e diagnóstico. Fechar a interface ou uma falha nela não afeta a emissão pelo serviço.

Para instalar vários computadores de uma vez, use a instalação silenciosa pelo MSI, veja Implantação em lote.

Assistente de instalação

Ao abrir a interface pela primeira vez entra o assistente de instalação, que só pede o código de pareamento e o certificado; endereço da plataforma, ambiente, empresa e série do dispositivo vêm do código e do resultado do pareamento.

EtapaConteúdo
1 Boas-vindasEscolha o idioma da interface; padrão português; as mensagens de erro devolvidas pela plataforma também vêm neste idioma, e uma troca posterior nas configurações vale na hora
2 Código de pareamentoCole o código, importe o arquivo .tfa ou leia pela câmera. O Assistente confere o código no próprio computador e mostra o ambiente (produção / homologação), a validade e a série do dispositivo e o número inicial definidos pelo integrador, ou que a plataforma os atribui começando em 1 quando não definidos; um código restrito à forma SDK é barrado aqui
3 CertificadoLista os certificados do repositório com CNPJ, dentro da validade e com chave privada; ou importe um PFX. A chave privada importada fica não exportável e a senha do PFX não é guardada
4 PIN do gerenteDefina um PIN de 6 a 8 dígitos, usado em cancelamento, correção, gestão de tokens, exportação, backup e outras operações
5 ParearPareia pela internet; no sucesso mostra nome da empresa, CNPJ, nome do dispositivo, série do dispositivo e o número da primeira nota deste dispositivo; na falha mostra o código de erro e o que fazer
6 ConcluídoMostra o endereço da interface local e leva a «Integração com PDV» para gerar o token de caixa, ou direto para «Emitir»

Pareamento

  • Se o pareamento falhar por falta de conexão com a plataforma, basta clicar de novo em parear com o mesmo código de pareamento; não gere outro código: um código novo ocupa mais uma vaga de dispositivo.
  • Certificados marcados na lista com o aviso «O serviço não tem acesso à chave» estão no repositório da máquina e a conta do serviço ainda não consegue usá-los: execute como administrador o scripts\conceder-acesso-chave.ps1 -Thumbprint {thumbprint} da pasta de instalação ({thumbprint} é a impressão digital do certificado) e clique em «Atualizar».
  • Para um mesmo computador atender várias empresas (vários CNPJ), entre de novo no assistente de instalação: isso é «Adicionar empresa», com o mesmo fluxo e exigindo o PIN do gerente.

2 Integração do PDV

Gerar o token de caixa

O gerente gera o token de caixa na página «Integração com PDV» do programa:

  • Informe um nome (por exemplo PDV 01), as empresas que ele acessa (marque-as quando houver vários CNPJ) e, opcionalmente, um endereço de callback.
  • O token tem a forma tfl_ mais 43 caracteres e só aparece uma vez, na geração; com endereço de callback, aparece junto o segredo de callback whsec_…, também uma única vez.
  • O token pode ser revogado na mesma página com um clique, com efeito imediato.

O token de caixa só chama o Assistente local; se vazar, o impacto se limita a esse Assistente e ele pode ser revogado sozinho; o segredo de aplicativo do integrador na nuvem não precisa ir para a loja.

O software do PDV usa só a interface local abaixo. A interface de gestão usada pelo próprio programa de desktop (caminhos que começam com /assistente/api/) não fica aberta ao software do PDV: só aceita origem local, exige sessão de gerente ou de caixa, e as requisições com sessão ainda precisam levar o token anti-CSRF entregue no login; outras páginas web ou programas não conseguem forjar essas requisições.

Endereço e autenticação

ItemValor
Endereçohttp://127.0.0.1:8765; no modo rede local, o endereço do computador do Assistente na rede local
AutenticaçãoCabeçalho Authorization: Bearer tfl_…; sem os token / timestamp / sign da nuvem
Tipo de conteúdoContent-Type: application/json

Operações

MétodoCaminhoUsoEquivalente na nuvem
POST/openapi/v2/empresas/{empresaId}/nfceEmitirEmitir NFC-e
GET/openapi/v2/empresas/{empresaId}/nfce/{nfceId}ConsultarConsultar NFC-e
POST/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelarCancelarCancelar NFC-e
POST/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar-substituicaoCancelamento por substituiçãoCancelar por substituição
GET/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cupom?formato=ESCPOS_80Cupom, inclusive em PDFSó local
GET/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xmlDownload do XML autorizadoSó local
GET/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml-cancelamentoDownload do XML de cancelamentoSó local
POST/openapi/v2/empresas/{empresaId}/nfce/{nfceId}/correcaoCorreção com o mesmo número depois de rejeição na transmissãoSó local
GET/openapi/local/v1/situacaoSituação do AssistenteSó local

Diferenças em relação à nuvem

  • Autenticação: token de caixa, veja Endereço e autenticação.
  • modoResposta não tem efeito: o local sempre espera o resultado. Com resultado online incerto, o núcleo abandona esse número e assina offline com o seguinte, e a plataforma resolve o número original depois de conferi-lo; só quando não dá para assinar offline naquele momento devolve HTTP 202 com AguardandoAutorizacao. Os demais sucessos devolvem 200.
  • 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; sem rede ou sem acesso à plataforma, devolve 400 e 10029780, indicando enviar impostos, sem consumir número. O Assistente não guarda classes de imposto, então para a contingência o programa de caixa precisa guardar os impostos expandidos, veja Classe de imposto e conexão.
  • empresaId: precisa ser uma empresa pareada neste Assistente e com acesso pelo token; não pareada devolve 404 e 10029801, token sem acesso devolve 403 e 10029902.
  • Links do cupom e do XML: linkDanfe aponta para o cupom local (formato HTML); linkDownloadXml aponta para o XML local quando o XML autorizado já foi baixado para o computador, senão é null.
  • Campos locais adicionais: a resposta traz, além dos campos da nuvem, os campos da tabela abaixo.
CampoDescrição
situacaoLocalSituação local. Tem dois valores a mais que status: Rejeitada (nota offline rejeitada pela SEFAZ na transmissão, pode ser corrigida com o mesmo número) e Recusada (recusada pela plataforma); nesses dois casos status mostra Negada. situacaoLocal igual a Negada indica rejeição online, sem correção com o mesmo número. Todos os valores em Valores de situação da nota
cStat / xMotivoCódigo e mensagem de resultado da SEFAZ. Vêm juntos; null em nota offline pendente e em recusa da plataforma
tentativaOnlineTentativa online. true quando houve tentativa online, o resultado ficou incerto e a nota foi assinada offline; false para a nota autorizada online e para a nota assinada offline direto logo após uma falha de conexão
transmitidaTransmitida. Só na consulta
cancelamentoPendenteCancelamento pendente. Só na consulta; true para cancelamento pedido antes da autorização da nota offline
correcoesNúmero de correções. Só na consulta
xmlAutorizadoDisponivelXML autorizado disponível. Só na consulta; true indica que já foi baixado para o computador
terminalIdentificação do caixa. Nome do token de caixa que emitiu a nota; null nas notas da emissão simples do programa. Vai para a plataforma junto com a nota; mesmo valor de terminal na consulta em nuvem e nos webhooks

Formato das respostas

CasoHTTPCorpo
Emissão, consulta ou correção com sucesso200; pendente online 202Objeto sem envelope com a mesma estrutura da consulta em nuvem, mais os campos locais
Cancelamento ou cancelamento por substituição aceito200Sem corpo; o destino vem no cabeçalho X-Tffiscal-Cancelamento
Download de cupom ou XML com sucesso200O arquivo original; o tipo está em Cupom e download de XML
Erro de negócio400; nota ou empresa inexistente 404; XML indisponível 409; Assistente ocupado 429; erro interno 500; proteção contra downgrade 503Array [{codigo, mensagem}], com codigo como texto numérico do código de erro; na validação de campos, um item por campo
Falha de autenticação do token ou da origem401 / 403Envelope da plataforma {success, errorType, code, message}

Os exemplos de erro e o tratamento de cada código de erro estão em Tratamento de erros.

3 Emissão, consulta e transmissão

Emissão com rede

O corpo é igual ao da emissão em nuvem; linhas de item que referenciam classe de imposto (classeImposto) exigem conexão, veja Diferenças em relação à nuvem. Com rede, o Assistente pega o número na série deste dispositivo, assina a nota e a entrega à plataforma, que a envia à SEFAZ; o resultado é o mesmo da emissão síncrona em nuvem. Sem rede, segue a mesma sequência nas notas offline, então a numeração online e offline é contínua, veja Números e série.

O exemplo abaixo é uma venda presencial com consumidor não identificado:

http
POST /openapi/v2/empresas/1934811222334455/nfce HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Content-Type: application/json
{
"id": "PDV01-000130",
"ambienteEmissao": "Homologacao",
"pedido": {
"presencaConsumidor": "OperacaoPresencial",
"pagamento": { "formas": [ { "tipo": "Dinheiro", "valor": 50.00 } ], "troco": 7.50 }
},
"itens": [
{
"cfop": "5102", "codigo": "PF-FRANGO", "descricao": "PRATO FEITO FRANGO", "ncm": "21069090",
"quantidade": 1, "unidadeMedida": "UN", "valorUnitario": 32.50,
"impostos": { "icms": { "situacaoTributaria": "102" }, "pis": { "situacaoTributaria": "49" }, "cofins": { "situacaoTributaria": "49" } }
},
{
"cfop": "5405", "codigo": "7894900011517", "descricao": "REFRIGERANTE LATA 350ML", "ncm": "22021000", "cest": "0300700",
"quantidade": 2, "unidadeMedida": "UN", "valorUnitario": 5.00,
"impostos": { "icms": { "situacaoTributaria": "500" }, "pis": { "situacaoTributaria": "49" }, "cofins": { "situacaoTributaria": "49" } }
}
]
}
CampoPreenchimento
idNúmero da venda no PDV. Obrigatório; é a chave de idempotência: ao repetir a mesma venda use o mesmo id, e o Assistente devolve a nota original sem emitir de novo
ambienteEmissaoAmbiente de emissão. Obrigatório; igual ao ambiente do pareamento do dispositivo
pedido, itensPedido e itens. Obrigatórios; mesmas regras de Emitir NFC-e
clienteConsumidor. Opcional; não preencha quando o consumidor não se identifica
modoRespostaModo de resposta. Não preencha; o local ignora

Com a autorização da SEFAZ volta HTTP 200. Primeiro vêm todos os campos da consulta em nuvem (aqui sem o eco de pedido e itens), depois os campos locais:

json
{
"id": "PDV01-000130",
"tipo": "NFC-e",
"status": "Autorizada",
"motivoStatus": null,
"ambienteEmissao": "Homologacao",
"dataCriacao": "2026-11-11T14:02:10Z",
"dataUltimaAlteracao": "2026-11-11T14:02:11Z",
"numero": "419",
"serie": "2",
"dataEmissao": "2026-11-11T14:02:10Z",
"chaveAcesso": "35261111222333000181650020000004191123456780",
"dataAutorizacao": "2026-11-11T14:02:11Z",
"protocolo": { "numero": "135261234567990" },
"qrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004191123456780|3|2",
"urlConsulta": "https://www.homologacao.nfce.fazenda.sp.gov.br/consulta",
"linkDanfe": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/cupom?formato=HTML",
"linkDownloadXml": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/xml",
"emitidaEmContingencia": false,
"alertas": [],
"valorTotal": 42.50,
"situacaoLocal": "Autorizada",
"cStat": 100,
"xMotivo": "Autorizado o uso da NF-e",
"tentativaOnline": false
}

Emissão sem rede

Requisição igual à da emissão com rede. Sem acesso à plataforma, o Assistente assina no computador a nota de contingência offline e devolve HTTP 200 com ContingenciaPendente:

json
{
"id": "PDV01-000131",
"tipo": "NFC-e",
"ambienteEmissao": "Homologacao",
"situacaoLocal": "ContingenciaPendente",
"status": "ContingenciaPendente",
"chaveAcesso": "35261111222333000181650020000004219123456783",
"serie": "2",
"numero": "421",
"dataEmissao": "2026-11-11T15:00:00Z",
"qrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004219123456783|3|2|...",
"urlConsulta": "https://www.homologacao.nfce.fazenda.sp.gov.br/consulta",
"emitidaEmContingencia": true,
"cStat": null,
"xMotivo": null,
"tentativaOnline": true,
"linkDanfe": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=HTML"
}
  • serie é a série deste dispositivo, compartilhada com as notas online e com numeração contínua, diferente da série do perfil da empresa usada na emissão em nuvem; o dígito 35 da chave de acesso é 9.
  • Não há protocolo; imprima o cupom e entregue ao consumidor: pegue os bytes ESC/POS pela operação de cupom e mande à impressora; o cupom já sai com a marca de contingência e o número de vias configurado pela plataforma.
  • tentativaOnline = true indica que houve tentativa online com resultado incerto; esta nota usa o número seguinte ao da tentativa online, e a plataforma resolve esse número original depois de conferi-lo; quando a última conexão tinha acabado de falhar e a nota foi assinada offline direto, vem false.
  • Com a rede de volta, a transmissão é automática; as regras de transmissão estão em Notas offline e transmissão. O servidor do integrador recebe nfce.contingency_issued e depois nfce.authorized, veja Como os resultados chegam; o PDV fica sabendo do resultado pelo callback local ou pela consulta.

Consulta e resultado da transmissão

Consulte a nota com o id usado na emissão:

http
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131 HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t

Depois da autorização na transmissão:

json
{
"id": "PDV01-000131",
"tipo": "NFC-e",
"ambienteEmissao": "Homologacao",
"situacaoLocal": "Autorizada",
"status": "Autorizada",
"chaveAcesso": "35261111222333000181650020000004219123456783",
"serie": "2",
"numero": "421",
"dataEmissao": "2026-11-11T15:00:00Z",
"qrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004219123456783|3|2|...",
"urlConsulta": "https://www.homologacao.nfce.fazenda.sp.gov.br/consulta",
"emitidaEmContingencia": true,
"protocolo": { "numero": "135261234568001" },
"cStat": 100,
"xMotivo": "Autorizado o uso da NF-e",
"tentativaOnline": true,
"transmitida": true,
"cancelamentoPendente": false,
"correcoes": 0,
"dataUltimaAlteracao": "2026-11-11T16:20:31Z",
"linkDanfe": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=HTML",
"xmlAutorizadoDisponivel": true,
"linkDownloadXml": "http://127.0.0.1:8765/openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/xml"
}
  • emitidaEmContingencia continua true depois da autorização.
  • O XML autorizado é baixado sozinho pelo Assistente depois da autorização na transmissão; com xmlAutorizadoDisponivel = false também dá para chamar direto a operação de XML, e o Assistente o recupera da plataforma, veja Cupom e download de XML.

4 Receber os resultados

O PDV tem duas formas de obter os resultados posteriores, como transmissão e cancelamento: configurar o callback local, em que o assistente envia os resultados, ou fazer consulta periódica. As duas podem ser usadas juntas.

Consulta periódica

Sem callback, o PDV chama a consulta de tempos em tempos, por exemplo a cada minuto, para as notas com situação ainda indefinida (ContingenciaPendente, AguardandoAutorizacao, situacaoLocal igual a Rejeitada), até a situação se definir; quando pendentesTransmissao de GET /openapi/local/v1/situacao chega a 0, todas as notas offline foram transmitidas.

Callback local

Se o token de caixa foi gerado com endereço de callback, o Assistente envia ao PDV os resultados das notas deste Assistente. Cabeçalhos, algoritmo de assinatura e estrutura do payload são os mesmos do webhook da nuvem, e o código de validação da nuvem pode ser reaproveitado; a única diferença é a chave: use o segredo de callback whsec_… inteiro mostrado na geração do token, e não o app_secret do integrador.

Eventos

Cabeçalho X-Tffiscal-EventQuandonfeStatus
nfce.contingency_issuedNota assinada offline no computadorContingenciaPendente
nfce.authorizedAutorizada na transmissão, depois de correção, ou depois de pendente onlineAutorizada
nfce.rejectedNota offline rejeitada pela SEFAZ na transmissão, ou nota pendente online rejeitada depois pela SEFAZNegada, nfeMotivoStatus com código e motivo
nfce.canceledCancelamento concluído, inclusive por substituiçãoCancelada
nfce.cancel_rejectedCancelamento recusadoCancelamentoNegado
nfce.intake_rejectedSó local: a plataforma recusou esta nota offlineRecusada, nfeMotivoStatus com código de erro da plataforma e motivo; fale com a plataforma
nfce.device.deactivatedSó local: dispositivo desativado ou revogadoPayload em Payload

O payload de nfce.rejected não distingue os dois tipos de rejeição: ao recebê-lo, consulte a nota e trate conforme situacaoLocal. Rejeitada é rejeição na transmissão e segue a correção com o mesmo número; Negada é rejeição online, sem correção com o mesmo número: corrija e emita de novo com um id novo.

Avisos operacionais de licença, certificado, conexão e informação de números não utilizados não são enviados ao PDV; aparecem na Visão geral do programa de desktop.

Cabeçalhos e validação da assinatura

http
POST {callbackUrl}
Content-Type: application/json; charset=utf-8
X-Tffiscal-Event: nfce.contingency_issued
X-Tffiscal-Event-Id: 7b0c1d9e-2a52-4e0f-9a3e-5d2f1c0b8a77
X-Tffiscal-Delivery-Id: 0f5f8d0c-9a4b-4b3d-8c0e-61f2b7d4a913
X-Tffiscal-Timestamp: 1762786800
X-Tffiscal-Signature: 9c1e…
  • {callbackUrl} é o endereço de callback informado ao gerar o token.
  • A assinatura é hex(HMAC-SHA256(segredo de callback, timestamp + "." + corpo original)), com 64 caracteres hexadecimais minúsculos, calculada sobre os bytes originais recebidos.
  • Deduplique por X-Tffiscal-Event-Id: ele não muda nas retentativas nem nos reenvios.

Teste a validação da assinatura com o vetor fixo abaixo:

EntradaValor
Segredo de callbackwhsec_testsecret
X-Tffiscal-Timestamp1762790400
Corpo{"tipo":"NFC-e","nfeId":"PDV-1"}
Assinatura esperada415bce74a6740037c540f3839e69a08bd3026c8337dd49c73e8a4877889de0a4

Payload

Os eventos de nota têm os mesmos campos, na mesma ordem, do callback de NFC-e da nuvem, com dispositivoId no fim. O computador local não tem links de arquivos da nuvem, então nfeLinkDanfe e nfeLinkXml são sempre null; o cupom vem da operação local de cupom:

json
{
"tipo": "NFC-e",
"empresaId": "1934811222334455",
"nfeId": "PDV01-000131",
"nfeStatus": "Autorizada",
"nfeMotivoStatus": null,
"nfeLinkDanfe": null,
"nfeLinkXml": null,
"nfeNumero": "421",
"nfeSerie": "2",
"nfeChaveAcesso": "35261111222333000181650020000004219123456783",
"nfeDataEmissao": "2026-11-11T15:00:00Z",
"nfeDataAutorizacao": "2026-11-11T16:20:30Z",
"nfeNumeroProtocolo": "135261234568001",
"nfeQrCode": "https://www.homologacao.nfce.fazenda.sp.gov.br/qrcode?p=35261111222333000181650020000004219123456783|3|2|...",
"dispositivoId": "1900000000000000001"
}

Payload do evento de dispositivo desativado nfce.device.deactivated:

json
{
"tipo": "NFC-e",
"empresaId": "1934811222334455",
"dispositivoId": "1900000000000000001",
"situacao": "Desativado",
"motivo": "Caixa substituido",
"ocorridoEm": "2026-11-20T18:00:00Z"
}

situacao é Desativado (desativado pelo integrador), Revogado (revogado pela plataforma), EmpresaDesativada (emissão offline da empresa desativada pela plataforma), AplicativoBloqueado (software do PDV bloqueado pela plataforma) ou VersaoBloqueada (versão do PDV bloqueada ou abaixo da mínima); veja Valores de situação do dispositivo.

Retentativas

  • Qualquer resposta 2xx conta como entregue; resposta não 2xx, falha de conexão ou falta de resposta em 5 segundos conta como falha.
  • Depois da falha tenta de novo em 10 segundos, 30 segundos, 2 minutos, 10 minutos e 30 minutos, e depois de hora em hora; se em 24 horas desde a entrada na fila ainda não foi entregue, para.
  • Na página «Integração com PDV» dá para ver o histórico de entregas (guardado por 7 dias) e reenviar manualmente.
  • Falha de callback não afeta a emissão nem a transmissão.

5 Operações comuns

OperaçãoComo fazerDetalhes
Tratar uma nota rejeitadaConforme situacaoLocal: Rejeitada corrige com o mesmo número; Negada / Recusada emite de novo com um id novoTratamento após rejeição
Imprimir o cupom, baixar o XMLGET …/cupom?formato=…, GET …/xml, GET …/xml-cancelamentoCupom e download de XML
Cancelar uma notaPOST …/cancelar, e veja o cabeçalho X-Tffiscal-CancelamentoCancelamento
A mesma venda gerou duas notasPOST …/cancelar-substituicao, que cancela a nota original online e aponta a nota offline substitutaCancelamento por substituição
Mostrar na tela do caixa «offline» e notas a transmitirGET /openapi/local/v1/situacaoSituação do Assistente
Tratar errosConforme o status HTTP e o código de erroTratamento de erros

Tratamento após rejeição

Toda nota rejeitada tem status igual a Negada; o tratamento depende de situacaoLocal:

situacaoLocalSignificadoO que fazer
RejeitadaNota offline rejeitada pela SEFAZ na transmissão. A nota já foi entregue ao consumidor e o número está ocupadoCorrija com o mesmo número e transmita de novo; não emita outra nota; veja abaixo
NegadaRejeitada online pela SEFAZ, inclusive depois de pendente online. A plataforma inutiliza o número; ele não é reaproveitadoCorrija a requisição e emita de novo com um id novo
RecusadaA plataforma recusou esta nota offline. O número não tem efeitoFale com a plataforma para apurar a causa; depois de corrigir, emita de novo com um id novo

Enviar com o id original uma requisição de emissão com conteúdo alterado devolve 400 e 10029818.

Exemplo de consulta de nota rejeitada na transmissão (sem os campos iguais aos de Consulta e resultado da transmissão):

json
{
"id": "PDV01-000131",
"tipo": "NFC-e",
"ambienteEmissao": "Homologacao",
"situacaoLocal": "Rejeitada",
"status": "Negada",
"chaveAcesso": "35261111222333000181650020000004219123456783",
"serie": "2",
"numero": "421",
"emitidaEmContingencia": true,
"motivoStatus": "778 - Rejeicao: Informado NCM inexistente",
"cStat": 778,
"xMotivo": "Rejeicao: Informado NCM inexistente",
"transmitida": true,
"correcoes": 0
}

Na correção com o mesmo número envie a requisição de emissão completa já corrigida, com o mesmo id da original. No exemplo abaixo, ... representa conteúdo igual ao da requisição original; só mudou o ncm da linha de item:

http
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/correcao HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Content-Type: application/json
{ "id": "PDV01-000131", "ambienteEmissao": "Homologacao", "pedido": { "...": "..." }, "itens": [ { "ncm": "22021000", "...": "..." } ] }
  • Só pode mudar o que não afeta valores e tributos, como NCM, CFOP e documento do consumidor; número, série, chave de acesso e data de emissão ficam iguais.
  • Mudança de total ou de tributo de qualquer linha devolve 400 e 10029821; situação diferente de Rejeitada devolve 10029820.
  • No sucesso volta HTTP 200 com a mesma estrutura da resposta de Emissão sem rede, e situacaoLocal volta a ContingenciaPendente, aguardando nova transmissão.

Cupom e download de XML

Ao pedir o cupom, escolha o formato com formato:

http
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=ESCPOS_80 HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
formatoTipo de respostaUso
ESCPOS_80 (padrão)application/octet-streamImpressora térmica de 80 mm; mande os bytes direto à impressora
ESCPOS_58application/octet-streamImpressora térmica de 58 mm
TEXTOtext/plain; charset=utf-8Texto puro
HTMLtext/html; charset=utf-8Pré-visualização na tela ou impressão pelo navegador
PDF_80application/pdfPDF em bobina de 80 mm, uma página por via; para arquivar ou enviar ao consumidor

O número de vias do cupom da nota offline é configurado pela plataforma e já vem montado no conteúdo; imprima como está. A interface local gera o cupom com os parâmetros de impressão padrão, sem efeito dos parâmetros do cupom do programa de desktop (veja Configurações e manutenção do programa de desktop); o PDV se adapta à própria impressora.

Download do XML autorizado:

http
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/xml HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
OperaçãoRetornoQuando indisponível
GET …/xmlXML autorizado original, application/xml; charset=utf-8Ainda não autorizada, ou ausente no computador e não recuperável da plataforma: 409 e 10029841
GET …/xml-cancelamentoXML de cancelamento original, application/xml; charset=utf-8Ainda não cancelada, ou ausente no computador e não recuperável da plataforma: 409 e 10029843
  • Quando a nota já está autorizada (ou cancelada) mas o XML correspondente não está no computador, o Assistente o recupera da plataforma na hora antes de responder, em até cerca de 30 segundos; quem chama não deve usar tempo limite curto demais.
  • No máximo 3 recuperações ao mesmo tempo; acima disso devolve 429 e 10029918; tente mais tarde.

Cancelamento

Basta enviar a justificativa do cancelamento:

http
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cancelar HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Content-Type: application/json
{ "justificativa": "Cliente desistiu da compra no caixa" }

justificativa é obrigatória, de 15 a 255 caracteres. Aceito, volta HTTP 200 sem corpo, e o cabeçalho X-Tffiscal-Cancelamento diz o destino:

ValorSignificado
SolicitadoEnviado à plataforma; o resultado vem pelo callback ou pela consulta
AgendadoA nota offline já foi transmitida, mas ainda não foi autorizada; o cancelamento fica guardado na plataforma e ela o envia no momento da autorização
EnfileiradoLocalFila local: sem rede, ou a nota offline / substituta ainda não foi transmitida; logo após a transmissão, é enviado na mesma rodada

O prazo de cancelamento é o mesmo da nuvem, veja Cancelar NFC-e; situação que não permite cancelamento devolve 400 e 10029822.

Cancelamento por substituição

Use quando a mesma venda gerou duas notas: por exemplo, PDV01-000130 foi emitida online, o PDV não recebeu o resultado e tratou como falha, e depois, sem rede, emitiu neste dispositivo a nota offline PDV01-000131 para a mesma venda, e as duas ficaram válidas. O cancelamento por substituição cancela a nota original emitida online e aponta a nota offline que a substitui:

http
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/cancelar-substituicao HTTP/1.1
Host: 127.0.0.1:8765
Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Content-Type: application/json
{
"chaveAcessoSubstituta": "35261111222333000181650020000004219123456783",
"justificativa": "Venda registrada em contingencia off-line"
}
CampoPreenchimento
nfceId (caminho)Número da nota original. A nota emitida online que será cancelada
chaveAcessoSubstitutaChave de acesso da nota substituta. Obrigatória, 44 dígitos; a nota offline que substitui a original
justificativaJustificativa do cancelamento. Obrigatória; mesmas regras do cancelamento por substituição em nuvem

Condições:

  • A nota original é uma nota normal emitida online e autorizada; nota offline, já cancelada ou com cancelamento pendente devolve 400 e 10029822.
  • A nota substituta é uma nota offline emitida por este dispositivo e para esta empresa e não recusada pela plataforma; chave sem 44 dígitos, modelo diferente de 65, dígito verificador errado, CNPJ diferente do da nota original ou chave igual à da original devolvem 400 e 10029845.
  • Sem chaveAcessoSubstituta devolve 400 e 10029909.

Aceito, devolve HTTP 200 sem corpo:

http
HTTP/1.1 200 OK
X-Tffiscal-Cancelamento: EnfileiradoLocal
  • Os valores do cabeçalho são os mesmos de Cancelamento. Com a nota substituta ainda não transmitida ou sem rede no momento, o valor é EnfileiradoLocal: o cancelamento fica na fila do computador e só é enviado depois que a nota substituta for transmitida com sucesso.
  • O resultado vem pelo callback nfce.canceled ou nfce.cancel_rejected, ou pela consulta da nota original. O prazo é o mesmo da nuvem.

Situação do Assistente

GET /openapi/local/v1/situacao devolve a situação das empresas que o token acessa, útil para mostrar avisos como «offline» e «N notas a transmitir» na tela do caixa:

json
{
"versaoNucleo": "1.0.0",
"empresas": [
{
"empresaId": "1934811222334455",
"dispositivoId": "1900000000000000001",
"situacao": "Ativo",
"conectado": false,
"ultimoContato": "2026-11-11T14:55:00Z",
"licencaExpiraEm": "2026-11-14T13:10:00Z",
"offlineAte": "2026-11-14T13:10:00Z",
"pendentesTransmissao": 3,
"pendenteMaisAntigaEm": "2026-11-11T13:02:00Z",
"prazoTransmissaoAte": "2026-11-12T13:02:00Z",
"certificadoValidoAte": "2027-03-01T00:00:00Z",
"ultimoErro": null,
"numerosNaoUtilizadosPendentes": 0,
"restauradoPendenteSincronizacao": false
}
],
"avisos": []
}
CampoDescrição
versaoNucleoVersão do núcleo
empresaId / dispositivoIdIdentificador da empresa e identificador do dispositivo
situacaoSituação do dispositivo. Valores em Valores de situação do dispositivo
conectadoConexão com a plataforma. true quando alcança a plataforma neste momento
ultimoContatoÚltimo contato. Data da última conexão bem-sucedida com a plataforma
licencaExpiraEmValidade da licença
offlineAtePrazo offline. Depois dele não dá mais para emitir offline
pendentesTransmissaoNotas a transmitir
pendenteMaisAntigaEmPendente mais antiga. Data de emissão da nota mais antiga a transmitir
prazoTransmissaoAtePrazo de transmissão. Prazo de transmissão da nota pendente mais antiga; depois dele o dispositivo não emite mais offline
certificadoValidoAteValidade do certificado
ultimoErroÚltimo erro. Descrição do último erro; null sem erro
numerosNaoUtilizadosPendentesFaixas de números não utilizados a informar. Quantidade de faixas de números não utilizados ainda a informar à plataforma para inutilização; se ficar acima de 0 e não cair por muito tempo, fale com a plataforma
restauradoPendenteSincronizacaoRestauração pendente de alinhamento. true depois de restaurar um backup e até chegar uma licença nova; nesse intervalo a emissão offline é recusada e a online sincroniza antes com a plataforma; false depois do alinhamento
avisosAvisos de execução. Problemas do ambiente de execução que precisam de um técnico; o texto vem em português e, sem avisos, é um array vazio; também aparecem no topo da página de visão geral do programa de desktop. Exemplo: a autenticação do proxy foi configurada, mas os parâmetros de inicialização do serviço do Assistente estão errados e a autenticação do proxy pode não funcionar; nesse caso, basta reinstalar o Assistente

Tratamento de erros

Erro de negócio em array:

json
[
{ "codigo": "10029817", "mensagem": "itens: obrigatório" },
{ "codigo": "10029817", "mensagem": "pedido.pagamento: obrigatório" }
]

Token ausente (HTTP 401), no envelope da plataforma:

json
{ "success": false, "errorType": 1, "code": 10029900, "message": "Token de caixa ausente (Authorization: Bearer tfl_...)" }
HTTPCódigo de erroCasoO que fazer
40110029900 / 10029901Token ausente / token inválido ou revogadoConfira o cabeçalho Authorization; com token revogado, o gerente gera outro
40310029902O token não tem acesso à empresaO gerente gera em «Integração com PDV» um token que inclua essa empresa
40310029903Origem fora das redes permitidas do modo rede localConfira as configurações do modo rede local
40410029801A empresa não está pareada neste AssistenteConfira o empresaId, ou adicione a empresa no assistente de instalação
40410029819A nota não existe neste computadorConfira o nfceId
40010029817Requisição inválida, um item por campo, inclusive campo obrigatório ausente e campo que não existe no contrato (nunca é ignorado em silêncio)Corrija conforme mensagem
40010029780Linha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumidoReenvie quando a rede voltar; sem rede, envie impostos nas linhas de item
40010029909Requisição inválida, por exemplo cancelamento por substituição sem a chave da nota substitutaCorrija conforme mensagem
40010029818O mesmo id já foi usado numa nota com conteúdo diferenteVenda nova com id novo; repetição com a requisição original; tratamento após rejeição em Tratamento após rejeição
40010029820 / 10029821A situação atual não permite correção / a correção alterou valores ou tributosSó Rejeitada pode ser corrigida, e só no que não envolve valores
40010029822A situação atual não permite cancelar (inclusive quando a situação local ainda não foi sincronizada e a plataforma recusa); no cancelamento por substituição, a nota original não é uma nota normal emitida onlineNão tente de novo
40010029845Chave da nota substituta inválida, ou não é uma nota offline não recusada deste dispositivo e desta empresaConfira a chave da nota substituta
40010029804 / 10029807Sem rede e licença vencida / prazo offline encerradoRestabeleça a rede; após renovar, volta sozinho
40010029808A 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
40010029810A nota pendente mais antiga passou do prazo de transmissãoRestabeleça a rede e transmita
40010029811A empresa ou o estado não permite emissão offlineSó é possível emitir com rede
40010029816Dispositivo desativadoFale com o integrador
40010029424A plataforma informa o número como já usado; o núcleo o descartou, tentou de novo uma vez e o conflito continuaExporte o pacote de diagnóstico e fale com a plataforma
40010029426O mesmo id já tem uma nota não rejeitada na plataforma, por exemplo emitida pela API em nuvemConfira a nota original; use um id novo para uma venda nova
40910029841XML autorizado indisponívelLeia depois da autorização; se não for possível recuperar, tente mais tarde
40910029843XML de cancelamento indisponívelLeia depois do cancelamento concluído; se não for possível recuperar, tente mais tarde
42910029918Limite de recuperações de XML simultâneas atingidoTente mais tarde
50010029912 / 10029836Erro interno do Assistente ou do núcleoExporte o pacote de diagnóstico em «Sobre e diagnóstico» e fale com o suporte técnico
50310029842Proteção contra downgrade: o diretório de dados foi usado por uma versão mais novaInstale um pacote de versão igual ou superior à indicada, sem apagar o diretório de dados; veja Proteção contra downgrade

A lista completa está em Códigos de erro. Os códigos de erro da plataforma e da SEFAZ são repassados sem alteração.

6 Checklist antes da produção

Instalação e pareamento:

  • O código de pareamento tem formaPermitida igual a Assistente ou Qualquer; ele vale 72 horas e só pode ser usado uma vez.
  • O CNPJ do certificado escolhido é o da empresa; o certificado do repositório já deu à conta do serviço acesso à chave privada.
  • O PIN do gerente foi definido e está com o gerente; em computador compartilhado, recomenda-se ligar «Exigir PIN para emitir» em «Configurações».

Integração do PDV:

  • Cada caixa tem seu próprio token de caixa, e o token e o segredo de callback foram guardados com cuidado na geração (só aparecem uma vez).
  • O endereço da interface é http://127.0.0.1:8765 ou, no modo rede local, o endereço do computador do Assistente na rede local; toda requisição leva Authorization: Bearer tfl_….
  • Cada venda usa um id único, e a repetição da mesma venda usa o mesmo id; ambienteEmissao é igual ao ambiente do pareamento do dispositivo.
  • O PDV trata HTTP 202 com AguardandoAutorizacao, ContingenciaPendente e os três tipos de rejeição distinguidos por situacaoLocal, veja Tratamento após rejeição.
  • Quando a nota offline volta, o cupom é impresso na hora e entregue ao consumidor, como está.
  • O tempo limite do download de XML não é menor que cerca de 30 segundos; com 429 e 10029918, tente mais tarde.

Recebimento dos resultados:

  • Com callback local: valide a assinatura com o segredo de callback whsec_…, deduplique por X-Tffiscal-Event-Id e responda 2xx em até 5 segundos.
  • Sem callback: consulte de tempos em tempos as notas com situação indefinida, até a situação se definir.
  • A tela do caixa pode chamar GET /openapi/local/v1/situacao para mostrar as notas a transmitir, com atenção a prazoTransmissaoAte e avisos.

Ambiente de execução:

  • Se a loja acessa a internet por proxy, o proxy de saída já está configurado em «Configurações».
  • No modo rede local, um administrador já executou o script de liberação do firewall.
  • O gerente sabe que o diretório de dados %ProgramData%\TFFiscal\Assistente\ guarda os originais com valor legal das notas offline não transmitidas, que não podem ser apagados nem copiados para outro computador; quando preciso, use «Exportar pacote de pendentes» e «Backup».

7 Implantação e operação

Implantação em lote

Vários computadores podem ser instalados e pareados em modo silencioso pelo MSI; se o pareamento falhar, a instalação é revertida. A senha do PFX e o PIN do gerente não vão na linha de comando (qualquer usuário do computador vê a linha de comando na lista de processos); eles ficam antes num arquivo de segredos.

Primeiro passo: o administrador gera o arquivo de segredos num PowerShell com privilégios elevados. O script pede o PIN e a senha do PFX por entrada segura; quando o certificado for um que já está no repositório de certificados, acrescente -SemPfx e só o PIN é pedido:

powershell
& "C:\Program Files\TFFiscal\Assistente\scripts\preparar-segredos.ps1"
  • O arquivo de segredos é sempre gerado no diretório protegido %ProgramData%\TFFiscal\deploy, com o nome padrão segredos.json, ou seja, C:\ProgramData\TFFiscal\deploy\segredos.json; para outro nome de arquivo use -Nome.
  • O script primeiro cria ou restringe esse diretório, permitindo acesso só a SYSTEM e Administrators, e então cria o arquivo já com permissões restritas. O conteúdo do arquivo é um JSON UTF-8 {"pin":"…","pfxSenha":"…"}.
  • No pareamento, o proprietário e as permissões de acesso do arquivo de segredos e do seu diretório são conferidos e, fora do exigido, o pareamento falha: o arquivo de segredos precisa ficar nesse diretório; copiado para outro diretório (por exemplo C:\deploy), ele é recusado.
  • O arquivo de segredos é sobrescrito e apagado logo depois da leitura, com sucesso ou não no pareamento, por isso é preciso gerá-lo de novo a cada nova execução da instalação.

Segundo passo: instalação silenciosa:

bat
msiexec /i TfFiscalAssistente-{versao}-x64.msi /qn /l*v instalar.log ^
TFA_FILE="C:\deploy\loja.tfa" PFX_FILE="C:\deploy\certificado.pfx" SECRETS_FILE="C:\ProgramData\TFFiscal\deploy\segredos.json"
PropriedadeObrigatórioDescrição
TFA_FILEObrigatório para parearCaminho do arquivo do código de pareamento. Sem ela é uma instalação comum e o gerente faz depois o assistente de instalação
PFX_FILEUma das duas linhasCaminho do arquivo do certificado PFX. A senha vem de pfxSenha no arquivo de segredos
CERT_THUMBPRINTUma das duas linhasImpressão digital do certificado existente. Pode vir com CERT_STORE, padrão LOCAL_MACHINE; exige rodar antes o script de acesso à chave privada
SECRETS_FILEObrigatório para parearCaminho do arquivo de segredos. Precisa estar em %ProgramData%\TFFiscal\deploy; contém pin (6 a 8 dígitos) e, com PFX, também pfxSenha
  • As propriedades antigas PFX_PASSWORD e ADMIN_PIN não são mais aceitas; se forem informadas, a instalação falha.
  • A instalação silenciosa exige que o computador já tenha o runtime WebView2.
  • Se o pareamento falhar por falta de conexão com a plataforma, basta executar a instalação de novo com os mesmos parâmetros (gerando de novo o arquivo de segredos); não troque o código de pareamento.

O pareamento silencioso tem duas situações, conforme o computador já tenha concluído a instalação ou não; vale tanto para a instalação silenciosa pelo MSI quanto para o comando de pareamento abaixo:

SituaçãoQuando ocorreO que o pareamento fazpin no arquivo de segredos
Primeira instalaçãoO computador ainda não concluiu nenhuma instalaçãoPareia direto; o pin passa a ser o PIN do gerenteO novo PIN do gerente, de 6 a 8 dígitos
Adicionar empresa depois de instaladoExecução com a instalação já concluída: reinstalação depois de desinstalar (o diretório de dados é mantido), instalação de versão nova por cima, ou o comando de pareamento num computador já instaladoPrimeiro abre a sessão de gerente com o pin e depois pareia, ou seja, adiciona uma empresa; as empresas já pareadas não são afetadasPrecisa ser o PIN de gerente atual; se estiver errado, o código de saída é 1 e o PIN do gerente não muda

Nas duas situações, com certificado PFX o arquivo de segredos também precisa conter pfxSenha. «Reparar» ou «Alterar» o MSI da mesma versão não dispara o pareamento silencioso; para adicionar empresa num computador já instalado, use direto o comando de pareamento abaixo.

Num computador com o Assistente já instalado, o administrador também pode executar direto o comando de pareamento (o serviço precisa estar rodando):

bat
"C:\Program Files\TFFiscal\Assistente\runtime\bin\java.exe" -cp "C:\Program Files\TFFiscal\Assistente\app\*" ^
com.tffiscal.nfce.assistant.AssistantMain ativar --arquivo C:\deploy\loja.tfa --pfx C:\deploy\certificado.pfx --segredos C:\ProgramData\TFFiscal\deploy\segredos.json
  • Com um certificado do repositório de certificados, troque --pfx por --thumbprint {thumbprint} e, se quiser, acrescente --store LOCAL_MACHINE ou --store CURRENT_USER.
  • --segredos - lê o JSON de segredos da entrada padrão, sem gravar em disco.
  • Executado num computador com a instalação concluída, ele adiciona uma empresa, e o pin do arquivo de segredos precisa ser o PIN de gerente atual; também é possível adicionar pelo assistente de instalação no programa de desktop.
Código de saídaSignificadoO que o script de implantação faz
0Pareamento concluídoNada
1Pareamento recusadoTrate conforme o código de erro na saída padrão
2Parâmetro errado, arquivo de segredos fora do exigido ou serviço inacessívelCorrija os parâmetros e o arquivo de segredos e rode de novo
3Pode tentar de novo com o mesmo código de pareamentoRode de novo o mesmo comando sem mudanças; não troque o código de pareamento

Atualização, desinstalação e diretório de dados

  • Atualização: instale a nova versão por cima; os dados locais são mantidos.
  • Diretório de dados: %ProgramData%\TFFiscal\Assistente\. Antes da transmissão, os arquivos assinados das notas offline só existem aqui e são o único original com valor legal; a desinstalação mantém o diretório de dados, não o apague à mão nem o copie para usar em outro computador.
  • Depois de renovar o certificado, use «Trocar certificado» em «Configurações» com o PIN do gerente; a identidade do dispositivo não muda.
  • Quando a versão mínima exigida pela plataforma é maior que a versão instalada, a Visão geral avisa para atualizar; até a atualização a situação do dispositivo é VersaoBloqueada e não dá para emitir notas novas.

Proteção contra downgrade

Depois que o diretório de dados foi usado por uma versão mais nova do Assistente, se uma versão antiga for instalada de novo, ela não inicia o núcleo de emissão, para não danificar os dados locais. Nesse caso o Assistente entra no modo de falha na inicialização:

  • O serviço em segundo plano não encerra e só escuta no endereço de loopback; reiniciar o computador ou o serviço não resolve.
  • A interface de desktop mostra uma página de bloqueio com a versão mínima a instalar e a versão atual.
  • Toda a interface local devolve HTTP 503:
json
[ { "codigo": "10029842", "mensagem": "… Instale o Assistente Fiscal na versão 1.4.0 ou superior …" } ]

O que fazer: instale um pacote de versão igual ou superior à indicada. Nunca apague o diretório de dados: ele pode ter notas offline ainda não transmitidas.

Modo rede local

Para um Assistente atender vários caixas da mesma loja, o gerente liga o modo rede local em «Configurações»:

  • Ligado, o Assistente escuta em todas as placas de rede do computador e só aceita origens dentro das «Redes permitidas» (por padrão a rede /24 do próprio computador); fora delas devolve 403 e 10029903.
  • O instalador não libera o firewall sozinho: um administrador precisa executar o scripts\abrir-firewall-rede-local.ps1 -RedesPermitidas {redesPermitidas} da pasta de instalação, onde {redesPermitidas} são as redes permitidas, por exemplo 192.168.0.0/24.
  • Ligado ou não, toda requisição precisa do token de caixa.
  • Com o modo rede local desligado, o endereço de callback só pode ser de loopback do próprio computador; endereços da rede local só depois de ligá-lo.

Vários caixas na mesma loja

Quando a loja tem vários caixas, instale um único Assistente Fiscal para a loja inteira, num computador do escritório ou em um dos caixas; os outros caixas o chamam pela rede local:

  1. Instale e pareie um Assistente: conclua o assistente de instalação como em Instalação e pareamento. A loja inteira usa um código de pareamento e ocupa uma vaga de dispositivo.
  2. Ligue o modo rede local: o gerente liga em «Configurações» no computador do Assistente. Vem desligado, e então o Assistente só escuta o próprio computador, e os outros computadores da rede não conseguem conectar; ligado, ele escuta todas as placas de rede e só aceita origens das redes permitidas, por padrão a rede /24 do computador do Assistente. Firewall e redes permitidas em Modo rede local.
  3. Um token de caixa por caixa: na página «Integração com PDV» o gerente gera um token para cada caixa (começa com tfl_), com o nome do caixa, por exemplo PDV 01, PDV 02; esse nome é a identificação do caixa terminal nas notas que ele emite, presente nas respostas da interface local, na consulta em nuvem e nos webhooks. Para receber callbacks, o endereço de callback é o endereço de rede local daquele caixa. Se um caixa for perdido ou desativado, revogue só o token dele; os outros caixas não são afetados.
  4. Aponte o software de PDV para o endereço de rede do Assistente: troque o endereço da interface de http://127.0.0.1:8765 pelo endereço de rede local do computador do Assistente, por exemplo http://192.168.0.10:8765, com o token daquele caixa no cabeçalho. A interface e as chamadas são as mesmas da instalação num só computador, veja Operações.

Resultado:

  • A loja inteira compartilha a série deste único dispositivo; as notas de todos os caixas têm numeração contínua, tirada em ordem pelo Assistente, sem colisão.
  • Sem internet mas com a rede local funcionando, todos os caixas continuam emitindo: o Assistente assina offline e transmite sozinho quando a conexão volta.
  • O programa de desktop (PIN de gerente, emissão simples, exportação e backup etc.) só abre no próprio computador do Assistente; os outros caixas usam só a interface local.

Cuidados:

  • O computador do Assistente é ponto único de falha: desligado, sem energia ou fora da rede, nenhum caixa emite, e as notas offline já emitidas esperam ele voltar para serem transmitidas. Mantenha-o sempre ligado; recomenda-se nobreak.
  • A rede local precisa funcionar: se a rede ou o switch entre um caixa e o computador do Assistente falhar, aquele caixa não alcança o Assistente e não emite.
  • Alternativa de contingência: instale outro Assistente em um segundo computador e pareie-o com um código de pareamento novo. Ele é outro dispositivo, com série e numeração próprias, e precisa de tokens de caixa próprios. Se o computador principal falhar, o software de PDV passa para o endereço e os tokens do reserva e continua emitindo; as notas já emitidas no principal continuam sendo consultadas e transmitidas nele e, se ele não tiver conserto, exporte o pacote de pendentes como em «Exportação e backup» de Configurações e manutenção do programa de desktop e entregue à plataforma.

Comparação com o SDK embarcado: com o SDK embarcado cada caixa é, por padrão, pareado como um dispositivo, com série própria, numeração contínua dentro de cada série e independente das outras. A legislação só exige numeração contínua dentro de uma mesma série, então várias séries na mesma loja são igualmente regulares. O SDK não tem ponto único de falha, mas cada caixa precisa do certificado e ocupa uma vaga de dispositivo. O SDK também pode usar uma só série para a loja toda no modo principal e secundário, veja Vários caixas (modo principal e secundário).

Configurações e manutenção do programa de desktop

Todas as funções abaixo são usadas no programa de desktop, no próprio computador do Assistente.

Detalhes da nota

A página de detalhes da nota mostra a nota, o QR Code e a linha do tempo da situação (assinatura offline, transmissão, autorização ou rejeição, correção) e oferece:

  • «Baixar XML» (XML autorizado) e «XML do cancelamento». Se não estiverem no computador, o Assistente os recupera da plataforma em até cerca de 30 segundos; espere o carregamento terminar e não clique de novo.
  • «Cupom em PDF» e «Baixar imagem» do QR Code.
  • Cancelamento por substituição: aparece quando a nota original é uma nota normal emitida online e autorizada, e exige o PIN do gerente; a nota substituta é escolhida entre as notas offline do dia, com as regras de Cancelamento por substituição.

Proxy de saída

Quando a rede da loja só acessa a internet por proxy, o gerente configura o proxy de saída em «Configurações»; as conexões do Assistente com a plataforma e com a SEFAZ passam todas por ele:

ItemDescrição
Conexão com a internetDireta (padrão), Proxy manual ou Proxy do Windows. O Proxy do Windows usa a configuração de proxy do Windows; scripts de configuração automática PAC não são suportados e, nesse caso, a conexão é direta
EndereçoEndereço do servidor proxy. Formato host:porta, obrigatório no modo manual; sem porta, usa 8080
UsuárioUsuário de autenticação do proxy. Em branco, sem autenticação, e a senha salva é apagada
SenhaSenha de autenticação do proxy. Só escrita: depois de salva não aparece mais, e em branco significa não alterar; é guardada criptografada, fora dos logs e do pacote de diagnóstico
Não usar proxy paraHosts que não passam pelo proxy. Separados por ;, aceita *.domínio e <local>
  • Depois de salvar, o Assistente reinicia o núcleo de emissão com o novo proxy para que a mudança valha; isso leva alguns segundos, e as emissões que chegam nesse intervalo esperam na fila, sem se perder; se o núcleo não subir com o novo proxy, a configuração anterior volta sozinha.
  • Ao mudar o modo, o endereço ou o usuário, é obrigatório digitar a senha de novo.
  • Com configuração inválida, a interface avisa e mostra o código de erro 10029919, e a configuração não muda.
  • Se houver exportação, backup ou download de XML em andamento que não termine em 15 segundos, aparece o código de erro 10029920 e a configuração não muda; salve de novo depois que essas operações terminarem.

Cupom impresso

A seção «Cupom impresso» de «Configurações» vale só para os cupons que o próprio Assistente imprime (emissão simples, reimpressão, pré-visualização nos detalhes), e não afeta o cupom que o PDV obtém pela interface local:

ItemValores
Colunas por linha48, 42, 32, ou o padrão da largura do papel
Página de código da impressoraCP1252 (padrão), CP860, CP850, CP437; caracteres que não existem na página de código são impressos sem acento
QR CodeComando da impressora: usa o comando de QR Code da própria impressora (padrão); Imagem: imprime como bitmap, para impressoras antigas que não reconhecem o comando de QR Code
Cortar o papel após imprimirSe o papel é cortado depois da impressão
ViasQuantidade de vias por impressão, ou conforme a regra do estado; a nota offline usa o número de vias configurado pela plataforma

Exportação e backup

A página «Sobre e diagnóstico» oferece três downloads e a restauração a partir de um backup, todos com o PIN do gerente; os arquivos baixados são salvos no local do computador escolhido pelo gerente. Só uma exportação ou um backup pode rodar por vez; com outro em andamento, a interface pede para tentar mais tarde (código de erro 10029918). Quando o disco do diretório de dados do Assistente tem menos de 256 MB livres, exportação, backup e upload do arquivo de backup são recusados (código de erro 10029922); libere espaço no disco antes de repetir a operação.

FunçãoConteúdoUso
Exportar XMLEscolha a empresa e o período de emissão (até 31 dias) e receba um zip: XMLs autorizados, XMLs de cancelamento e uma lista das notas que não puderam ser obtidas, com o motivo; dá para marcar «Somente deste computador» para exportar só os XMLs já presentes no computador, sem buscar na plataformaEntregar ao contador todo mês
Exportar pacote de pendentesTodas as notas offline assinadas e ainda não transmitidas de todas as empresas, em zip; o pacote é dividido em diretórios por dispositivo, com até 500 notas por pacote, e a plataforma pode importá-lo diretamenteEntregar à plataforma para transmissão em nome da loja quando o computador quebrou e não deu tempo de transmitir
BackupCópia completa e criptografada da base local do núcleo de emissão; o gerente define uma senha de backup com pelo menos 8 caracteres (digitada duas vezes)Recuperação de dados no mesmo computador
Restaurar backupEscolha e envie o arquivo de backup (até 4 GB) e depois informe a senha do backup; a base local atual é substituída pelo backupRecuperar a base local depois de perdida ou corrompida

Exportação:

  • Na exportação de XML, os XMLs que não estão no computador são recuperados da plataforma um a um; com muitos, leva alguns minutos; espere terminar. Se a plataforma não estiver acessível, as notas restantes não ficam esperando e entram direto na lista das que não puderam ser obtidas.
  • O pacote de pendentes contém os originais assinados com valor legal; guarde-o com cuidado. A exportação não impede o computador de continuar transmitindo.

Backup:

  • A senha do backup não fica guardada em lugar nenhum: sem a senha, o backup não pode ser restaurado. Guarde-a separada do arquivo de backup. Durante o backup, a emissão continua normalmente.
  • O backup só pode ser restaurado no mesmo computador (a chave do dispositivo fica presa ao computador). Para trocar de computador é obrigatório parear de novo, e as notas não transmitidas são tratadas com «Exportar pacote de pendentes».

Restauração do backup:

  • Restaurar o backup exige o PIN do gerente. A restauração substitui a base local atual, e a base original é guardada automaticamente no diretório de dados; com senha errada ou arquivo de backup alterado ou corrompido, aparece o código de erro 10029846, a base original fica inalterada e o Assistente continua funcionando normalmente. O arquivo de backup enviado é apagado com sucesso ou não na restauração; para tentar de novo, escolha o arquivo outra vez.
  • Durante a restauração o Assistente reinicia o núcleo de emissão, o que leva alguns segundos; as requisições de emissão que chegarem nesse intervalo ficam na fila. Se ainda houver exportação, backup ou download de XML em andamento, o Assistente espera até 15 segundos; se não terminarem, a restauração não é feita e aparece o código de erro 10029920; clique em restaurar de novo depois que essas operações terminarem.
  • As notas offline emitidas depois do backup não estão nele: se o Assistente ainda funciona normalmente, exporte o pacote de pendentes e entregue à plataforma antes de restaurar.
  • Depois da restauração, cada empresa primeiro se realinha com a plataforma: até lá não emite offline, e a emissão online sincroniza uma vez 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, que são inutilizados automaticamente, e a emissão online e offline volta ao normal, para não repetir números de notas emitidas depois do backup. Até o realinhamento terminar não dá para emitir sem alcançar a plataforma.

8 Sem sistema de caixa: emissão simples

Lojas pequenas sem sistema de caixa podem usar direto a página «Emitir» do programa de desktop:

  • Leia o código de barras com o leitor, ou busque em «Produtos» por código ou nome; ou use o «Produto rápido», só com descrição e valor, e os dados fiscais do grupo tributário padrão das configurações.
  • Na lista de compras dá para mudar quantidade, aplicar desconto na linha e excluir; o total é calculado na hora.
  • Pagamento em dinheiro (com troco calculado), cartão de débito, cartão de crédito, PIX e outras formas; acima do limite de identificação do estado é obrigatório informar CPF ou CNPJ do consumidor.
  • Ao confirmar, mostra o resultado (autorizada ou offline aguardando transmissão) e imprime sozinho; a nota offline sai com o número de vias configurado pela plataforma.
  • Atalhos: F2 nova venda, F4 ir para o pagamento, F8 emitir e imprimir, Esc voltar / cancelar a venda; a página toda pode ser usada só pelo teclado.

A página «Produtos» mantém código, nome, código de barras, NCM, CFOP, unidade, preço e grupo tributário de cada produto; os dados fiscais do produto têm a mesma estrutura de itens[].impostos da requisição de emissão.

A página de emissão abre por padrão em modo caixa, sem PIN; em «Configurações» a opção «Exigir PIN para emitir» passa a exigir o PIN do gerente. Com isso desligado, qualquer pessoa no mesmo computador pode emitir e ver as notas do dia; em computador compartilhado recomenda-se ligar.

As vendas da emissão simples aparecem em «Notas do dia» junto com as notas do PDV:

  • A página de emissão gera para cada venda um número no formato PDV-{yyyyMMdd}-{8 caracteres alfanuméricos}; ao repetir a mesma venda o número original é mantido, e o Assistente devolve a nota original sem emitir de novo.
  • Quando a requisição vem sem número de venda, o Assistente gera um no formato PDV-{yyyyMMdd}-{sequência} e pula sozinho os números já ocupados.

Quando a emissão é rejeitada, clique em «Voltar à venda»; há dois caminhos conforme o tipo de rejeição:

  • Rejeição na transmissão (Rejeitada): o número está ocupado; segue a correção com o mesmo número, com o PIN do gerente.
  • Rejeição online ou recusa da plataforma (Negada / Recusada): o número não tem efeito; depois de corrigir, emita como venda nova, com número de venda novo.

A página «Notas do dia» filtra por data e situação e, para cada nota, oferece «Ver», «Imprimir», «Cancelar» e «Corrigir» (este só quando rejeitada na transmissão); um clique abre os detalhes da nota, veja Configurações e manutenção do programa de desktop.

Perguntas frequentes

O assistente de instalação diz que o código de pareamento é inválido ou venceu?

O código vale 72 horas e só pode ser usado uma vez. Códigos vencidos, já usados ou cancelados não servem mais; peça ao integrador para gerar outro código.

No pareamento aparece que o CNPJ do certificado não confere com a empresa?

O CNPJ do certificado escolhido precisa ser o da empresa. Quando um computador atende vários CNPJ, gere um código de pareamento para cada empresa e escolha o certificado correspondente no assistente de instalação.

A interface local devolve 401 para o PDV?

O cabeçalho precisa ser Authorization: Bearer tfl_…. O token só aparece uma vez; se foi perdido ou revogado, o gerente gera outro em «Integração com PDV».

Sem rede aparece licença vencida?

A emissão offline tem limite de tempo, renovado sozinho com a rede de volta. Ficar sem rede tempo demais dispara esse aviso; restabeleça a rede.

As notas offline não são transmitidas?

A transmissão precisa do serviço do Assistente rodando e com acesso à plataforma. Veja na Visão geral a situação da conexão e a data de «Mais antiga a transmitir»; se a loja acessa a internet por proxy, confira a configuração do proxy de saída (veja Configurações e manutenção do programa de desktop); também dá para fazer uma consulta pelo PDV ou clicar em «Sincronizar agora» no programa.

Como trocar o computador da loja?

Primeiro deixe o computador antigo transmitir as notas offline com rede («A transmitir» em 0 na Visão geral), depois o integrador desativa o dispositivo antigo e gera um código de pareamento novo para o computador novo. Não copie o diretório de dados para o computador novo: a chave do dispositivo fica presa ao computador e não funciona em outro.

Se o computador antigo quebrou e não deu tempo de transmitir: desde que o Assistente ainda abra, exporte o pacote de pendentes em «Sobre e diagnóstico» (veja Configurações e manutenção do programa de desktop) e entregue o arquivo zip como está (sem descompactar) à operação da plataforma, que faz a importação e a transmissão. O pacote já vem dividido por dispositivo, com até 500 notas por pacote, e não precisa ser dividido de novo; a importação continua possível depois que o dispositivo antigo for desativado.

O PIN foi bloqueado depois de erros?

A cada 5 erros acumulados há um bloqueio: o primeiro dura 5 minutos e cada bloqueio seguinte dobra de duração, até 24 horas. Durante o bloqueio até o PIN certo é recusado; ao fim do bloqueio a contagem de erros não zera, e só zera quando o PIN é digitado certo uma vez.

O que enviar ao suporte técnico?

Exporte o pacote de diagnóstico em «Sobre e diagnóstico». Ele tem situação e logs, sem chaves privadas, tokens, segredo de callback nem PIN.

Valores de situação do dispositivo

situacaoSignificadoAção
AtivoPode emitirNada
DesativadoO integrador desativou o dispositivoNão volta; para continuar usando o mesmo computador, pareie de novo
RevogadoA plataforma revogou o dispositivoFale com a plataforma
EmpresaDesativadaEmissão offline da empresa desativadaFale com a plataforma
AplicativoBloqueadoSoftware do PDV bloqueado pela plataformaFale com a plataforma
VersaoBloqueadaA versão do PDV foi bloqueada ou está abaixo da mínimaAtualize o Assistente Fiscal

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

Valores de situação da nota

situacaoLocal e status nas respostas da interface local. status usa os valores da nuvem; situacaoLocal mantém a situação local completa.

situacaoLocalstatusSignificadoAparece em
AutorizadaAutorizadaAutorizada pela SEFAZ, online ou depois da transmissão da nota offlineEmissão, consulta
ContingenciaPendenteContingenciaPendenteAssinada offline neste computador, aguardando transmissãoEmissão, consulta, correção
AguardandoAutorizacaoAguardandoAutorizacaoAceita online, a SEFAZ ainda não respondeu e não foi possível assinar offline naquele momento; a emissão devolve HTTP 202Emissão, consulta
NegadaNegadaEmissão online rejeitada pela SEFAZ, inclusive depois de resultado online pendente; não pode ser corrigida com o mesmo númeroEmissão, consulta
RejeitadaNegadaTransmissão da nota offline rejeitada pela SEFAZ; corrija com o mesmo número, veja Tratamento após rejeiçãoConsulta, correção
RecusadaNegadaA plataforma recusou esta nota offline; exige intervenção manualConsulta
CanceladaCanceladaCancelada, inclusive por substituiçãoConsulta