TF Fiscal
Documentação

NFC-e offline

Entrada da emissão offline de NFC-e: quando ela é necessária, como escolher entre o SDK embarcado e o Assistente Fiscal, o fluxo de integração, as regras de números e de transmissão e como chegam os resultados.

Esta página é a entrada da emissão offline de NFC-e: explica quando ela é necessária, como escolher entre as duas opções de integração e quais passos seguir. Ao final você terá escolhido a opção e saberá em que página fazer cada passo. O pré-requisito é a empresa já estar integrada conforme as exigências da NFC-e na nuvem.

Quando você precisa da emissão offline

Quando a loja fica sem internet e não alcança a plataforma, o caixa ainda precisa emitir a nota na hora e entregá-la ao consumidor. A emissão offline permite que o caixa emita no próprio computador uma nota de contingência offline (NFC-e assinada no próprio computador sem rede, aguardando transmissão para autorização) e imprima o cupom na hora; quando a rede volta, a nota passa pela transmissão automática (a nota offline vai à plataforma e depois à SEFAZ para autorização), e o resultado chega a você como de costume.

Com a rede normal, a emissão continua sendo autorizada online, com o mesmo resultado da NFC-e na nuvem.

Qual opção escolher

Opção 1: SDK embarcado no PDVOpção 2: integrar o Assistente Fiscal
O que éO PDV integra o pacote de desenvolvimento, e o núcleo de emissão offline roda junto com o PDVO computador da loja instala o TF Fiscal Assistente Fiscal (programa Windows), e o PDV chama a interface local dele
Para quemPDV próprio em Java, que quer evitar mais um programa na lojaIntegradores que não querem mexer no PDV por dentro; ou lojas sem sistema de caixa, que usam a emissão simples do próprio assistente
O que fazerIncluir o SDK, distribuir o runtime com o instalador, chamar o método de emissão e tratar os eventosA loja instala o assistente; o PDV troca o endereço de emissão pelo local, e o corpo da requisição é o mesmo da API de emissão na nuvem
EsforçoMédio: é preciso escrever inicialização, pareamento e tratamento de eventosPequeno: só muda o endereço chamado e o cabeçalho de autenticação
Classe de impostoSuportada com conexão; sem rede, envie impostosSuportada com conexão; sem rede, envie impostos

Recomendação: se o PDV é um programa próprio em Java, escolha o SDK embarcado; caso contrário, escolha o Assistente Fiscal. O SDK embarcado só existe na versão Java. Use uma das duas opções; caixas diferentes da mesma empresa também podem usar uma opção cada.

Fluxo de integração

Antes de começar, a empresa já deve estar registrada com NFC-e habilitada e com o certificado vinculado.

  1. Gerar o código de pareamento: para cada caixa, chame Gerar código de pareamento e entregue à loja o código de pareamento devolvido (credencial de uso único que vincula um caixa à empresa). A primeira chamada já habilita a emissão offline da empresa.
  2. A loja instala e pareia: no SDK embarcado, veja as seções de preparação e de pareamento do Tutorial do SDK embarcado; no Assistente Fiscal, veja a seção de instalação e pareamento do Tutorial do Assistente Fiscal. Cada caixa é pareado uma única vez.
  3. Emitir: no SDK embarcado, chame o método de emissão, veja Emitir a primeira nota; no Assistente Fiscal, chame a emissão da interface local, veja Emissão, consulta e transmissão. Com rede e sem rede a chamada é a mesma.
  4. Receber os resultados: o PDV recebe no próprio computador, e o servidor do integrador recebe os webhooks de sempre, veja Como os resultados chegam.

A validade do código de pareamento e o tempo máximo offline são controlados pela plataforma. O ambiente de homologação permite testar tudo; as notas de homologação não têm valor fiscal. Se a empresa mudar de ambiente, gere novos códigos de pareamento no novo ambiente e pareie os caixas de novo.

Números e série

  • Série do dispositivo: uma série NFC-e exclusiva de cada caixa. A emissão online e a offline usam essa série: o caixa pega os números numa única sequência e assina no próprio computador; com rede, entrega a nota assinada à plataforma, que a envia à SEFAZ; sem rede, continua emitindo notas offline na mesma sequência. Por isso as notas online e offline de um caixa têm numeração contínua. Pelo mesmo motivo a emissão online também precisa do certificado e dos dados tributários locais, que são sincronizados sozinhos depois do pareamento.
  • Série e número inicial definidos: ao gerar o código de pareamento, serie define a série do dispositivo e numeroInicial o número da primeira nota; omitidos, a plataforma atribui a série e começa em 1. serieOffline em Listar dispositivos é a série do dispositivo.
  • Separada da série da nuvem: a NFC-e emitida pela API de emissão em nuvem continua usando a série do perfil da empresa, que nunca coincide com uma série de dispositivo. Se o mesmo CNPJ emite por vários integradores, cada um precisa usar séries que não se sobreponham (inclusive as séries dos dispositivos); caso contrário a SEFAZ rejeita.
  • Uma série para vários caixas da loja: vários caixas também podem usar uma única série de dispositivo, com os números tirados num só lugar e contínuos. O Assistente Fiscal em modo rede local atende a loja toda, veja Vários caixas na mesma loja; o SDK embarcado usa o modo principal e secundário, veja Vários caixas (modo principal e secundário).
  • Números tratados pela plataforma: quando um envio online fica com resultado incerto, uma nota online é rejeitada ou alguns estados não aceitam a inutilização, a plataforma fecha os números sozinha, sem nenhuma ação do PDV ou do integrador. Detalhes no apêndice.

