--- title: "Arquitetura — NFS-e Inbound" description: "Visão sistêmica do serviço de captura automática de NFS-e do padrão nacional: atores, fluxo SEFIN → ADN → NFE.io → cliente, conceitos e pontos de falha." source_url: https://nfe.io/docs/distribuicao-nfse-inbound-arquitetura/ last_updated: 2026-07-30 --- # 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](https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp214.htm)) 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](#diagrama) - [Atores](#atores) - [Fluxo passo-a-passo](#fluxo-passo-a-passo) - [Conceitos-chave](#conceitos-chave) - [Diferenças em relação a NF-e e CT-e](#diferenças-em-relação-a-nf-e-e-ct-e) - [Pontos de falha](#pontos-de-falha) - [Garantias e limitações](#garantias-e-limitações) ## Diagrama ```mermaid sequenceDiagram participant Prestador participant SEFIN as SEFIN Nacional participant ADN as ADN (Ambiente de Distribuição Nacional) participant NFEIO as NFE.io participant Cliente as Sistema do Tomador Prestador->>SEFIN: Emite NFS-e (DPS assinada) SEFIN->>SEFIN: Autoriza, atribui chave 50 dígitos SEFIN->>ADN: Publica NFS-e e eventos NFEIO->>ADN: Poll a cada ~30s (mTLS por CNPJ) ADN-->>NFEIO: Lote paginado por NSU NFEIO->>NFEIO: Persiste XML, extrai metadados NFEIO->>Cliente: Webhook POST (inbound.serviceInvoice.received) Cliente-->>NFEIO: HTTP 2xx (idempotente) Cliente->>NFEIO: GET /v2/.../inbound/nfse/{id} (consulta sob demanda) Cliente->>NFEIO: POST manifestações (Ciência/Rejeição) — opcional ``` ## 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. :::info 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](/documentacao/nota-fiscal-servico-eletronica/primeiros-passos), 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](../reference/codigos-evento.md). - **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: | Aspecto | NFS-e Inbound | NF-e / CT-e Inbound | |---|---|---| | Origem dos documentos | SEFIN Nacional (ADN — federal unificado) | SEFAZ — Ambiente Nacional (estadual federado) | | Frequência de polling | ~30 segundos | ~3 minutos | | Chave de acesso | 50 dígitos | 44 dígitos | | Certificado digital | Não exigido para o cliente (gerenciado pela NFE.io) | Exigido — você sobe certificado A1 da empresa | | Tipos de manifestação | 2 (Ciência, Rejeição) | 4 (Ciência, Confirmação, Operação Não Realizada, Desconhecimento) | | Vocabulário do webhook | Dotted: `inbound.serviceInvoice.received` | Snake legacy: `issued_successfully`, `event_raised_successfully`, `input_event_raised_successfully` | | Payload tributário | Bloco `document.taxes.ibsCbs` para RTC | Sem bloco RTC (ICMS, IPI, PIS, COFINS apenas) | | Paginação em listagem | REST clássico `pageIndex` / `pageCount` | OData `$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 - [Quickstart — primeira NFS-e em 5 minutos](../00-quickstart.md) - [Tutorial — primeira integração](../tutorials/primeira-integracao.md) - [Integração via REST](../how-to/integracao-rest.md) - [Catálogo de eventos do webhook](../reference/webhook-events.md) - [Códigos de evento — XSD vs CSV](../reference/codigos-evento.md) - [Receita — Manifestação do tomador](../how-to/manifestacao-tomador.md) - [Receita — Bulk Export](../how-to/bulk-export.md) - [Troubleshooting](../reference/troubleshooting.md) - [Mapa cross-repos](../99-mapa-cross-repos.md)