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 にプラグインを登録する

ツールを 1 つずつ手入力する必要はありません。Re:port Flow が Coze 用に用意している OpenAPI ファイルをインポート すれば、ベース URL・ツール・パラメータ・説明文がまとめて登録されます。

1. OpenAPI ファイルをインポートする

Coze のダッシュボードで Create plugin → Create a plugin based on API を選び、JSON / YAML の取り込み（Import）で次のファイルを読み込ませます。

https://doc.re-port-flow.com/openapi/coze-plugin.yaml

ファイルとして手元に保存してから読み込ませる場合は、次のコマンドでダウンロードできます。

curl -fsSL -o coze-plugin.yaml https://doc.re-port-flow.com/openapi/coze-plugin.yaml

このファイルは Coze で読み込めるよう OpenAPI 3.0 で書かれています（API 全体の仕様 https://doc.re-port-flow.com/openapi/content-service.yaml は OpenAPI 3.1）。ベース URL（https://api.re-port-flow.com/v1）もファイルに含まれています。

2. 認証を設定する

インポート後、プラグインの認証を次のとおり設定します。

項目	値
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 が返ります。切り分け方は 認証方法 を参照してください。

3. 登録されるツールを確認する

インポートすると、チャットから使う次の 4 つのツールが登録されます。この順番でエージェントに呼ばせるのが基本です。ファイルには同期生成の generatePdfSync も含まれていますが、後述の理由でチャットからは使いません。インポートすると generatePdfSync もツールとして登録されるので、プラグインのツール一覧から generatePdfSync を削除してください（残すとエージェントが選ぶことがあり、ページ数を消費したうえで結果を取り出せません）。

ツール名	メソッド	パス	役割
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の非同期生成
• PDF のダウンロード

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

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

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

4. ツールの説明文を確認する

Coze のエージェントは、ツールの説明文を読んでどれを呼ぶか判断します。インポートしたファイルの説明文には次の点が書かれています。説明文を編集する場合も、これらは必ず残してください。実測で挙動が変わる部分です。

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

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

POST /file/sync/single は既定ではレスポンスボディが PDF のバイナリそのもの で、生成結果の識別子（File-URL / Request-Id / X-File-Mapping）は レスポンスヘッダーにしか入りません。URL に ?response=json を付けると識別子を JSON で返しますが、このプラグイン定義には含めていません。

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

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

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

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

Re:port Flow API には生成状態の取得 API（GET /v1/file/status/{requestId}）がありますが、このプラグインの OpenAPI 定義には含めていません。プラグインでは、完了確認をダウンロードエンドポイントで行います。

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

• 200 — ファイルが存在する = 生成完了。ここで初めてユーザーに完了を伝えます
• 409（FILE_NOT_READY）— まだ生成中。レスポンス本文の retryAfter の秒数（現在は 2 秒）待ってから再度呼んでください（Coze はレスポンスヘッダーを読めないため、Retry-After ヘッダーではなく本文の値を使います）
• 422（FILE_GENERATION_FAILED）— 生成に失敗した。リトライせず、失敗したとユーザーに伝えます
• 404（FILE_NOT_FOUND）— ID の誤り、別ワークスペースの ID、失敗から 24 時間を過ぎた単一生成、または出力の削除。生成中は通常 409 が返りますが、ジョブの記録を保存できなかったリクエストは生成中でも 404 になります。生成直後に 404 が返ったら、数秒待って 1〜2 回だけ確かめ直してから失敗と判断してください

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

自前のサーバーから呼ぶ場合は、生成状態の取得（GET /v1/file/status/{requestId}）で processing / completed / failed と失敗理由を直接確認できます。

ヒント

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

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

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

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

危険

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

公開が必要な場合は、ユーザーが明示的にそれを求めたときにだけ "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 ページまで PDF を出力できます。

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

UTF-8 の文字列はそのまま params に渡せますが、PDF に表示できるかはテンプレートのフォント次第です。テンプレートに埋め込まれたフォントがその文字を含んでいる必要があります。日本語の禁則処理・フォント埋め込みには対応していますが、簡体字・繁体字のフォントが標準で選べるかは未検証です（テンプレートでできること）。使う前に、その文字を含むフォントがテンプレートの編集画面で選べるかと、実際のデータでの出力結果を確認してください。

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

ワークスペース単位で、同期エンドポイントが 30 req/min、非同期・ダウンロードが 100 req/min です。超過すると 429 が返り、待つ秒数がレスポンス本文の retryAfter（Retry-After ヘッダーにも同じ値）に入ります。詳細は 制限事項 を参照してください。

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

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