Consultar Estado de un Documento

Cómo verificar si un documento fue aprobado o rechazado por SIFEN usando el CDC, con la estrategia de polling recomendada.

Cuando emitís un documento electrónico, Sifende lo recibe al instante y te devuelve el CDC, pero el procesamiento real en SIFEN es asíncrono. Esta guía cubre cómo consultar el estado y cuándo dejar de hacer polling.

El endpoint

GET /api/v1/documento-electronico/status/:cdc

curl https://api.sifende.com.py/api/v1/documento-electronico/status/$CDC \
  -H "Authorization: Bearer $SIFENDE_API_KEY"

Respuesta (DocumentoElectronicoStatusDTO):

{
  "cdc": "01800123451001001000000122026042710000000006",
  "estado": "APROBADO",
  "iTiDe": 1,
  "numeroDocumento": 1,
  "fechaCreacion": "2026-04-27T10:30:00",
  "protocoloAutorizacion": "20260427103018987654",
  "mensajeRechazo": null
}

Campo	Tipo	Descripción
`cdc`	`string`	CDC del documento (44 caracteres)
`estado`	`enum`	Estado actual (ver tabla abajo)
`iTiDe`	`int`	Código numérico del tipo de documento SIFEN
`numeroDocumento`	`Long`	Número correlativo dentro del rango de timbrado (entero)
`fechaCreacion`	`string`	Fecha y hora en que Sifende registró el documento (ISO 8601)
`protocoloAutorizacion`	`string \| null`	Número de protocolo SIFEN. Solo si `estado: "APROBADO"`
`mensajeRechazo`	`string \| null`	Mensaje detallado de SIFEN. Solo si `estado: "RECHAZADO"`

numeroDocumento es un entero (Long). Si necesitás el formato "NNN-NNN-NNNNNNN" para mostrar al usuario, usá el campo numeroFormateado que devuelve la respuesta de emisión (POST /documento-electronico). Son dos campos separados, no los confundas.

Estados posibles

Estado	Significado	¿Seguir consultando?
`PENDIENTE`	Sifende lo recibió pero todavía no se asignó a un lote	Sí
`EN_LOTE`	Está agrupado en un lote, listo para enviar a SIFEN	Sí
`ENVIADO`	El lote ya fue enviado a SIFEN, esperando respuesta	Sí
`APROBADO`	SIFEN lo aprobó. El documento es válido y firmado	No, terminado
`RECHAZADO`	SIFEN lo rechazó. Leer `mensajeRechazo`	No, terminado
`ERROR`	Falla técnica en el envío o procesamiento	No, revisar logs y reemitir
`CANCELADO`	Fue aprobado y luego cancelado vía evento	No, terminado
`DESCONOCIDO`	Estado no determinable (caso raro de inconsistencia con SIFEN)	Consultar nuevamente

Estrategia de polling recomendada

Intervalo: entre 3 y 5 segundos. Más frecuente solo agrega carga sin reducir la latencia real.
Timeout: 5 minutos como máximo. Si no resuelve antes, hay un problema de procesamiento; revisá el panel de Sifende.
Detenete apenas el estado pase a APROBADO, RECHAZADO o CANCELADO.

Implementación en TypeScript

type EstadoDE =
  | 'PENDIENTE'
  | 'EN_LOTE'
  | 'ENVIADO'
  | 'APROBADO'
  | 'RECHAZADO'
  | 'ERROR'
  | 'CANCELADO'
  | 'DESCONOCIDO';

interface EstadoResponse {
  cdc: string;
  estado: EstadoDE;
  iTiDe: number;
  numeroDocumento: number; // Long en backend
  fechaCreacion: string;
  protocoloAutorizacion: string | null;
  mensajeRechazo: string | null;
}

async function esperarResultadoSIFEN(
  cdc: string,
  { intervaloMs = 5000, timeoutMs = 300_000 } = {}
): Promise<EstadoResponse> {
  const inicio = Date.now();

  while (Date.now() - inicio < timeoutMs) {
    const res = await fetch(
      `https://api.sifende.com.py/api/v1/documento-electronico/status/${cdc}`,
      { headers: { Authorization: `Bearer ${process.env.SIFENDE_API_KEY}` } }
    );

    if (!res.ok) {
      throw new Error(`Error consultando estado: ${res.status}`);
    }

    const data: EstadoResponse = await res.json();

    if (
      data.estado === 'APROBADO' ||
      data.estado === 'RECHAZADO' ||
      data.estado === 'ERROR' ||
      data.estado === 'CANCELADO'
    ) {
      return data;
    }

    await new Promise(r => setTimeout(r, intervaloMs));
  }

  throw new Error(`Timeout esperando resultado SIFEN para CDC ${cdc}`);
}

Uso típico

const resultado = await esperarResultadoSIFEN(cdc);

switch (resultado.estado) {
  case 'APROBADO':
    // Descargá el KuDE, marcá la venta como facturada, mandá email al cliente
    break;
  case 'RECHAZADO':
    // Logueá mensajeRechazo, alertá al equipo, corregí los datos
    console.error('SIFEN rechazó el DE:', resultado.mensajeRechazo);
    break;
  case 'CANCELADO':
    // El documento fue cancelado; usualmente esto no aparece en flujo de emisión
    break;
}

¿Qué hacer en cada estado final?

APROBADO

Tu documento ya es legalmente válido en SIFEN.
Generá el KuDE y entregalo al cliente. Ver Descargar KuDE.
Si necesitás revertirlo o ajustarlo, emití una Nota de Crédito o Nota de Débito.

RECHAZADO

El campo mensajeRechazo contiene el código y descripción de SIFEN (ej: 1108 - Timbrado vencido).
Corregí los datos del documento o la configuración subyacente (timbrado, certificado, etc.). El documento rechazado no se reintenta tal cual; emitís uno nuevo.
Detalle paso a paso en Manejar Errores y Reintentar Rechazados.

CANCELADO

El documento fue aprobado y posteriormente cancelado mediante evento.
Este estado normalmente lo vas a ver al consultar un documento ya procesado, no como resultado del flujo de emisión.

Alternativa: webhooks (próximamente)

El polling es sencillo pero puede ser ineficiente a alto volumen. Sifende está implementando webhooks para notificar cambios de estado de manera push; seguí los avances en el changelog.

Próximos pasos

Si recibís RECHAZADO, andá a Manejar Errores.
Para volúmenes altos y polling de muchos documentos, ver Polling de Resultados.
Para entender los códigos SIFEN que aparecen en mensajeRechazo, ver Rechazos SIFEN.

Consultar Estado de un Documento

On this page