Notas offline e transmissão

  • A nota emitida sem rede fica em ContingenciaPendente; o cupom já sai com a marca de contingência e é entregue ao consumidor normalmente.
  • Quando a rede volta, a transmissão é automática, sem nenhuma ação; autorizada pela SEFAZ, a nota passa a Autorizada.
  • Nota offline rejeitada pela SEFAZ precisa ser corrigida com o mesmo número e retransmitida; só é possível mudar o que não afeta valores e tributos (por exemplo NCM, CFOP, documento do consumidor).
  • A nota offline precisa ser transmitida dentro do prazo do estado, conforme a configuração da plataforma; perto do prazo há um aviso, e depois dele aquele caixa não pode mais emitir offline.
  • Cancelamento pedido antes da autorização da nota offline fica pendente na plataforma e é enviado no momento da autorização.
  • Nota com combustível não pode ser emitida offline.
  • Linhas de item que referenciam classe de imposto (classeImposto) exigem conexão; sem rede, envie impostos, veja Classe de imposto e conexão.

Classe de imposto e conexão

As linhas de item podem referenciar uma classe de imposto com classeImposto, como na emissão em nuvem; assim cfop e impostos podem ser omitidos. As classes de imposto ficam só na plataforma: ao emitir, o Assistente Fiscal e o SDK embarcado enviam antes a requisição à plataforma, que a expande em impostos completos; depois o cálculo, a assinatura e a emissão acontecem no dispositivo. A expansão é a mesma da emissão em nuvem.

  • Exige conexão: sem rede ou sem acesso à plataforma, a requisição que referencia classe de imposto é recusada com 10029780, indicando enviar impostos. A requisição recusada não consome número, e a nota seguinte mantém a sequência.
  • O programa de caixa cuida da contingência: o Assistente Fiscal e o SDK embarcado não guardam classes de imposto. Para continuar emitindo sem rede, o programa de caixa precisa guardar os impostos expandidos e, sem rede, enviar impostos nas linhas de item. No SDK embarcado, o Pedido devolvido por Consultar de uma nota emitida com rede já é a requisição expandida.
  • Classe de imposto recusada: classe inexistente, incompatível com o regime atual da empresa (IncompativelComRegime) e casos parecidos devolvem os mesmos códigos e mensagens da emissão em nuvem, como 10005202 e 10005220; as mensagens seguem o idioma da interface do Assistente Fiscal ou o idioma do SDK embarcado.
  • Classe de imposto registrada: cada nota registra o código e a versão da classe de imposto usada em cada linha e os informa à plataforma junto com a nota.

Como os resultados chegam

CanalConteúdo
PDVNo SDK embarcado, eventos do SDK; no Assistente Fiscal, callback local ou consulta do assistente
Servidor do integradorOs webhooks de NFC-e de sempre: transmissão aceita nfce.contingency_issued, autorização nfce.authorized, rejeição nfce.rejected, cancelamento nfce.canceled / nfce.cancel_rejected
Eventos de dispositivonfce.device.activated (pareamento), nfce.device.deactivated (desativação), nfce.device.upload_overdue (transmissão perto do prazo), com o objeto dispositivo em data
  • Notas emitidas por um caixa: a carga do webhook traz no fim o campo dispositivoId; quando o dispositivo informou o caixa, vem em seguida a identificação do caixa terminal, que diz qual caixa emitiu a nota. No Assistente Fiscal é o nome do token de caixa; no modo principal e secundário do SDK embarcado é o nome do terminal secundário.
  • Notas sem identificação do caixa: quando o dispositivo não informou o caixa, por exemplo nas notas emitidas pelo próprio principal do SDK embarcado ou no modo independente, a consulta e o webhook não trazem a chave terminal; ela não vem como null.
  • Assinatura: quais eventos são enviados e como assinar só parte deles está nas regras de assinatura de Webhooks.

Endpoints

EndpointPara quê
Gerar código de pareamentoUm por caixa, válido por 72 horas e de uso único
Listar dispositivosConexão e notas a transmitir de cada caixa
Desativar dispositivoPara quando o caixa é trocado ou sai de uso; não tem volta, e as notas offline já emitidas continuam sendo transmitidas

Apêndice: números que a plataforma trata por você

Todos os casos abaixo são tratados pela plataforma; nem o PDV nem o integrador precisam fazer nada.

CasoO que a plataforma faz
Envio online com resultado incerto, por exemplo tempo esgotado, queda de rede ou a plataforma não respondeu a tempoEsse número não é usado de novo: o caixa emite uma nota offline com o número seguinte e a entrega ao consumidor. Depois a plataforma confere o número original: se a SEFAZ o autorizou, a plataforma o cancela por substituição; se não, a plataforma inutiliza o número na SEFAZ
Nota online rejeitada pela SEFAZA plataforma inutiliza o número, e ele não é reaproveitado
A plataforma recusou na hora, sem enviarO número fica para a nota seguinte
AC, BA e SP, ou outro estado com o serviço de inutilização desativadoOs números que acima seriam inutilizados não são declarados, e a numeração simplesmente continua depois do intervalo. Esses números contam como usados e nunca mais são emitidos