Descargar KuDE

Cómo obtener el KuDE (comprobante PDF) de un documento aprobado para entregarlo al cliente.

El KuDE (Kuatia'i Documento Electrónico) es la representación gráfica del documento electrónico: el PDF imprimible o adjuntable por email que entregás al cliente. No es el documento legal en sí mismo, pero es la versión legible para humanos.

El documento legal es el XML firmado, no el KuDE. El cliente puede validar su factura escaneando el QR del KuDE, que apunta al portal SIFEN. No estás obligado a imprimirlo o enviarlo, pero sí es la forma estándar de entregarlo.

Requisitos

El documento debe estar en estado APROBADO. KuDE no se genera para PENDIENTE, EN_LOTE ni RECHAZADO.
Necesitás el CDC del documento.
Aplica a los tipos soportados: FE, NCE, NDE.

El endpoint

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

Respuesta: binario PDF (Content-Type: application/pdf).

Descargar y guardar a disco (cURL)

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

Descargar desde Node.js / TypeScript

Guardar el PDF en disco usando fs/promises:

import { writeFile } from 'node:fs/promises';

async function descargarKuDE(cdc: string, destino: string): Promise<void> {
  const res = await fetch(
    `https://api.sifende.com.py/api/v1/documento-electronico/${cdc}/kude`,
    { headers: { Authorization: `Bearer ${process.env.SIFENDE_API_KEY}` } }
  );

  if (!res.ok) {
    const problem = await res.json();
    throw new Error(`No se pudo descargar KuDE: ${problem.title}`);
  }

  const buffer = Buffer.from(await res.arrayBuffer());
  await writeFile(destino, buffer);
}

await descargarKuDE(
  '01800123451001001000000122026042710000000006',
  './kude/factura-001.pdf'
);

Stream a una respuesta HTTP (Express)

Si tu backend está sirviendo el KuDE al frontend o al cliente directamente, podés streamearlo sin guardarlo en disco:

import express from 'express';

const app = express();

app.get('/facturas/:cdc/kude', async (req, res) => {
  const upstream = await fetch(
    `https://api.sifende.com.py/api/v1/documento-electronico/${req.params.cdc}/kude`,
    { headers: { Authorization: `Bearer ${process.env.SIFENDE_API_KEY}` } }
  );

  if (!upstream.ok) {
    return res.status(upstream.status).json(await upstream.json());
  }

  res.setHeader('Content-Type', 'application/pdf');
  res.setHeader(
    'Content-Disposition',
    `inline; filename="factura-${req.params.cdc}.pdf"`
  );

  // Stream del body upstream a la respuesta del cliente
  const reader = upstream.body!.getReader();
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    res.write(value);
  }
  res.end();
});

Usá Content-Disposition: inline para que se muestre embebido en el navegador, o attachment; filename="..." para forzar descarga.

Adjuntar el KuDE a un email al cliente

Patrón típico: una vez que el DE pasa a APROBADO, descargás el KuDE y lo enviás al receptor.

import { Resend } from 'resend';
const resend = new Resend(process.env.RESEND_API_KEY);

async function enviarFacturaPorEmail(cdc: string, emailCliente: string) {
  const res = await fetch(
    `https://api.sifende.com.py/api/v1/documento-electronico/${cdc}/kude`,
    { headers: { Authorization: `Bearer ${process.env.SIFENDE_API_KEY}` } }
  );
  const pdf = Buffer.from(await res.arrayBuffer());

  await resend.emails.send({
    from: 'facturas@miempresa.com.py',
    to: emailCliente,
    subject: `Tu factura electrónica`,
    html: '<p>Adjuntamos tu factura electrónica. Podés validarla escaneando el QR.</p>',
    attachments: [
      { filename: `factura-${cdc}.pdf`, content: pdf },
    ],
  });
}

Errores frecuentes

Status	Tipo	Causa	Solución
404	`documento-electronico-not-found`	CDC inexistente	Verificá el CDC
422	`kude-generation-error`	El DE no está aprobado, o falta data para el render	Confirmá `estado: "APROBADO"` antes de pedir KuDE
501	`kude-not-supported`	Tipo de documento sin soporte de KuDE (ej: AFE 🚧)	Esperá a que se implemente. Solo FE/NCE/NDE actualmente

Buenas prácticas

No descargues KuDE en cada request del cliente. Guardalo en blob storage (S3, GCS) la primera vez y serví desde ahí.
No mostrés KuDE de documentos no aprobados. Pueden cambiar, y al cliente le confunde.
Cacheá el KuDE: una vez que el DE está APROBADO, el PDF no cambia. Tiene sentido cachear indefinidamente.
Si el QR del KuDE no resuelve en SIFEN, verificá que estés en el ambiente correcto (test vs producción).

Próximos pasos

¿Todavía no aprobaron tu DE? → Consultar Estado.
Si tu cliente reporta problemas con el QR del KuDE, ver FAQ.
Detalles de la API → Referencia: Descargar KuDE.

On this page