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 PDV | Opçã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 PDV | O computador da loja instala o TF Fiscal Assistente Fiscal (programa Windows), e o PDV chama a interface local dele |
| Para quem | PDV próprio em Java, que quer evitar mais um programa na loja | Integradores 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 fazer | Incluir o SDK, distribuir o runtime com o instalador, chamar o método de emissão e tratar os eventos | A 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ço | Médio: é preciso escrever inicialização, pareamento e tratamento de eventos | Pequeno: só muda o endereço chamado e o cabeçalho de autenticação |
| Classe de imposto | Suportada com conexão; sem rede, envie impostos | Suportada 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.
- 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.
- 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.
- 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.
- 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,
seriedefine a série do dispositivo enumeroInicialo número da primeira nota; omitidos, a plataforma atribui a série e começa em 1.serieOfflineem 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, envieimpostos, 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 enviarimpostos. 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
impostosexpandidos e, sem rede, enviarimpostosnas linhas de item. No SDK embarcado, oPedidodevolvido porConsultarde 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, como10005202e10005220; as mensagens seguem o idioma da interface do Assistente Fiscal ou oidiomado 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
| Canal | Conteúdo |
|---|---|
| PDV | No SDK embarcado, eventos do SDK; no Assistente Fiscal, callback local ou consulta do assistente |
| Servidor do integrador | Os 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 dispositivo | nfce.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 caixaterminal, 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 comonull. - Assinatura: quais eventos são enviados e como assinar só parte deles está nas regras de assinatura de Webhooks.
Endpoints
| Endpoint | Para quê |
|---|---|
| Gerar código de pareamento | Um por caixa, válido por 72 horas e de uso único |
| Listar dispositivos | Conexão e notas a transmitir de cada caixa |
| Desativar dispositivo | Para 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.
| Caso | O que a plataforma faz |
|---|---|
| Envio online com resultado incerto, por exemplo tempo esgotado, queda de rede ou a plataforma não respondeu a tempo | Esse 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 SEFAZ | A plataforma inutiliza o número, e ele não é reaproveitado |
| A plataforma recusou na hora, sem enviar | O número fica para a nota seguinte |
| AC, BA e SP, ou outro estado com o serviço de inutilização desativado | Os 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 |
