NFS-e
Cancel NFS-e
Asynchronous cancellation: within the window it registers the cancellation event, past the window it files a tax review request.
/openapi/v2/empresas/{empresaId}/nfse/{nfseId}/cancelartoken, timestamp and sign signature headers, see Authentication.Cancels an Autorizada document. The call is asynchronous: HTTP 200 returns only the acceptance receipt, and the outcome arrives through the nfse.canceled / nfse.cancel_requested / nfse.cancel_denied webhooks or through the query. The platform decides on its own between registering a cancellation event and filing a tax review request, depending on the municipal window. The body is optional.
Path parameters
empresaId* | string | Company identifier |
nfseId* | string | Document id |
* Required field
Request body
codigoMotivo | string | Reason code |
motivo | string | Justification |
* Required field
nfseTaskId | int | Platform task id |
status | int | Task status |
reused | bool | Task reused |
createTime | string | Acceptance time |
The body is the same in both cases; the platform picks the path from the municipal cancellation window counted from authorization. Only an Autorizada document can be cancelled.
Within the window: cancellation event
The platform registers official event 101101. Success: the document becomes Cancelada and nfse.canceled arrives; the query shows a Cancelamento event. Synchronous refusal by the authority: the document stays Autorizada and nfse.cancel_denied arrives.
{"codigoMotivo": "1","motivo": "Erro no valor informado pelo cliente"}
codigoMotivo | string | Reason code |
motivo | string | Justification |
* Required field
Past the window: tax review request
The platform files review request 101103 on its own. The document becomes EmProcessoDeCancelamento and nfse.cancel_requested arrives; the query shows a PedidoAnalise event. The municipality decides: granted, the document turns Cancelada with an AnaliseDeferida event and nfse.canceled arrives; refused, it goes back to Autorizada with an AnaliseIndeferida event and nfse.cancel_denied arrives. Do not book the document as cancelled when you send the request.
{"codigoMotivo": "2","motivo": "Servico nao prestado ao tomador"}
codigoMotivo | string | Reason code |
motivo | string | Justification |
* Required field
São Paulo channel
The São Paulo municipal system has neither a window nor a review request: the cancellation is registered directly with the municipal system and the outcome is Cancelada with nfse.canceled, or a refusal with nfse.cancel_denied.
The HTTP 200 of this call is only the acceptance receipt. The outcome arrives through the webhooks below (NFS-e result object, see Register webhook) or through the query, whose motivoStatus carries the authority verdict. A cancellation message that fails the official format validation makes the task fail with 10018064 and no event is registered; check the motivo length and character set.
Cancelled: nfse.canceled
Cancellation event registered or review granted.
{"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 | Document status after this event |
nfseMotivoStatus | string | Verdict |
nfseNumeroProtocolo | string | Event protocol |
nfseAtualizadoEm* | string | Time of this change |
* Required field
Under review: nfse.cancel_requested
The municipality still has to decide; the document stays valid until then.
{"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 | Document status after this event |
nfseMotivoStatus | string | Verdict |
nfseNumeroProtocolo | string | Event protocol |
nfseAtualizadoEm* | string | Time of this change |
* Required field
Refused: nfse.cancel_denied
Synchronous refusal by the authority, dispatch retries exhausted or review refused. The document stays 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 | Document status after this event |
nfseMotivoStatus | string | Verdict |
nfseNumeroProtocolo | string | Event protocol |
nfseAtualizadoEm* | string | Time of this change |
* Required field
Pendente ─┬─► Negada├─► Falha└─► Autorizada ─┬─► Cancelada├─► EmProcessoDeCancelamento ─┬─► Cancelada│ └─► Autorizada└─► Substituida
Negada, Falha, Cancelada and Substituida are terminal. The meaning of each status is in the enumeration of Query NFS-e.
codigoMotivoCancellation reason code
Omitted means 9.
| Values | Meaning |
|---|---|
| 1 | Issuing error |
| 2 | Service not provided |
| 9 | Other |
statusTask status
| Values | Meaning |
|---|---|
| 0 | Pending, waiting to be processed |
| 1 | Processing |
| 2 | Success |
| 3 | Failed |
nfseStatusStatus on cancellation callbacks
Only the values carried by the three cancellation callbacks; the full list is in Register webhook.
| Values | Meaning |
|---|---|
| Cancelada | Cancelled (nfse.canceled) |
| EmProcessoDeCancelamento | Review request accepted, awaiting the municipality (nfse.cancel_requested) |
| Autorizada | Cancellation refused, document stays valid (nfse.cancel_denied) |
| Code | HTTP | |
|---|---|---|
| 10018002 | 404 | Document not found: the nfseId does not belong to this issuer. Check the nfseId and the empresaId. |
| 10018003 | 404 | Document not found: the nfseId does not belong to this issuer. Check the nfseId and the empresaId. |
| 10018001 | 400 | codigoMotivo outside 1 / 2 / 9. |
| 10001001 | 400 | motivo or codigoMotivo over the maximum length. |
| 10018040 | 400 | A cancellation review is already in progress. Wait for the municipal outcome. |
| 10018041 | 400 | The document has already been replaced; no further operation applies to it. |
| 10018042 | 400 | The current status does not allow cancelling: the document is still queued (query returns Pendente), was denied, failed or is already cancelled. Check the status; this is not a 404. |