単一PDF非同期生成

POST /file/async/single エンドポイントは、指定されたテンプレートとパラメータから単一のPDFファイルを非同期的に生成します。即座に requestId とファイル情報を返すため、タイムアウトを避けることができます。

エンドポイント情報

URL: https://api.re-port-flow.com/v1/file/async/single
メソッド: POST
認証: appkey ヘッダーが必要
タイムアウト: なし（非同期処理）
リクエストサイズ上限: 50MB（Base64エンコード後、実質約37MB相当）

使用例

cURL

curl -X POST https://api.re-port-flow.com/v1/file/async/single \
  -H "appkey: your-application-key" \
  -H "Content-Type: application/json" \
  -d '{
    "designId": "0eUDdgAjNXrrItA2",
    "version": 1,
    "content": {
      "fileName": "invoice.pdf",
      "shareType": "01",
      "passcodeEnabled": false,
      "params": {
        "customerName": "山田太郎",
        "invoiceNumber": "INV-2024-001",
        "amount": 10000
      }
    }
  }'

リクエストパラメータ

フィールド	型	必須	説明
`designId`	string	✓	テンプレート ID（16文字の英数字。例: `0eUDdgAjNXrrItA2`）
`version`	integer	✓	バージョン番号
`webhookUrl`	string	-	このリクエストの Webhook 通知先（https、2048文字以内）。ワークスペースに登録済みで有効な Webhook エンドポイントの URL と一致する必要があり、一致しなければ 400 `WEBHOOK_URL_NOT_ALLOWED`。指定すると、その宛先だけがこのリクエストのイベントを受け取る（詳細）
`content.fileName`	string	✓	ファイル名（`/ \\ : * ? " < > \|` および制御文字以外は使用可能）
`content.shareType`	string	-	共有タイプ（リクエストは数値コード）。`"01"`=ワークスペース内共有(デフォルト) / `"02"`=招待者共有 / `"03"`=公開URL共有。レスポンスの `share.shareType` は `workspace` / `invited` / `public` の人間可読な名前で返ります
`content.passcodeEnabled`	boolean	-	パスコード保護（デフォルト: `false`）
`content.passthrough`	object	-	レスポンスの `files[].passthrough` に透過する任意のメタデータ（例: `{ "pageId": "abc123" }`）。トップレベルの文字列・数値は帳票検索メタデータとしても保存されます
`content.params`	object	✓	テンプレートに埋め込むパラメータ（テンプレートのパラメータ取得APIで構造を確認可能）

レスポンス

成功時 (202 Accepted)

{
  "requestId": "kZ3mP9qL2xV7nR4t",
  "url": "https://re-port-flow.com/{workspaceId}/templates/{designId}/outputs?requestId={requestId}",
  "files": [
    {
      "fileName": "invoice.pdf",
      "fileId": "Hn4sT8wQ1cV6bX2e",
      "passthrough": { "pageId": "abc123" },
      "share": {
        "shareType": "workspace",
        "url": "https://re-port-flow.com/file/{requestId}/{fileId}",
        "passcodeEnabled": false
      }
    }
  ]
}

フィールド	型	説明
`requestId`	string	リクエストID（16文字の英数字。ダウンロードエンドポイントで使用）
`url`	string (URI)	生成結果を確認できるアプリ画面（出力履歴）のURL。ファイルの直接ダウンロードURLではない — 取得はPDF のダウンロードを使う
`files`	array	生成されたファイルの情報
`files[].fileName`	string	ファイル名
`files[].fileId`	string	ファイルID（個別ダウンロードエンドポイントで使用）
`files[].passthrough`	object	リクエスト時に指定した `content.passthrough` の値（指定時のみ）
`files[].share.shareType`	string	共有タイプ（`workspace` / `invited` / `public`）
`files[].share.url`	string	ファイル表示URL
`files[].share.passcodeEnabled`	boolean	パスコード有効フラグ
`files[].share.passcode`	string	サーバー生成パスコード（`passcodeEnabled=true` かつ生成直後のみ）

passthrough の使い所

ReportFlow はセキュリティとペイロードサイズの観点から、レスポンスや Webhook 通知に params（生成データ）を返しません。

受信側で「どの業務レコードに対する PDF か」を識別したい場合は、リクエスト時に passthrough に自社DBのIDなどを入れてください。レスポンスや Webhook でそのまま返却されます。

{
  "fileName": "invoice.pdf",
  "passthrough": { "invoiceId": "INV-001", "tenantId": "acme" },
  "params": { "customerName": "山田太郎", "amount": 10000 }
}

Webhook 受信時に passthrough の値がそのまま返るため、invoiceId から DB を引いて該当レコードを更新する、といった処理が組めます。 params（顧客名や金額）は外部に送信されません。

