# Cancelar Documento (/docs/referencia/documentos-electronicos/cancelar)



## POST /api/v1/documento-electronico/:cdc/cancelar [#post-apiv1documento-electronicocdccancelar]

Envía el evento de cancelación a SIFEN. Solo se pueden cancelar documentos registrados en SIFEN, o sea en estado `APROBADO` o `APROBADO_OBSERVACION`.

Esta operación requiere DEV o PROD. En SANDBOX devuelve [`422 sandbox-operation-not-supported`](/docs/solucion-problemas/sandbox-operation-not-supported) sin crear ni enviar un evento.

### Autenticación [#autenticación]

`Authorization: Bearer {api-key}` — requerido

### Idempotencia [#idempotencia]

`Idempotency-Key` es un header opcional de 1 a 255 caracteres ASCII visibles, sin espacios al inicio ni al final. El flujo compartido está definido en [Idempotencia y Reintentos Seguros](/docs/guias/idempotencia).

```http
Idempotency-Key: 72f42d5e-366d-4f67-a9da-764a3f02cf55
```

En cancelación, el reintento reutiliza el evento original. Si SIFEN responde `4003` porque el CDC ya tiene la cancelación registrada, Sifende lo conserva como éxito equivalente.

### Path parameters [#path-parameters]

| Parámetro | Tipo     | Descripción                  |
| --------- | -------- | ---------------------------- |
| `cdc`     | `string` | CDC del documento a cancelar |

### Cuerpo de la solicitud [#cuerpo-de-la-solicitud]

```json
{
  "motivo": "Error en datos del cliente"
}
```

| Campo    | Tipo     | Req. | Descripción                            |
| -------- | -------- | ---- | -------------------------------------- |
| `motivo` | `string` | Sí   | Motivo de la cancelación (texto libre) |

El plazo es de 48 horas desde la aprobación para FE y 168 horas para NCE, NDE y NRE.

### Respuesta exitosa [#respuesta-exitosa]

**Status:** `200 OK`

Revisá `estadoEvento`: sólo `APROBADO` confirma la cancelación. SIFEN puede rechazar el evento y la API devolverlo con `estadoEvento: "RECHAZADO"` y HTTP `200`.

`0600` representa la aprobación original. `4003` también produce `estadoEvento: APROBADO`: confirma que el mismo tipo de evento ya estaba registrado para el CDC, normalmente porque SIFEN aplicó un intento cuya respuesta se perdió. En ese éxito equivalente, `protocoloAutorizacion` puede ser `null`; `codigoRespuesta` y `mensajeRespuesta` conservan la evidencia `4003`.

### Errores [#errores]

| Status | Tipo                                                                                          | Descripción                                                                                               |
| ------ | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 400    | `evento-cancelacion-error`                                                                    | El estado, el plazo o los datos del documento no permiten cancelar                                        |
| 400    | `validation-error`                                                                            | `Idempotency-Key` vacía, repetida o con formato inválido                                                  |
| 403    | `document-archived`                                                                           | El período de acceso del plan actual finalizó; no se envía el evento. No aplica a una clave ya registrada |
| 404    | `documento-electronico-not-found`                                                             | CDC no encontrado o documento cuya conservación física venció                                             |
| 409    | `evento-cancelacion-error`                                                                    | Ya existe una cancelación activa o aprobada; consultá el evento                                           |
| 409    | `idempotency-in-progress`                                                                     | La misma intención sigue en curso. Incluye `Retry-After: 2`                                               |
| 409    | `idempotency-outcome-unknown`                                                                 | Resultado terminal indeterminado. No incluye `Retry-After`                                                |
| 409    | `idempotency-key-expired`                                                                     | Venció el replay de 7 días; la clave permanece reservada                                                  |
| 422    | [`sandbox-operation-not-supported`](/docs/solucion-problemas/sandbox-operation-not-supported) | La operación no está disponible en SANDBOX                                                                |
| 422    | `idempotency-key-reused`                                                                      | La clave ya corresponde a otro tipo de operación                                                          |
| 503    | `idempotency-upstream-unknown`                                                                | SIFEN no confirmó el resultado. Incluye `Retry-After: 2`; reintentá con la misma clave                    |

Un documento archivado responde el [Problem Detail `document-archived`](/docs/referencia/errores#documento-archivado) antes de enviar la cancelación, salvo que la clave ya esté registrada: en ese caso se recupera la cancelación original. Estado y KuDE aplican el mismo comportamiento.

### Ejemplos del ciclo idempotente [#ejemplos-del-ciclo-idempotente]

#### Primera ejecución [#primera-ejecución]

```http
POST /api/v1/documento-electronico/01800123451001001000000122026042710000000006/cancelar HTTP/1.1
Idempotency-Key: 72f42d5e-366d-4f67-a9da-764a3f02cf55
Content-Type: application/json

{ "motivo": "Error en datos del cliente" }

HTTP/1.1 200 OK

{ "eventoSifenId": 91, "tipoEvento": "CANCELACION", "estadoEvento": "APROBADO", "cdc": "01800123451001001000000122026042710000000006", "protocoloAutorizacion": "123456789", "codigoRespuesta": "0600" }
```

#### Replay dentro de 7 días [#replay-dentro-de-7-días]

La misma solicitud devuelve el `200` y body originales sin otro envío a SIFEN.

```http
HTTP/1.1 200 OK

{ "eventoSifenId": 91, "tipoEvento": "CANCELACION", "estadoEvento": "APROBADO", "cdc": "01800123451001001000000122026042710000000006", "protocoloAutorizacion": "123456789", "codigoRespuesta": "0600" }
```

#### Mismatch de payload u operación [#mismatch-de-payload-u-operación]

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{ "type": "https://sifende.com.py/docs/solucion-problemas/idempotency-key-reused", "title": "Clave de idempotencia reutilizada", "status": 422, "detail": "La clave de idempotencia ya fue usada para otro tipo de operación" }
```

#### Primera ejecución todavía en curso [#primera-ejecución-todavía-en-curso]

```http
HTTP/1.1 409 Conflict
Retry-After: 2
Content-Type: application/problem+json

{ "type": "https://sifende.com.py/docs/solucion-problemas/idempotency-in-progress", "title": "Solicitud idempotente en proceso", "status": 409, "detail": "Ya existe una solicitud con esta clave en proceso; reintentá después del intervalo indicado" }
```

#### Timeout reintentable [#timeout-reintentable]

```http
HTTP/1.1 503 Service Unavailable
Retry-After: 2
Content-Type: application/problem+json

{ "type": "https://sifende.com.py/docs/solucion-problemas/idempotency-upstream-unknown", "title": "Resultado SIFEN no confirmado", "status": 503, "detail": "No se pudo confirmar el resultado en SIFEN; reintentá con la misma Idempotency-Key después del intervalo indicado" }
```

#### Éxito equivalente después del timeout [#éxito-equivalente-después-del-timeout]

```http
HTTP/1.1 200 OK

{ "eventoSifenId": 91, "tipoEvento": "CANCELACION", "estadoEvento": "APROBADO", "cdc": "01800123451001001000000122026042710000000006", "protocoloAutorizacion": null, "codigoRespuesta": "4003", "mensajeRespuesta": "[4003] CDC ya se encuentra con el mismo evento solicitado" }
```

#### Replay expirado [#replay-expirado]

```http
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{ "type": "https://sifende.com.py/docs/solucion-problemas/idempotency-key-expired", "title": "Clave de idempotencia expirada", "status": 409, "detail": "El resultado asociado a la clave de idempotencia expiró y ya no puede reproducirse; la clave no puede reutilizarse" }
```
