Generar facturas PDF desde JSON sin librerías de layout

El problema de las librerías PDF tradicionales (mPDF, FPDF, iText, PDFSharp)

Las librerías de renderizado PDF al estilo antiguo (ya sean en PHP, Node.js, C# o Python) presentan tres problemas fundamentales para las software houses modernas:

• Acoplamiento entre datos y layout: el código que recupera los datos de la base de datos está mezclado con las instrucciones gráficas que dibujan las tablas.
• Escasa flexibilidad: modificar la plantilla de una factura requiere cambios en el código y ciclos de deploy.
• Consumo de recursos: la generación de PDF masivos es una operación intensiva en CPU que puede ralentizar la aplicación principal si no se aísla correctamente.

Separar los datos del diseño es la solución: la aplicación backend solo debe preocuparse de recopilar los datos, formatearlos en un objeto JSON limpio y enviarlos a una API de generación documental que devuelve el PDF listo. Si buscas cómo generar PDF desde JSON, crear facturas PDF por API o una alternativa a las librerías PDF C# / PHP / Node, este es el patrón moderno JSON-to-PDF.

Fase 1: estructurar el payload JSON de la factura

El primer paso consiste en definir la estructura de los datos. Un diccionario JSON bien diseñado para una factura debe contener los datos del emisor, del cliente, los metadatos del documento y el array de las líneas de artículos.

Aquí tienes un ejemplo de payload estandarizado (cópialo y adáptalo a tu esquema de plantilla):

{
  "documento": {
    "tipo": "Fattura Differita",
    "numero": "FPA-2026-1044",
    "data": "18/07/2026",
    "valuta": "EUR"
  },
  "emittente": {
    "ragione_sociale": "Sviluppo Software S.r.l.",
    "partita_iva": "IT01234567890",
    "indirizzo": "Via dell'Innovazione 42",
    "cap_citta": "66034 Lanciano (CH)",
    "email": "amministrazione@softwarehouse.it"
  },
  "cliente": {
    "ragione_sociale": "Azienda Cliente SpA",
    "partita_iva": "IT09876543210",
    "indirizzo": "Corso Vittorio Emanuele II, 100",
    "cap_citta": "00100 Roma (RM)"
  },
  "righe_fattura": [
    {
      "codice": "SW-SAAS-01",
      "descrizione": "Abbonamento Cloud SaaS QuartzAPI - Licenza Enterprise (Mensile)",
      "quantita": 1,
      "prezzo_unitario": 249.00,
      "aliquota_iva": 22
    },
    {
      "codice": "CONS-PRO-02",
      "descrizione": "Attività di integrazione sistemi ERP e configurazione Webhook",
      "quantita": 8,
      "prezzo_unitario": 75.00,
      "aliquota_iva": 22
    }
  ],
  "totali": {
    "imponibile": 849.00,
    "imposta": 186.78,
    "totale_documento": 1035.78
  }
}

Fase 2: configurar la plantilla en el portal cloud

En lugar de programar la lógica de los bucles foreach para imprimir las filas de la tabla en PDF, cargas una plantilla gráfica (Template Builder visual) en el portal QuartzAPI. En la plantilla insertas marcadores de posición que corresponden a las claves del JSON (p. ej. campo ligado a cliente.ragione_sociale).

El motor lee el array righe_fattura y recorre automáticamente la banda Details de la tabla, calculando dónde interrumpir la página si los artículos se extienden a 2, 3 o más páginas, manteniendo el encabezado y el pie de página. Ninguna coordenada X/Y que escribir en tu gestional.

Fase 3: ejecutar la llamada Web API para generar el PDF

Una vez configurada la plantilla (código de plantilla en el portal, p. ej. INVOICE1) y obtenida la API key, tu aplicación envía una solicitud HTTP POST. QuartzAPI genera el PDF y puede guardarlo en una carpeta de documentos (folderId) lista para descarga y envío por email.

Endpoint: POST …/index.php?r=api/v1-jobs/generate-document — body con templateCode, data (el JSON de arriba) y opcional folderId. Documentación: Web API.

Ejemplo en Node.js (Axios)

const axios = require('axios');

const payloadFattura = { /* ... el JSON definido arriba ... */ };

async function generaFattura() {
  try {
    const response = await axios.post(
      'https://backend.quartzapi.com/index.php?r=api/v1-jobs/generate-document',
      {
        templateCode: 'INVOICE1',
        folderId: 'fld_ESEMPIO_CARTELLA',
        externalId: 'FPA-2026-1044',
        outputFormat: 'pdf',
        data: payloadFattura
      },
      {
        headers: {
          Authorization: 'Bearer TUO_API_KEY_SEGRETA',
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('¡PDF generado con éxito!', response.data);
    // result.documentId y downloadUrl para la descarga segura
  } catch (error) {
    console.error(
      'Error durante la generación del PDF:',
      error.response ? error.response.data : error.message
    );
  }
}

generaFattura();

Ejemplo en PHP (cURL)

<?php

$payloadFattura = [ /* ... el diccionario JSON en array PHP ... */ ];

$ch = curl_init('https://backend.quartzapi.com/index.php?r=api/v1-jobs/generate-document');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'templateCode' => 'INVOICE1',
    'folderId' => 'fld_ESEMPIO_CARTELLA',
    'externalId' => 'FPA-2026-1044',
    'outputFormat' => 'pdf',
    'data' => $payloadFattura,
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer TUO_API_KEY_SEGRETA',
    'Content-Type: application/json',
]);

$response = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error cURL: ' . curl_error($ch);
} else {
    $data = json_decode($response, true);
    echo 'Documento guardado. documentId: ' . ($data['result']['documentId'] ?? '');
}
curl_close($ch);

Gestión posterior: descarga y envío automático por email

Una de las mayores ventajas del enfoque basado en API es la flexibilidad después de la generación. Dado que el PDF se almacena en las carpetas del portal:

• Descarga bajo demanda: descarga el archivo con GET …/index.php?r=api/v1-documents/download&uid={documentId}.
• Envío de email integrado: invoca POST …/index.php?r=api/v1-jobs/send-document pasando el documentId y los destinatarios. Puedes usar el SMTP configurado en la API key, sin gestionar un mailer complejo en el gestional.

Conclusiones

Tratar los documentos PDF como código gráfico a mantener es una deuda técnica que las software houses no pueden permitirse más. Pasar a una arquitectura JSON-to-PDF vía API reduce los tiempos de desarrollo, aísla la carga computacional y permite también a perfiles no técnicos actualizar las plantillas sin tocar una línea de código de la aplicación.

¿Estás listo para eliminar las librerías PDF de tu código? QuartzAPI está en versión Beta pública: regístrate gratis, obtén la API key y prueba la generación de facturas e informes enviando tus objetos JSON.

👉 Empieza gratis con la Beta de QuartzAPI