API de NFS-e Nacional para ERPs e software houses

Para quem serve

ERPs e software houses que emitem pelos seus clientes

Vários prestadores, uma conta

Cada prestador de serviço, identificado pelo CNPJ, é um emitente, com o próprio certificado A1 e a própria numeração de DPS, todos na mesma conta.

Quem já integra a NF-e

A NFS-e segue o molde da NF-e: um POST com Idempotency-Key, e o desfecho pelo webhook do emitente, que é o mesmo, ou pelo feed, que tem o mesmo cursor. Muda a família de rotas: /v1/nfse.

O que existe

Do POST ao DANFSe, pela mesma API da NF-e

O que a plataforma faz com a NFS-e hoje. Fora o pacote do contador, que é do painel, tudo isso está na API.

Emissão em uma chamada

Um POST com o serviço prestado e o tomador. Você não monta a DPS nem assina, e a numeração fica com a plataforma, ou com o seu ERP, se você preferir numerar.

POST /v1/emitentes/{id}/nfse

Consulta

Detalhe, lista e feed de desfechos. A consulta ao Sistema Nacional procura a nota de uma DPS que ficou sem desfecho e traz os cancelamentos feitos fora da plataforma.

GET /v1/nfse GET /v1/nfse/{id} GET /v1/nfse/events POST /v1/nfse/{id}/consulta

Cancelamento e substituição

Cancele a NFS-e autorizada ou substitua-a por outra. Na substituição, a original fica marcada como substituída, e o detalhe das duas mostra o vínculo.

POST /v1/nfse/{id}/cancelamento substituicao no POST /v1/emitentes/{id}/nfse

DANFSe em PDF

O PDF do DANFSe e o XML da NFS-e autorizada, uma chamada para cada um. Você não desenha o documento.

GET /v1/nfse/{id}/danfse GET /v1/nfse/{id}/xml

Pacote do contador por competência

No painel, peça o pacote de um mês de produção: um ZIP com os XMLs das NFS-e da competência e os dos cancelamentos delas, pronto para o seu contador.

Consulta de convênio

Consulte o que qualquer município publicou de convênio no Sistema Nacional da NFS-e, e não só o do seu emitente. A consulta informa, e não bloqueia a emissão.

POST /v1/emitentes/{id}/consultas-convenio

Cobertura

Onde a NFS-e Padrão Nacional vale

Municípios conveniados ao Emissor Nacional

Atendemos os municípios conveniados ao Emissor Nacional. A consulta de convênio devolve a parametrização que o município publicou no Sistema Nacional da NFS-e; sozinha, ela não diz se o município aderiu.

Seu município usa um sistema próprio?

Integramos outros provedores sob consulta. Escreva para suporte@flexdfe.com.br, com o município e o provedor.

Primeiros passos

Do cadastro do emitente à primeira NFS-e

O certificado, a ativação e a série seguem a ordem que a Referência manda, e a consulta de convênio entra antes da ativação, para você avaliar o município antes de emitir. Para criar a conta, subir o certificado e gerar a credencial pelo painel, siga o tutorial de primeiros passos, escrito para NF-e e NFC-e.

Cadastre o emitente, com a inscrição municipal quando o município a exige

POST /v1/emitentes, no campo inscricao_municipal. A que vale é a do cadastro nacional (CNC NFS-e), que o Emissor Nacional mostra como “Indicador Municipal”, e pode não ser a do cartão ou a do alvará. Sem ela, num município que a exige, a DPS volta rejeitada, salvo para o MEI.
Suba o certificado A1 do emitente

PUT /v1/emitentes/{id}/certificado. Ele assina a DPS e autentica a conexão com o Sistema Nacional, e a consulta de convênio, no passo seguinte, também o usa.
Consulte o convênio do município

POST /v1/emitentes/{id}/consultas-convenio, com o código IBGE do município em codigoMunicipio. A consulta informa o que ele publicou e não bloqueia a emissão: a plataforma não recusa uma DPS por causa da resposta. Antes da ativação ela vai com a credencial de integrador, porque a do emitente só autentica depois dela.
Ative o emitente e provisione a série de DPS

PATCH /v1/emitentes/{id} com ativo: true, que exige certificado vigente, e POST /v1/emitentes/{id}/series com tipoDocumento: "dps", pela credencial de integrador ou pela do emitente. A série pode vir antes da ativação: o emitente em rascunho já provisiona, e só não emite.
Emita a primeira NFS-e

