メインコンテンツまでスキップ

n8n Integration

n8n のワークフローから Report Flow API を呼び出すための公式コミュニティノード n8n-nodes-reportflow を提供しています。コードを書かずに「フォーム送信 → PDF 生成 → メール添付」のような自動化を組めます。

インストール​

n8n の Settings → Community Nodes → Install から、パッケージ名を入力してインストールします。

n8n-nodes-reportflow

詳細は n8n Community Nodes インストールガイド を参照してください。

セルフホスト n8n の場合

セルフホスト環境では、N8N_COMMUNITY_PACKAGES_ENABLED=true がセットされている必要があります。Docker Compose で運用している場合は環境変数を追加してから再起動してください。

インストール後、ノードパレットに ReportFlow が表示されます。

認証情報の作成​

ReportFlow ノードの認証は AppKey 方式 です。

  1. Report Flow にログインし ワークスペース設定 → API連携 を開く
  2. アプリケーションキー をコピー（ak_xxxxxxxxxxxxxxxx 形式）
  3. n8n で Credentials → New → ReportFlow AppKey API を作成
  4. App Key に貼り付けて保存

操作（Operations）​

PDF リソース​

Operation同期/非同期説明
Generate (Sync)同期単一 PDF を即時生成。ノードの出力にバイナリプロパティとして PDF を返す
Generate (Async)非同期単一 PDF を非同期生成。requestId とダウンロード URL を返す（Webhook と組み合わせ推奨）
Generate Multiple (Sync)同期複数 PDF を一括生成し ZIP で受け取る
Generate Multiple (Async)非同期複数 PDF を非同期で一括生成
Download-requestId / fileId を指定して既存ファイルをダウンロード

Design リソース​

Operation説明
Get Parametersデザインテンプレートが要求するパラメータ構造を取得

エンドポイントとパラメータの詳細は API リファレンスを参照してください：

使い方​

1. パラメータ構造を確認する​

PDF 生成の前に、デザインが要求するパラメータを把握しておくとスムーズです。

  1. ReportFlow ノードを追加
  2. Resource = Design、Operation = Get Parameters
  3. Design ID に Report Flow ダッシュボードからコピーした UUID を入力
  4. 実行すると、{ "customerName": "string", "amount": "number", ... } のような構造が返る

2. 単一 PDF を同期生成する​

最も基本的なワークフローです。

  1. ReportFlow ノードを追加
  2. Resource = PDF、Operation = Generate (Sync)
  3. 以下を設定:
    • Design ID: 対象デザインの UUID
    • Version: バージョン番号（整数）
    • File Name: 出力ファイル名（例: invoice.pdf）
    • Parameters: JSON でパラメータを指定。前ステップから式（{{ $json.params }}）で受け取る形が便利
  4. 後続ノードでバイナリプロパティ（既定 data）を Email/Slack/Drive 等に渡す
ファイル名のバリデーション

/ \ : * ? " < > | および制御文字は使用できません。エラー詳細は エラーハンドリングガイド を参照。

3. 非同期生成 + Webhook で完了通知​

大量生成や数十秒かかる処理では、非同期エンドポイントと Webhook の組み合わせが推奨です。

  1. ReportFlow ノードで Generate (Async) を実行 → requestId が即時返る
  2. Report Flow 側で Workspace Settings → Developer → Webhook URL に n8n の Webhook ノード URL を登録
  3. PDF 生成完了時に Webhook が n8n に POST される
  4. Webhook ノードに続けて ReportFlow の Download Operation を requestId / fileId 指定で実行

業務 ID とのひも付けには passthrough フィールドを使ってください。params（業務データ）は Webhook には含まれません。詳しくは Webhook 通知ガイド を参照。

4. 複数 PDF の一括生成​

CSV や DB の各行から PDF を作る場合：

  1. Spreadsheet File や MySQL などで行データを取得
  2. ReportFlow ノードで Generate Multiple (Sync) または (Async)
  3. Files に行ごとの { fileName, params } 配列を渡す（n8n の式エディタでマッピング）

レート制限（同期 30 req/min、非同期 100 req/min）を超えないよう、必要に応じて Split In Batches ノードでスロットリングしてください。

トラブルシューティング​

Authentication header is missing (412)​

AppKey 方式で Credential が紐付いていない、もしくはノードのバージョン更新でリセットされたケース。Credentials を再選択して保存してください。

Invalid credentials (401)​

  • AppKey の値を再確認（前後の空白・改行に注意）
  • Report Flow 管理画面で AppKey を再生成した場合は、n8n 側の Credentials も更新する必要あり

Plan limit exceeded (403)​

ワークスペースの月次生成上限またはデザインファイル数上限に到達しています。管理画面からプランをアップグレードしてください。

Rate limit exceeded (429)​

ワークスペース単位の制限です。Retry-After ヘッダの秒数だけ待ってから再試行してください。バッチ処理では非同期エンドポイントの利用と Split In Batches ノードでの分割が有効です。

Webhook が届かない​

  1. Webhook URL は HTTPS であること（localhost や HTTP は拒否される）
  2. n8n をセルフホストしている場合、外部公開できているか確認（ngrok や Cloudflare Tunnel など）
  3. n8n の Webhook ノードを Production URL に切り替えて保存（Test URL は実行中のみ有効）

詳細は Webhook 通知ガイド を参照。

サポート​

次のステップ​