Guida all'integrazione LLM e prompt per agenti AI

Questa pagina fornisce istruzioni contestuali specificamente progettate per essere lette da Modelli Linguistici di Grandi Dimensioni (LLM) come GPT-4, Claude o Gemini. Puoi fornire direttamente questa pagina al tuo assistente AI per aiutarlo a integrare rapidamente l'API Quote3D nel tuo progetto.

Prompt di Sistema

Utilizza il testo sottostante per spiegare l'architettura di Quote3D al tuo assistente AI o strumento di generazione di codice (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.

Contesto LLM per l'Integrazione di Widget

Puoi chiedere al tuo assistente LLM di eseguire queste attività relative ai widget:

Configurazione JS SDK: Genera una configurazione Quote3D.init che utilizza token, locale, tema, colore, quoteId opzionale e redirectUrl.
Ascolto Eventi: Scrivi listener nella pagina host per gli eventi QUOTE3D_RESULT, QUOTE3D_ADD_TO_CART e QUOTE3D_RESIZE.
Mappatura del payload: Salva i campi del payload della quotazione restituiti, come quoteId, totalPrice, currency, technology, quantity, thumbnailUrl, fileName, weight e filamentWeight.

Logica di elaborazione dei Webhook

Fornisci questi dettagli per far sì che il tuo bot scriva il codice per la sicurezza e la gestione degli eventi dei webhook:

Verifica della firma: Scrivi funzioni per verificare l'header X-Webhook-Signature utilizzando HMAC-SHA256, confrontandolo con il formato sha256=<hex> e utilizza un confronto a tempo sicuro.
Gestione degli eventi: Gestisci gli eventi quote.completed, quote.failed, job.status_changed e widget.added_to_cart con gestori idempotenti.

Migliori pratiche per gli agenti

Quando si scrive codice di integrazione per Quote3D, gestire sempre quanto segue:

Implementare il polling asincrono per la generazione del preventivo. Non aspettarsi ritorni di prezzo immediati sul POST iniziale.
Utilizzare il backoff esponenziale o un loop di ritardo fisso di 2-3 secondi durante il polling /v2/jobs/{job_id}.
Preserva entrambi weight &filamentWeight e il peso del filamento nei metadati del carrello o dell'ordine per rimanere compatibili con i payload e i plugin dei widget correnti.
Preferire i webhook per le integrazioni di produzione e rendere i gestori idempotenti perché i tentativi possono verificarsi.

Riepilogo Endpoint Critici

Un indice di riferimento rapido degli endpoint più utilizzati necessari per l'implementazione di base:

Carica File: POST /v2/file

Avvia Preventivo: POST /v2/file/quote/{file_id}

Verifica Stato: GET /v2/jobs/{job_id}

Leggi Risultato Lavoro Asincrono: job.result

Ottieni Storico Preventivi: GET /v2/quotes