Pular para o conteúdo
Escola Ninja WP Blog

Nota Fiscal · · 6 min de leitura

Como emitir NFS-e nacional por API: passo a passo com certificado A1

Por Flávio Henrique, CEO da Escola Ninja WP, à frente da escola desde 2009.

Resumo

Para emitir NFS-e nacional por API, o seu sistema monta a DPS (Declaração de Prestação de Serviço), assina com o certificado A1 da empresa e envia ao ambiente nacional, que devolve a NFS-e autorizada. O município do prestador precisa ter aderido ao padrão nacional, e todo teste deve começar no ambiente de produção restrita. Com uma API própria, você faz isso pelo seu sistema, sem pagar por nota.

A nota fiscal de serviço sempre foi a mais trabalhosa de integrar: cada prefeitura tinha o seu sistema, o seu leiaute e as suas regras. O padrão nacional da NFS-e muda esse cenário. Com um leiaute único e um ambiente nacional, emitir a nota de serviço por API, direto do seu sistema, ficou muito mais simples.

Este é um passo a passo prático para quem quer usar a API da NFS-e nacional: o que precisa ter antes, como é o fluxo de emissão e onde estão os erros mais comuns.

O que mudou com a NFS-e nacional

No modelo antigo, quem emitia em várias cidades precisava integrar com vários sistemas municipais. No padrão nacional:

  • existe um leiaute único para o país;
  • o prestador envia uma DPS (Declaração de Prestação de Serviço);
  • o ambiente nacional valida a DPS e gera a NFS-e;
  • o documento auxiliar em PDF é o DANFSe.

O ponto de atenção é a adesão do município: a emissão pelo ambiente nacional vale para os municípios que aderiram a ele. Para o MEI, o padrão nacional é obrigatório desde setembro de 2023. Para as demais empresas, o calendário varia por regime e por município, então confirme a sua situação com o contador antes de virar a chave.

O que você precisa antes de emitir NFS-e nacional por API

Da empresa prestadora

  • Certificado digital ICP-Brasil, de preferência o A1 (arquivo .pfx com senha), porque ele pode ficar no servidor e assinar sem intervenção humana.
  • Município aderente ao padrão nacional.
  • Cadastro em dia e o regime tributário correto (Simples Nacional, MEI ou regime normal).
  • Código de tributação nacional do serviço, ligado à lista de serviços da Lei Complementar nº 116/2003. O contador define qual código usar.

Do seu sistema

  • Uma forma de guardar o certificado e a senha com segurança, cifrados e fora do alcance da interface.
  • Numeração da DPS com série e número controlados, sem repetição.
  • Um lugar para guardar o XML da NFS-e e o DANFSe de cada nota.

Passo a passo da emissão por API

1. Monte os dados do serviço

Reúna, para cada nota:

  • prestador (CNPJ e inscrição municipal, quando houver);
  • tomador (CPF ou CNPJ, nome e endereço);
  • descrição do serviço;
  • código de tributação nacional;
  • município de incidência do imposto;
  • valores, deduções, alíquota e retenções, quando houver.

2. Gere a DPS

Com esses dados, o sistema monta o XML da DPS no leiaute nacional. Se você usa uma API própria de emissão, normalmente envia um JSON e ela monta o XML por você.

3. Assine com o certificado A1

A DPS é assinada digitalmente com o certificado da empresa. É a assinatura que dá validade jurídica ao documento.

4. Envie ao ambiente nacional

A comunicação com a API nacional usa conexão autenticada com o certificado digital. O ambiente valida a DPS e, se tudo estiver certo, devolve a NFS-e gerada, com a chave de acesso.

5. Guarde e entregue

Grave o XML da NFS-e, gere o DANFSe e envie ao tomador. Registre no seu banco a chave, a data e o status, para consultas futuras.

Homologação: teste antes de valer

O padrão nacional oferece um ambiente de produção restrita, para testes. Comece sempre por ele:

  1. configure a empresa e o certificado;
  2. emita notas de teste com serviços e tomadores variados;
  3. teste o cancelamento;
  4. provoque erros de propósito (código de serviço inválido, tomador incompleto) para ver como o seu sistema reage;
  5. só então mude para produção.

Cancelamento e substituição

Errou a nota? No padrão nacional, o cancelamento é um evento enviado sobre a NFS-e já gerada, com justificativa. Há também a substituição, quando se emite uma nova nota no lugar da anterior. As regras de prazo e de quando cada um é permitido podem variar por município, então confirme com o contador.

