Coze 連携（OpenAPI プラグイン）

Coze（ByteDance の AI エージェントプラットフォーム）のボットから Re:port Flow を呼び出して、チャットの会話から帳票 PDF を生成できます。Coze はツール連携を プラグイン（OpenAPI 形式） で扱うため、Re:port Flow の REST API をプラグインとして登録します。

備考

Coze Plugin Store での公式プラグイン公開は準備中です。現時点では、下記の手順で 自分の Coze アカウントに自分専用のプラグインとして登録 すれば利用できます。ワークスペースの API キーは自分のものを使うため、他人に共有されることはありません。

Coze と MCP はどちらを使う？

Re:port Flow は AI エージェント向けに 2 つの入口を持っています。クライアントが MCP に対応しているかで選んでください。

使うクライアント	推奨
Claude Desktop / Claude Code / Cursor / VS Code	MCP サーバー（reportflow-mcp）
Coze のボット・ワークフロー	本ページのプラグイン方式

MCP 側は OAuth 2.0 でユーザーごとに認可しますが、Coze のプラグインは OpenAPI + API キーで接続します。どちらも同じ Re:port Flow API を呼ぶため、生成される PDF は同一です。

事前に用意するもの

1. Re:port Flow のワークスペース（re-port-flow.com で作成）
2. アプリケーションキー（ak_ で始まる文字列）— ワークスペース設定 → API連携 から取得します。詳細は APIキーの取得と管理 を参照してください
3. PDF のもとになるデザイン（テンプレート）を 1 つ以上作成しておくこと。まだ無い場合は テンプレートギャラリー から複製できます

Coze にプラグインを登録する

Coze のダッシュボードで Create plugin → Create a plugin based on API を選び、次のとおり設定します。

1. 基本設定

項目	値
Plugin URL（ベース URL）	https://api.re-port-flow.com/v1
Authorization method	Service（ヘッダーにトークンを付与する方式）
Location	Header
Parameter name（Key）	appkey
Service token	取得したアプリケーションキー（ak_...）

警告

appkey は ヘッダー名を小文字 で指定します。値が違うと 401、ヘッダーごと送られていないと 412 が返ります。切り分け方は 認証方法 を参照してください。

2. ツールを 4 つ追加する

Coze の「Add tool」で、次の 4 つを登録します。この順番でエージェントに呼ばせるのが基本です。

ツール名	メソッド	パス	役割
listTemplates	GET	/file/designs	ワークスペース内のテンプレート一覧を取得（id と latestVersion が返る）
getDesignParameters	GET	/file/design/parameter/{designId}	テンプレートが要求するパラメータ定義を取得
generatePdfAsync	POST	/file/async/single	PDF の生成を開始し、requestId と files[] を JSON で返す
downloadGeneratedFile	GET	/file/download/{requestId}/{fileId}	生成完了を確認する（後述）

各エンドポイントのリクエスト・レスポンス構造は次のページにまとまっています。

• デザインパラメータ取得
• 単一PDFの非同期生成
• ファイルダウンロード

generatePdfAsync のリクエストボディは次の形です。

{
  "designId": "0eUDdgAjNXrrItA2",
  "version": 1,
  "content": {
    "fileName": "invoice_2026-08.pdf",
    "params": {
      "請求書番号": "INV-2026-0812",
      "発行日": "2026-08-12",
      "請求先名": "株式会社サンプル",
      "合計金額": 110000
    }
  }
}

params のキーは、getDesignParameters が返す各フィールドの name と一致させます。テンプレートごとに違うので、固定で書かずに必ず取得してから組み立ててください。

3. ツールの説明文を書く

Coze のエージェントは、ツールの説明文を読んでどれを呼ぶか判断します。次の 2 点は説明文に必ず含めてください。実測で挙動が変わる部分です。

• generatePdfAsync の前に必ず getDesignParameters を呼ぶこと。パラメータ値を推測で埋めないこと。 これを書かないと、エージェントが params を架空の値で埋めた PDF を生成します。
• generatePdfAsync の 202 は「受付」であって完了ではないこと。downloadGeneratedFile が 200 を返してから完了と報告すること。 これを書かないと、生成が遅延・失敗したジョブを「出来ました」とユーザーに提示します。
• shareType は指定しないこと。 既定の "01"（ワークスペース内共有）のままにします。

なぜ同期生成（sync）ではなく非同期（async）を使う？

POST /file/sync/single はレスポンスボディが PDF のバイナリそのもの で、生成結果の識別子（File-URL / Request-Id / X-File-Mapping）は レスポンスヘッダーにしか入りません。

