Cancelando uma NFS-e

POST /v1/nfse/cancelar

{
  "cpf_cnpj": "11222333000181",
  "job_id": "6f8dc295-...",
  "justificativa": "Serviço não executado, conforme acordo com o tomador"
}

Informe job_id ou numero da NFS-e. O cancelamento é assíncrono: devolve 202 com um novo job_id, e consome cota de NFS-e.

Aqui não existe "a regra" — existe a regra do município

Esta é a diferença que mais surpreende quem vem da NF-e

A NF-e tem regra nacional: evento de cancelamento, justificativa de 15 caracteres, prazo em torno de 24 horas. A NFS-e não. Prazo, campos exigidos e até a possibilidade de cancelar são definidos por cada município.

Existem municípios que:

• não permitem cancelamento pela API, só pelo portal da prefeitura;
• exigem um código de motivo de uma lista própria;
• exigem o CPF de quem autorizou o cancelamento;
• aceitam substituição em vez de cancelamento;
• têm prazo de dias, e outros de horas.

Antes de desenhar o fluxo, confirme a regra do município do prestador.

Campos condicionais

Além de job_id/numero e justificativa, a rota aceita campos que alguns provedores exigem:

Campo	Quando
codigo_cancelamento	municípios que usam lista própria de motivos
cpf_autor	provedores que registram quem pediu o cancelamento
provedor	para forçar o provedor, quando a empresa tem mais de um configurado

Enviar um campo que o município não usa não atrapalha; faltar um que ele exige vira rejeição com a mensagem do próprio provedor. Ver Provedores.

Só se cancela o que foi autorizado

Situação	Cancelamento
autorizada	possível, conforme a regra do município
rejeitada	não existe o que cancelar
já cancelada	nada a fazer

Uma NFS-e rejeitada não consome numeração de NFS-e — mas o RPS já foi numerado. O contador de RPS é nosso e por ambiente; ver Referência de campos.

Depois do cancelamento

O XML do evento fica disponível como xml_cancelamento — ver Arquivos. O xml original continua lá: cancelar não apaga a nota.

Se a prefeitura aceitou mas o Conota não registrou

Acontece quando o provedor responde e a conexão cai no meio. Use POST /v1/nfse/consultar-sefaz para perguntar a ela qual é o estado real — é a consulta que vale como verdade.