Guía de Integración LLM y Prompts para Agentes de IA

Indicación del Sistema

Utilice el texto a continuación para explicar la arquitectura de Quote3D a su asistente de IA o herramienta de generación de código (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.

Contexto LLM para la Integración de Widgets

Puedes pedirle a tu asistente LLM que realice estas tareas relacionadas con los widgets:

• Configuración del SDK de JS: Genera una configuración de Quote3D.init que utilice token, locale, tema, color, quoteId opcional y redirectUrl.
• Escucha de Eventos: Escribe listeners en la página de destino para los eventos QUOTE3D_RESULT, QUOTE3D_ADD_TO_CART y QUOTE3D_RESIZE.
• Mapeo de Carga Útil: Persista los campos de carga útil de la cotización devueltos, como quoteId, totalPrice, currency, technology, quantity, thumbnailUrl, fileName, weight y filamentWeight.

Lógica de Procesamiento de Webhooks

Proporcione estos detalles para que su bot escriba código de seguridad de webhook y manejo de eventos:

• Verificación de Firma: Escriba funciones para verificar el encabezado X-Webhook-Signature utilizando HMAC-SHA256, compare contra el formato sha256=<hex> y utilice una comparación segura en cuanto al tiempo.
• Manejo de Eventos: Administre los eventos quote.completed, quote.failed, job.status_changed y widget.added_to_cart con controladores idempotentes.

Mejores prácticas para Agentes

Al escribir código de integración para Quote3D, siempre maneje lo siguiente:

• Implemente sondeo asíncrono para la generación de cotizaciones. No espere retornos de precios inmediatos en el POST inicial.
• Utilice retroceso exponencial o un bucle de retardo fijo de 2-3 segundos al realizar el sondeo /v2/jobs/{job_id}.
• Conserve tanto weight &filamentWeight y el peso del filamento en los metadatos del carrito o del pedido para mantener la compatibilidad con las cargas útiles y los plugins actuales.
• Prefiera los webhooks para las integraciones de producción y haga que los controladores sean idempotentes, ya que pueden ocurrir reintentos.

Resumen de Puntos Finales Críticos

Un índice de referencia rápida de los puntos finales más utilizados necesarios para la implementación básica: