NFS-e Nacional

A NFS-e Nacional é a nota de serviço única do país. Você emite com POST /nfse, do mesmo jeito que emite NF-e: mesma chave de API, mesma ref, mesmos webhooks. O que muda é o que a nota leva (serviços e tomador, no lugar de itens e destinatário) e quem autoriza: a Sefin Nacional, que responde na hora.

Palavras desta página. DPS é a Declaração de Prestação de Serviço, o documento que vai para a Sefin; o MadNotas monta e assina a DPS por você. Sefin Nacional é quem autoriza a NFS-e, o papel que a SEFAZ tem na NF-e. ADN é o ambiente nacional onde ficam as notas e as consultas. Tomador é quem contrata o serviço. E-código é o código de recusa da Sefin, como E0625.

O que é igual à NF-e

Se você já integrou a NF-e ou a NFC-e, o seu cliente HTTP continua valendo.

Assunto	Como funciona na NFS-e
Chave de API	A mesma. O ambiente vem da chave: `mn_sim_` (simulação), `mn_hom_` (homologação, que na NFS-e é a produção restrita da Sefin, sem valor fiscal) e `mn_prod_`. As permissões novas são `nfse.read` e `nfse.write`; a chave de acesso completo já cobre.
`ref` e `Idempotency-Key`	Iguais. A mesma `ref` com os mesmos dados devolve a mesma nota (`200` com o cabeçalho `Idempotent-Replayed`). Com dados diferentes, se a nota foi rejeitada, vira correção; em outro estado, dá `409 ref_em_uso`.
Erros	O mesmo envelope. `422` quer dizer dados inválidos: nada foi criado e nenhum número foi usado. Recusa da Sefin não é erro HTTP: é a nota no estado `rejeitada`.
Listas	`dados`, `tem_mais` e `proximo_cursor`, com `limite` de 1 a 100.
Webhooks	O mesmo endpoint e a mesma assinatura. Basta inscrever os eventos `nfse.*`.
Simulação	Os valores `SIM-…` funcionam do mesmo jeito (veja Simulação).

O que muda

	NF-e e NFC-e	NFS-e Nacional
Quem autoriza	A SEFAZ da UF	A Sefin Nacional
Identificador	`nfe_…` / `nfce_…`	`nfse_…`
Chave	44 dígitos, calculada antes de enviar	50 posições, só existe depois da autorização. Use a que vem na resposta; não calcule.
Numeração	Série e número da nota	Série e número da DPS (`serie_dps`, `numero_dps`). O número da nota (`numero_nfse`) é dado pela Sefin ao autorizar.
Código de recusa	Número, como `778`	E-código, como `E0625`, no mesmo campo `sefaz.cstat`, em texto. Na autorização, `sefaz.cstat` fica `null`.
Protocolo	Existe	Não existe, nem código de verificação. Para conferir uma nota, use a `chave`.
Itens	Até 990 itens	Um serviço por nota. `servicos[]` aceita de 1 a 50 linhas, todas com os mesmos códigos fiscais; o MadNotas soma os valores e monta uma descrição só. Códigos diferentes vão em notas diferentes.
Contingência, inutilização e carta de correção	Existem	Não existem. Se a Sefin estiver fora do ar, a nota fica `processando` e o MadNotas tenta de novo sozinho. Para corrigir uma nota autorizada, use a substituição.
Cancelamento	Justificativa de texto	Um motivo (`1`, `2` ou `9`) mais a justificativa de 15 a 255 caracteres.
PDF	DANFE / DANFCE	DANFSe, sempre gerado pelo MadNotas, nos três ambientes.
Município	Não importa	O município do emitente precisa estar ativo no Sistema Nacional da NFS-e. O MadNotas confere antes de reservar número: se não estiver, `422 municipio_nao_conveniado`.

Os três ambientes

	Simulação	Homologação	Produção
