LLM 集成指南与 AI 代理提示

此页面提供专门为大型语言模型 (LLM)（如 GPT-4、Claude 或 Gemini）设计的上下文说明。您可以直接将此页面提供给您的 AI 助手，以帮助它快速将 Quote3D API 集成到您的项目中。

系统提示

使用以下文本向您的AI助手或代码生成工具（Copilot）解释Quote3D的架构：

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 配置：生成使用 token、locale、theme、color、可选的 quoteId 和 redirectUrl 的 Quote3D.init 设置。
事件监听：编写宿页监听器，用于监听 QUOTE3D_RESULT、QUOTE3D_ADD_TO_CART 和 QUOTE3D_RESIZE 事件。
有效载荷映射：持久化返回的报价有效载荷字段，例如 quoteId、totalPrice、currency、technology、quantity、thumbnailUrl、fileName、weight 和 filamentWeight。

Webhook 处理逻辑

提供这些详细信息，以便您的机器人编写 webhook 安全性和事件处理代码：

签名验证：编写函数以使用 HMAC-SHA256 验证 X-Webhook-Signature 标头，将其与 sha256=<hex> 格式进行比较，并使用安全计时比较。
事件处理：使用幂等处理程序管理 quote.completed、quote.failed、job.status_changed 和 widget.added_to_cart 事件。

代理最佳实践

在编写 Quote3D 集成代码时，请始终处理以下事项：

为报价生成实现异步轮询。不要期望在初始 POST 请求后立即返回价格。
在轮询时使用指数退避或固定的 2-3 秒延迟循环 /v2/jobs/{job_id}.
保留两者 weight &filamentWeight 并且在购物车或订单元数据中包含灯丝重量，以与当前小部件负载和插件保持兼容。
对于生产集成，建议使用 Webhooks，并使处理程序具有幂等性，因为可能会发生重试。

关键端点摘要

用于基本实施所需的最常用端点的快速参考索引：

上传文件: POST /v2/file

开始报价: POST /v2/file/quote/{file_id}

检查状态: GET /v2/jobs/{job_id}

读取异步作业结果: job.result

获取报价历史: GET /v2/quotes