Pular para o conteúdo principal
Ver como MarkdownDocs para agentes

Arquitetura — NFS-e Inbound

O NFS-e Inbound captura automaticamente todas as Notas Fiscais de Serviço Eletrônicas (NFS-e) do padrão nacional (Lei Complementar 214/2025) emitidas contra o CNPJ da sua empresa, sem necessidade de consultar cada prefeitura. Este documento descreve o fluxo entre os atores envolvidos, os conceitos da arquitetura e os pontos de falha que sua integração deve tratar.

Para desenvolvedores cliente que estão decidindo como integrar (REST e webhook), entendendo o que esperar do sistema, ou avaliando diferenças em relação ao NF-e/CT-e Inbound da mesma plataforma.

Sumário​

Diagrama​

Atores​

  • Prestador de serviço: empresa que presta o serviço e emite a NFS-e. Pode estar em qualquer município integrado ao padrão nacional. Não precisa ser cliente da NFE.io.
  • SEFIN Nacional: Secretaria Especial da Fazenda Nacional. Autoriza a NFS-e, atribui a chave de acesso de 50 dígitos e publica o documento no ADN.
  • ADN (Ambiente de Distribuição Nacional): sistema central onde todas as NFS-es ficam disponíveis para consulta pelos tomadores autenticados via certificado digital ICP-Brasil.
  • NFE.io: faz o polling periódico no ADN em nome do seu CNPJ, baixa os XMLs, extrai metadados, persiste e dispara webhooks.
  • Sistema do Tomador (seu sistema): recebe webhooks, consulta documentos via API REST e, opcionalmente, envia manifestações.
Convenção de papéis

O cliente desta API é sempre o tomador do serviço (quem contrata e recebe). Quando você atua como prestador (emitindo NFS-e), use a API de emissão de NFS-e, não esta.

Fluxo passo-a-passo​

  1. Cadastro inicial. Seu sistema ativa o NFS-e Inbound chamando POST /v2/companies/inbound/nfse com companyId, initialNsu, webhookUrl e parâmetros opcionais de manifestação automática.
  2. Polling autônomo. A NFE.io consulta o ADN a cada ~30 segundos usando o certificado digital ICP-Brasil cadastrado para a empresa. Você não precisa expor o certificado — ele fica seguro no servidor.
  3. Captura por lote. O ADN entrega lotes paginados por NSU (Número Sequencial Único). Cada documento recebe um NSU incremental, garantindo continuidade sem perda.
  4. Processamento. Para cada documento do lote, a NFE.io classifica o tipo (NFS-e autorizada, DPS, evento, CNC, EventRegistrationRequest), extrai metadados (prestador, tomador, valores, impostos), persiste o XML em blob storage e marca status Processed.
  5. Notificação. Um webhook HTTP POST é enviado ao endpoint configurado em webhookUrl. O envelope traz o documento completo em JSON, sem necessidade de consulta adicional à API.
  6. Consulta opcional. Seu sistema pode consultar a qualquer momento via GET /v2/companies/{companyId}/inbound/nfse (com filtros amplos) ou GET .../inbound/nfse/{id} (detalhe), e baixar XML, PDF ou JSON literal do XML.
  7. Manifestação opcional. Para sinalizar Ciência (203202) ou Rejeição (203206) ao SEFIN, seu sistema envia POST .../by-access-key/{accessKey}/manifestations?eventCode=.... O processamento é assíncrono — o resultado retorna via webhook inbound.manifestation.submitted.

Conceitos-chave​

  • NSU (Número Sequencial Único): contador incremental do ADN por CNPJ, atribuído a cada documento. Funciona como cursor de paginação — a NFE.io guarda o último NSU processado e busca apenas o que vier depois.
  • Chave de acesso (50 dígitos): identifica unicamente cada NFS-e no padrão nacional. Difere da chave NF-e/CT-e (44 dígitos) e do conceito municipal antigo. Usada em consultas idempotentes e em manifestações.
  • DPS (Declaração de Prestação de Serviço): XML enviado pelo prestador antes da autorização. Você recebe DPS quando precisar de auditoria do pedido original — documentos com type=Dps no payload do webhook indicam essa situação.
  • NFS-e autorizada: XML após autorização do SEFIN, identificado por type=serviceInvoice no payload do webhook. É o documento principal que você consome.
  • Eventos (type=Event): ações que modificam ou complementam uma NFS-e — cancelamento (101101), substituição (105102), confirmações por parte (203202 tomador, 202201 prestador, 204203 intermediário), rejeições e atos de ofício. A lista canônica vem do XSD tiposEventos_v1.01.xsd do padrão nacional — veja Códigos de evento.
  • Manifestação binária: diferente da NF-e (4 tipos), o endpoint de manifestação da NFS-e padrão nacional aceita apenas os dois códigos do tomador — Confirmação (203202) e Rejeição (203206). Códigos de prestador (202201) e intermediário (204203) existem no schema como eventos recebíveis, mas não são aceitos por este endpoint.
  • IBS e CBS: tributos da Reforma Tributária do Consumo (RTC) presentes no payload dentro de document.taxes.ibsCbs. IBS é repartido entre UF e Município sobre a mesma base; CBS é federal. Para NFS-e pré-RTC sem o grupo IBSCBS no XML, o bloco vem null.

