NFS-e
Cancelar NFS-e
Cancelamento assíncrono: dentro da janela registra o evento de cancelamento, fora dela abre um pedido de análise fiscal.
/openapi/v2/empresas/{empresaId}/nfse/{nfseId}/cancelartoken, timestamp e sign, veja Autenticação.Cancela um documento Autorizada. A chamada é assíncrona: o HTTP 200 devolve apenas o recibo de aceitação, e o resultado chega pelos webhooks nfse.canceled / nfse.cancel_requested / nfse.cancel_denied ou pela consulta. A plataforma escolhe sozinha entre registrar o evento de cancelamento e abrir um pedido de análise fiscal, conforme a janela do município. O corpo é opcional.
Parâmetros de caminho
empresaId* | string | Identificador da empresa |
nfseId* | string | Id do documento |
* Campo obrigatório
Corpo da requisição
codigoMotivo | string | Código do motivo |
motivo | string | Justificativa |
* Campo obrigatório
nfseTaskId | int | Id da tarefa na plataforma |
status | int | Status da tarefa |
reused | bool | Tarefa reaproveitada |
createTime | string | Momento da aceitação |
O corpo é o mesmo nos dois casos; quem escolhe o caminho é a plataforma, pela janela de cancelamento do município contada a partir da autorização. Só um documento Autorizada pode ser cancelado.
Dentro da janela: evento de cancelamento
A plataforma registra o evento oficial 101101. Sucesso: o documento passa a Cancelada e chega nfse.canceled; a consulta mostra um evento Cancelamento. Recusa síncrona da autoridade: o documento continua Autorizada e chega nfse.cancel_denied.
{"codigoMotivo": "1","motivo": "Erro no valor informado pelo cliente"}
codigoMotivo | string | Código do motivo |
motivo | string | Justificativa |
* Campo obrigatório
Fora da janela: pedido de análise fiscal
A plataforma abre sozinha o pedido de análise 101103. O documento passa a EmProcessoDeCancelamento e chega nfse.cancel_requested; a consulta mostra um evento PedidoAnalise. O município decide: deferido, o documento vira Cancelada com evento AnaliseDeferida e chega nfse.canceled; indeferido, volta a Autorizada com evento AnaliseIndeferida e chega nfse.cancel_denied. Não contabilize o documento como cancelado ao enviar o pedido.
{"codigoMotivo": "2","motivo": "Servico nao prestado ao tomador"}
codigoMotivo | string | Código do motivo |
motivo | string | Justificativa |
* Campo obrigatório
Canal de São Paulo
O sistema municipal de São Paulo não tem janela nem pedido de análise: o cancelamento é registrado direto no sistema municipal e o resultado é Cancelada com nfse.canceled, ou recusa com nfse.cancel_denied.
O HTTP 200 desta chamada é só o recibo de aceitação. O resultado chega pelos webhooks abaixo (objeto de resultado da NFS-e, veja Registrar webhook) ou pela consulta, cujo motivoStatus traz o veredito da autoridade. Uma mensagem de cancelamento que não passa na validação do formato oficial faz a tarefa falhar com 10018064 e nenhum evento é registrado; confira o tamanho de motivo e o conjunto de caracteres.
Cancelado: nfse.canceled
Evento de cancelamento registrado ou análise deferida.
{"tipo": "NFS-e","empresaId": "1001","nfseId": "PED-20260918-001","nfseStatus": "Cancelada","nfseMotivoStatus": null,"nfseChaveAcesso": "35503082406730610001340000000000000000000000000077","nfseDataAutorizacao": "2026-09-19T10:00:00Z","nfseNumeroProtocolo": "3550308000000000000000000000000000000000000000000001","nfseAtualizadoEm": "2026-09-19T10:00:00Z"}
nfseStatus* | string | Status do documento após este evento |
nfseMotivoStatus | string | Veredito |
nfseNumeroProtocolo | string | Protocolo do evento |
nfseAtualizadoEm* | string | Momento desta mudança |
* Campo obrigatório
Em análise: nfse.cancel_requested
O município ainda vai decidir; o documento continua válido até lá.
{"tipo": "NFS-e","empresaId": "1001","nfseId": "PED-20260918-001","nfseStatus": "EmProcessoDeCancelamento","nfseMotivoStatus": null,"nfseChaveAcesso": "35503082406730610001340000000000000000000000000077","nfseNumeroProtocolo": "3550308000000000000000000000000000000000000000000002","nfseAtualizadoEm": "2026-09-19T10:00:00Z"}
nfseStatus* | string | Status do documento após este evento |
nfseMotivoStatus | string | Veredito |
nfseNumeroProtocolo | string | Protocolo do evento |
nfseAtualizadoEm* | string | Momento desta mudança |
* Campo obrigatório
Recusado: nfse.cancel_denied
Recusa síncrona da autoridade, tentativas de envio esgotadas ou análise indeferida. O documento continua Autorizada.
{"tipo": "NFS-e","empresaId": "1001","nfseId": "PED-20260918-001","nfseStatus": "Autorizada","nfseMotivoStatus": "105105 - Pedido de analise de cancelamento indeferido","nfseChaveAcesso": "35503082406730610001340000000000000000000000000077","nfseNumeroProtocolo": "3550308000000000000000000000000000000000000000000003","nfseAtualizadoEm": "2026-09-20T09:00:00Z"}
nfseStatus* | string | Status do documento após este evento |
nfseMotivoStatus | string | Veredito |
nfseNumeroProtocolo | string | Protocolo do evento |
nfseAtualizadoEm* | string | Momento desta mudança |
* Campo obrigatório
Pendente ─┬─► Negada├─► Falha└─► Autorizada ─┬─► Cancelada├─► EmProcessoDeCancelamento ─┬─► Cancelada│ └─► Autorizada└─► Substituida
Negada, Falha, Cancelada e Substituida são terminais. O significado de cada status está na enumeração de Consultar NFS-e.
codigoMotivoCódigo do motivo do cancelamento
Omitido vale 9.
| Valores | Significado |
|---|---|
| 1 | Erro na emissão |
| 2 | Serviço não prestado |
| 9 | Outros |
statusStatus da tarefa
| Valores | Significado |
|---|---|
| 0 | Pendente, aguardando processamento |
| 1 | Em processamento |
| 2 | Sucesso |
| 3 | Falha |
nfseStatusStatus nos callbacks de cancelamento
Só os valores que os três callbacks de cancelamento carregam; a lista completa está em Registrar webhook.
| Valores | Significado |
|---|---|
| Cancelada | Cancelado (nfse.canceled) |
| EmProcessoDeCancelamento | Pedido de análise aceito, aguardando o município (nfse.cancel_requested) |
| Autorizada | Cancelamento recusado, documento continua válido (nfse.cancel_denied) |
| Código | HTTP | |
|---|---|---|
| 10018002 | 404 | Documento não encontrado: o nfseId não pertence a este emitente. Confira o nfseId e o empresaId. |
| 10018003 | 404 | Documento não encontrado: o nfseId não pertence a este emitente. Confira o nfseId e o empresaId. |
| 10018001 | 400 | codigoMotivo fora de 1 / 2 / 9. |
| 10001001 | 400 | motivo ou codigoMotivo acima do tamanho máximo. |
| 10018040 | 400 | Já existe um pedido de análise de cancelamento em andamento. Aguarde o veredito do município. |
| 10018041 | 400 | O documento já foi substituído; não cabe mais nenhuma operação sobre ele. |
| 10018042 | 400 | O status atual não permite cancelar: o documento ainda está na fila (consulta em Pendente), foi negado, falhou ou já está cancelado. Confira o status; não é 404. |