Atendimento

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 }
}
CampoObservação
serieOpcional; padrão = série NFSE padrão do ambiente
competenciaData da competência do serviço
tomadorOpcional: cnpjCpf (DV conferido), inscricaoMunicipal, nome, endereco, telefone, email
servico.codigoTributacaoNacional6 dígitos (código de tributação nacional)
servico.codigoTributacaoMunicipal3 dígitos, quando o município desdobra o serviço (ex.: Brasília 001)
servico.codigoNbs, descricao, codigoMunicipioPrestacao, informacoesComplementares
valorServico2 casas; mais casas → 400 (nunca arredonda)
issqn.tributacaoOPERACAO_TRIBUTAVEL, IMUNIDADE, EXPORTACAO, NAO_INCIDENCIA
issqn.retencaoNAO_RETIDO, RETIDO_TOMADOR, RETIDO_INTERMEDIARIO
issqn.aliquotaSó se o município de incidência não parametriza a alíquota no Sistema Nacional
retencoesFederaisOpcional: valorRetidoCp, valorRetidoIrrf, valorRetidoCsll
ibsCbsOpcional: cst, classificacaoTributaria, indicadorOperacao, usoConsumoPessoal
tributosAproximadosOpcional: 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.

RotaResposta
GET /nfse/{id}a NFS-e
GET /nfse/{id}/xmlXML íntegro da NFS-e gerada; 409 nfse-nao-autorizada antes disso
GET /nfse/{id}/danfsePDF conforme NT 008/2026 (marcas "CANCELADA"/"SUBSTITUÍDA"); 409 antes da autorização
GET /nfsepágina, mais recentes primeiro
GET /nfse/resumo?competencia=2026-11totais do mês (só autorizadas) e quantidade por status
GET /nfse/resumo/mensal?de=2025-12&ate=2026-11um 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_PRESTADO ou OUTROS; justificativa de 15 a 255 caracteres.
  • Síncrono: responde 200 com a NFS-e CANCELADA. Repetir é idempotente.
  • Erros: 409 nfse-nao-autorizada, 422 cancelamento-rejeitado (com erros da 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-Key e é assíncrona como a emissão: 202 com a substituta em PENDENTE.
  • Quando a substituta é gerada, a original passa a SUBSTITUIDA. Substituta rejeitada não altera a original.
  • Na substituta vêm substituiNfseId, chaveSubstituida e motivoSubstituicao; na original, substituidaPorNfseId.
  • Erros: 409 nfse-nao-autorizada, 409 substituicao-em-andamento, 409 idempotency-conflito.
  • NFS-e SUBSTITUIDA não pode ser cancelada; XML e DANFSe continuam disponíveis.

Nesta página