Fala com	Um simulador do MadNotas. Nada sai dele.	Produção restrita da Sefin, sem valor fiscal	Sefin Nacional
Certificado A1	Dispensado	Obrigatório (`422 certificado_indisponivel`)	Obrigatório
Chave e número da nota	Fictícios, no formato real. O número começa com `9`.	Da Sefin	Da Sefin
DANFSe	Com a tarja “SIMULAÇÃO — SEM VALOR FISCAL”	Com a tarja “HOMOLOGAÇÃO — SEM VALOR FISCAL”	Sem tarja
Valores `SIM-…`	Valem	Ignorados, com o aviso `simulacao_ignorada`

Da primeira chave à primeira nota em simulação

Todos os exemplos abaixo usam dados fictícios e vêm da mesma fonte da referência e do Playground. Troque $MADNOTAS_URL pelo endereço base da API e $MADNOTAS_CHAVE pela sua chave mn_sim_.

1. Crie a chave e o emitente

Crie uma chave de simulação em Integração › Chaves de API e cadastre o emitente (o CNPJ de cada filial), como mostra o Primeiros passos. O id que o emitente recebe é um número inteiro; é ele que vai nas rotas abaixo no lugar de {id}.

2. Ligue a NFS-e no emitente

Os dados municipais ficam no emitente, uma vez só. Os códigos que você guardar aqui valem quando a nota não os trouxer, e é o que deixa a emissão curta.

PUT /emitentes/{id}/nfse

curl -X PUT "$MADNOTAS_URL/emitentes/12/nfse" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE" \
  -H "Content-Type: application/json" \
  -d @nfse-emitente.json

nfse-emitente.json (dados fictícios)

{
    "habilitada": true,
    "opcao_simples": "me_epp",
    "regime_apuracao_simples": "tudo_no_simples",
    "regime_especial": "nenhum",
    "municipio_prestacao_padrao": "3550308",
    "tributacao_iss_padrao": "tributavel",
    "aliquota_iss_padrao": "2.0000",
    "codigo_tributacao_nacional_padrao": "010701",
    "codigo_nbs_padrao": "115013000",
    "codigo_tributacao_municipal_padrao": null,
    "percentual_tributos_simples": "6.0000",
    "ibscbs": {
        "habilitado": false,
        "cst": "000",
        "classificacao_tributaria": "000001",
        "indicador_operacao": "100301"
    }
}

Campo	Para que serve
`habilitada`	Sem `true`, `POST /nfse` responde `422 nfse_nao_habilitada`.
`opcao_simples`	`nao_optante`, `mei` ou `me_epp`.
`regime_apuracao_simples`	Só para `me_epp`: `tudo_no_simples`, `iss_fora_do_simples` ou `tudo_fora_do_simples`.
`aliquota_iss_padrao`	Alíquota do ISS quando a nota não trouxer. Quem é ME/EPP e apura tudo no Simples não informa alíquota: a Sefin recusaria com `E0625`, e o MadNotas já não envia.
`codigo_tributacao_nacional_padrao`, `codigo_nbs_padrao`	Os códigos do serviço, quando a linha não trouxer. Procure-os em `GET /utilitarios/ctribnac?q=` e `GET /utilitarios/nbs?q=`.
`municipio_prestacao_padrao`	Código IBGE do município onde o serviço é prestado, quando a nota não trouxer. Sem ele, vale o município do emitente.

3. Defina a série da DPS

A numeração da NFS-e é separada da NF-e. Use a mesma rota, com "modelo": "nfse":

PUT /emitentes/{id}/numeracao

curl -X PUT "$MADNOTAS_URL/emitentes/12/numeracao" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"modelo":"nfse","serie":1,"proximo_numero":1}'

A série vai de 1 a 89999 e o número de 1 a 999999999. O número só sobe. Sem esta etapa, a emissão responde 422 serie_dps_ausente, antes de reservar qualquer número.

4. Confira se está pronto

GET /emitentes/{id}/prontidao?modelo=nfse

curl "$MADNOTAS_URL/emitentes/12/prontidao?modelo=nfse" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE"

