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​

認証方式ヘッダーが存在しません (412)​

The server returns this Japanese string ("Authentication header is missing"). The AppKey credential is unlinked, or got reset by a node version upgrade. Re-select the credential and save.

認証情報が不正です (401)​

The server returns this Japanese string ("Invalid credentials").

  • 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

プラン情報が見つからないため、この操作は許可されていません (403)​

The server returns this Japanese string ("Plan information was not found, so this operation is not permitted"). Either the workspace plan information is unavailable, or you've hit the monthly file creation cap. In the latter case the message is 今月のファイル作成回数上限（X）に達しました。プランをアップグレードするか、翌月までお待ちください。 ("This month's file creation limit (X) has been reached. Please upgrade the plan or wait until next month."). 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​