Emissão de NFS-e

Emita NFS-e pelo mesmo motor da planilha e do painel: mesma validação, mesma fila, mesma recuperação de falha técnica. A nota emitida pela API aparece no painel, com a origem "API".

Você manda sempre o mesmo JSON, qualquer que seja o município. O que muda por município ou por cenário tributário (preencher, omitir, exigir um campo) é decidido do nosso lado, e a resposta conta o que foi feito em ajustes:

{
  "campo": "/prestador/inscricao_municipal",
  "acao": "omitido",
  "motivo": "O município não aceita a inscrição municipal do prestador nesta DPS (E0120). A nota foi reenviada sem ela.",
  "regra": "correcao.E0120"
}

acao é preenchido, omitido, derivado ou exigido; regra é o identificador estável da regra no nosso catálogo (por exemplo dps.pAliq.exigido.simples_retido, param.aliquota_iss, correcao.E0120). regras_versao traz a versão dos dois catálogos que decidiram a nota, correção automática e regras de campo, nessa ordem (2026-09-30.1+2026-10-02.1).

Quando a alíquota do ISS é obrigatória e você não manda nenhuma (nem a empresa tem uma padrão), usamos a alíquota OFICIAL que o município cadastrou no Sistema Nacional para o serviço, se ela for única na competência. Aparece como ajuste preenchido com regra param.aliquota_iss.

Status

O ciclo completo, com o que fazer em cada um e o webhook correspondente, está em Estados da NFS-e.

Status	O que significa
transmitindo	Estamos cuidando: na fila, enviando, ou recuperando uma falha técnica do Sistema Nacional. Não reenvie.
autorizada	NFS-e emitida. numero e chave_acesso preenchidos.
rejeitada	O Sistema Nacional recusou. Motivo em rejeicao. Corrija e emita uma nota nova.
cancelada	Cancelada depois de autorizada. Protocolo em cancelamento. Se foi por substituição, substituida_por diz qual nota a substituiu.
falha_transmissao	Final. A transmissão não pôde ser concluída nem confirmada, e nada mais será tentado automaticamente. Veja falha: com dps_enviada: "desconhecido", confira no Emissor Nacional antes de emitir de novo.
descartada	A nota voltou sem sucesso e foi descartada no painel.
aguardando_confirmacao	A competência da nota acabou antes de uma retentativa automática. Nada é transmitido até você confirmar em POST /v1/nfse/{id}/confirmacao (pode trocar a competência).

Se a nota passar 30 minutos em transmitindo, a resposta ganha aviso: {"codigo": "processamento_prolongado"} e sai o webhook NFSE_PROCESSAMENTO_PROLONGADO, uma vez. É só aviso: a nota continua sendo cuidada e o status não muda.

Substituir uma NFS-e

Para corrigir uma nota autorizada sem cancelar e emitir outra, emita a nota certa em POST /v1/nfse com o bloco substituicao:

{
  "empresa_id": "…",
  "tomador": { "documento": "11222333000181" },
  "valor": "1500.00",
  "servico": { "descricao": "Consultoria de setembro, valor corrigido" },
  "substituicao": { "nfse_id": "id-da-nota-original", "codigo_motivo": "99", "motivo": "Valor do serviço informado errado na nota original." }
}

A nota nova segue o caminho de sempre. Quando ela é autorizada, o Sistema Nacional cancela a original sozinho (cancelamento por substituição): a original passa a cancelada, com substituida_por, e sai o webhook NFSE_CANCELADA dela. Se a nova for rejeitada, a original continua autorizada e nada muda nela.

Antes de transmitir, recusamos com 422 o que já se sabe que não passa: nota cancelada ou já substituída (E0046), nota de outro ambiente (E0065), outra substituição da mesma nota em andamento, e codigo_motivo 99 sem motivo (E0078). O prazo de substituição do município (E0050) e a manifestação do tomador (E0070) só o Sistema Nacional sabe; voltam como rejeição, com rejeicao.explicacao.

Para NFS-e emitida fora da Sudrel, use chave_acesso no lugar de nfse_id. A substituição não existe por lote.

Construção civil: dados da obra

Nos códigos de construção civil (07.02.01, 07.02.02, 07.04.01, 07.05.01, 07.05.02, 07.06.01, 07.06.02, 07.07.01, 07.08.01, 07.17.01, 07.19.01, 14.14.03 e 14.14.04) o Sistema Nacional exige os dados da obra, e nos demais recusa. Mande servico.obra com o CNO, o CIB ou o CEP e número do endereço da obra, e o município, quando ele não vem do CEP:

{ "servico": { "codigo_nacional": "070201", "obra": { "cno": "90.012.34567/89", "municipio": "Lauro de Freitas - BA" } } }

O município da obra vira o local da prestação da nota. Nos códigos em que o ISS é devido onde a obra fica, é o convênio desse município que decide se a alíquota do ISS é exigida. Na planilha, são as colunas "CNO da obra", "CEP da obra" etc., no layout Completo.

Testando a integração (sandbox)

Use uma chave sdr_test_ nas MESMAS rotas e com o MESMO JSON. A nota é transmitida de verdade ao ambiente de testes do Sistema Nacional (produção restrita), com o certificado real da empresa, e volta autorizada ou rejeitada pelas mesmas regras. Ela não tem valor fiscal, não conta na franquia, não depende de plano e não aparece no painel. ambiente vem sandbox na resposta e nos webhooks.

Os dois ambientes nunca se cruzam: a chave de teste só enxerga notas de teste, a de produção só as de produção, e a mesma referencia ou Idempotency-Key pode ser usada nos dois. Empresa que emite pelo sistema do próprio município não tem ambiente de teste: a prontidão traz o item sandbox_municipio_proprio em bloqueio, e a emissão é recusada com 412 empresa_nao_pronta.

Falha técnica do Sistema Nacional não é resposta pra você: a nota continua transmitindo enquanto a recuperação automática trabalha (ela consulta a DPS antes de qualquer reenvio, então a nota nunca é emitida duas vezes).

Emissão mínima

curl https://api.sudrel.com.br/api/v1/nfse \
  -H "Authorization: Bearer sdr_live_..." \
  -H "Idempotency-Key: 7f1c0d9a-4a51-4e0e-9b1f-2b6f0d3c5a10" \
  -H "Prefer: wait=15" \
  -H "Content-Type: application/json" \
  -d '{"empresa_id":"0b7e6a52-3c1d-4f8e-9a20-5d4c3b2a1f00","referencia":"PED-1001","tomador":{"documento":"11222333000181"},"valor":"1500.00","servico":{"descricao":"Consultoria em sistemas"}}'

Valores em dinheiro e alíquotas vão como TEXTO com ponto decimal ("1500.00"). Número JSON é recusado, pra nenhum valor de nota fiscal depender de arredondamento de ponto flutuante.