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:
- configure a empresa e o certificado;
- emita notas de teste com serviços e tomadores variados;
- teste o cancelamento;
- provoque erros de propósito (código de serviço inválido, tomador incompleto) para ver como o seu sistema reage;
- 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.