Produkt- und API-Leitfaden

Vollständiger Berichtsablauf

1. Berichtsstruktur erstellen

Erstellen Sie eine Berichtsvorlage mit Überschrift, Berichtszeitraum, Diagramm und Detailtabelle. Verwenden Sie flow für seitenübergreifende Inhalte. Ergänzen Sie nach Bedarf Kopfzeile, Fußzeile und Seitenzahl.

2. Daten einmal definieren

Verwenden Sie etwa die Eigenschaften month und revenue in einem Array namens monthlyRevenue. Binden Sie das Diagramm daran und wählen Sie month als Kategoriefeld und revenue als Serienfeld. Binden Sie die Detailtabelle an dasselbe Array, damit beide Ansichten dieselben Daten verwenden.

3. Grenzfälle testen

Testen Sie ein leeres Array, eine einzelne Kategorie, lange Kategorienamen, fehlende Felder und viele Zeilen. Vergleichen Sie Diagrammsummen mit der Tabelle. Verwenden Sie keine negativen Werte für Kreis- oder Ringdiagramme. Vergrößern Sie bei überfüllten Beschriftungen das Diagramm, reduzieren Sie Kategorien oder zeigen Sie Details in der Tabelle.

Der vollständige Berichtsablauf

Berichte werden meist stapelweise erstellt und benötigen länger als eine einzelne Rechnung, daher durchlaufen sie die Warteschlange. Prüfen Sie zuerst das Diagramm einzeln, stellen Sie dann das Dokument in die Warteschlange und verfolgen Sie es per Webhook oder regelmäßiger Statusabfrage.

cURL 
# 1 - Diagramm einzeln prüfen, bevor es ins Dokument eingefügt wird
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": "de",
        "element": {
          "id": "quarterly-volume",
          "type": "chart",
          "placementMode": "flow",
          "layout": { "width": 100, "widthUnit": "percent", "height": 240 },
          "content": {
            "title": "Erstellte Dokumente",
            "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": "Dokumente", "color": "#e3232a" }],
            "showLegend": true,
            "showValues": true
          }
        }
      }'

# 2 - Bericht einreihen - die Antwort ist 202 mit einer 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": "de",
        "webhookUrl": "https://example.com/hooks/pdfgine",
        "data": { "document": { "title": "Vierteljährliche Wartung" } }
      }'

# 3 - Auftrag verfolgen - diesen Endpunkt abfragen, falls kein Webhook gesetzt ist
curl -s https://api.pdfgine.com/api/v1/async-jobs/queue_fe86ad38402a4909b3b5a7965847924a \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

Die Warteschlange antwortet mit 202 und einer statusUrl, nicht mit dem fertigen Dokument. Geben Sie eine webhookUrl an, wenn Sie lieber benachrichtigt werden möchten: Die Warteschlange ruft Sie auf, sobald das Dokument fertig ist, und wiederholt fehlgeschlagene Aufrufe.

4. Ausgabe prüfen und teilen

Prüfen Sie Speichern und Veröffentlichung und erzeugen Sie die benötigten PDF- und Word-Ausgaben. Prüfen Sie im Viewer Seitenzahl und die Nutzung der verfügbaren Diagrammfläche. Ein Word-Diagramm ist ein Bild, kein nativ bearbeitbares Diagramm. Prüfen Sie bei externer Freigabe Ablauf und Downloadrechte; fügen Sie niemals einen API-Schlüssel in einen geteilten Link ein.

Diagramme und Berichte →

Häufige Fehler

  • Die Warteschlange antwortet mit 202 und statusUrl, nicht mit dem Bericht. documentId direkt aus dieser Antwort zu lesen ergibt immer null.
  • Ein Monat ohne Zeilen ist ein echter Anwendungsfall. Testen Sie das leere Array, bevor ein Kunde einen Bericht mit leerem Diagramm und Tabelle ohne Kopfzeile erhält.
  • Vergleichen Sie Diagramm und Tabelle. Ein an ein Array gebundenes Diagramm neben einer aus einem anderen Array berechneten Summe erzeugt besonders unauffällige falsche Zahlen.
  • Negative Werte in Kreis- oder Ringdiagrammen lassen sich nicht korrekt darstellen. Korrigieren Sie die Quelldaten, nicht das Diagramm.
  • Stapelaufträge stoßen an zwei Grenzen: das Seitenkontingent und die Dokumente pro Minute Ihres Tarifs. Verteilen Sie die Verarbeitung, statt 429-Antworten zu sammeln.