A resposta traz pronto e uma lista de itens (NFS-e habilitada, regime, série da DPS e, em homologação e produção, certificado e município conveniado). Enquanto houver item em falta, a emissão vai parar nele.

5. Emita a primeira nota

Com os padrões do emitente, só o serviço e o tomador são obrigatórios:

POST /nfse

curl -X POST "$MADNOTAS_URL/nfse" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE" \
  -H "Content-Type: application/json" \
  -d @servico.json

servico.json (mínimo, dados fictícios)

{
    "ref": "nfse-os-778-1",
    "servicos": [
        {
            "descricao": "Manutenção preventiva de impressora",
            "valor_unitario": "350.00"
        }
    ],
    "tomador": {
        "documento": "38461592719",
        "nome": "Maria Fictícia da Silva"
    }
}

Ver um exemplo completo, com retenções

servico-completo.json (dados fictícios)

{
    "ref": "nfse-venda-1234-1",
    "emitente_id": 12,
    "data_competencia": "2026-10-30",
    "calcular": true,
    "municipio_prestacao": "3550308",
    "servicos": [
        {
            "codigo": "SUP-MENSAL",
            "descricao": "Suporte técnico em informática — outubro/2026",
            "quantidade": "1",
            "valor_unitario": "1500.00",
            "codigo_tributacao_nacional": "010701",
            "codigo_nbs": "115013000",
            "codigo_tributacao_municipal": null
        },
        {
            "descricao": "Visita técnica extra (2 h)",
            "quantidade": "2",
            "valor_unitario": "150.00",
            "codigo_tributacao_nacional": "010701",
            "codigo_nbs": "115013000"
        }
    ],
    "informacoes_complementares": null,
    "tomador": {
        "documento": "72619438000163",
        "nome": "Comercial Horizonte Ltda",
        "inscricao_municipal": null,
        "email": "fiscal@horizonte.example",
        "telefone": "1133334444",
        "endereco": {
            "codigo_municipio": "3550308",
            "cep": "01001000",
            "logradouro": "Praça da Sé",
            "numero": "100",
            "complemento": "sala 5",
            "bairro": "Sé"
        }
    },
    "valores": {
        "desconto_incondicionado": "0.00",
        "desconto_condicionado": "0.00",
        "ajuste_base_iss": null
    },
    "iss": {
        "tributacao": "tributavel",
        "aliquota": "2.0000",
        "retido": true,
        "tipo_imunidade": null
    },
    "retencoes": {
        "irrf": {
            "aliquota": "1.5000"
        },
        "csll": {
            "aliquota": "1.0000"
        },
        "inss": {
            "aliquota": "11.0000"
        },
        "pis": {
            "retido": true
        },
        "cofins": {
            "retido": true
        }
    },
    "tributos_federais": {
        "pis_cofins": {
            "cst": "01",
            "aliquota_pis": "0.6500",
            "aliquota_cofins": "3.0000"
        }
    },
    "ibscbs": null,
    "obra": null,
    "totais": {
        "valor_servicos": "1800.00",
        "valor_liquido": "1455.30"
    }
}

Com calcular: true (o padrão), o MadNotas calcula o ISS, as retenções e o valor líquido. Se você mandar totais, ele confere.

A resposta sai na hora, porque a Sefin responde na hora. POST /nfse espera até 20 segundos (mude com ?aguardar=, de 0 a 25): 201 com a nota já no estado final ou 202 se ainda estiver processando.

Resposta 201 (dados fictícios)

