PDF-Rechnungen aus JSON generieren ohne Layout-Bibliotheken

Das Problem traditioneller PDF-Bibliotheken (mPDF, FPDF, iText, PDFSharp)

PDF-Rendering-Bibliotheken im alten Stil (ob in PHP, Node.js, C# oder Python) stellen für moderne Softwarehäuser drei grundlegende Probleme dar:

• Kopplung von Daten und Layout: der Code, der Daten aus der Datenbank holt, ist vermischt mit den grafischen Anweisungen, die die Tabellen zeichnen.
• Geringe Flexibilität: das Ändern eines Rechnungs-Templates erfordert Codeänderungen und Deploy-Zyklen.
• Ressourcenverbrauch: die Erzeugung großer PDFs ist CPU-intensiv und kann die Hauptanwendung verlangsamen, wenn sie nicht richtig isoliert ist.

Daten vom Design zu trennen ist die Lösung: Die Backend-Anwendung muss nur die Daten sammeln, sie in ein sauberes JSON-Objekt formatieren und an eine Dokumentenerzeugungs-API senden, die das fertige PDF zurückgibt. Wenn Sie suchen, wie man PDFs aus JSON erzeugt, PDF-Rechnungen per API erstellt oder eine Alternative zu C#-/PHP-/Node-PDF-Bibliotheken braucht — das ist das moderne JSON-to-PDF-Muster.

Schritt 1: das JSON-Payload der Rechnung strukturieren

Der erste Schritt besteht darin, die Datenstruktur festzulegen. Ein gut gestaltetes JSON-Dictionary für eine Rechnung muss Emittentendaten, Kundendaten, Dokument-Metadaten und das Array der Positionszeilen enthalten.

Hier ein Beispiel für ein standardisiertes Payload (kopieren und an Ihr Template-Schema anpassen):

{
  "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
  }
}

Schritt 2: das Template im Cloud-Portal konfigurieren

Anstatt foreach-Schleifen zu programmieren, um Tabellenzeilen im PDF zu drucken, laden Sie ein grafisches Template (visueller Template Builder) im QuartzAPI-Portal hoch. Im Template fügen Sie Platzhalter ein, die den JSON-Schlüsseln entsprechen (z. B. Feld gebunden an cliente.ragione_sociale).

Die Engine liest das Array righe_fattura und durchläuft automatisch die Details-Bande der Tabelle, berechnet, wo die Seite zu unterbrechen ist, wenn Artikel über 2, 3 oder mehr Seiten gehen, und behält Kopf- und Fußzeile bei. Keine X/Y-Koordinaten in Ihrer Warenwirtschaft zu schreiben.

Schritt 3: den Web-API-Aufruf zur PDF-Erzeugung ausführen

Sobald das Template konfiguriert ist (Template-Code im Portal, z. B. INVOICE1) und Sie den API-Key haben, sendet Ihre Anwendung eine HTTP-POST-Anfrage. QuartzAPI erzeugt das PDF und kann es in einem Dokumentenordner (folderId) speichern — bereit für Download und E-Mail-Versand.

Endpoint: POST …/index.php?r=api/v1-jobs/generate-document — Body mit templateCode, data (das JSON oben) und optionalem folderId. Dokumentation: Web API.

Beispiel in Node.js (Axios)

const axios = require('axios');

const payloadFattura = { /* ... das oben definierte JSON ... */ };

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 erfolgreich erzeugt!', response.data);
    // result.documentId und downloadUrl für den sicheren Download
  } catch (error) {
    console.error(
      'Fehler bei der PDF-Erzeugung:',
      error.response ? error.response.data : error.message
    );
  }
}

generaFattura();

Beispiel in PHP (cURL)

<?php

$payloadFattura = [ /* ... das JSON-Dictionary als PHP-Array ... */ ];

$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 'cURL-Fehler: ' . curl_error($ch);
} else {
    $data = json_decode($response, true);
    echo 'Dokument gespeichert. documentId: ' . ($data['result']['documentId'] ?? '');
}
curl_close($ch);

Weiterverarbeitung: Download und automatischer E-Mail-Versand

Einer der größten Vorteile des API-basierten Ansatzes ist die Flexibilität nach der Erzeugung. Da das PDF in den Portalordnern gespeichert wird:

• On-Demand-Download: laden Sie die Datei herunter mit GET …/index.php?r=api/v1-documents/download&uid={documentId}.
• Integrierter E-Mail-Versand: rufen Sie POST …/index.php?r=api/v1-jobs/send-document auf und übergeben Sie die documentId sowie die Empfänger. Sie können das auf dem API-Key konfigurierte SMTP nutzen, ohne einen komplexen Mailer in der Warenwirtschaft zu betreiben.

Fazit

PDF-Dokumente als zu pflegenden Grafikcode zu behandeln ist technische Schuld, die sich Softwarehäuser nicht mehr leisten können. Der Wechsel zu einer JSON-to-PDF-Architektur per API verkürzt die Entwicklungszeit, isoliert die Rechenlast und ermöglicht auch nicht-technischen Rollen, Templates zu aktualisieren, ohne eine Zeile Anwendungscode anzufassen.

Bereit, PDF-Bibliotheken aus Ihrem Code zu entfernen? QuartzAPI ist in der öffentlichen Beta: Registrieren Sie sich kostenlos, holen Sie den API-Key und testen Sie die Erzeugung von Rechnungen und Reports mit Ihren JSON-Objekten.

👉 Kostenlos mit der QuartzAPI-Beta starten