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

単一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": "550e8400-e29b-41d4-a716-446655440000",
    "version": 1,
    "content": {
      "fileName": "invoice.pdf",
      "shareType": "01",
      "passcodeEnabled": false,
      "params": {
        "customerName": "山田太郎",
        "invoiceNumber": "INV-2024-001",
        "amount": 10000
      }
    }
  }'

リクエストパラメータ​

フィールド型必須説明
designIdstring (UUID)✓デザインID
versioninteger✓バージョン番号
content.fileNamestring✓ファイル名（/ \\ : * ? " < > | および制御文字以外は使用可能）
content.shareTypestring-共有タイプ（リクエストは数値コード）。"01"=ワークスペース内共有(デフォルト) / "02"=招待者共有 / "03"=公開URL共有。レスポンスの share.shareType は workspace / invited / public の人間可読な名前で返ります
content.passcodeEnabledboolean-パスコード保護（デフォルト: false）
content.passthroughobject-レスポンスの files[].passthrough に透過する任意のメタデータ（例: { "pageId": "abc123" }）
content.paramsobject✓テンプレートに埋め込むパラメータ（デザインパラメータ取得APIで構造を確認可能）

レスポンス​

成功時 (202 Accepted)​

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://api.re-port-flow.com/v1/file/download/{requestId}",
  "files": [
    {
      "fileName": "invoice.pdf",
      "fileId": "7f3d1a2b-4c5e-6f7a-8b9c-0d1e2f3a4b5c",
      "passthrough": { "pageId": "abc123" },
      "share": {
        "shareType": "workspace",
        "url": "https://app.re-port-flow.com/file/{requestId}/{fileId}",
        "passcodeEnabled": false
      }
    }
  ]
}
フィールド型説明
requestIdstring (UUID)リクエストID（ダウンロードエンドポイントで使用）
urlstring (URI)ZIPダウンロードURL
filesarray生成されたファイルの情報
files[].fileNamestringファイル名
files[].fileIdstringファイルID（個別ダウンロードエンドポイントで使用）
files[].passthroughobjectリクエスト時に指定した content.passthrough の値（指定時のみ）
files[].share.shareTypestring共有タイプ（workspace / invited / public）
files[].share.urlstringファイル表示URL
files[].share.passcodeEnabledbooleanパスコード有効フラグ
files[].share.passcodestringサーバー生成パスコード（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（顧客名や金額）は外部に送信されません。

エラー時​

同期生成エンドポイントと同様のエラーレスポンスを返します。詳細は単一PDF同期生成を参照してください。

非同期処理のフロー​

1. クライアント → API: 生成リクエスト送信
   ↓
2. API → クライアント: 即座に requestId・url・files を返す (202 Accepted)
   ↓
3. API: バックグラウンドでPDF生成開始
   ↓
4. API: PDF生成完了後、S3にアップロード
   ↓
5. クライアント: 返された url または /download/{requestId}/{fileId} からPDFをダウンロード

ユースケース​

ケース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: 'レポート生成を開始しました',
    requestId,
    downloadUrl: url,
    fileId: files[0].fileId
  });
});

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

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

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

次のステップ​