{
    "id": "nfse_01m69evn1vyj7zt0feqh41hpks",
    "objeto": "nfse",
    "ambiente": "simulacao",
    "modelo": "nfse",
    "ref": "QAN3-140635-full",
    "status": "substituida",
    "etapa": "concluido",
    "emitente": {
        "id": 122,
        "cnpj": "40643205000100",
        "razao_social": "QA N3 Serviços Rio de Janeiro Ltda"
    },
    "serie_dps": 1,
    "numero_dps": 11,
    "id_dps": "DPS330455724064320500010000001000000000000011",
    "chave": "33045572240643205000100900100000001126102826225382",
    "numero_nfse": "9001000000011",
    "competencia": "2026-10-30",
    "data_emissao": "2026-10-31T14:07:02-03:00",
    "municipio_emissor": "3304557",
    "municipio_prestacao": "3550308",
    "codigo_tributacao_nacional": "010701",
    "codigo_nbs": "115013000",
    "valor_servicos": "1800.00",
    "valor_iss": "36.00",
    "iss_retido": true,
    "valor_retido": "344.70",
    "valor_liquido": "1455.30",
    "valor_total": "1800.00",
    "tomador": {
        "documento": "72619438000163",
        "nome": "Comercial Horizonte Ltda"
    },
    "sefaz": {
        "cstat": null,
        "motivo": null,
        "protocolo": null,
        "recibo": null
    },
    "autorizada_em": "2026-10-31T14:07:02-03:00",
    "cancelada_em": "2026-10-31T14:10:05-03:00",
    "erros": [],
    "avisos": [
        {
            "campo": null,
            "codigo": "simulacao_assinatura_teste",
            "mensagem": "Em simulação a DPS é assinada com um certificado de teste."
        }
    ],
    "tentativas": 1,
    "proxima_tentativa_em": null,
    "origem": "api",
    "substitui": null,
    "substituida_por": "nfse_01m69f11n9drg9h93bmgaa72my",
    "criado_em": "2026-10-31T14:07:02-03:00",
    "atualizado_em": "2026-10-31T14:10:05-03:00",
    "links": {
        "self": "https://api.madnotas.com.br/api/v1/nfse/nfse_01m69evn1vyj7zt0feqh41hpks",
        "xml": "https://api.madnotas.com.br/api/v1/nfse/nfse_01m69evn1vyj7zt0feqh41hpks/xml",
        "danfse": "https://api.madnotas.com.br/api/v1/nfse/nfse_01m69evn1vyj7zt0feqh41hpks/danfse",
        "eventos": "https://api.madnotas.com.br/api/v1/nfse/nfse_01m69evn1vyj7zt0feqh41hpks/eventos"
    }
}

Repare nestes campos: id (guarde, é a identidade da nota); chave (50 posições, só depois de autorizada); numero_nfse (da Sefin; em simulação começa com 9); numero_dps (use só para exibir, porque o MadNotas pode trocá-lo se a Sefin recusar o número); valor_liquido (já com as retenções).

6. Consulte, baixe o XML e o PDF

Consultar e baixar

curl "$MADNOTAS_URL/nfse/nfse_ID?aguardar=10" -H "Authorization: Bearer $MADNOTAS_CHAVE"
curl "$MADNOTAS_URL/nfse/nfse_ID/xml" -H "Authorization: Bearer $MADNOTAS_CHAVE"
curl "$MADNOTAS_URL/nfse/nfse_ID/danfse" -H "Authorization: Bearer $MADNOTAS_CHAVE" -o nota.pdf

O XML da NFS-e é o que a Sefin devolveu; com ?tipo=dps você baixa a DPS assinada. O DANFSe é gerado pelo MadNotas e só existe para nota autorizada, cancelada ou substituída. Para esperar uma nota processando, use GET /nfse/{id}?aguardar=10 ou o webhook; chamar mais de uma vez a cada 30 segundos não acelera nada.

Estados da nota

Estado	Quando	O que vem depois
`processando`	A DPS foi assinada e está indo, sendo consultada ou esperando nova tentativa.	`autorizada` ou `rejeitada`
`autorizada`	A Sefin gerou a NFS-e.	`cancelada` ou `substituida`
`rejeitada`	A Sefin recusou a DPS.	Correção (volta a `processando`) ou descarte
`cancelada`	O cancelamento foi aceito, inclusive se feito fora do MadNotas.	Estado final
`substituida`	A nota que a substitui foi autorizada.	Estado final
`descartada`	Uma nota rejeitada que você desistiu de corrigir.	Estado final

