Guide d'intégration LLM et invites d'agent IA

Invite Système

Utilisez le texte ci-dessous pour expliquer l'architecture de Quote3D à votre assistant IA ou à votre outil de génération de code (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.

Contexte LLM pour l'intégration de widgets

Vous pouvez demander à votre assistant LLM d'effectuer les tâches liées aux widgets suivantes :

• Configuration du SDK JS : Générez une configuration Quote3D.init qui utilise un token, une locale, un thème, une couleur, un quoteId optionnel et un redirectUrl.
• Écoute d'événements : Écrivez des écouteurs de page hôte pour les événements QUOTE3D_RESULT, QUOTE3D_ADD_TO_CART et QUOTE3D_RESIZE.
• Mappage de la charge utile : Conservez les champs de la charge utile du devis renvoyés tels que quoteId, totalPrice, currency, technology, quantity, thumbnailUrl, fileName, weight et filamentWeight.

Logique de traitement des Webhooks

Fournissez ces détails pour que votre bot écrive le code de sécurité et de gestion des événements des webhooks :

• Vérification de la signature : Écrivez des fonctions pour vérifier l'en-tête X-Webhook-Signature en utilisant HMAC-SHA256, comparez-le au format sha256=<hex> et utilisez une comparaison résistante aux attaques temporelles.
• Gestion des événements : Gérez les événements quote.completed, quote.failed, job.status_changed et widget.added_to_cart avec des gestionnaires idempotents.

Meilleures pratiques pour les agents

Lors de la rédaction du code d'intégration pour Quote3D, gérez toujours les éléments suivants :

• Implémentez un sondage asynchrone pour la génération de devis. Ne vous attendez pas à des retours de prix immédiats lors du POST initial.
• Utilisez un retour exponentiel ou une boucle de délai fixe de 2 à 3 secondes lors du sondage /v2/jobs/{job_id}.
• Conservez les deux weight &filamentWeight et le poids du filament dans les métadonnées du panier ou de la commande pour rester compatible avec les charges utiles et les plugins actuels.
• Privilégiez les webhooks pour les intégrations en production et rendez les gestionnaires idempotents car des tentatives peuvent se produire.

Résumé des points de terminaison critiques

Un index de référence rapide des points de terminaison les plus utilisés pour une implémentation de base :