LLM Integration Guide & AI Agent Prompts

This page provides contextual instructions specifically designed to be read by Large Language Models (LLMs) like GPT-4, Claude, or Gemini. You can feed this page directly to your AI assistant to help it quickly integrate the Quote3D API into your project.

System Prompt

Use the text below to explain Quote3D's architecture to your AI assistant or code generation tool (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 Context for Widget Integration

You can ask your LLM assistant to perform these widget-related tasks:

JS SDK Configuration: Generate a Quote3D.init setup that uses token, locale, theme, color, optional quoteId, and redirectUrl.
Event Listening: Write host-page listeners for QUOTE3D_RESULT, QUOTE3D_ADD_TO_CART, and QUOTE3D_RESIZE.
Payload Mapping: Persist the returned quote payload fields such as quoteId, totalPrice, currency, technology, quantity, thumbnailUrl, fileName, weight, and filamentWeight.

Webhook Processing Logic

Provide these details to have your bot write webhook security and event handling code:

Signature Verification: Write functions to verify the X-Webhook-Signature header using HMAC-SHA256, compare against the sha256=<hex> format, and use a timing-safe comparison.
Event Handling: Manage quote.completed, quote.failed, job.status_changed, and widget.added_to_cart events with idempotent handlers.

Best Practices for Agents

When writing integration code for Quote3D, always handle the following:

Implement asynchronous polling for quote generation. Do not expect immediate price returns from the initial quote creation request.
Use a bounded polling loop with exponential backoff or a fixed 2-3 second delay when checking /v2/jobs/{job_id}.
Preserve both weight &filamentWeight and filamentWeight in cart or order metadata to stay compatible with current widget payloads and plugins.
Prefer webhooks for production integrations, and make handlers idempotent because retries can happen.

Critical Endpoints Summary

A quick reference index of the most used endpoints required for basic implementation:

Upload File: POST /v2/file

Start Quote: POST /v2/file/quote/{file_id}

Check Status: GET /v2/jobs/{job_id}

Read Async Job Result: job.result

Get Quote History: GET /v2/quotes