Não existe denegada nem contingencia na NFS-e. Antes de reenviar uma DPS cuja resposta se perdeu, o MadNotas consulta o ADN: se a nota já existe, ele a anexa. Nunca sai nota em dobro.

Se a Sefin recusar

A recusa volta como 201 com status: "rejeitada" e a lista erros. Cada erro traz o E-código em sefaz.cstat, o campo provável, uma dica e o link para a explicação em /desenvolvedores/erros/E…, como E0625.

Resposta 201 com nota rejeitada (dados fictícios)

{
    "id": "nfse_01m69f6x872ssjbg053z9v2c50",
    "objeto": "nfse",
    "ambiente": "simulacao",
    "modelo": "nfse",
    "ref": "QAN3-140635-exrej",
    "status": "rejeitada",
    "etapa": "concluido",
    "emitente": {
        "id": 121,
        "cnpj": "47591675000116",
        "razao_social": "QA N3 Serviços São Paulo Ltda"
    },
    "serie_dps": 1,
    "numero_dps": 46,
    "id_dps": "DPS355030824759167500011600001000000000000046",
    "chave": null,
    "numero_nfse": null,
    "competencia": "2026-10-31",
    "data_emissao": "2026-10-31T14:13:10-03:00",
    "municipio_emissor": "3550308",
    "municipio_prestacao": "3550308",
    "codigo_tributacao_nacional": "010701",
    "codigo_nbs": "115013000",
    "valor_servicos": "350.00",
    "valor_iss": "0.00",
    "iss_retido": false,
    "valor_retido": "0.00",
    "valor_liquido": "350.00",
    "valor_total": "350.00",
    "tomador": {
        "documento": "38461592719",
        "nome": "Maria Fictícia da Silva"
    },
    "sefaz": {
        "cstat": "E0625",
        "motivo": "Alíquota informada para optante ME/EPP do Simples Nacional que apura o ISSQN no Simples e não tem retenção.",
        "protocolo": null,
        "recibo": null
    },
    "autorizada_em": null,
    "cancelada_em": null,
    "erros": [
        {
            "campo": "iss.aliquota",
            "codigo": "sefaz_E0625",
            "mensagem": "Alíquota informada para optante ME/EPP do Simples Nacional que apura o ISSQN no Simples e não tem retenção.",
            "sefaz": {
                "cstat": "E0625",
                "xmotivo": "Alíquota informada para optante ME/EPP do Simples Nacional que apura o ISSQN no Simples e não tem retenção."
            },
            "dica": "Optante ME/EPP que apura o ISS no Simples e não tem retenção não informa alíquota. Tire `iss.aliquota` ou confira o regime do emitente.",
            "documentacao": "https://api.madnotas.com.br/desenvolvedores/erros/E0625"
        }
    ],
    "avisos": [
        {
            "campo": null,
            "codigo": "simulacao_assinatura_teste",
            "mensagem": "Em simulação a DPS é assinada com um certificado de teste."
        }
    ],
    "tentativas": 1,
    "proxima_tentativa_em": null,
    "origem": "api",
    "substitui": null,
    "substituida_por": null,
    "criado_em": "2026-10-31T14:13:11-03:00",
    "atualizado_em": "2026-10-31T14:13:11-03:00",
    "links": {
        "self": "https://api.madnotas.com.br/api/v1/nfse/nfse_01m69f6x872ssjbg053z9v2c50",
        "xml": "https://api.madnotas.com.br/api/v1/nfse/nfse_01m69f6x872ssjbg053z9v2c50/xml",
        "eventos": "https://api.madnotas.com.br/api/v1/nfse/nfse_01m69f6x872ssjbg053z9v2c50/eventos"
    }
}

