Générer des factures PDF depuis JSON sans bibliothèques de layout

Le problème des bibliothèques PDF traditionnelles (mPDF, FPDF, iText, PDFSharp)

Les bibliothèques de rendu PDF à l’ancienne (qu’elles soient en PHP, Node.js, C# ou Python) présentent trois problèmes fondamentaux pour les software houses modernes :

• Couplage entre données et layout : le code qui récupère les données de la base est mélangé aux instructions graphiques qui dessinent les tableaux.
• Faible flexibilité : modifier le modèle d’une facture nécessite des changements de code et des cycles de déploiement.
• Consommation de ressources : la génération de PDF volumineux est une opération CPU-intensive qui peut ralentir l’application principale si elle n’est pas correctement isolée.

Séparer les données du design est la solution : l’application backend doit uniquement collecter les données, les formater dans un objet JSON propre et les envoyer à une API de génération documentaire qui renvoie le PDF prêt. Si vous cherchez comment générer des PDF à partir de JSON, créer des factures PDF via API ou une alternative aux bibliothèques PDF C# / PHP / Node, voici le pattern moderne JSON-to-PDF.

Étape 1 : structurer le payload JSON de la facture

La première étape consiste à définir la structure des données. Un dictionnaire JSON bien conçu pour une facture doit contenir les données de l’émetteur, du client, les métadonnées du document et le tableau des lignes d’articles.

Voici un exemple de payload standardisé (copiez-le et adaptez-le à votre schéma de 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
  }
}

Étape 2 : configurer le template sur le portail cloud

Au lieu de programmer la logique des boucles foreach pour imprimer les lignes du tableau en PDF, vous chargez un template graphique (Template Builder visuel) sur le portail QuartzAPI. Dans le template, vous insérez des placeholders qui correspondent aux clés du JSON (ex. champ lié à cliente.ragione_sociale).

Le moteur lit le tableau righe_fattura et itère automatiquement la bande Details du tableau, en calculant où interrompre la page si les articles s’étendent sur 2, 3 pages ou plus, tout en conservant l’en-tête et le pied de page. Aucune coordonnée X/Y à écrire dans votre logiciel de gestion.

Étape 3 : exécuter l’appel Web API pour générer le PDF

Une fois le template configuré (code template dans le portail, ex. INVOICE1) et la clé API obtenue, votre application envoie une requête HTTP POST. QuartzAPI génère le PDF et peut le sauvegarder dans un dossier documents (folderId) prêt pour le téléchargement et l’envoi d’e-mail.

Endpoint : POST …/index.php?r=api/v1-jobs/generate-document — body avec templateCode, data (le JSON ci-dessus) et folderId optionnel. Documentation : Web API.

Exemple en Node.js (Axios)

const axios = require('axios');

const payloadFattura = { /* ... le JSON défini ci-dessus ... */ };

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 généré avec succès !', response.data);
    // result.documentId et downloadUrl pour le téléchargement sécurisé
  } catch (error) {
    console.error(
      'Erreur lors de la génération du PDF :',
      error.response ? error.response.data : error.message
    );
  }
}

generaFattura();

Exemple en PHP (cURL)

<?php

$payloadFattura = [ /* ... le dictionnaire JSON en tableau 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 'Erreur cURL : ' . curl_error($ch);
} else {
    $data = json_decode($response, true);
    echo 'Document enregistré. documentId : ' . ($data['result']['documentId'] ?? '');
}
curl_close($ch);

Gestion suivante : téléchargement et envoi automatique par e-mail

L’un des principaux avantages de l’approche basée sur les API est la flexibilité après la génération. Dès lors que le PDF est mémorisé dans les dossiers du portail :

• Téléchargement à la demande : téléchargez le fichier avec GET …/index.php?r=api/v1-documents/download&uid={documentId}.
• Envoi e-mail intégré : invoquez POST …/index.php?r=api/v1-jobs/send-document en passant le documentId et les destinataires. Vous pouvez utiliser le SMTP configuré sur la clé API, sans gérer un mailer complexe dans le logiciel de gestion.

Conclusions

Traiter les documents PDF comme du code graphique à maintenir est une dette technique que les software houses ne peuvent plus se permettre. Passer à une architecture JSON-to-PDF via API réduit les temps de développement, isole la charge de calcul et permet aussi à des profils non techniques de mettre à jour les templates sans toucher une ligne de code de l’application.

Prêt à supprimer les bibliothèques PDF de votre code ? QuartzAPI est en version Beta publique : inscrivez-vous gratuitement, obtenez la clé API et testez la génération de factures et de rapports en envoyant vos objets JSON.

👉 Commencer gratuitement avec la Beta QuartzAPI