Como cancelar NFS-e pelo seu sistema sem declarar errado ao fisco

A chamada que cancela:

O cancelamento usa a mesma referência com que a nota foi emitida, a da venda no seu sistema. Não é preciso guardar o número que a prefeitura deu: o TexFiscal sabe qual documento corresponde a cada referência, inclusive na NFS-e nacional, onde a nota se identifica pela chave de acesso.

O pedido leva dois campos no corpo. A justificativa é obrigatória, com pelo menos 15 caracteres. O motivo é opcional e aceita 1, 2 ou 3; sem ele, vale 1. Qualquer outro valor é recusado com uma mensagem que diz quais valores existem, porque declaração fiscal errada é pior do que pedido recusado.

Só uma nota autorizada pode ser cancelada. Pedir o cancelamento de uma nota que ainda está em processamento ou que foi recusada devolve 422 com o estado atual, e o seu sistema sabe que não há o que cancelar.

curl -u "SEU_TOKEN:" -X DELETE https://nfse.texfiscal.com.br/v2/nfse/PED-4471 \
  -H "Content-Type: application/json" \
  -d '{"justificativa": "Valor digitado errado no pedido", "motivo": 1}'

200  cancelada na hora
202  pedido enviado, desfecho pela consulta ou pelo webhook
422  recusado (estado, justificativa, motivo ou prefeitura)

Justificativa e motivo não são a mesma coisa:

Confundir os dois é o erro mais comum de quem integra cancelamento, e ele declara errado ao município.

• A justificativa é registro nosso. Ela fica gravada na trilha da nota no instante do pedido, mesmo quando a prefeitura ainda não respondeu, e serve de prova de auditoria. Ela não chega à prefeitura: o padrão ABRASF, usado pela maioria dos municípios, não tem campo livre para isso.
• O motivo é a declaração ao fisco. Vale 1 para erro na emissão, 2 para serviço não prestado e 3 para erro de assinatura. É ele que o município registra como causa do cancelamento.

Na tela do seu sistema, isso costuma virar um seletor com as três opções e um campo de texto livre. O seletor vira o motivo; o texto vira a justificativa. Quem escolhe o motivo é quem conhece o fato: a pessoa que emitiu ou o contador, e não um valor padrão escondido no código.

O prazo é da prefeitura, e ninguém mais o conhece:

Cada município define até quando uma NFS-e pode ser cancelada, e há municípios que exigem pedido no portal ou processo administrativo depois de certo prazo. O TexFiscal não guarda essa regra e não finge conhecê-la: ele encaminha o pedido, e quem responde é a prefeitura.

Passado o prazo, a recusa volta como 422 cancelamento_recusado, com a mensagem do município. Nesse caso a nota continua autorizada, exatamente como estava, e o seu sistema deve mostrar a mensagem a quem pediu, em vez de marcar a venda como cancelada.

A consequência prática para quem desenha a tela: não planeje um botão de cancelar que valha para sempre. O botão pode existir, mas a resposta da prefeitura é que decide, e a tela precisa saber dizer não.

Os quatro desfechos, e o que o seu sistema faz com cada um:

1. Cancelada na hora (200). A prefeitura confirmou. A nota passa a cancelada e o webhook avisa nfse_cancelada.
2. Pedido enviado, sem resposta conclusiva (202). A nota fica em cancelamento pendente, e a consulta resolve o desfecho. Um segundo pedido nesse estado não manda outro cancelamento à prefeitura: ele consulta o que já foi pedido.
3. Recusado (422). A prefeitura disse não, por prazo ou por regra dela. A nota volta a autorizada e continua valendo.
4. Cancelamento não efetivado. O pedido parecia ter ido, mas a prefeitura ainda tem a nota como autorizada. O TexFiscal devolve a nota a autorizada e avisa nfse_cancelamento_nao_efetivado, que existe justamente para alguém agir: conferir o prazo e repetir o pedido.

Mais um cuidado que já vem pronto: dois pedidos de cancelamento simultâneos para a mesma nota, vindos de dois cliques ou de duas telas, não viram dois pedidos à prefeitura. O primeiro marca a nota antes de transmitir, e o segundo encontra o pedido em andamento.

A nota substituta, com uma referência nova:

Cancelou porque o valor estava errado? A substituta é uma nota nova, e precisa de uma referência nova. Repetir a emissão com a referência da nota cancelada devolve 409 ref_encerrada, porque a nota cancelada continua existindo como documento fiscal e a referência é a chave que impede duas notas para a mesma venda.

O padrão mais simples é acrescentar um sufixo à referência original: PED-4471 vira PED-4471-R2. Assim o seu sistema mantém a ligação entre a venda e as duas notas, e a conciliação do mês mostra as duas com clareza.

Atenção a uma regra que vale para tudo: a referência distingue maiúscula de minúscula. Derive sempre da mesma forma, senão a mesma venda pode ganhar duas notas.