Corrija com PUT /nfse/{id}, mandando os dados completos de novo, ou repita POST /nfse com a mesma ref e os dados corrigidos: os dois fazem a mesma coisa, e a nota volta a processando com o mesmo id. Para desistir, DELETE /nfse/{id} descarta a nota e devolve o número da DPS. Só nota rejeitada aceita as duas coisas (409 documento_nao_corrigivel e documento_nao_descartavel nos outros estados). Para testar sem emitir, use POST /nfse/validar: ele responde 200 sempre, com valido verdadeiro ou falso, a lista de erros e a DPS que seria enviada, sem reservar número.

Cancelar

Só nota autorizada se cancela. O prazo e as regras são do município e da Sefin: fora deles o cancelamento volta como evento rejeitado (o HTTP é 201), a nota continua autorizada e sai o webhook nfse.evento_rejeitado.

POST /nfse/{id}/cancelamento

{
    "codigo_motivo": "1",
    "justificativa": "Valor do serviço digitado errado na emissão"
}

codigo_motivo é 1 (erro na emissão), 2 (serviço não prestado) ou 9 (outros), e a justificativa tem de 15 a 255 caracteres.

Substituir uma nota autorizada

Não há carta de correção na NFS-e. Para corrigir uma nota autorizada, emita uma nova que a substitua: a rota recebe os dados completos da nota nova mais o bloco substituicao, com um motivo e um texto de 15 a 255 caracteres.

POST /nfse/{id}/substituicao (trecho)

{
    "ref": "nfse-venda-1234-2",
    "substituicao": {
        "codigo_motivo": "99",
        "motivo": "Correção da descrição e do valor do serviço prestado"
    },
    "servicos": [
        {
            "descricao": "Suporte técnico em informática — outubro/2026",
            "valor_unitario": "1650.00"
        }
    ],
    "tomador": {
        "documento": "72619438000163",
        "nome": "Comercial Horizonte Ltda"
    }
}

A resposta é a nota nova, com id novo e substitui apontando para a antiga. Use uma ref nova.
A antiga só vira substituida quando a nova é autorizada. Saem os webhooks nfse.autorizada (nova) e nfse.substituida (antiga).
Se a nova for rejeitada, a antiga continua autorizada. Corrija a nova com PUT; não abra outra.
O motivo vai de 01 a 05 ou 99. Só nota autorizada, do mesmo emitente, pode ser substituída (409 documento_nao_substituivel).

Município e inscrição municipal

Em homologação e produção, o MadNotas pergunta ao ADN se o município do emitente está ativo no Sistema Nacional (e guarda a resposta por 24 horas) e consulta o cadastro nacional de contribuintes para saber se a inscrição municipal vai na DPS. Você só cadastra a inscrição: o MadNotas põe ou tira da DPS sozinho. Para ver a situação de um município, use GET /utilitarios/municipios/{ibge}/nfse. Quando um município entra ou sai do convênio, sai o webhook emitente.nfse_convenio_alterado.

Webhooks

Inscreva-se em nfse.* (ou nos eventos que quiser). O formato, a assinatura e as novas tentativas são os mesmos dos outros webhooks, em Webhooks.

Evento	Quando
`nfse.autorizada`	A Sefin gerou a NFS-e.
`nfse.rejeitada`	A Sefin recusou a DPS. Os dados trazem a lista `erros`.
`nfse.cancelada`	O cancelamento foi aceito, inclusive o feito fora do MadNotas.
`nfse.substituida`	A nota nova foi autorizada e a antiga virou `substituida`.
`nfse.evento_rejeitado`	A Sefin recusou um cancelamento; a nota segue autorizada.
`emitente.nfse_convenio_alterado`	O município do emitente entrou ou saiu do convênio.

Se o webhook não chegar, consulte com GET /nfse/{id}?aguardar=10.

Simulação

Com chave mn_sim_, escreva o cenário no cabeçalho MadNotas-Simular ou no codigo do primeiro serviço (o cabeçalho vale mais). O resultado é sempre o mesmo, e nada sai do MadNotas. O Playground do painel (Integração › Playground) emite cada cenário e mostra a resposta.

