Cancelar Documento

POST /api/v1/documento-electronico/:cdc/cancelar — enviá el evento de cancelación a SIFEN para un documento aprobado.

POST /api/v1/documento-electronico/:cdc/cancelar

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.

Autenticación

Authorization: Bearer {api-key} — requerido

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.

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

En cancelación, el retry 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

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

Request body

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

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

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

Status	Tipo	Descripción
400	`evento-cancelacion-error`	SIFEN rechazó el evento con un código distinto de `4003`
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
404	`documento-electronico-not-found`	CDC no encontrado o documento cuya conservación física venció
409	`evento-cancelacion-error`	El documento no puede cancelarse en su estado actual
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	`idempotency-key-reused`	La clave ya corresponde a otro payload u otra operación
503	`idempotency-upstream-unknown`	SIFEN no confirmó el resultado. Incluye `Retry-After: 2`; reintentá con la misma clave
503	`idempotency-unavailable` / `idempotency-fingerprint-unsupported`	La operación no se ejecutó porque el contrato idempotente no está disponible

Un documento archivado responde el Problem Detail document-archived antes de enviar la cancelación. Estado y KuDE aplican el mismo comportamiento.

Ejemplos del ciclo idempotente

Primera ejecución

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

El mismo request devuelve el 200 y body originales sin otro envío a SIFEN.

HTTP/1.1 200 OK

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

Mismatch de payload u operación

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 otra solicitud" }

Primera ejecución todavía en curso

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

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

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

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" }