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.

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: 550e8400-e29b-41d4-a716-446655440000

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

Cuerpo de la solicitud

{
  "numeroTimbrado": 12557896,
  "establecimiento": "001",
  "puntoExpedicion": "001",
  "numeroInicio": "0000025",
  "numeroFin": "0000030",
  "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

numeroFin debe ser mayor que numeroInicio; la diferencia no puede superar 1.000.

Respuesta exitosa

Status: 200 OK

La respuesta contiene el evento. Revisá estadoEvento: APROBADO confirma la inutilización; RECHAZADO indica que SIFEN no la aceptó. Conservá también codigoRespuesta y mensajeRespuesta.

Errores

Status	Tipo	Descripción
400	`evento-inutilizacion-error`	Rango, timbrado o tipo de documento inválido
400	`validation-error`	`Idempotency-Key` vacía, repetida o con formato inválido
409	`evento-inutilizacion-error`	Ya existe una inutilización activa para el mismo rango
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	`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

Ejemplos del ciclo idempotente

Primera ejecución

POST /api/v1/documento-electronico/inutilizar HTTP/1.1
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "numeroTimbrado": 12557896,
  "establecimiento": "001",
  "puntoExpedicion": "001",
  "numeroInicio": "0000025",
  "numeroFin": "0000030",
  "tipoDocumento": 1,
  "motivo": "Números no utilizados por error de sistema"
}

HTTP/1.1 200 OK

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

`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