Valor	O que acontece	O que você vê
(nenhum) ou `SIM-NORMAL`	A Sefin simulada autoriza.	`201 autorizada`, com chave e número fictícios.
`SIM-REJ-E0625` (ou outro E-código)	Recusa com esse código e o texto da base.	`201 rejeitada`, com o código em `sefaz.cstat`.
`SIM-TIMEOUT`	A DPS chega e é autorizada, mas a resposta se perde.	O MadNotas consulta o ADN simulado e termina `autorizada`, sem duplicar. O pedido volta `202 processando` (etapa `verificando`) com o cabeçalho `Retry-After`; a nota aparece autorizada na consulta depois de uns 30 segundos. Acompanhe com `GET /nfse/{id}?aguardar=10` ou pelo webhook.
`SIM-LENTO`	A primeira tentativa encontra a Sefin fora do ar; a seguinte autoriza.	`202 processando` e, em cerca de 1 minuto, `autorizada`.
`SIM-DUPLICIDADE`	A Sefin diz que a DPS já foi processada.	O MadNotas consulta pela DPS, anexa a nota e termina `autorizada`.
`SIM-CONFLITO`	O número da DPS já foi usado por outra DPS.	O MadNotas usa o próximo número, avisa pelo webhook `emitente.numeracao_conflito` e autoriza.
`SIM-NAO-CONVENIADO`	O município não está no convênio.	`422 municipio_nao_conveniado`; nenhum número usado.
`SIM-REJ-…` na justificativa do cancelamento	A Sefin recusa o cancelamento.	Evento `rejeitado`; a nota segue `autorizada`.
`SIM-REJ-…` no `codigo` do primeiro serviço da substituta	A Sefin recusa a nota nova.	A nova fica `rejeitada`; a antiga segue `autorizada`.

O cabeçalho MadNotas-Simular-Atraso (0 a 600 segundos) adia a resposta do SIM-LENTO e do SIM-TIMEOUT. Os cenários SIM-DENEGADA, SIM-OFFLINE e SIM-OFFLINE-REJ não existem na NFS-e: a nota é autorizada e vem o aviso simulacao_cenario_invalido. Para derrubar a Sefin simulada da sua empresa, use POST /simulacao/sefaz com "autoridade": "sefin_nacional"; veja Simulação.

Limites e cobrança

Pedidos por minuto: o do plano da empresa (ou o limite da chave, se for menor).
Corpo de até 5 MB; servicos[] de 1 a 50 linhas; ref de até 100 caracteres sem acento; justificativa de 15 a 255.
Em produção, a NFS-e conta na mesma franquia e no mesmo excedente da NF-e e da NFC-e. Cancelar e substituir não contam como nota nova; a nota substituta conta, porque é uma nota autorizada. Simulação e homologação não contam.
Fora do que está aqui, vale o OpenAPI: se algo divergir, ele manda.

Rotas da NFS-e

Esta lista vem do OpenAPI publicado. Os parâmetros, as respostas e o campo “Experimente” de cada rota estão na referência.

Rota	O que faz
`GET /nfse`	Listar NFS-e
`POST /nfse`	Emitir NFS-e
`POST /nfse/validar`	Validar NFS-e (sem emitir)
`GET /nfse/{id}`	Consultar NFS-e
`PUT /nfse/{id}`	Corrigir NFS-e rejeitada
`DELETE /nfse/{id}`	Descartar NFS-e rejeitada
`GET /nfse/{id}/xml`	Baixar XML
`GET /nfse/{id}/danfse`	Baixar DANFSe (PDF)
`POST /nfse/{id}/cancelamento`	Cancelar NFS-e
`POST /nfse/{id}/substituicao`	Substituir NFS-e
`GET /nfse/{id}/eventos`	Listar eventos
`POST /nfse/{id}/email`	Enviar por e-mail
`PUT /emitentes/{id}/nfse`	Configurar a NFS-e do emitente
`GET /utilitarios/municipios/{ibge}/nfse`	Convênio do município com a NFS-e Nacional
`GET /utilitarios/ctribnac` · `/utilitarios/nbs`	Códigos de serviço nacionais (busca por `q`)