Coze はツールの出力をレスポンスボディから組み立てるため、sync を登録するとエージェントは「PDF は生成されたが、ユーザーに渡す情報を取り出せない」状態になります。チャットから使う場合は POST /file/async/single（JSON を返す）を使ってください。

同期生成そのものは 単一PDFの同期生成 のとおり有効で、レスポンスヘッダーを読めるクライアント（自前のサーバーなど）からは問題なく使えます。

生成が終わったことはどうやって確認する？

generatePdfAsync が返す 202 Accepted は ジョブを受け付けた という意味で、PDF が出来たという意味ではありません。ここで打ち切ると、生成が遅延・失敗した場合でもエージェントが「出来ました」と答えてしまいます。

Re:port Flow には ジョブステータス専用の API がありません。完了確認はダウンロードエンドポイントで行います。

GET https://api.re-port-flow.com/v1/file/download/{requestId}/{fileId}

• 200 — ファイルが存在する = 生成完了。ここで初めてユーザーに完了を伝えます
• 404 — まだ取得できない。「生成中」と「ID が誤っている」は区別できません。数秒待って数回リトライしてから失敗と判断してください

requestId と fileId は generatePdfAsync のレスポンス（requestId と files[0].fileId）から取ります。レスポンスボディは PDF 本体ですが、完了確認ではステータスコードだけを見れば十分です。

ヒント

1 回の呼び出しで完了保証が欲しい場合は同期生成（/file/sync/single）が使えます。ただし前節のとおり、Coze からはレスポンスの識別子を取り出せません。自前のサーバーを経由する構成であれば同期生成のほうが単純です。

生成した PDF はどうやってユーザーに渡す？

完了を確認したうえで、generatePdfAsync のレスポンスに含まれる files[].share.url を渡します。このリンクを開くのに Re:port Flow へのログインが必要かどうかは、リクエストの shareType で決まります。

shareType	意味	リンクを開くのに必要なもの
"01"（既定）	ワークスペース内共有	Re:port Flow へのログイン
"02"	招待者共有	招待 + ログイン
"03"	公開URL共有	なし（URL を知っていれば誰でも閲覧可能）

危険

「チャットからそのまま開きたい」という理由だけで "03" を使わないでください。"03" は URL を知っている全員が中身を読める状態です。請求書のように取引先情報を含む帳票では、意図しない情報公開になります。

公開が必要な場合は、ユーザーが明示的にそれを求めたときにだけ "03" を指定し、あわせて passcodeEnabled: true（パスコード保護）の利用を検討してください。

Coze から使えるテンプレートはどこにある？

listTemplates のレスポンスは { "designs": [...], "total": 12, "page": 1, "pageSize": 30, "totalPages": 1 } という形のオブジェクトです（トップレベルが配列ではない点に注意）。designs が空配列の場合、そのワークスペースにはまだデザインがありません。テンプレートギャラリー で請求書・見積書・領収書などの公開テンプレートを自分のワークスペースへ複製すると、その時点から listTemplates に出てきます。

ギャラリーの検索 API（GET https://re-port-flow.com/api/v1/public/templates）は認証不要のため、「どんなテンプレートがあるか探す」だけのプラグインを認証なしで別途登録することもできます。ただしギャラリーの slug では PDF を生成できません（生成には複製後の designId が必要です）。

よくある質問

Coze の無料プランでも使えますか？

Re:port Flow 側の制約はありません。Coze 側のプラグイン作成可否は Coze のプラン規定に従います。Re:port Flow は FREE プランで月 30 ファイルまで生成できます。

中国語のパラメータ値は使えますか？

使えます。Re:port Flow は日本語の禁則処理・フォント埋め込みに対応しており、UTF-8 の文字列をそのまま params に渡せます。ただし テンプレートに埋め込まれたフォントがその文字を含んでいる必要があります。簡体字・繁体字を使う場合は、デザイン編集画面で対応するフォントを選択してください。

レート制限はありますか？

ワークスペース単位で、同期エンドポイントが 30 req/min、非同期・ダウンロードが 100 req/min です。超過すると 429 と Retry-After ヘッダーが返ります。詳細は 制限事項 を参照してください。

生成に失敗したときは何を見ればいいですか？

まず HTTP ステータスを確認してください。400 はほとんどの場合 params がテンプレートのスキーマと一致していないケースです。getDesignParameters の出力とキー名・型を突き合わせてください。401 / 412 は認証設定の問題です。詳細は エラーハンドリング を参照してください。