Inutilizar numeración en SIFEN: cuándo y cómo hacerlo

Cómo inutilizar rangos de números de documento no utilizados para cumplir con la normativa de la SET.

SIFEN exige que la numeración de documentos sea secuencial y sin huecos. Cuando se generan brechas (por errores de sistema, pruebas, fallos de emisión), debés inutilizar formalmente esos números para mantener la integridad del timbrado.

Cuándo inutilizar

Inutilizá una numeración cuando:

Tenés un hueco en la secuencia de un timbrado activo
Un documento fue rechazado y su número quedó sin utilizar
Cambiaste de timbrado y querés cerrar el rango anterior

La inutilización es irreversible. Los números marcados como inutilizados quedan registrados en SIFEN para siempre y no podrán reutilizarse.

Cómo inutilizar un rango

Identificá el rango que querés inutilizar: desde qué número hasta qué número, dentro de un mismo establecimiento y punto de expedición.

Enviá el evento de inutilización con el rango y motivo:

curl -X POST "https://api.sifende.com.py/api/v1/documento-electronico/inutilizar" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numeroTimbrado": 12557896,
    "establecimiento": "001",
    "puntoExpedicion": "001",
    "numeroInicio": "0000025",
    "numeroFin": "0000030",
    "tipoDocumento": 1,
    "motivo": "Números no utilizados por error de sistema"
  }'

Campo	Tipo	Req.	Restricción
`numeroTimbrado`	`integer`	Sí	Número de timbrado SET
`establecimiento`	`string`	Sí	Código de 3 caracteres (ej.: `"001"`)
`puntoExpedicion`	`string`	Sí	Código de 3 caracteres (ej.: `"001"`)
`numeroInicio`	`string`	Sí	1-7 caracteres
`numeroFin`	`string`	Sí	1-7 caracteres
`tipoDocumento`	`integer`	Sí	Código numérico del tipo de documento
`motivo`	`string`	Sí	5-500 caracteres
`serie`	`string`	No	Máximo 2 caracteres

Revisá la respuesta del evento. Un HTTP 200 también puede contener estadoEvento: "RECHAZADO". Sólo APROBADO confirma la inutilización.

Conservá el resultado. Guardá la confirmación del evento junto con el rango inutilizado.

Ejemplo en TypeScript

async function inutilizarNumeracion(rango: {
  numeroTimbrado: number;
  establecimiento: string;
  puntoExpedicion: string;
  numeroInicio: string;
  numeroFin: string;
  motivo: string;
}, idempotencyKey: string) {
  const response = await fetch(
    "https://api.sifende.com.py/api/v1/documento-electronico/inutilizar",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.SIFENDE_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify({
        tipoDocumento: 1, // 1 = FACTURA_ELECTRONICA
        ...rango,
      }),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Inutilización fallida: ${error.detail}`);
  }

  const evento = await response.json();
  if (evento.estadoEvento !== "APROBADO") {
    throw new Error(`Inutilización sin confirmar: ${evento.estadoEvento}. ${evento.mensajeRespuesta ?? ''}`);
  }
  return evento;
}

const idempotencyKey = await obtenerOCrearClaveDeInutilizacion(solicitudId);

await inutilizarNumeracion({
  numeroTimbrado: 12557896,
  establecimiento: "001",
  puntoExpedicion: "001",
  numeroInicio: "0000025",
  numeroFin: "0000030",
  motivo: "Números no utilizados por error de sistema",
}, idempotencyKey);

Buenas prácticas

Inutilizá pronto. No dejes huecos abiertos por más de unos días, dificulta auditorías.
Documentá el motivo internamente. El campo motivo queda en SIFEN, pero también guardá un registro propio.
Verificá antes de inutilizar. Confirmá que los números efectivamente no se emitieron. Si ya hay un DE con ese número, la inutilización fallará.

Restricciones

Restricción	Detalle
Solo números no emitidos	No podés inutilizar un número ya usado en un DE existente
Mismo establecimiento + punto	El rango debe estar dentro del mismo `establecimiento` y `puntoExpedicion`
Timbrado activo	El timbrado al que pertenecen los números debe seguir vigente

Errores comunes

Error	Causa	Solución
`400 evento-inutilizacion-error`	`numeroFin` no es mayor que `numeroInicio`, o su diferencia supera 1.000	Verificá el orden del rango
`400 evento-inutilizacion-error`	Tipo de documento inválido	Usá el código numérico del tipo de documento
`409 evento-inutilizacion-error`	Hay una inutilización activa para el mismo rango	Consultá el evento existente; no uses otra clave para evitar el conflicto

Recuperar una respuesta perdida

El procedimiento de recuperación está en Idempotencia y Reintentos Seguros. En inutilización, 0600 confirma el resultado; 4066 deja el evento INDETERMINADA y exige detener los envíos.

Próximos pasos

Cancelar Documento: para documentos ya emitidos
Reintentar Rechazados: flujo después de un rechazo
Referencia: Inutilizar

Inutilizar Numeración