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.
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
| Item | Descrição |
|---|---|
| Computador | Windows, o mesmo do PDV; para um Assistente atender vários caixas veja Modo rede local |
| Permissão | A instalação exige permissão de administrador |
| Instalador | TfFiscalAssistente-{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 pareamento | Gerado pelo integrador em Gerar código de pareamento, com formaPermitida Assistente ou Qualquer; vale como texto ou arquivo .tfa |
| Certificado | Certificado 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.
| Etapa | Conteúdo |
|---|---|
| 1 Boas-vindas | Escolha 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 pareamento | Cole 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 Certificado | Lista 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 gerente | Defina 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 Parear | Pareia 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ído | Mostra 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 callbackwhsec_…, 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
| Item | Valor |
|---|---|
| Endereço | http://127.0.0.1:8765; no modo rede local, o endereço do computador do Assistente na rede local |
| Autenticação | Cabeçalho Authorization: Bearer tfl_…; sem os token / timestamp / sign da nuvem |
| Tipo de conteúdo | Content-Type: application/json |
Operações
| Método | Caminho | Uso | Equivalente na nuvem |
|---|---|---|---|
| POST | /openapi/v2/empresas/{empresaId}/nfce | Emitir | Emitir NFC-e |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId} | Consultar | Consultar NFC-e |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar | Cancelar | Cancelar NFC-e |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cancelar-substituicao | Cancelamento por substituição | Cancelar por substituição |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/cupom?formato=ESCPOS_80 | Cupom, inclusive em PDF | Só local |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml | Download do XML autorizado | Só local |
| GET | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/xml-cancelamento | Download do XML de cancelamento | Só local |
| POST | /openapi/v2/empresas/{empresaId}/nfce/{nfceId}/correcao | Correção com o mesmo número depois de rejeição na transmissão | Só local |
| GET | /openapi/local/v1/situacao | Situação do Assistente | Só local |
Diferenças em relação à nuvem
- Autenticação: token de caixa, veja Endereço e autenticação.
modoRespostanã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 comAguardandoAutorizacao. 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 e10029780, indicando enviarimpostos, sem consumir número. O Assistente não guarda classes de imposto, então para a contingência o programa de caixa precisa guardar osimpostosexpandidos, 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 e10029801, token sem acesso devolve 403 e10029902.- Links do cupom e do XML:
linkDanfeaponta para o cupom local (formato HTML);linkDownloadXmlaponta 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.
| Campo | Descrição |
|---|---|
situacaoLocal | Situaçã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 / xMotivo | Código e mensagem de resultado da SEFAZ. Vêm juntos; null em nota offline pendente e em recusa da plataforma |
tentativaOnline | Tentativa 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 |
transmitida | Transmitida. Só na consulta |
cancelamentoPendente | Cancelamento pendente. Só na consulta; true para cancelamento pedido antes da autorização da nota offline |
correcoes | Número de correções. Só na consulta |
xmlAutorizadoDisponivel | XML autorizado disponível. Só na consulta; true indica que já foi baixado para o computador |
terminal | Identificaçã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
| Caso | HTTP | Corpo |
|---|---|---|
| Emissão, consulta ou correção com sucesso | 200; pendente online 202 | Objeto sem envelope com a mesma estrutura da consulta em nuvem, mais os campos locais |
| Cancelamento ou cancelamento por substituição aceito | 200 | Sem corpo; o destino vem no cabeçalho X-Tffiscal-Cancelamento |
| Download de cupom ou XML com sucesso | 200 | O arquivo original; o tipo está em Cupom e download de XML |
| Erro de negócio | 400; nota ou empresa inexistente 404; XML indisponível 409; Assistente ocupado 429; erro interno 500; proteção contra downgrade 503 | Array [{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 origem | 401 / 403 | Envelope 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:
POST /openapi/v2/empresas/1934811222334455/nfce HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-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" } }}]}
| Campo | Preenchimento |
|---|---|
id | Nú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 |
ambienteEmissao | Ambiente de emissão. Obrigatório; igual ao ambiente do pareamento do dispositivo |
pedido, itens | Pedido e itens. Obrigatórios; mesmas regras de Emitir NFC-e |
cliente | Consumidor. Opcional; não preencha quando o consumidor não se identifica |
modoResposta | Modo 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:
{"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:
{"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=trueindica 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, vemfalse.- 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_issuede depoisnfce.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:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131 HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
Depois da autorização na transmissão:
{"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"}
emitidaEmContingenciacontinuatruedepois da autorização.- O XML autorizado é baixado sozinho pelo Assistente depois da autorização na transmissão; com
xmlAutorizadoDisponivel=falsetambé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-Event | Quando | nfeStatus |
|---|---|---|
nfce.contingency_issued | Nota assinada offline no computador | ContingenciaPendente |
nfce.authorized | Autorizada na transmissão, depois de correção, ou depois de pendente online | Autorizada |
nfce.rejected | Nota offline rejeitada pela SEFAZ na transmissão, ou nota pendente online rejeitada depois pela SEFAZ | Negada, nfeMotivoStatus com código e motivo |
nfce.canceled | Cancelamento concluído, inclusive por substituição | Cancelada |
nfce.cancel_rejected | Cancelamento recusado | CancelamentoNegado |
nfce.intake_rejected | Só local: a plataforma recusou esta nota offline | Recusada, nfeMotivoStatus com código de erro da plataforma e motivo; fale com a plataforma |
nfce.device.deactivated | Só local: dispositivo desativado ou revogado | Payload 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
POST {callbackUrl}Content-Type: application/json; charset=utf-8X-Tffiscal-Event: nfce.contingency_issuedX-Tffiscal-Event-Id: 7b0c1d9e-2a52-4e0f-9a3e-5d2f1c0b8a77X-Tffiscal-Delivery-Id: 0f5f8d0c-9a4b-4b3d-8c0e-61f2b7d4a913X-Tffiscal-Timestamp: 1762786800X-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:
| Entrada | Valor |
|---|---|
| Segredo de callback | whsec_testsecret |
X-Tffiscal-Timestamp | 1762790400 |
| Corpo | {"tipo":"NFC-e","nfeId":"PDV-1"} |
| Assinatura esperada | 415bce74a6740037c540f3839e69a08bd3026c8337dd49c73e8a4877889de0a4 |
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:
{"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:
{"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ção | Como fazer | Detalhes |
|---|---|---|
| Tratar uma nota rejeitada | Conforme situacaoLocal: Rejeitada corrige com o mesmo número; Negada / Recusada emite de novo com um id novo | Tratamento após rejeição |
| Imprimir o cupom, baixar o XML | GET …/cupom?formato=…, GET …/xml, GET …/xml-cancelamento | Cupom e download de XML |
| Cancelar uma nota | POST …/cancelar, e veja o cabeçalho X-Tffiscal-Cancelamento | Cancelamento |
| A mesma venda gerou duas notas | POST …/cancelar-substituicao, que cancela a nota original online e aponta a nota offline substituta | Cancelamento por substituição |
| Mostrar na tela do caixa «offline» e notas a transmitir | GET /openapi/local/v1/situacao | Situação do Assistente |
| Tratar erros | Conforme o status HTTP e o código de erro | Tratamento de erros |
Tratamento após rejeição
Toda nota rejeitada tem status igual a Negada; o tratamento depende de situacaoLocal:
situacaoLocal | Significado | O que fazer |
|---|---|---|
Rejeitada | Nota offline rejeitada pela SEFAZ na transmissão. A nota já foi entregue ao consumidor e o número está ocupado | Corrija com o mesmo número e transmita de novo; não emita outra nota; veja abaixo |
Negada | Rejeitada online pela SEFAZ, inclusive depois de pendente online. A plataforma inutiliza o número; ele não é reaproveitado | Corrija a requisição e emita de novo com um id novo |
Recusada | A plataforma recusou esta nota offline. O número não tem efeito | Fale 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):
{"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:
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/correcao HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-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 deRejeitadadevolve10029820. - No sucesso volta HTTP 200 com a mesma estrutura da resposta de Emissão sem rede, e
situacaoLocalvolta aContingenciaPendente, aguardando nova transmissão.
Cupom e download de XML
Ao pedir o cupom, escolha o formato com formato:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cupom?formato=ESCPOS_80 HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
formato | Tipo de resposta | Uso |
|---|---|---|
ESCPOS_80 (padrão) | application/octet-stream | Impressora térmica de 80 mm; mande os bytes direto à impressora |
ESCPOS_58 | application/octet-stream | Impressora térmica de 58 mm |
TEXTO | text/plain; charset=utf-8 | Texto puro |
HTML | text/html; charset=utf-8 | Pré-visualização na tela ou impressão pelo navegador |
PDF_80 | application/pdf | PDF 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:
GET /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/xml HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7t
| Operação | Retorno | Quando indisponível |
|---|---|---|
GET …/xml | XML autorizado original, application/xml; charset=utf-8 | Ainda não autorizada, ou ausente no computador e não recuperável da plataforma: 409 e 10029841 |
GET …/xml-cancelamento | XML de cancelamento original, application/xml; charset=utf-8 | Ainda 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:
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000131/cancelar HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-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:
| Valor | Significado |
|---|---|
Solicitado | Enviado à plataforma; o resultado vem pelo callback ou pela consulta |
Agendado | A 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 |
EnfileiradoLocal | Fila local: sem rede, ou a nota offline / substituta ainda não foi transmitida; logo após a transmissão, é enviado na mesma rodada |
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:
POST /openapi/v2/empresas/1934811222334455/nfce/PDV01-000130/cancelar-substituicao HTTP/1.1Host: 127.0.0.1:8765Authorization: Bearer tfl_3q8Zr0k1LxV7mN2pQ9sT4uW6yA8cE1gH5jK0bD3fR7tContent-Type: application/json{"chaveAcessoSubstituta": "35261111222333000181650020000004219123456783","justificativa": "Venda registrada em contingencia off-line"}
| Campo | Preenchimento |
|---|---|
nfceId (caminho) | Número da nota original. A nota emitida online que será cancelada |
chaveAcessoSubstituta | Chave de acesso da nota substituta. Obrigatória, 44 dígitos; a nota offline que substitui a original |
justificativa | Justificativa 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
chaveAcessoSubstitutadevolve 400 e10029909.
Aceito, devolve HTTP 200 sem corpo:
HTTP/1.1 200 OKX-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.canceledounfce.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:
{"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": []}
| Campo | Descrição |
|---|---|
versaoNucleo | Versão do núcleo |
empresaId / dispositivoId | Identificador da empresa e identificador do dispositivo |
situacao | Situação do dispositivo. Valores em Valores de situação do dispositivo |
conectado | Conexã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 |
licencaExpiraEm | Validade da licença |
offlineAte | Prazo offline. Depois dele não dá mais para emitir offline |
pendentesTransmissao | Notas a transmitir |
pendenteMaisAntigaEm | Pendente mais antiga. Data de emissão da nota mais antiga a transmitir |
prazoTransmissaoAte | Prazo de transmissão. Prazo de transmissão da nota pendente mais antiga; depois dele o dispositivo não emite mais offline |
certificadoValidoAte | Validade do certificado |
ultimoErro | Último erro. Descrição do último erro; null sem erro |
numerosNaoUtilizadosPendentes | Faixas 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 |
restauradoPendenteSincronizacao | Restauraçã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 |
avisos | Avisos 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:
[{ "codigo": "10029817", "mensagem": "itens: obrigatório" },{ "codigo": "10029817", "mensagem": "pedido.pagamento: obrigatório" }]
Token ausente (HTTP 401), no envelope da plataforma:
{ "success": false, "errorType": 1, "code": 10029900, "message": "Token de caixa ausente (Authorization: Bearer tfl_...)" }
| HTTP | Código de erro | Caso | O que fazer |
|---|---|---|---|
| 401 | 10029900 / 10029901 | Token ausente / token inválido ou revogado | Confira o cabeçalho Authorization; com token revogado, o gerente gera outro |
| 403 | 10029902 | O token não tem acesso à empresa | O gerente gera em «Integração com PDV» um token que inclua essa empresa |
| 403 | 10029903 | Origem fora das redes permitidas do modo rede local | Confira as configurações do modo rede local |
| 404 | 10029801 | A empresa não está pareada neste Assistente | Confira o empresaId, ou adicione a empresa no assistente de instalação |
| 404 | 10029819 | A nota não existe neste computador | Confira o nfceId |
| 400 | 10029817 | Requisiçã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 |
| 400 | 10029780 | Linha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumido | Reenvie quando a rede voltar; sem rede, envie impostos nas linhas de item |
| 400 | 10029909 | Requisição inválida, por exemplo cancelamento por substituição sem a chave da nota substituta | Corrija conforme mensagem |
| 400 | 10029818 | O mesmo id já foi usado numa nota com conteúdo diferente | Venda nova com id novo; repetição com a requisição original; tratamento após rejeição em Tratamento após rejeição |
| 400 | 10029820 / 10029821 | A situação atual não permite correção / a correção alterou valores ou tributos | Só Rejeitada pode ser corrigida, e só no que não envolve valores |
| 400 | 10029822 | A 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 online | Não tente de novo |
| 400 | 10029845 | Chave da nota substituta inválida, ou não é uma nota offline não recusada deste dispositivo e desta empresa | Confira a chave da nota substituta |
| 400 | 10029804 / 10029807 | Sem rede e licença vencida / prazo offline encerrado | Restabeleça a rede; após renovar, volta sozinho |
| 400 | 10029808 | A série do dispositivo chegou ao número 999999999 | Desative o dispositivo e pareie-o de novo com um código de pareamento novo que informe outra série em serie; a plataforma não troca a série sozinha |
| 400 | 10029810 | A nota pendente mais antiga passou do prazo de transmissão | Restabeleça a rede e transmita |
| 400 | 10029811 | A empresa ou o estado não permite emissão offline | Só é possível emitir com rede |
| 400 | 10029816 | Dispositivo desativado | Fale com o integrador |
| 400 | 10029424 | A plataforma informa o número como já usado; o núcleo o descartou, tentou de novo uma vez e o conflito continua | Exporte o pacote de diagnóstico e fale com a plataforma |
| 400 | 10029426 | O mesmo id já tem uma nota não rejeitada na plataforma, por exemplo emitida pela API em nuvem | Confira a nota original; use um id novo para uma venda nova |
| 409 | 10029841 | XML autorizado indisponível | Leia depois da autorização; se não for possível recuperar, tente mais tarde |
| 409 | 10029843 | XML de cancelamento indisponível | Leia depois do cancelamento concluído; se não for possível recuperar, tente mais tarde |
| 429 | 10029918 | Limite de recuperações de XML simultâneas atingido | Tente mais tarde |
| 500 | 10029912 / 10029836 | Erro interno do Assistente ou do núcleo | Exporte o pacote de diagnóstico em «Sobre e diagnóstico» e fale com o suporte técnico |
| 503 | 10029842 | Proteção contra downgrade: o diretório de dados foi usado por uma versão mais nova | Instale 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
formaPermitidaigual aAssistenteouQualquer; 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:8765ou, no modo rede local, o endereço do computador do Assistente na rede local; toda requisição levaAuthorization: Bearer tfl_…. - Cada venda usa um
idúnico, e a repetição da mesma venda usa o mesmoid;ambienteEmissaoé igual ao ambiente do pareamento do dispositivo. - O PDV trata HTTP 202 com
AguardandoAutorizacao,ContingenciaPendentee os três tipos de rejeição distinguidos porsituacaoLocal, 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 porX-Tffiscal-Event-Ide 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/situacaopara mostrar as notas a transmitir, com atenção aprazoTransmissaoAteeavisos.
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:
& "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ãosegredos.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:
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"
| Propriedade | Obrigatório | Descrição |
|---|---|---|
TFA_FILE | Obrigatório para parear | Caminho do arquivo do código de pareamento. Sem ela é uma instalação comum e o gerente faz depois o assistente de instalação |
PFX_FILE | Uma das duas linhas | Caminho do arquivo do certificado PFX. A senha vem de pfxSenha no arquivo de segredos |
CERT_THUMBPRINT | Uma das duas linhas | Impressão digital do certificado existente. Pode vir com CERT_STORE, padrão LOCAL_MACHINE; exige rodar antes o script de acesso à chave privada |
SECRETS_FILE | Obrigatório para parear | Caminho 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_PASSWORDeADMIN_PINnã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ção | Quando ocorre | O que o pareamento faz | pin no arquivo de segredos |
|---|---|---|---|
| Primeira instalação | O computador ainda não concluiu nenhuma instalação | Pareia direto; o pin passa a ser o PIN do gerente | O novo PIN do gerente, de 6 a 8 dígitos |
| Adicionar empresa depois de instalado | Execuçã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á instalado | Primeiro 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 afetadas | Precisa 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):
"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
--pfxpor--thumbprint {thumbprint}e, se quiser, acrescente--store LOCAL_MACHINEou--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
pindo 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ída | Significado | O que o script de implantação faz |
|---|---|---|
0 | Pareamento concluído | Nada |
1 | Pareamento recusado | Trate conforme o código de erro na saída padrão |
2 | Parâmetro errado, arquivo de segredos fora do exigido ou serviço inacessível | Corrija os parâmetros e o arquivo de segredos e rode de novo |
3 | Pode tentar de novo com o mesmo código de pareamento | Rode 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 é
VersaoBloqueadae 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:
[ { "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 exemplo192.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:
- 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.
- 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.
- 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 exemploPDV 01,PDV 02; esse nome é a identificação do caixaterminalnas 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. - 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:8765pelo endereço de rede local do computador do Assistente, por exemplohttp://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:
| Item | Descrição |
|---|---|
| Conexão com a internet | Direta (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ço | Endereço do servidor proxy. Formato host:porta, obrigatório no modo manual; sem porta, usa 8080 |
| Usuário | Usuário de autenticação do proxy. Em branco, sem autenticação, e a senha salva é apagada |
| Senha | Senha 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 para | Hosts 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
10029920e 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:
| Item | Valores |
|---|---|
| Colunas por linha | 48, 42, 32, ou o padrão da largura do papel |
| Página de código da impressora | CP1252 (padrão), CP860, CP850, CP437; caracteres que não existem na página de código são impressos sem acento |
| QR Code | Comando 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 imprimir | Se o papel é cortado depois da impressão |
| Vias | Quantidade 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ção | Conteúdo | Uso |
|---|---|---|
| Exportar XML | Escolha 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 plataforma | Entregar ao contador todo mês |
| Exportar pacote de pendentes | Todas 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 diretamente | Entregar à plataforma para transmissão em nome da loja quando o computador quebrou e não deu tempo de transmitir |
| Backup | Có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 backup | Escolha e envie o arquivo de backup (até 4 GB) e depois informe a senha do backup; a base local atual é substituída pelo backup | Recuperar 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:
F2nova venda,F4ir para o pagamento,F8emitir e imprimir,Escvoltar / 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
situacao | Significado | Ação |
|---|---|---|
Ativo | Pode emitir | Nada |
Desativado | O integrador desativou o dispositivo | Não volta; para continuar usando o mesmo computador, pareie de novo |
Revogado | A plataforma revogou o dispositivo | Fale com a plataforma |
EmpresaDesativada | Emissão offline da empresa desativada | Fale com a plataforma |
AplicativoBloqueado | Software do PDV bloqueado pela plataforma | Fale com a plataforma |
VersaoBloqueada | A versão do PDV foi bloqueada ou está abaixo da mínima | Atualize o 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.
situacaoLocal | status | Significado | Aparece em |
|---|---|---|---|
Autorizada | Autorizada | Autorizada pela SEFAZ, online ou depois da transmissão da nota offline | Emissão, consulta |
ContingenciaPendente | ContingenciaPendente | Assinada offline neste computador, aguardando transmissão | Emissão, consulta, correção |
AguardandoAutorizacao | AguardandoAutorizacao | Aceita online, a SEFAZ ainda não respondeu e não foi possível assinar offline naquele momento; a emissão devolve HTTP 202 | Emissão, consulta |
Negada | Negada | Emissão online rejeitada pela SEFAZ, inclusive depois de resultado online pendente; não pode ser corrigida com o mesmo número | Emissão, consulta |
Rejeitada | Negada | Transmissão da nota offline rejeitada pela SEFAZ; corrija com o mesmo número, veja Tratamento após rejeição | Consulta, correção |
Recusada | Negada | A plataforma recusou esta nota offline; exige intervenção manual | Consulta |
Cancelada | Cancelada | Cancelada, inclusive por substituição | Consulta |
