> ## Documentation Index > Fetch the complete documentation index at: https://docs.bizmori.com/llms.txt > Use this file to discover all available pages before exploring further. # AI エージェント連携 > Claude Code、Cursor、Codex に貼り付けるだけで、BIZ MORI API 連携に必要なすべてのルールが伝わります ## このプロンプトをコピーしてくださいコピーしてエージェントに貼り付け、`<...>` の部分だけ埋めてください — サービス、スタック、実際の作業内容です。それ以外はそのままで構いません。このプロンプトは意図的に短くしてあります。API 仕様をそのまま書き写す代わりに、エージェントが自力ではやらない3つのことだけを指示します。**コードを書く前にドキュメントを読んでリスクを報告させ**、**出荷してはいけないミスを明確に禁止し**（confirm ステップの省略、Webhook 署名の未検証、API キーのハードコーディング）、最後に**連携が実際に動作することを証明させます** — 動作すると主張するだけで終わらせないためです。 ```text wrap theme={null} BIZ MORI API を統合してください。ドキュメント: https://docs.bizmori.com 全文ドキュメント: https://docs.bizmori.com/llms-full.txt <- ガイド全文（プレーンテキスト） OpenAPI: https://docs.bizmori.com/api-reference/openapi.yaml <- 正式なスキーマベース URL: https://api.bizmori.com 認証: Authorization: Bearer $BIZMORI_API_KEY （環境変数から読み込むこと。ハードコーディングやログ出力は禁止）サービス: スタック: <例: TypeScript + Express, Python + FastAPI> 作業内容: <実装してほしい内容> コードを書く前に、上記の2つのファイルを両方取得してください: - llms-full.txt: ガイドを読むため — 該当サービスのクイックスタートに加えて、Webhook とエラーコードのページも読むこと。 - openapi.yaml: 正確なリクエスト/レスポンススキーマのため。ガイドにはフィールド定義が含まれていないので、フィールド名・型・enum 値・必須/任意の区分はすべて仕様から取得すること。コードサンプルだけからフィールドを推測してはならない。その後、実装方針と、リスクや曖昧な点があれば教えてください。エンドポイント・フィールド・パラメータを勝手に作り出さないこと — 仕様に存在しない場合は、推測せずにそう伝えること。仕様上 deprecated と示されているエンドポイントは使用せず、指定されている代替を使うこと。以下はドキュメントで明確に定められている項目であり、実装を誤りやすい部分でもあります。思い込みで進めず、必ず一つずつ確認してください — これらを省略したコードを出荷しないこと: - 注文は非同期（ASYNCHRONOUS）であり、confirm ステップはサービスごとに異なる。アップロード後に confirm 呼び出しが必要なサービスもあれば、confirm エンドポイント自体が存在せず、呼び出してはならないサービスもある。フローを書く前に、該当サービスがどちらに当たるか確認すること。 - Webhook の署名は、生のリクエストボディ（RAW request body）に対して、定数時間（constant time）で検証しなければならない。 - プリサインド URL（アップロード/ダウンロード用）には有効期限があり、それを再発行するエンドポイントが存在する。 - 注文作成には冪等性キー（idempotency key）を指定する。リトライ時は同じキーを再利用すること。実装が終わったら、動作すると主張するだけでなく、必ず検証すること: 1. テスト画像を使って実際にエンドツーエンドで注文を実行し、`complete` に到達することを見せること。 2. 実際に取得した結果（ダウンロードしたファイル、または detection フィールド）を見せること。 3. 自分の差分（diff）に対してハードコーディングされたキーやログに出力されたトークンがないか grep し、その出力を見せること。 4. Webhook レシーバーを実装した場合は、不正な署名を送信して 401 が返ることを見せること。上記のいずれかを実行できなかった場合は、動作したと主張せず、正直にその旨を伝えること。 ``` プロンプト本文はあえて英語で書かれています。コーディングエージェントは英語の指示で最も安定して動作し、エンドポイント名やフィールド名と表記を一致させるためです。冒頭の `My task` の項目は日本語で作業内容を書いても問題なく動作します。 ## エディタで使う一回限りの作業であれば、そのままセッションに貼り付ければ十分です。すべてのセッションで自動的に読み込ませたい場合は、プロンプトを `.claude/bizmori-api.md` として保存し、`CLAUDE.md` から import してください。 ```markdown CLAUDE.md theme={null} @.claude/bizmori-api.md ``` Claude Code は起動時に import されたファイルを読み込むため、リクエストする前にすでに指示がコンテキストへ入っています。プロジェクトルールとして保存しておくと、連携コードを触るたびに Cursor が自動的に適用します。`.cursor/rules/bizmori-api.mdc` ファイルを作成してください。 ```markdown theme={null} --- description: BIZ MORI API integration contract globs: ["**/*bizmori*", "**/api/**"] --- （ここにプロンプトを貼り付けてください） ``` 一回限りの作業であれば、`Cmd/Ctrl + L` でチャットパネルに直接貼り付けても構いません。 Codex をはじめとするほとんどのコーディングエージェントは、リポジトリルートの `AGENTS.md` を読み込みます。`## BIZ MORI API` という見出しの下にプロンプトを貼り付けておけば、実行のたびに自動的に参照されます。規約ファイルを持たないエージェントの場合は、会話の最初のメッセージとしてプロンプトを貼り付けてください。 ## エージェントにライブドキュメントを渡す上記のプロンプトが短くて済む理由はここにあります。このドキュメントは機械可読な形式でも公開されているため、エージェントはプロンプトが書かれた時点の内容ではなく、**リクエストするその瞬間の最新スペック**を自ら取得します。 | リソース | URL | 用途 | | --------------- | ----------------------------------------------------- | ---------------------------------------------------------- | | OpenAPI スペック | `https://docs.bizmori.com/api-reference/openapi.yaml` | 正確なリクエスト/レスポンススキーマ — フィールド名、型、enum、必須かどうか。型付きクライアントの生成にも使用 | | フルドキュメント | `https://docs.bizmori.com/llms-full.txt` | ガイド全体を1つのプレーンテキストファイルに — フロー、Webhook 検証、エラーコード | | ドキュメントインデックス | `https://docs.bizmori.com/llms.txt` | すべてを一度に読み込ませるのではなく、必要なドキュメントだけを探させたいとき | | 個別ページの Markdown | ページ URL の末尾に `.md` を付加 | 特定のガイド1つだけをコンテキストに入れたいとき | どちらも必要であり、互いを代替するものではありません。`llms-full.txt` にはガイドは含まれますが、**フィールド定義は含まれません** — パラメータ表は OpenAPI スペックからレンダリングされるものであり、プレーンテキストには引き継がれないためです。`llms-full.txt` だけを渡されたエージェントは、コードサンプルからリクエストボディを逆算し、残りは推測することになります。プロンプトが両方のファイルを取得させるのはこのためです。 ## デプロイ前に確認することデプロイ前に、以下の4点は必ず確認してください。最も頻繁に発生するミスです。キーは必ず環境変数またはシークレットマネージャーから読み込む必要があり、ソースコードに直接書かれていてはいけません。差分の中で `Bearer ` やキーらしきリテラルを検索し、キーがログに残っていないことを確認してください。 Anti-AI（アップロードモード）と AI Detection は confirm 呼び出しが必要です。 Watermark Embed と Watermark Extract は不要で、呼び出すと失敗します。 Anti-AI を URL モードのみで使う場合も confirm は呼び出しません。 HMAC は元のリクエストバイト列（raw body）で計算する必要があります。 JSON パーサーが先に実行され、オブジェクトを再シリアライズすると署名が一致しなくなり、エージェントが検証をスキップする形で「修正」しようとすることがあります。比較は必ず定数時間（constant-time）で行う必要があります。アップロード用 URL は1時間、ダウンロード用 URL は7日間有効です。時間のかかるバッチ処理の場合、期限切れの URL を再利用せず、 [URL 再発行](/ja/api-reference/orders/refresh-urls)エンドポイントを呼び出す必要があります。 ## 次のステップ自動化する前に、まず自分の手でフローを一通り試してみましょう。すべてのエンドポイントの基準となるスペックです。署名検証とイベントペイロードの詳細な説明です。エージェントのエラー処理がカバーすべきすべてのコードです。