Erros comuns na API da NFS-e nacional

  • Município não aderente. A DPS é recusada porque o município do prestador não emite pelo ambiente nacional.
  • Código de tributação errado. O código não corresponde ao serviço ou não é aceito pelo município.
  • Certificado vencido ou de outra empresa. O certificado A1 costuma valer um ano; coloque um alerta de vencimento.
  • Número de DPS repetido. Duas requisições simultâneas usando o mesmo número. A numeração precisa ser reservada de forma atômica.
  • Requisição repetida. O usuário clica duas vezes, a rede oscila e o sistema reenvia. Uma chave de idempotência na sua API impede que isso gere duas notas.
  • Ambiente nacional indisponível. Pode acontecer. O seu sistema precisa guardar a nota como pendente e tentar de novo depois, sem duplicar. Vamos tratar disso no guia sobre o que fazer quando a API da NFS-e nacional sai do ar.

Checklist de segurança da integração

A API de emissão lida com o certificado digital da empresa, que é praticamente a assinatura dela. Trate a integração como um sistema sensível:

  • Certificado cifrado em repouso e senha que nunca volta em tela, log ou resposta de erro.
  • Chave de acesso obrigatória em toda chamada à sua API, com troca simples quando alguém sai da equipe.
  • Conexão sempre em HTTPS entre o seu sistema e a API.
  • Webhooks assinados, para que o seu sistema confira que o aviso de nota emitida veio mesmo da sua API.
  • Auditoria de cada emissão e cancelamento: quem pediu, quando, de qual IP e com qual resultado.
  • Backup dos XML fora do servidor principal.

Integração com o seu sistema

O fluxo mais comum é o seu sistema chamar a API no momento do faturamento e esperar a resposta. Outra opção é o webhook de entrada: o seu sistema, ERP ou loja virtual manda os dados da nota e a API emite na hora, devolvendo o resultado por webhook de saída. Isso evita que uma lentidão do ambiente nacional trave a tela do usuário, porque o sistema não fica esperando a resposta para seguir em frente.

NFS-e recorrente: mensalidades e contratos

Quem presta serviço mensal (contabilidade, suporte, hospedagem, cursos) emite a mesma nota todo mês. Pela API, isso vira uma rotina agendada: o sistema guarda o modelo da nota e a frequência, e emite na data certa. O cuidado é o mesmo de sempre: registrar cada tentativa e nunca emitir duas vezes para o mesmo período.

Contador com vários clientes

Um escritório de contabilidade que emite para vários prestadores precisa de um sistema que separe empresa, certificado e numeração de cada CNPJ. Em alguns cenários, o padrão nacional permite emitir com o certificado de um procurador autorizado; confirme as regras antes de montar o fluxo. Um painel multiempresa simplifica bastante o dia a dia.

E a NF-e e a NFC-e?

A NFS-e é a nota de serviço. Para venda de mercadorias, a nota é a NF-e (modelo 55) ou, no varejo, a NFC-e (modelo 65), que falam com a SEFAZ do estado e não com o ambiente nacional. Se o seu sistema precisa das três, vale escolher uma API que emita todas pelo mesmo padrão de integração. Comparamos as opções em emissor de NF-e com código-fonte: comprar pronto ou montar do zero.

Conclusão

Emitir NFS-e nacional por API segue um caminho claro: dados do serviço, DPS, assinatura com o certificado A1, envio ao ambiente nacional e guarda do XML e do DANFSe. O que separa uma integração tranquila de uma dor de cabeça são os detalhes: município aderente, código de tributação certo, numeração sem repetição, idempotência e testes em produção restrita. Resolva esses pontos e a nota de serviço passa a sair do seu sistema sem digitação e sem pagar por nota.

Perguntas frequentes

O que é a NFS-e nacional?

É o padrão nacional da nota fiscal de serviço eletrônica, com leiaute único para o país e um ambiente nacional que recebe a declaração do prestador e gera a nota. Ele substitui, nos municípios que aderiram, os vários sistemas de prefeitura com leiautes diferentes.

Preciso de certificado digital para emitir NFS-e nacional por API?

Sim. A comunicação com a API do ambiente nacional usa certificado digital ICP-Brasil, e a declaração enviada é assinada com ele. Para emissão automática por sistema, o certificado A1 é o mais prático.

Todo município aceita a NFS-e nacional?

Não. A emissão pelo ambiente nacional depende da adesão do município do prestador. Confira a situação do seu município antes de integrar.

O MEI é obrigado a emitir pelo padrão nacional?

Sim. Para o MEI, a emissão da NFS-e pelo padrão nacional é obrigatória desde setembro de 2023. Para as demais empresas, o calendário depende do regime e do município; confirme com o seu contador.

Dá para emitir NFS-e recorrente, todo mês, pela API?

Dá, desde que o seu sistema agende a emissão. No nosso Emissor, a NFS-e recorrente já vem pronta: você define a frequência e a nota sai sozinha, sem duplicar, com histórico de cada tentativa.

Leia também