API: descargar el KuDE en PDF de un documento

GET /api/v1/documento-electronico/:cdc/kude — descargá el KuDE (comprobante) en PDF o seguí la preparación asincrónica cuando todavía no está disponible.

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

Retorna el KuDE (Kuatia Ñe'ẽ Mba'eporu — comprobante electrónico) en formato PDF binario cuando ya existe una copia legible. Si falta el PDF, la llamada inicial puede solicitar su preparación y responder 202 Accepted.

Autenticación

Authorization: Bearer {api-key} — requerido

Path parameters

Parámetro	Tipo	Descripción
`cdc`	`string`	CDC del documento aprobado

Query parameters

Parámetro	Tipo	Default	Descripción
`soloConsulta`	`boolean`	`false`	Si es `true`, sólo consulta el estado registrado: no publica, no reencola y no crea otra solicitud de preparación.

Respuestas

200 OK

Content-Type: application/pdf

El body es el PDF binario del KuDE. Conserva Content-Disposition y Content-Length.

202 Accepted

Content-Type: application/json

La preparación del PDF está pendiente. Esta respuesta no es un PDF y no debe guardarse como archivo.

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /api/v1/documento-electronico/01800123451001001000000122026042710000000006/kude?soloConsulta=true
Retry-After: 5
Cache-Control: no-store

{
  "estado": "PENDIENTE",
  "url": null
}

Seguí exactamente el Location recibido. Esa URL usa soloConsulta=true: consultar no reencola, no repara por sí mismo y un PENDIENTE no confirma que Pub/Sub haya recibido un mensaje; sólo informa una intención registrada. Retry-After: 5 indica el intervalo mínimo recomendado para volver a consultar.

Errores

Status	Tipo	Descripción
403	`document-archived`	El período de acceso del plan actual finalizó
404	`documento-electronico-not-found`	CDC no encontrado, documento ajeno o documento cuya conservación física venció
500	`kude-generation-error`	Error técnico interno al obtener o preparar el KuDE
501	`kude-not-supported`	Tipo de documento no soporta KuDE
503	`kude-unavailable`	Indisponibilidad temporal identificada; ver `kude-unavailable`

Los errores técnicos de KuDE se informan como 500 o 503 según la causa. No se clasifican como 422, porque no son problemas semánticos del documento enviado.

Un documento archivado responde el Problem Detail document-archived y no entrega el PDF. Estado y cancelación aplican el mismo comportamiento.

Ejemplo — polling seguro y guardar sólo el 200

type KuDePendiente = {
  estado: 'PENDIENTE';
  url: null;
};

type ProblemDetail = {
  type: string;
  title: string;
  status: number;
  detail: string;
  traceId?: string;
  estado?: 'FALLIDO';
};

async function descargarKuDE(cdc: string): Promise<Uint8Array> {
  let url = `https://api.sifende.com.py/api/v1/documento-electronico/${cdc}/kude`;

  for (;;) {
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.SIFENDE_API_KEY}` },
    });

    if (res.status === 200 && res.headers.get('content-type')?.includes('application/pdf')) {
      return new Uint8Array(await res.arrayBuffer());
    }

    if (res.status === 202) {
      const location = res.headers.get('location');
      if (!location) throw new Error('KuDE pendiente sin Location');
      await res.json() as KuDePendiente;
      await new Promise(resolve => setTimeout(resolve, Number(res.headers.get('retry-after') ?? '5') * 1000));
      url = new URL(location, url).toString();
      continue;
    }

    const problem = await res.json() as ProblemDetail;
    throw new Error(`No se pudo descargar KuDE (${problem.status}): ${problem.type}`);
  }
}

Controles conservados

La API valida autenticación, titularidad, retención y disponibilidad antes de consultar archivos o solicitar preparación.
501 kude-not-supported sigue vigente para tipos sin KuDE.
No se promete trabajo durable, exactly-once, recuperación de correo ni reenvío automático. Pub/Sub puede reentregar; el cliente sólo debe seguir la URL de consulta.

Descargar KuDE