Flux complet d’un rapport

1. Créez la structure du rapport

Créez un modèle de rapport avec titre, période, graphique et tableau détaillé. Utilisez le flux pour le contenu pouvant s’étendre sur plusieurs pages. Ajoutez en-tête, pied de page et numéro de page selon vos besoins.

2. Définissez les données une fois

Par exemple, utilisez month et revenue dans un tableau nommé monthlyRevenue. Liez le graphique à ce tableau, choisissez month comme catégorie et revenue comme série. Liez le tableau détaillé aux mêmes données pour assurer la cohérence des deux vues.

3. Testez les cas limites

Testez un tableau vide, une catégorie, des noms longs, des champs manquants et de nombreuses lignes. Comparez les totaux du graphique et du tableau. N’utilisez pas de valeurs négatives dans les camemberts ou anneaux. Si les libellés se chevauchent, agrandissez le graphique, réduisez les catégories ou présentez les détails dans le tableau.

Le traitement complet d’un rapport

Un rapport est généralement produit en lot et prend plus de temps qu’une simple facture ; il passe donc par la file. Vérifiez d’abord le graphique seul, puis mettez le document en file et suivez-le par webhook ou par interrogation périodique.

# 1 - Vérifier le graphique seul avant de l’insérer dans un document
curl -X POST https://api.pdfgine.com/api/v1/templates/chart-preview \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "width": 640,
        "locale": "fr",
        "element": {
          "id": "quarterly-volume",
          "type": "chart",
          "placementMode": "flow",
          "layout": { "width": 100, "widthUnit": "percent", "height": 240 },
          "content": {
            "title": "Documents produits",
            "data": [
              { "quarter": "Q1", "documents": 120 },
              { "quarter": "Q2", "documents": 180 },
              { "quarter": "Q3", "documents": 240 },
              { "quarter": "Q4", "documents": 310 }
            ]
          },
          "chart": {
            "type": "bar",
            "labelField": "quarter",
            "series": [{ "field": "documents", "label": "Documents", "color": "#e3232a" }],
            "showLegend": true,
            "showValues": true
          }
        }
      }'

# 2 - Mettre le rapport en file - la réponse est 202 avec un statusUrl
curl -X POST https://api.pdfgine.com/api/v1/documents/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "maintenance-report",
        "format": "pdf",
        "locale": "fr",
        "webhookUrl": "https://example.com/hooks/pdfgine",
        "data": { "document": { "title": "Maintenance trimestrielle" } }
      }'

# 3 - Le suivre - interroger ce point de terminaison si aucun webhook n’est défini
curl -s https://api.pdfgine.com/api/v1/async-jobs/queue_fe86ad38402a4909b3b5a7965847924a \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

La file répond 202 avec un statusUrl, et non avec le document terminé. Indiquez webhookUrl si vous préférez être averti plutôt que d’interroger l’état ; la file vous appelle lorsque le document est prêt et réessaie les appels en échec.

4. Vérifiez et partagez la sortie

Après vérification de l’enregistrement et de la publication, générez PDF et Word. Dans la Visionneuse, vérifiez le nombre de pages et l’espace des graphiques. Un graphique Word est une image, pas un graphique natif modifiable. Vérifiez l’expiration et les droits de téléchargement pour le partage externe ; ne mettez jamais une clé API dans un lien partagé.

Les problèmes les plus courants

• La file répond 202 avec statusUrl, pas avec le rapport. Lire documentId directement dans cette réponse donne toujours null.
• Un mois sans lignes est un cas réel. Testez le tableau vide avant qu’un client reçoive un rapport avec un graphique vide et un tableau sans en-tête.
• Comparez le graphique avec son tableau. Un graphique lié à un tableau de données et une ligne de total calculée à partir d’un autre produisent une erreur de chiffre particulièrement discrète.
• Les valeurs négatives ne peuvent pas être représentées fidèlement dans un camembert ou un anneau. Corrigez-les dans les données sources, pas dans le graphique.
• Un traitement par lots rencontre deux limites : les pages du quota et les documents par minute de votre offre. Étalez le traitement plutôt que d’accumuler des réponses 429.