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.
Esta operación requiere DEV o PROD. En SANDBOX devuelve 422 sandbox-operation-not-supported sin crear ni enviar un evento.
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-764a3f02cf55En 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
| Parámetro | Tipo | Descripción |
|---|---|---|
cdc | string | CDC del documento a cancelar |
Cuerpo de la solicitud
{
"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
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
| 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 | 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 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
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
La misma solicitud 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 otro tipo de operación" }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" }