Skip to main content

n8n Integration

We provide an official community node, n8n-nodes-reportflow, that lets you call the Report Flow API from any n8n workflow. Wire up flows like "form submission → PDF generation → email delivery" without writing code.

Installation​

In n8n, open Settings → Community Nodes → Install and enter the package name:

n8n-nodes-reportflow

For details, see the n8n Community Nodes installation guide.

Self-hosted n8n

On self-hosted instances, N8N_COMMUNITY_PACKAGES_ENABLED=true must be set. If you run n8n via Docker Compose, add the env var and restart the container.

After installation, ReportFlow appears in the node palette.

Creating credentials​

The ReportFlow node uses AppKey authentication.

  1. Sign in to Report Flow and open Workspace Settings → API Keys
  2. Copy the Application Key (ak_xxxxxxxxxxxxxxxx format)
  3. In n8n, create Credentials → New → ReportFlow AppKey API
  4. Paste the key into App Key and save

Operations​

PDF resource​

OperationSync/AsyncDescription
Generate (Sync)syncGenerate a single PDF and return the binary inline
Generate (Async)asyncKick off a single PDF generation. Returns requestId and a download URL (combine with webhooks)
Generate Multiple (Sync)syncGenerate multiple PDFs in one call and receive a ZIP
Generate Multiple (Async)asyncGenerate multiple PDFs asynchronously
Download-Download a previously generated file by requestId / fileId

Design resource​

OperationDescription
Get ParametersRetrieve the parameter structure expected by a design template

For endpoint and parameter details, see the API reference:

Usage​

1. Inspect the parameter structure​

Before generating, it helps to know what parameters your design expects.

  1. Add a ReportFlow node
  2. Set Resource = Design, Operation = Get Parameters
  3. Enter the Design ID (UUID copied from the Report Flow dashboard)
  4. Run — you'll see something like { "customerName": "string", "amount": "number", ... }

2. Generate a single PDF (sync)​

The most basic flow.

  1. Add a ReportFlow node
  2. Set Resource = PDF, Operation = Generate (Sync)
  3. Configure:
    • Design ID: the design's UUID
    • Version: integer version number
    • File Name: e.g. invoice.pdf
    • Parameters: JSON; mapping from a previous step like {{ $json.params }} works well
  4. Pass the binary property (default data) to downstream nodes (Email, Slack, Drive, …)
Filename validation

/ \ : * ? " < > | and control characters are not allowed. See the error handling guide for details.

3. Async generation + webhook for completion​

For high-volume or multi-second jobs, combine the async endpoint with webhooks.

  1. Run Generate (Async) in the ReportFlow node — requestId returns immediately
  2. In Report Flow, set Workspace Settings → Developer → Webhook URL to your n8n Webhook node URL
  3. When the PDF is ready, Report Flow POSTs the webhook to n8n
  4. Chain the webhook to a ReportFlow node with Download Operation, passing requestId / fileId

Use the passthrough field to correlate PDFs with your business records — params (business data) is never included in webhook payloads. See the webhook guide for details.

4. Bulk generation​

When generating PDFs from each row of a CSV or database table:

  1. Fetch rows with Spreadsheet File, MySQL, etc.
  2. Use ReportFlow with Generate Multiple (Sync) or (Async)
  3. Pass an array of { fileName, params } to Files (map via n8n's expression editor)

Rate limits are 30 req/min for sync and 100 req/min for async endpoints. Use Split In Batches to throttle if needed.

Troubleshooting​

Authentication header is missing (412)​

The AppKey credential is unlinked, or got reset by a node version upgrade. Re-select the credential and save.

Invalid credentials (401)​

  • Re-check the AppKey value (watch for leading/trailing whitespace and newlines)
  • If you regenerated the AppKey in the Report Flow admin UI, update the n8n credentials accordingly

Plan limit exceeded (403)​

You've hit the workspace's monthly generation cap or design-file cap. Upgrade the plan from the admin console.

Rate limit exceeded (429)​

Per-workspace rate limit. Wait the number of seconds reported in the Retry-After header before retrying. For batch jobs, prefer the async endpoints and split with Split In Batches.

Webhooks aren't arriving​

  1. The webhook URL must be HTTPS (localhost and HTTP are rejected)
  2. If you self-host n8n, make sure it's reachable from the public internet (ngrok, Cloudflare Tunnel, …)
  3. Switch the n8n Webhook node to Production URL before saving (the Test URL only fires while the workflow is being edited)

See the Webhook guide for more.

Support​

Next steps​