NFS-e
Cancelar NFS-e
Cancelación asíncrona: dentro de la ventana registra el evento de cancelación, fuera de ella abre una solicitud de análisis fiscal.
/openapi/v2/empresas/{empresaId}/nfse/{nfseId}/cancelartoken, timestamp y sign, vea Autenticación.Cancela un documento Autorizada. La llamada es asíncrona: el HTTP 200 devuelve solo el recibo de aceptación, y el resultado llega por los webhooks nfse.canceled / nfse.cancel_requested / nfse.cancel_denied o por la consulta. La plataforma decide por sí misma entre registrar el evento de cancelación y abrir una solicitud de análisis fiscal, según la ventana del municipio. El cuerpo es opcional.
Parámetros de ruta
empresaId* | string | Identificador de la empresa |
nfseId* | string | Id del documento |
* Campo obligatorio
Cuerpo de la petición
codigoMotivo | string | Código del motivo |
motivo | string | Justificación |
* Campo obligatorio
nfseTaskId | int | Id de la tarea en la plataforma |
status | int | Estado de la tarea |
reused | bool | Tarea reutilizada |
createTime | string | Momento de la aceptación |
El cuerpo es el mismo en los dos casos; la plataforma elige el camino por la ventana de cancelación del municipio contada desde la autorización. Solo un documento Autorizada puede cancelarse.
Dentro de la ventana: evento de cancelación
La plataforma registra el evento oficial 101101. Éxito: el documento pasa a Cancelada y llega nfse.canceled; la consulta muestra un evento Cancelamento. Rechazo síncrono de la autoridad: el documento sigue Autorizada y llega nfse.cancel_denied.
{"codigoMotivo": "1","motivo": "Erro no valor informado pelo cliente"}
codigoMotivo | string | Código del motivo |
motivo | string | Justificación |
* Campo obligatorio
Fuera de la ventana: solicitud de análisis fiscal
La plataforma abre por sí sola la solicitud de análisis 101103. El documento pasa a EmProcessoDeCancelamento y llega nfse.cancel_requested; la consulta muestra un evento PedidoAnalise. El municipio decide: concedida, el documento pasa a Cancelada con evento AnaliseDeferida y llega nfse.canceled; denegada, vuelve a Autorizada con evento AnaliseIndeferida y llega nfse.cancel_denied. No contabilice el documento como cancelado al enviar la solicitud.
{"codigoMotivo": "2","motivo": "Servico nao prestado ao tomador"}
codigoMotivo | string | Código del motivo |
motivo | string | Justificación |
* Campo obligatorio
Canal de São Paulo
El sistema municipal de São Paulo no tiene ventana ni solicitud de análisis: la cancelación se registra directamente en el sistema municipal y el resultado es Cancelada con nfse.canceled, o rechazo con nfse.cancel_denied.
El HTTP 200 de esta llamada es solo el recibo de aceptación. El resultado llega por los webhooks siguientes (objeto de resultado de la NFS-e, vea Registrar webhook) o por la consulta, cuyo motivoStatus trae el veredicto de la autoridad. Un mensaje de cancelación que no pasa la validación del formato oficial hace fallar la tarea con 10018064 y no se registra ningún evento; verifique el tamaño de motivo y el conjunto de caracteres.
Cancelado: nfse.canceled
Evento de cancelación registrado o análisis concedida.
{"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 | Estado del documento tras este evento |
nfseMotivoStatus | string | Veredicto |
nfseNumeroProtocolo | string | Protocolo del evento |
nfseAtualizadoEm* | string | Momento de este cambio |
* Campo obligatorio
En análisis: nfse.cancel_requested
El municipio todavía va a decidir; el documento sigue válido hasta entonces.
{"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 | Estado del documento tras este evento |
nfseMotivoStatus | string | Veredicto |
nfseNumeroProtocolo | string | Protocolo del evento |
nfseAtualizadoEm* | string | Momento de este cambio |
* Campo obligatorio
Rechazado: nfse.cancel_denied
Rechazo síncrono de la autoridad, reintentos de envío agotados o análisis denegada. El documento sigue 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 | Estado del documento tras este evento |
nfseMotivoStatus | string | Veredicto |
nfseNumeroProtocolo | string | Protocolo del evento |
nfseAtualizadoEm* | string | Momento de este cambio |
* Campo obligatorio
Pendente ─┬─► Negada├─► Falha└─► Autorizada ─┬─► Cancelada├─► EmProcessoDeCancelamento ─┬─► Cancelada│ └─► Autorizada└─► Substituida
Negada, Falha, Cancelada y Substituida son terminales. El significado de cada estado está en la enumeración de Consultar NFS-e.
codigoMotivoCódigo del motivo de cancelación
Omitido vale 9.
| Valores | Significado |
|---|---|
| 1 | Error en la emisión |
| 2 | Servicio no prestado |
| 9 | Otros |
statusEstado de la tarea
| Valores | Significado |
|---|---|
| 0 | Pendiente, a la espera de procesamiento |
| 1 | En procesamiento |
| 2 | Éxito |
| 3 | Fallo |
nfseStatusEstado en los callbacks de cancelación
Solo los valores que llevan los tres callbacks de cancelación; la lista completa está en Registrar webhook.
| Valores | Significado |
|---|---|
| Cancelada | Cancelado (nfse.canceled) |
| EmProcessoDeCancelamento | Solicitud de análisis aceptada, a la espera del municipio (nfse.cancel_requested) |
| Autorizada | Cancelación rechazada, el documento sigue válido (nfse.cancel_denied) |
| Código | HTTP | |
|---|---|---|
| 10018002 | 404 | Documento no encontrado: el nfseId no pertenece a este emisor. Verifique el nfseId y el empresaId. |
| 10018003 | 404 | Documento no encontrado: el nfseId no pertenece a este emisor. Verifique el nfseId y el empresaId. |
| 10018001 | 400 | codigoMotivo fuera de 1 / 2 / 9. |
| 10001001 | 400 | motivo o codigoMotivo por encima del tamaño máximo. |
| 10018040 | 400 | Ya hay una solicitud de análisis de cancelación en curso. Espere el veredicto del municipio. |
| 10018041 | 400 | El documento ya fue sustituido; no cabe ninguna otra operación sobre él. |
| 10018042 | 400 | El estado actual no permite cancelar: el documento todavía está en la cola (la consulta devuelve Pendente), fue negado, falló o ya está cancelado. Verifique el estado; no es un 404. |