さらに passthrough のトップレベルにある文字列・数値は、帳票検索用のメタデータとしても保存されます（生成PDF内の XMP メタデータと、Re:port Flow アプリの帳票検索インデックス）。対象になる値の条件・上限と、個人情報を入れてはいけない理由は passthrough と帳票検索メタデータを参照してください。

エラー時

同期生成エンドポイントと同様のエラーレスポンスを返します。詳細は単一PDF同期生成とエラーコード一覧を参照してください。受付（202）後に生成が失敗した場合は、生成状態の取得の error / failedFiles で理由が分かります。生成リクエストで webhookUrl を指定した場合は、その宛先に Webhook の file.failed も届きます。

非同期処理のフロー

1. クライアント → API: 生成リクエスト送信
   ↓
2. API → クライアント: 即座に requestId・url・files を返す (202 Accepted)
   ↓
3. API: バックグラウンドでPDF生成開始
   ↓
4. API: PDF生成完了後、S3にアップロード（失敗した場合は failed として記録）
   ↓
5. クライアント: GET /v1/file/status/{requestId} で完了・失敗を確認
   （または Webhook の file.completed を受信。file.failed は webhookUrl を指定した場合だけ届く）
   ↓
6. クライアント: /v1/file/download/{requestId}/{fileId} からPDFをダウンロード
   （レスポンスの url はアプリ画面へのリンクでダウンロードには使えない）

ユースケース

ケース1: バックグラウンドでPDF生成

ユーザーのリクエストを即座に受け付け、バックグラウンドで処理します。

app.post('/api/generate-report', async (req, res) => {
  const response = await axios.post(
    'https://api.re-port-flow.com/v1/file/async/single',
    { designId: '...', version: 1, content: { fileName: 'report.pdf', params: req.body } },
    { headers: { 'appkey': process.env.APP_KEY } }
  );

  const { requestId, url, files } = response.data;

  // 即座にレスポンス
  res.status(202).json({
    message: 'PDF の生成を開始しました',
    requestId,
    fileId: files[0].fileId,
    // 生成結果を確認するアプリ画面（出力履歴）へのリンク。要ログイン。
    // ファイルの直接ダウンロードURLではない
    outputsUrl: url
  });
});

生成されたファイルは requestId / fileId を使ってPDF のダウンロードから取得します。認証は appkey ヘッダーか OAuth 2.0 のアクセストークン（Authorization: Bearer）で、どちらを使うかは認証方法の選択指針に従ってください。

生成と取得は同じワークスペースの資格情報で行う

appkey はワークスペース単位で発行され、OAuth 2.0 のアクセストークンは同意時に選ばれたワークスペースにバインドされます。生成したワークスペースと異なるワークスペースの資格情報では、その requestId / fileId を取得できません。

上の例のように appkey をサーバー側に置く構成は「単一ワークスペースの自動化」向けで、生成も取得もその appkey のワークスペース内で完結します。

外部ユーザーや他社ユーザーに自分のワークスペースのデータを扱わせる場合は、OAuth 2.0 の Authorization Code + PKCE でユーザー自身に認可させ、生成リクエストもダウンロードも同じアクセストークンで行ってください（必要スコープは pdf:generate）。上の例の appkey で生成したファイルを、別ワークスペースのトークンで取得することはできません。

ケース2: Webhook通知の活用（推奨）

ReportFlowの標準Webhook機能を使用すると、ポーリング不要でリアルタイムに完了通知を受け取れます。

詳細はWebhook通知ガイドを参照してください。

よくある質問

同期生成と非同期生成はどちらを使うべきですか

即座にPDFを受け取りたい場合は単一PDF同期生成を使います。生成に 60 秒を超えうる場合や、同期のタイムアウト（60 秒）を避けたい場合は、本エンドポイント（非同期）を使ってください。

生成完了はどうやって確認すればよいですか

Webhook通知を設定するとポーリング不要でリアルタイムに完了を受け取れます（詳細はWebhook通知ガイド）。Webhookを使わない場合は、レスポンスの requestId を使って生成状態の取得（GET /v1/file/status/{requestId}）をポーリングし、status が completed / failed になるのを待ちます。生成中は Retry-After ヘッダーが付くので、その秒数を間隔にしてください。手順は非同期ワークフローを参照してください。

次のステップ

複数PDF非同期生成 - 複数のPDFを非同期で一括生成
非同期ワークフロー - 大量生成のベストプラクティス
生成状態の取得 - 完了・失敗の確認
PDF のダウンロード - 生成されたファイルのダウンロード方法

エンドポイント情報​

使用例​

cURL​

リクエストパラメータ​

レスポンス​

成功時 (202 Accepted)​

エラー時​

非同期処理のフロー​

ユースケース​

ケース1: バックグラウンドでPDF生成​

ケース2: Webhook通知の活用（推奨）​

よくある質問​

同期生成と非同期生成はどちらを使うべきですか​

生成完了はどうやって確認すればよいですか​

次のステップ​