POST /v1/emitentes/{id}/nfse, como no exemplo abaixo. Em homologação, nada é cobrado.

Exemplo mínimo

Um POST emite a NFS-e

A identidade do prestador não vai no corpo: ele é o emitente da credencial, e o CNPJ, a inscrição municipal e o município emissor saem do cadastro dele.

flexdfe-api — HTTP

POST /v1/emitentes/6b2f0c9e-1a2b-4c3d-8e4f-5a6b7c8d9e0f/nfse HTTP/1.1
Host: SEU-HOST
Authorization: Basic base64(client_id:secret)
Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json

{
  "serie": 1,
  "documento": {
    "dCompet": "2026-09-01",
    "toma": {
      "cnpj": "12ABC345000188",
      "razaoSocial": "Cliente Exemplo Ltda",
      "email": "financeiro@cliente.com.br"
    },
    "serv": {
      "cLocPrestacao": "4106902",
      "cTribNac": "010701",
      "xDescServ": "Suporte técnico em sistemas — setembro/2026"
    },
    "valores": {
      "vServ": 1500,
      "tribMun": {
        "tribISSQN": "1",
        "tpRetISSQN": "1"
      },
      "totTrib": {
        "pTotTribSN": 6
      }
    }
  }
}

← 202 Accepted
{
  "id": "0b6f3c1e-7a2d-4e59-9f10-3c8a5d2e7b41",
  "tipo": "nfse.emit",
  "situacao": "pendente",
  "causa": null,
  "motivo": null,
  "emitente": {
    "id": "6b2f0c9e-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
  },
  "ambiente": "producao",
  "documento": {
    "id": "0b6f3c1e-7a2d-4e59-9f10-3c8a5d2e7b41",
    "tipo": "nfse",
    "situacao": "pendente",
    "xmlDisponivel": true
  },
  "resultado": {
    "chave": null
  },
  "tentativas": 0,
  "retentativa": null,
  "criadoEm": "2026-07-11T12:00:00.000Z",
  "atualizadoEm": "2026-07-11T12:00:00.000Z",
  "links": {
    "self": "/v1/comandos/0b6f3c1e-7a2d-4e59-9f10-3c8a5d2e7b41",
    "documento": "/v1/nfse/0b6f3c1e-7a2d-4e59-9f10-3c8a5d2e7b41"
  }
}

A resposta 202 diz que o pedido foi aceito, e traz o comando, o mesmo de GET /v1/comandos/{id}. O desfecho vem depois, por essa leitura, pelo detalhe (GET /v1/nfse/{id}), pelo feed (GET /v1/nfse/events) ou pelo webhook do emitente; com ?wait=, em milissegundos, a chamada aguarda o desfecho por até esse tempo, com teto de 15.000 ms. Todos os campos do documento estão no schema NFSeData, na Referência da API.

Para ver o ciclo da NFS-e num sistema pequeno, o exemplo de integração é um repositório público, de código aberto. Ele cadastra o emitente, provisiona a série de DPS, emite, acompanha o desfecho pelo feed (e, se você configurar, pelo webhook), consulta, cancela, substitui e obtém o XML e o DANFSe. O fluxo da NFS-e nele segue o contrato da versão 0.5.0 da API, mas ainda não foi rodado contra a API real, em homologação: leia-o como código de referência, não como prova de que o Sistema Nacional aceita cada passo.

Preço

A mesma franquia da NF-e

A NFS-e consome a mesma franquia de transmissões da NF-e e da NFC-e, no mesmo plano e sem adicional. Em homologação, nada é cobrado.

O que conta como transmissão

Em produção, cada veredito do Sistema Nacional NFS-e, de autorização ou de rejeição, conta uma transmissão: a DPS rejeitada que você corrige e reenvia conta de novo. A substituição conta uma, a da nota substituta. O cancelamento de NFS-e não conta.

Planos e regra completa

Os preços, as franquias e o excedente estão na seção de preços da página inicial. A regra inteira está na cláusula 12 dos Termos de Uso.

Comece pela homologação

Crie a conta, cadastre um emitente e emita a primeira NFS-e em homologação, sem custo.

Criar conta Referência da API

API de NFS-e Nacional para o seu ERP