End-to-end report workflow

1. Create the report structure

Create a report template with a heading, reporting period, chart and detail table. Use flow placement for content that can span pages. Add a header, footer and page number as required.

2. Define the data once

For example, use month and revenue properties in an array named monthlyRevenue. Bind the chart to that array, choose month as its category field and revenue as its series field. Bind the detail table to the same array so both views use the same data.

3. Test edge cases

Test an empty array, a single category, long category names, missing fields and many rows. Compare chart totals with the table. Do not use negative values for pie or donut charts. If labels become crowded, enlarge the chart, reduce categories or present the details in the table.

The full report run

A report is usually produced in bulk and takes longer than a single invoice, so it goes through the queue. Verify the chart on its own first, then queue the document and follow it - either with a webhook or by polling.

# 1 - Verify the chart on its own before putting it in a 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": "en",
        "element": {
          "id": "quarterly-volume",
          "type": "chart",
          "placementMode": "flow",
          "layout": { "width": 100, "widthUnit": "percent", "height": 240 },
          "content": {
            "title": "Documents produced",
            "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 - Queue the report - the answer is 202 with a 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": "en",
        "webhookUrl": "https://example.com/hooks/pdfgine",
        "data": { "document": { "title": "Quarterly maintenance" } }
      }'

# 3 - Follow it - poll this endpoint if you set no webhook
curl -s https://api.pdfgine.com/api/v1/async-jobs/queue_fe86ad38402a4909b3b5a7965847924a \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

The queue answers 202 with a statusUrl, not the finished document. Give webhookUrl if you would rather be told than ask; the queue then calls you when the document is ready and retries a failed call.

4. Verify and share the output

After checking saving and publishing, generate the required PDF and Word outputs. In Viewer, check the page count and that charts fill their available space. A Word chart is an image, not a native editable chart. Check expiry and download permissions for external sharing; never put an API key in a shared link.

What usually goes wrong

• The queue answers 202 with a statusUrl, not the report. Reading documentId straight from that answer gives null every time.
• A month with no rows is a real case. Test the empty array before the report reaches a customer with a blank chart and a headerless table.
• Compare the chart with its table. A chart bound to one array and a total row computed from another is the quietest wrong number in a report.
• Negative values in a pie or donut cannot be drawn honestly. Fix them in the source data, not in the chart.
• A bulk run meets two ceilings: the pages in your quota and the documents per minute in your plan. Spread the run rather than collecting 429s.