Como emitir NFS-e pelo Emissor Nacional via API (padrão DPS)

Durante anos, emitir NFS-e no Brasil significou integrar com o sistema de cada prefeitura — layouts diferentes, autenticações diferentes, documentação de qualidade variável, e cada cidade nova era um projeto. O Emissor Nacional de NFS-e resolveu isso: um layout, um webservice, um padrão de assinatura para todos os municípios que aderirem.

A palavra importante é aderirem. E é aí que está a primeira das três armadilhas que fazem uma integração de NFS-e falhar mesmo quando o código está certo.

Armadilha 1: o município aderiu?

O padrão nacional só atende município que aderiu ao Emissor Nacional. Se o seu cliente está numa cidade que mantém o sistema próprio, a emissão pelo nacional simplesmente não é possível — não é limitação de fornecedor, é de escopo do convênio.

Isso precisa ser verificado antes de tentar emitir, e de preferência antes de vender a integração ao cliente. No AceleraAPI a consulta é pública e não consome requisição:

GET /api/v1/nfse/municipios/3131307

O retorno diz se a cidade é atendida e em qual ambiente. Também publicamos a cobertura completa por estado, navegável — útil para conferir a carteira de clientes de uma vez, antes de prometer prazo.

Armadilha 2: um certificado por prestador

Aqui está a diferença estrutural entre a NFS-e e os demais documentos. Na NF-e, NFC-e, CT-e e MDF-e é possível centralizar: um emitente, um certificado, muitas notas. No padrão nacional da NFS-e, o DPS é assinado pelo próprio prestador — não existe a figura da emissão em nome de terceiro.

Consequência para quem desenvolve: cada CNPJ que vai emitir precisa ter o certificado A1 dele cadastrado. Não dá para usar um certificado da software house para emitir por todos os clientes. É trabalho de onboarding a mais, e é melhor descobrir isso no planejamento do que na véspera de subir.

POST /api/v1/nfse/certificado
Authorization: Bearer ace_TOKEN_DA_EMPRESA
Content-Type: application/json

{ "certificado_base64": "MIIK...", "senha": "senha-do-pfx" }

No AceleraAPI o arquivo fica fora da raiz web, em diretório bloqueado, e a senha é cifrada. A assinatura acontece no servidor, no momento da emissão — o certificado não volta para você e não é usado para mais nada.

Armadilha 3: a numeração do DPS

O DPS (Declaração de Prestação de Serviço) tem numeração global por CNPJ e série dentro do ambiente nacional. Isso significa que ela não pertence ao seu sistema: pertence ao prestador, no ambiente da SEFIN.

O erro clássico de migração é este: o cliente já emitia NFS-e nacional por outro sistema, chegou até o DPS número 1.482, e a integração nova começa do 1. Todas as tentativas são rejeitadas por número já utilizado, e a equipe passa o dia procurando bug onde não tem.

Emitindo

Com município aderente, certificado cadastrado e numeração acertada, a emissão é uma chamada:

curl -X POST https://aceleraapi.com.br/api/v1/nfse/emitir \
  -H "Authorization: Bearer ace_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tomador": {
      "cnpj": "11222333000181",
      "razao_social": "CLIENTE EXEMPLO LTDA"
    },
    "servico": {
      "codigo_tributacao_nacional": "010101",
      "descricao": "Desenvolvimento de software sob demanda",
      "valor": 4500.00
    }
  }'

O retorno traz o número da NFS-e, a chave de acesso e os caminhos do XML autorizado e da DANFSe em PDF, que é gerada aqui mesmo. O corpo completo, com todos os campos de retenção e de tributação, está na documentação da NFS-e.

O que costuma dar rejeição

• Código de tributação nacional errado. É o campo que substitui o antigo código de serviço municipal, e ele tem lista própria — não é o CNAE.
• Tomador sem endereço completo quando o serviço exige local de prestação distinto do estabelecimento.
• Certificado vencido. Trivial, e responsável por boa parte dos chamados. Vale monitorar a validade e avisar o cliente 30 dias antes.
• Retenção de ISS informada de forma inconsistente com o regime do prestador.

E a reforma tributária?

O ISS será substituído pelo IBS municipal, e para vários serviços muda o local de incidência — o que altera qual município arrecada. A vantagem de já estar no padrão nacional é que a adaptação vem no layout único, e não em dezenas de sistemas municipais. Sobre o impacto no código, veja IBS, CBS e IS na nota fiscal.

Perguntas frequentes

Dá para testar sem emitir nota de verdade?

Sim, o ambiente de homologação existe e é grátis. No AceleraAPI, emissão em homologação não consome requisição.

Posso emitir para município não aderente?

Não pelo padrão nacional. Nesses casos a emissão depende do sistema da prefeitura, e é uma integração separada.

A DANFSe é obrigatória?

O documento válido é o XML autorizado; a DANFSe é o espelho para o tomador. Na prática, todo cliente quer o PDF — por isso ele já vem pronto.