Come generare fatture in PDF da JSON senza librerie di layout

Il problema delle librerie PDF tradizionali (mPDF, FPDF, iText, PDFSharp)

Le librerie di rendering PDF vecchio stile (siano esse in PHP, Node.js, C# o Python) presentano tre problemi fondamentali per le software house moderne:

• Accoppiamento tra dati e layout: il codice che recupera i dati dal database è mescolato con le istruzioni grafiche che disegnano le tabelle.
• Scarsa flessibilità: modificare il template di una fattura richiede modifiche al codice e cicli di deploy.
• Consumo di risorse: la generazione di PDF massivi è un’operazione CPU-intensive che può rallentare l’applicazione principale se non isolata correttamente.

Separare i dati dal design è la soluzione: l’applicazione backend deve solo preoccuparsi di raccogliere i dati, formattarli in un oggetto JSON pulito e inviarli a un’API di generazione documentale che restituisce il PDF pronto. Se cerchi come generare PDF da JSON, creare fatture PDF API o un’alternativa alle librerie PDF C# / PHP / Node, questo è il pattern moderno JSON-to-PDF.

Fase 1: strutturare il payload JSON della fattura

Il primo passo consiste nel definire la struttura dei dati. Un dizionario JSON ben progettato per una fattura deve contenere i dati dell’emittente, del cliente, i metadati del documento e l’array delle righe degli articoli.

Ecco un esempio di payload standardizzato (copialo e adattalo al tuo schema template):

{
  "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: configurare il template sul portale cloud

Invece di programmare la logica dei cicli foreach per stampare le righe della tabella in PDF, carichi un template grafico (Template Builder visuale) sul portale QuartzAPI. Nel template inserisci dei segnaposto che corrispondono alle chiavi del JSON (es. campo legato a cliente.ragione_sociale).

Il motore legge l’array righe_fattura e cicla automaticamente la banda Details della tabella, calcolando dove interrompere la pagina se gli articoli si estendono su 2, 3 o più pagine, mantenendo intestazione e piè di pagina. Nessuna coordinata X/Y da scrivere nel tuo gestionale.

Fase 3: eseguire la chiamata Web API per generare il PDF

Una volta configurato il template (codice template nel portale, es. INVOICE1) e ottenuta la API key, la tua applicazione invia una richiesta HTTP POST. QuartzAPI genera il PDF e può salvarlo in una cartella documenti (folderId) pronta per download e invio email.

Endpoint: POST …/index.php?r=api/v1-jobs/generate-document — body con templateCode, data (il JSON sopra) e opzionale folderId. Documentazione: Web API.

Esempio in Node.js (Axios)

const axios = require('axios');

const payloadFattura = { /* ... il JSON definito sopra ... */ };

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 generato con successo!', response.data);
    // result.documentId e downloadUrl per il download sicuro
  } catch (error) {
    console.error(
      'Errore durante la generazione del PDF:',
      error.response ? error.response.data : error.message
    );
  }
}

generaFattura();

Esempio in PHP (cURL)

<?php

$payloadFattura = [ /* ... il dizionario JSON in 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 'Errore cURL: ' . curl_error($ch);
} else {
    $data = json_decode($response, true);
    echo 'Documento salvato. documentId: ' . ($data['result']['documentId'] ?? '');
}
curl_close($ch);

Gestione successiva: download e invio automatico via email

Uno dei maggiori vantaggi dell’approccio basato su API è la flessibilità dopo la generazione. Dal momento che il PDF viene memorizzato nelle cartelle del portale:

• Download on-demand: scarica il file con GET …/index.php?r=api/v1-documents/download&uid={documentId}.
• Invio email integrato: invoca POST …/index.php?r=api/v1-jobs/send-document passando il documentId e i destinatari. Puoi usare lo SMTP configurato sulla API key, senza gestire un mailer complesso nel gestionale.

Conclusioni

Trattare i documenti PDF come codice grafico da mantenere è un debito tecnico che le software house non possono più permettersi. Passare a un’architettura JSON-to-PDF via API riduce i tempi di sviluppo, isola il carico computazionale e permette anche a figure non tecniche di aggiornare i template senza toccare una riga di codice dell’applicazione.

Sei pronto a eliminare le librerie PDF dal tuo codice? QuartzAPI è in versione Beta pubblica: registrati gratuitamente, ottieni la API key e testa la generazione di fatture e report inviando i tuoi oggetti JSON.

👉 Inizia gratis con la Beta di QuartzAPI