Quote3D ドキュメントへようこそ！⏳
Quote3D LogoQuote3Dドキュメント

LLM連携ガイドとAIエージェントプロンプト

このページには、GPT-4、Claude、Geminiなどの大規模言語モデル（LLM）によって読み取られるように特別に設計されたコンテキスト情報が記載されています。このページをAIアシスタントに直接入力することで、Quote3D APIをプロジェクトに迅速に統合するのに役立ちます。

システムプロンプト

以下のテキストを使用して、Quote3DのアーキテクチャをAIアシスタントまたはコード生成ツール（Copilot）に説明してください：

You are integrating the Quote3D REST API, async quote jobs, webhooks, and the embeddable widget.

Use these current integration rules:
1. Authentication: REST requests use 'Authorization: Bearer <token>' or 'X-API-Token'. The embeddable widget also receives the token client-side through the iframe URL or JS SDK init options.
2. Async quotes: Upload a model with POST /v2/file. Start pricing with POST /v2/file/quote/{file_id}. This returns an async job. Poll GET /v2/jobs/{job_id} until the job status is 'COMPLETED', 'FAILED', or 'CANCELLED'. On completion, read the quote payload from the job response result or from stored quote records.
3. Widget SDK: Use Quote3D.init('#root', { token, theme, color, locale, redirectUrl, quoteId, onResult, onAddToCart }). The SDK converts redirectUrl into the iframe query parameter 'redirect_url'.
4. Widget messaging: The iframe posts 'QUOTE3D_RESULT', 'QUOTE3D_ADD_TO_CART', and 'QUOTE3D_RESIZE' messages to the host page. Handle resize by updating iframe height.
5. Widget payload contract: Host listeners should expect fields such as quoteId, totalPrice, currency, material, technology, quantity, thumbnailUrl, fileName, weight, and filamentWeight. Keep backward-compatible handling for both weight and filamentWeight.
6. Webhooks: Quote3D sends webhook events like 'quote.completed', 'quote.failed', 'job.status_changed', and 'widget.added_to_cart'. Verify 'X-Webhook-Signature' using HMAC-SHA256 over the raw request body. The signature format is 'sha256=<hex>'.
7. Security: Do not claim a special widget-only restricted token model unless the product explicitly exposes one. Document the real token flow and verify webhook authenticity server-side.

Flow for AI agents:
- Generate working upload -> async quote -> polling flows for v2 API integrations.
- Generate widget embed code with redirect handling and postMessage listeners.
- Write add-to-cart bridges that preserve Quote3D payload fields.
- Implement webhook handlers with timing-safe signature verification and idempotent processing.

ウィジェット連携のためのLLMコンテキスト

LLMアシスタントにこれらのウィジェット関連のタスクを実行させることができます:

  • JS SDK設定: トークン、ロケール、テーマ、色、オプションのquoteId、およびredirectUrlを使用するQuote3D.init設定を生成します。
  • イベントリスニング: QUOTE3D_RESULT、QUOTE3D_ADD_TO_CART、およびQUOTE3D_RESIZEイベントのホストページリスナーを作成します。
  • ペイロードマッピング: quoteId、totalPrice、currency、technology、quantity、thumbnailUrl、fileName、weight、filamentWeightなどの返された引用符ペイロードフィールドを保持します。

Webhook処理ロジック

ボットにWebhookセキュリティとイベント処理コードを記述してもらうために、これらの詳細を提供してください。

  • 署名検証: X-Webhook-SignatureヘッダーをHMAC-SHA256を使用して検証する関数を記述します。
  • イベント処理: quote.completed、quote.failed、job.status_changed、widget.added_to_cartイベントをべき等なハンドラーで管理します。

エージェントのためのベストプラクティス

Quote3Dの連携コードを記述する際は、常に以下の点に注意してください。

  • 見積もり生成のために、非同期ポーリングを実装してください。最初のPOSTリクエストに対して即時の価格リターンを期待しないでください。
  • ポーリング時には、指数バックオフまたは固定の2〜3秒の遅延ループを使用してください。 /v2/jobs/{job_id}.
  • 両方を保持してください weight &filamentWeight 現在のウィジェットのペイロードおよびプラグインとの互換性を維持するために、カートまたは注文メタデータにfilamentWeightを含めます。
  • 本番環境の連携にはWebhookを推奨し、再試行が発生する可能性があるため、ハンドラーをべき等にしてください。

重要なエンドポイントの概要

基本的な実装に必要な最も頻繁に使用されるエンドポイントのクイックリファレンスインデックス:

ファイルアップロード: POST /v2/file
見積もり開始: POST /v2/file/quote/{file_id}
ステータス確認: GET /v2/jobs/{job_id}
非同期ジョブの結果を読み込み: job.result
見積もり履歴取得: GET /v2/quotes