API NFS-e Nacional: como integrar (e quando não vale a pena)

A API NFS-e Nacional é a via oficial para consultar e baixar notas fiscais de serviço direto do Portal Nacional, sem passar pela interface web. Se você chegou aqui, provavelmente está avaliando integrar — e a pergunta real não é "dá pra fazer?", mas "quanto vai custar manter isso funcionando?".

Este texto cobre as duas coisas: o que a integração exige de verdade, e em que ponto construir deixa de compensar.

O que a API do Portal Nacional permite

O Portal Nacional expõe serviços para emissão e para distribuição de documentos. Para quem precisa capturar notas — o caso típico de escritórios contábeis — o que interessa é a parte de distribuição: consultar os documentos vinculados a um CNPJ e baixar o XML autenticado.

Isso resolve um problema concreto: o Emissor Nacional não tem download em lote nativo. Pela interface, cada nota exige abrir, clicar em baixar XML, salvar e repetir. Com 100 notas no mês, são pelo menos 400 cliques.

O que você precisa antes de escrever a primeira linha

1. Certificado digital

A autenticação é feita por certificado digital (A1 ou A3) — não existe API key. Na prática, isso significa configurar TLS mútuo (mTLS) na sua aplicação, com a cadeia de certificados ICP-Brasil.

Dois detalhes que costumam surpreender:

• A1 vence em 12 meses. Você precisa de um processo de renovação, ou a integração para sem aviso.

• Cada cliente tem o seu. Se você atende 30 empresas, são 30 certificados para armazenar com segurança, monitorar validade e rotacionar.

2. Tratamento de rate limit

O Portal aplica limite de requisições por certificado, não por aplicação. Isso muda o desenho: filiais que compartilham o mesmo certificado dividem o mesmo orçamento de chamadas, e um lote agressivo em uma entidade derruba as outras do mesmo grupo.

Quando o limite estoura, você recebe HTTP 429 e precisa de backoff — idealmente por certificado, não por empresa. Errar isso gera um ciclo em que o bloqueio se renova sozinho e a captura nunca termina.

3. Parsing e armazenamento do XML

O retorno é XML no layout da NFS-e Nacional. Você vai precisar validar contra o schema, extrair os campos que importam (valores, tomador, prestador, retenções de ISS) e guardar o arquivo original — porque o XML autenticado é o documento com valor fiscal, não o PDF.

O custo que ninguém coloca na conta

Construir a primeira versão é a parte fácil. O que pesa é o que vem depois:

• O layout muda. Notas técnicas são publicadas periodicamente e alteram schema e regras de validação. Cada uma exige adaptação.

• Nem todo município aderiu. O Padrão Nacional convive com centenas de portais municipais próprios. Se seus clientes emitem fora do ambiente nacional, a API nacional não vê essas notas — e você volta ao problema original, multiplicado.

• Instabilidade acontece. Você precisa de fila, retentativa e visibilidade de falha, senão descobre que faltou nota no fechamento.

• NFS-e é só um dos documentos. NF-e, CT-e e MDF-e vivem em ambientes diferentes (SEFAZ), com autenticação e contratos próprios. Cada um é uma integração nova.

Quando vale construir

Integrar direto faz sentido quando:

• Você é um software house ou ERP e a captura fiscal faz parte do seu produto

• Tem time de desenvolvimento para manter isso indefinidamente, não só para entregar

• Precisa de controle fino sobre o fluxo, para embutir em processos próprios

Quando não vale

Não vale quando o objetivo final é simplesmente ter os XMLs na mão todo mês. Nesse caso você estaria construindo e mantendo infraestrutura fiscal para resolver uma tarefa operacional — e o custo de manutenção não desaparece nunca.

É o caso típico do escritório contábil: a integração não é o produto, é um meio. Cada hora gasta mantendo backoff, renovando certificado e acompanhando nota técnica é uma hora que não foi para o cliente.

O atalho

A ServLink faz essa captura para você: conecta o certificado digital dos seus clientes e baixa NFS-e, NF-e, CT-e e MDF-e em lote — XML e PDF — num painel só. O rate limit, o backoff, as notas técnicas e a renovação de certificado ficam do nosso lado.

São 30 dias grátis, sem cartão. Se depois disso a conta fechar melhor construindo internamente, você terá perdido nada além do tempo de testar.