Polling de Resultados SIFEN

Después de emitir, guardá el CDC y consultá el resultado sin volver a emitir el documento.

Cuándo consultar

• Consultá cada 5 segundos, con un máximo de 5 minutos por espera.
• Seguí mientras el estado sea PENDIENTE o EN_LOTE.
• Detenete al recibir APROBADO, APROBADO_OBSERVACION, RECHAZADO, CANCELADO o ERROR.
• Si se agota la espera, conservá el CDC y retomá la consulta después. Un timeout no es un rechazo ni autoriza una emisión nueva.

Ejemplo en TypeScript

Ejecutá este ejemplo desde tu servidor para mantener la API key fuera del navegador. La función devuelve el primer estado que requiere terminar la espera; revisá cuál es antes de continuar tu flujo.

type EstadoDocumento =
  | 'PENDIENTE' | 'EN_LOTE'
  | 'APROBADO' | 'APROBADO_OBSERVACION' | 'RECHAZADO' | 'CANCELADO' | 'ERROR';

interface EstadoRespuesta {
  cdc: string;
  estado: EstadoDocumento;
  ambiente: 'DEV' | 'PROD' | 'SANDBOX';
  iTiDe: number;
  numeroDocumento: number;
  fechaCreacion: string;
  protocoloAutorizacion: string | null;
  mensajeRechazo: string | null;
}

async function esperarResultado(cdc: string, apiKey: string): Promise<EstadoRespuesta> {
  const limite = Date.now() + 300_000;
  while (true) {
    const restante = limite - Date.now();
    if (restante <= 0) break;
    const respuesta = await fetch(
      `https://api.sifende.com.py/api/v1/documento-electronico/status/${cdc}`,
      {
        headers: { Authorization: `Bearer ${apiKey}` },
        signal: AbortSignal.timeout(Math.min(10_000, restante)),
      },
    );
    if (!respuesta.ok) {
      throw new Error(`No se pudo consultar el estado: HTTP ${respuesta.status}`);
    }
    const documento: EstadoRespuesta = await respuesta.json();
    if (!['PENDIENTE', 'EN_LOTE'].includes(documento.estado)) {
      return documento;
    }
    await new Promise(resolve => setTimeout(resolve, Math.min(5_000, Math.max(0, limite - Date.now()))));
  }
  throw new Error('Terminó la espera. Conservá el CDC y retomá la consulta después.');
}

Guardar el CDC y retomar consultas

Guardá el CDC en tu base de datos antes de iniciar las consultas, junto con la operación de tu sistema, el ambiente y el último estado conocido. Actualizá ese registro con cada resultado.

Al iniciar de nuevo tu proceso, recuperá los documentos en PENDIENTE o EN_LOTE y retomá la consulta con el mismo CDC y una clave del mismo contribuyente y ambiente. También podés retomar los que agotaron el tiempo de espera: el timeout de tu proceso no cambia el estado del documento.

Si tu proceso se interrumpió antes de guardar la respuesta de emisión, recuperala mediante la misma intención, clave y contenido según la guía de idempotencia. No emitas de nuevo con una clave distinta.

Consejos para producción

• Consultá en segundo plano desde tu servidor para no bloquear la interacción del usuario ni exponer la API key.
• Guardá mensajeRechazo completo cuando recibas RECHAZADO o APROBADO_OBSERVACION.
• Medí el tiempo desde la aceptación de la emisión hasta que tu integración observa APROBADO o APROBADO_OBSERVACION. Ese dato permite detectar cambios en los tiempos de respuesta.
• Limitá las consultas simultáneas y respetá Retry-After ante un 429.

Interpretar el resultado

En SANDBOX, APROBADO representa una aprobación de prueba de Sifende, sin envío a SIFEN ni validez fiscal. Los estados de envío y las respuestas de SIFEN de esta tabla corresponden a DEV y PROD.

En ERROR, el documento no se reintenta solo. Pedí el reintento a soporte o seguí la guía para reintentar el lote. Al reintentarlo vuelve a EN_LOTE y podés retomar las consultas con el mismo CDC.

Si después de varias horas sigue en EN_LOTE, puede pertenecer a un lote Fallido. Revisá Historial de Lotes en el detalle del documento y, si el lote está Fallido, seguí la guía de reintento. Conservá el mismo CDC.

Una consulta de estado no consume numeración ni cupo. Si la consulta falla por conexión o recibe 5xx, podés repetirla. Ante 429, respetá Retry-After. Ante 401 o 403, revisá las credenciales o el acceso antes de seguir.

Para recibir el resultado sin mantener una espera continua, configurá webhooks. Podés usar las consultas de estado para confirmar el estado de los documentos pendientes.