Inutilizar Numeración

POST /api/v1/documento-electronico/inutilizar — inutilizá rangos de números de documento no utilizados.

POST /api/v1/documento-electronico/inutilizar

Envía el evento de inutilización a SIFEN para un rango de números de documento no emitidos.

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: cff0f0aa-e018-48e7-9a7f-5da3306fe746

En inutilización, 4066 deja el evento INDETERMINADA y devuelve 409 idempotency-outcome-unknown. No reenvíes el rango ni uses otra clave.

Request body

{
  "numeroTimbrado": 12345678,
  "establecimiento": "001",
  "puntoExpedicion": "001",
  "numeroInicio": "50",
  "numeroFin": "55",
  "tipoDocumento": 1,
  "motivo": "Números no utilizados por error de sistema"
}

Campo	Tipo	Req.	Descripción
`numeroTimbrado`	`integer`	Sí	Número del timbrado
`establecimiento`	`string`	Sí	Código de establecimiento de 3 caracteres
`puntoExpedicion`	`string`	Sí	Código de punto de expedición de 3 caracteres
`numeroInicio`	`string`	Sí	Primer número del rango, de 1 a 7 caracteres
`numeroFin`	`string`	Sí	Último número del rango, de 1 a 7 caracteres
`tipoDocumento`	`integer`	Sí	Código SIFEN del tipo de documento
`motivo`	`string`	Sí	Motivo de la inutilización, de 5 a 500 caracteres
`serie`	`string`	No	Serie de hasta 2 caracteres

Respuesta exitosa

Status: 200 OK

Errores

Status	Tipo	Descripción
400	`evento-inutilizacion-error`	SIFEN rechazó el evento con un código distinto de `4066`
400	`validation-error`	`Idempotency-Key` vacía, repetida o con formato inválido
409	`evento-inutilizacion-error`	Rango ya utilizado o inutilizado con resultado conocido
409	`idempotency-in-progress`	La misma intención sigue en curso. Incluye `Retry-After: 2`
409	`idempotency-outcome-unknown`	`4066` u otro 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

Ejemplos del ciclo idempotente

Primera ejecución

POST /api/v1/documento-electronico/inutilizar HTTP/1.1
Idempotency-Key: cff0f0aa-e018-48e7-9a7f-5da3306fe746
Content-Type: application/json

{
  "numeroTimbrado": 12345678,
  "establecimiento": "001",
  "puntoExpedicion": "001",
  "numeroInicio": "50",
  "numeroFin": "55",
  "tipoDocumento": 1,
  "motivo": "Números no utilizados por error de sistema"
}

HTTP/1.1 200 OK

{ "eventoSifenId": 92, "tipoEvento": "INUTILIZACION", "estadoEvento": "APROBADO", "numeroInicio": "0000050", "numeroFin": "0000055", "protocoloAutorizacion": "987654321", "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": 92, "tipoEvento": "INUTILIZACION", "estadoEvento": "APROBADO", "numeroInicio": "0000050", "numeroFin": "0000055", "protocoloAutorizacion": "987654321", "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" }

`4066` indeterminado terminal

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

{ "type": "https://sifende.com.py/docs/solucion-problemas/idempotency-outcome-unknown", "title": "Resultado idempotente indeterminado", "status": 409, "detail": "El resultado de la operación es indeterminado; no vuelvas a enviar la operación" }

El evento asociado queda con estadoEvento: INDETERMINADA, codigoRespuesta: "4066" y el mensaje original de SIFEN para auditoría. No existe replay exitoso ni reconciliación por consulta.

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

Inutilizar Numeración

On this page