# Inutilizar Numeración (/docs/referencia/documentos-electronicos/inutilizar)



## POST /api/v1/documento-electronico/inutilizar [#post-apiv1documento-electronicoinutilizar]

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

<Callout type="warn">
  En inutilización, `4066` deja el evento `INDETERMINADA` y devuelve `409 idempotency-outcome-unknown`. No reenvíes el rango ni uses otra clave.
</Callout>

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

```json
{
  "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` no puede ser menor que `numeroInicio`; para un solo número, enviá los dos iguales. La diferencia no puede superar 1.000.

### Respuesta exitosa [#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 [#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`](/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 |

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

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

```http
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 [#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": 92, "tipoEvento": "INUTILIZACION", "estadoEvento": "APROBADO", "numeroInicio": "0000025", "numeroFin": "0000030", "protocoloAutorizacion": "987654321", "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" }
```

#### `4066` indeterminado terminal [#4066-indeterminado-terminal]

```http
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 [#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" }
```
