Inutilizar Numeración

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 proceso falló al generar el XML y consumió el número
Emitiste documentos en un ambiente de pruebas que reservaron números reales
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 "Content-Type: application/json" \
  -d '{
    "numeroTimbrado": 12345678,
    "establecimiento": 1,
    "puntoExpedicion": 1,
    "numeroInicio": "0000105",
    "numeroFin": "0000107",
    "tipoDocumento": 1,
    "motivo": "Documentos no emitidos por falla del sistema"
  }'

Campo	Tipo	Req.	Restricción
`numeroTimbrado`	`integer`	Sí	Número de timbrado SET
`establecimiento`	`integer`	Sí	Número del establecimiento (ej: `1`)
`puntoExpedicion`	`integer`	Sí	Número del punto de expedición (ej: `1`)
`numeroInicio`	`string`	Sí	1-7 caracteres
`numeroFin`	`string`	Sí	1-7 caracteres
`tipoDocumento`	`short`	Sí	Código SIFEN `iTiDe` (1=FE, 5=NCE, 6=NDE)
`motivo`	`string`	Sí	5-500 caracteres
`serie`	`string`	No	Máximo 2 caracteres

SIFEN procesa el evento y registra los números como inutilizados.

Continuá facturando normalmente. El siguiente DE usará el próximo número disponible (108 en el ejemplo).

Ejemplo en TypeScript

async function inutilizarNumeracion(rango: {
  numeroTimbrado: number;
  establecimiento: number;
  puntoExpedicion: number;
  numeroInicio: string;
  numeroFin: string;
  motivo: 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",
      },
      body: JSON.stringify({
        tipoDocumento: 1, // 1 = FACTURA_ELECTRONICA (iTiDe)
        ...rango,
      }),
    }
  );

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

await inutilizarNumeracion({
  numeroTimbrado: 12345678,
  establecimiento: 1,
  puntoExpedicion: 1,
  numeroInicio: "0000105",
  numeroFin: "0000107",
  motivo: "Documentos no emitidos por falla del sistema",
});

Buenas prácticas

Inutilizá pronto. No dejes huecos abiertos por más de unos días, dificulta auditorías.
Mantené los rangos chicos. Inutilizar 3 números es manejable; inutilizar 500 levanta sospechas.
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
`409 evento-inutilizacion-error`	Algún número del rango ya tiene DE	Ajustá el rango excluyendo los números usados
`400 evento-inutilizacion-error`	`desde` mayor que `hasta`	Verificá el orden del rango
`400 validation-error`	Tipo de documento inválido	Usá uno de los enums permitidos

Próximos pasos

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