LLM-Integrationsanleitung & KI-Agent-Prompts

System Prompt

Verwenden Sie den Text unten, um die Architektur von Quote3D Ihrem KI-Assistenten oder Code-Generierungstool (Copilot) zu erklären:

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-Kontext für Widget-Integration

Sie können Ihren LLM-Assistenten bitten, diese Widget-bezogenen Aufgaben auszuführen:

• JS SDK-Konfiguration: Generieren Sie eine Quote3D.init-Konfiguration, die Token, Gebietsschema, Thema, Farbe, optional QuoteId und RedirectUrl verwendet.
• Ereignisüberwachung: Schreiben Sie Host-Seiten-Listener für QUOTE3D_RESULT, QUOTE3D_ADD_TO_CART und QUOTE3D_RESIZE.
• Payload-Zuordnung: Behalten Sie die zurückgegebenen Angebots-Payload-Felder wie quoteId, totalPrice, currency, technology, quantity, thumbnailUrl, fileName, weight und filamentWeight bei.

Webhook-Verarbeitungslogik

Bitte geben Sie diese Details an, damit Ihr Bot Code für die Webhook-Sicherheit und Ereignisbehandlung schreiben kann:

• Signaturverifizierung: Schreiben Sie Funktionen, um den X-Webhook-Signature-Header mit HMAC-SHA256 zu verifizieren, vergleichen Sie ihn mit dem Format sha256=<hex> und verwenden Sie einen zeitlich sicheren Vergleich.
• Event Handling: Manage quote.completed, quote.failed, job.status_changed, and widget.added_to_cart events with idempotent handlers.

Best Practices für Agenten

Beim Schreiben von Integrationscode für Quote3D sollten Sie immer Folgendes berücksichtigen:

• Implementieren Sie asynchrone Abfragen für die Angebotserstellung. Erwarten Sie keine sofortigen Preisrückmeldungen auf die anfängliche POST-Anfrage.
• Verwenden Sie exponentiellen Backoff oder eine feste Schleife mit einer Verzögerung von 2-3 Sekunden beim Abfragen. /v2/jobs/{job_id}.
• Beide beibehalten weight &filamentWeight und filamentWeight in den Warenkorb- oder Bestellmetadaten, um mit den aktuellen Widget-Payloads und Plugins kompatibel zu bleiben.
• Prefer webhooks for production integrations, and make handlers idempotent because retries can happen.

Zusammenfassung kritischer Endpunkte

Ein schneller Referenzindex der am häufigsten verwendeten Endpunkte, die für die grundlegende Implementierung erforderlich sind: