O que a API de NFS-e faz
No padrão nacional, quem emite a NFS-e é o sistema nacional: o prestador envia a DPS, e a nota nasce da validação dela. A DPS ocupa o lugar que o RPS tinha nos sistemas municipais.
| Operação | O que acontece | Retorno |
|---|---|---|
| Emitir | Monta a DPS, assina e envia à Sefin Nacional. | HTTP 202, operação; após autorização, chave de 50 dígitos, XML e DANFSe |
| Consultar | Consulta a NFS-e pela chave de acesso. | Situação e eventos da nota |
| Cancelar | Registra o evento de cancelamento da NFS-e. | Protocolo do evento |
| Baixar arquivos | Entrega o XML da NFS-e e o DANFSe. | XML e PDF |
Como funciona a emissão de NFS-e por API
-
Serviço em JSON
Prestador, tomador, código de tributação nacional do serviço, local da prestação, valores, ISSQN e retenções.
cTribNac -
DPS assinada
A API monta a DPS no leiaute vigente e assina com o certificado do prestador.
infDPS -
Sefin Nacional
A DPS é enviada à API do Sistema Nacional NFS-e, com conexão TLS mútua.
Sefin -
NFS-e gerada
Validada a DPS, o sistema gera a NFS-e com chave de 50 dígitos e a publica no ADN, onde município e tomador a acessam.
ADN -
DANFSe
A representação da nota para o tomador, gerada a partir do XML autorizado.
Exemplo de emissão de NFS-e
POST https://erp.fideflow.com.br/api/flow-fiscal/v1/homologacao/emitentes/{emitente}/documentos/nfse
Authorization: Bearer {credencial_de_homologacao}
Content-Type: application/json
Idempotency-Key: exemplo-nfse-001
{
"referencia_externa": "exemplo-nfse-001",
"dados": {
"cabecalho": {
"cliente_id": 1,
"valor_total": "10.00"
},
"itens": [
{
"discriminacao": "Serviço prestado conforme contrato",
"valor_servico": "10.00"
}
]
}
}Exemplo de homologação extraído do OpenAPI v1. IDs e valores são fictícios e precisam corresponder aos cadastros e à operação do emitente; HTTP 202 ainda não é autorização fiscal.
Pontos de atenção na NFS-e
- Município: o MEI emite pelo padrão nacional desde setembro de 2023, qualquer que seja o município. Para os demais prestadores, confirme a habilitação no emissor nacional; município com sistema próprio pode manter o emissor dele e compartilhar as notas com o ADN.
- Código do serviço: o código de tributação nacional segue a lista de serviços da Lei Complementar 116. Código errado muda alíquota, local de incidência e retenções.
- Retenções: ISS, IR, CSLL, PIS, COFINS e INSS retidos dependem do serviço e do tomador. Veja o guia de retenções na fonte.
- Reforma Tributária: as notas técnicas do padrão nacional incluem os campos de IBS e CBS. A classificação continua sendo decisão do prestador e da contabilidade.
Perguntas frequentes sobre a API de NFS-e
Como saber se o meu município usa o padrão nacional?
O portal oficial da NFS-e publica a relação de municípios conveniados. Com a Reforma Tributária, os municípios integram seus dados ao ambiente nacional, pelo emissor nacional ou compartilhando as notas do sistema próprio.
Preciso de certificado digital para emitir NFS-e pela API?
Sim. A DPS é assinada com certificado ICP-Brasil, e a conexão com a API da Sefin Nacional usa TLS mútuo. Para emissão em servidor, use o A1.
Como testar a NFS-e nacional sem valor fiscal?
O Sistema Nacional NFS-e oferece o ambiente de produção restrita, com as mesmas regras e documentação da produção. Notas emitidas ali são de teste.
A DPS substitui o RPS?
No padrão nacional, sim. A DPS é a declaração que o prestador envia, e a NFS-e é gerada a partir dela pelo sistema nacional.
Fontes oficiais
No teste grátis do Flow Fiscal, a API de emissão vem completa, sem contratar; depois do teste, requer plano Flow Fiscal ativo e o opcional de emissão contratado. Exige certificado A1 válido e vínculo autorizado de cada CNPJ. CT-e, CT-e OS e MDF-e atendem o modal rodoviário; NFS-e segue o padrão nacional e os requisitos do município. Consulte as capacidades do emitente antes de transmitir.