Diferenças em relação a NF-e e CT-e​

A NFE.io também oferece Inbound de NF-e (modelo 55) e CT-e (modelo 57) com arquitetura similar. As diferenças relevantes na decisão de integração:

AspectoNFS-e InboundNF-e / CT-e Inbound
Origem dos documentosSEFIN Nacional (ADN — federal unificado)SEFAZ — Ambiente Nacional (estadual federado)
Frequência de polling~30 segundos~3 minutos
Chave de acesso50 dígitos44 dígitos
Certificado digitalNão exigido para o cliente (gerenciado pela NFE.io)Exigido — você sobe certificado A1 da empresa
Tipos de manifestação2 (Ciência, Rejeição)4 (Ciência, Confirmação, Operação Não Realizada, Desconhecimento)
Vocabulário do webhookDotted: inbound.serviceInvoice.receivedSnake legacy: issued_successfully, event_raised_successfully, input_event_raised_successfully
Payload tributárioBloco document.taxes.ibsCbs para RTCSem bloco RTC (ICMS, IPI, PIS, COFINS apenas)
Paginação em listagemREST clássico pageIndex / pageCountOData $top / $skiptoken

Você pode ativar os três subsistemas independentemente por CNPJ.

Pontos de falha​

  • ADN indisponível. O SEFIN Nacional pode retornar 429 (rate limit) ou 5xx. A NFE.io aplica backoff exponencial e exibe rateLimitedUntil na empresa. Após 10 falhas consecutivas (MaxConsecutiveFailures=10), o polling entra em circuit breaker e a empresa é desativada. O campo deactivationReason carrega um dos quatro valores de certificado/autorização (CertificateExpired, CertificateRejected, CertificateNotFound, CompanyNotAuthorized) quando aplicável. Mitigação: reativar via POST .../maintenance/reactivate após sanar a causa.
  • Certificado da empresa expirado ou rejeitado. Resulta em deactivationReason=CertificateExpired ou CertificateRejected. Você é notificado via webhook inbound.company.deactivated. Mitigação: atualizar o certificado no painel e reativar.
  • Webhook do cliente fora do ar. A NFE.io retenta até 50 vezes em 24 horas com backoff exponencial e jitter de ±20%. Após exaurir, marca webhookStatus=DefinitivelyFailed. O documento permanece consultável via API e o reenvio manual é feito por POST .../{id}/resend-webhook.
  • Documento com XML corrompido na origem. Sinalizado via webhook inbound.document.failed. O XML não fica armazenado. Casos recorrentes devem ser reportados ao suporte da NFE.io.

Garantias e limitações​

  • Sem perda de documentos: a paginação por NSU garante que toda NFS-e destinada ao CNPJ é capturada em ordem crescente. Falhas pontuais são recuperadas pelo reprocessamento do mesmo NSU.
  • Idempotência: o par (companyId, nsu) é único na base. Webhooks reentregues após falha temporária podem ser deduplicados por NSU ou pelo document.id.
  • Histórico amplo: documentos ficam disponíveis no ADN desde a entrada em produção do padrão nacional. Configure initialNsu baixo para sincronizar histórico completo na primeira ativação.
  • Captura não é manifestação: capturar a NFS-e não envia Ciência automaticamente. Você precisa habilitar isAutomaticManifestationEnabled na empresa ou disparar manualmente via API/console.
  • Limites de paginação: pageCount ≤ 100 em listagens. Consultas com hasTotals=true são mais lentas (envolvem count no banco). Não cacheie URLs assinadas — elas expiram em 30 minutos.
  • CT-e ainda não tem bulk export. XML, PDF e CSV em massa estão disponíveis para NF-e e NFS-e via shared-usage-api. CT-e está no roadmap.

Veja também​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.