NFS-e
Emissão de NFS-e do Padrão Nacional, cancelamento, substituição e DANFSe.
A NFS-e é emitida no Padrão Nacional: a API monta a DPS, assina com o A1 do emitente e envia à Sefin Nacional.
Toda rota exige X-Emitente-Id e o produto NFSE contratado.
Antes de emitir, o emitente precisa de certificado A1, inscrição municipal e uma
série NFSE no ambiente dele.
Emissão
POST /api/v1/nfse
X-Emitente-Id: 8b3c1f0e-5d2a-4a1b-9c3d-2e1f0a9b8c7d
Idempotency-Key: 3f1c2b9e-5a7d-4c1e-9b2f-8d6a0e4c7b21
{
"competencia": "2026-11-06",
"tomador": {
"cnpjCpf": "11222333000181",
"nome": "Cliente Exemplo Ltda",
"endereco": { "logradouro": "Rua Exemplo", "numero": "100", "bairro": "Centro",
"codigoMunicipio": "5300108", "cep": "70000000" },
"email": "financeiro@cliente.example"
},
"servico": {
"codigoTributacaoNacional": "010101",
"codigoTributacaoMunicipal": "001",
"codigoNbs": "115022000",
"descricao": "Análise e desenvolvimento de sistemas.",
"codigoMunicipioPrestacao": "5300108"
},
"valorServico": "19200.00",
"issqn": { "tributacao": "OPERACAO_TRIBUTAVEL", "retencao": "NAO_RETIDO" },
"ibsCbs": { "cst": "000", "classificacaoTributaria": "000001", "indicadorOperacao": "100301",
"usoConsumoPessoal": false }
}| Campo | Observação |
|---|---|
serie | Opcional; padrão = série NFSE padrão do ambiente |
competencia | Data da competência do serviço |
tomador | Opcional: cnpjCpf (DV conferido), inscricaoMunicipal, nome, endereco, telefone, email |
servico.codigoTributacaoNacional | 6 dígitos (código de tributação nacional) |
servico.codigoTributacaoMunicipal | 3 dígitos, quando o município desdobra o serviço (ex.: Brasília 001) |
servico.codigoNbs, descricao, codigoMunicipioPrestacao, informacoesComplementares | |
valorServico | 2 casas; mais casas → 400 (nunca arredonda) |
issqn.tributacao | OPERACAO_TRIBUTAVEL, IMUNIDADE, EXPORTACAO, NAO_INCIDENCIA |
issqn.retencao | NAO_RETIDO, RETIDO_TOMADOR, RETIDO_INTERMEDIARIO |
issqn.aliquota | Só se o município de incidência não parametriza a alíquota no Sistema Nacional |
retencoesFederais | Opcional: valorRetidoCp, valorRetidoIrrf, valorRetidoCsll |
ibsCbs | Opcional: cst, classificacaoTributaria, indicadorOperacao, usoConsumoPessoal |
tributosAproximados | Opcional: percentualFederal, percentualEstadual, percentualMunicipal |
Desdobro municipal: GET /nfse/tributacao-municipal?municipio=5300108&codigoTributacaoNacional=010101 lista os
codigoTributacaoMunicipal e as alíquotas que o município aceita para o serviço. A emissão recusa (400 em
servico.codigoTributacaoMunicipal) um desdobro fora dessa lista.
Erros do POST: 400 corpo inválido ou DPS fora do leiaute; 409 idempotency-conflito;
422 certificado-indisponivel, serie-nao-configurada. Rejeição da Sefin aparece no GET, com
status: REJEITADA e os códigos em erros (veja Erros).
A NFS-e
A resposta traz id, status, ambiente, serie, numeroDps, idDps, chaveAcesso, numeroNfse,
dataHoraProcessamento, os valores calculados pela Sefin (valorLiquido, valorIss, valorIbsCbs), erros e o
conteúdo pedido, no mesmo formato da emissão.
| Rota | Resposta |
|---|---|
GET /nfse/{id} | a NFS-e |
GET /nfse/{id}/xml | XML íntegro da NFS-e gerada; 409 nfse-nao-autorizada antes disso |
GET /nfse/{id}/danfse | PDF conforme NT 008/2026 (marcas "CANCELADA"/"SUBSTITUÍDA"); 409 antes da autorização |
GET /nfse | página, mais recentes primeiro |
GET /nfse/resumo?competencia=2026-11 | totais do mês (só autorizadas) e quantidade por status |
GET /nfse/resumo/mensal?de=2025-12&ate=2026-11 | um resumo por mês (até 60 meses) |
Filtros de GET /nfse (todos opcionais, combinados): status (um ou vários, separados por vírgula),
competenciaDe/competenciaAte, tomador (CPF/CNPJ exato ou prefixo, ou parte do nome), q (número da NFS-e, da
DPS ou tomador), pagina, tamanho.
Cancelamento
POST /api/v1/nfse/{id}/cancelamento
{ "motivo": "ERRO_NA_EMISSAO", "justificativa": "Nota emitida com o valor errado" }motivo:ERRO_NA_EMISSAO,SERVICO_NAO_PRESTADOouOUTROS;justificativade 15 a 255 caracteres.- Síncrono: responde
200com a NFS-eCANCELADA. Repetir é idempotente. - Erros:
409 nfse-nao-autorizada,422 cancelamento-rejeitado(comerrosda Sefin, ex.: prazo expirado),502 sefin-indisponivel(repita).
Substituição
POST /nfse/{id}/substituicao emite uma nova NFS-e no lugar da original. O corpo tem os mesmos campos da emissão
mais motivo (DESENQUADRAMENTO_SIMPLES, ENQUADRAMENTO_SIMPLES, INCLUSAO_IMUNIDADE_ISENCAO,
EXCLUSAO_IMUNIDADE_ISENCAO, REJEICAO_TOMADOR_INTERMEDIARIO, OUTROS) e descricaoMotivo (opcional, 15 a 255).
- Exige
Idempotency-Keye é assíncrona como a emissão:202com a substituta emPENDENTE. - Quando a substituta é gerada, a original passa a
SUBSTITUIDA. Substituta rejeitada não altera a original. - Na substituta vêm
substituiNfseId,chaveSubstituidaemotivoSubstituicao; na original,substituidaPorNfseId. - Erros:
409 nfse-nao-autorizada,409 substituicao-em-andamento,409 idempotency-conflito. - NFS-e
SUBSTITUIDAnão pode ser cancelada; XML e DANFSe continuam disponíveis.