Quote3D Dokümantasyonuna Hoş Geldiniz! ⏳
Quote3D LogoQuote3DDokümantasyon

LLM Entegrasyon Rehberi ve Yapay Zeka Promptları

Bu sayfa, özellikle GPT-4, Claude veya Gemini gibi Büyük Dil Modelleri (LLM'ler) tarafından okunmak üzere tasarlanmış bağlamsal talimatlar sağlar. Quote3D API'sini projenize hızla entegre etmesi için bu sayfayı doğrudan Yapay Zeka asistanınıza besleyebilirsiniz.

Sistem Mesajı (System Prompt)

Yapay zeka asistanınıza veya kod üreticisine (Copilot) Quote3D mimarisini anlatmak için aşağıdaki metni kullanın:

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.

Widget Entegrasyonu İçin LLM Bağlamı

LLM asistanınızdan şu widget işlemlerini yapmasını isteyebilirsiniz:

  • JS SDK Yapılandırması: token, locale, tema, renk, isteğe bağlı quoteId ve yönlendirmeUrl kullanarak bir Quote3D.init kurulumu oluşturun.
  • Olay Dinleme: QUOTE3D_RESULT, QUOTE3D_ADD_TO_CART ve QUOTE3D_RESIZE olayları için ana sayfa dinleyicileri yazın.
  • Payload Eşleme: Dönen quote payload alanlarını quoteId, totalPrice, currency, technology, quantity, thumbnailUrl, fileName, weight ve filamentWeight ile birlikte saklama.

Webhook İşleme Mantığı

Webhook güvenliği ve olay işleme kodlarını botunuzun yazması için şu detayları verin:

  • İmza Doğrulama: X-Webhook-Signature başlığını HMAC-SHA256 ile doğrulayan, sha256=&lt;hex&gt; formatını kontrol eden ve timing-safe karşılaştırma kullanan fonksiyonu yazma.
  • Olay İşleme: quote.completed, quote.failed, job.status_changed ve widget.added_to_cart olaylarını idempotent handler'larla yönetme.

Ajanlar için En İyi Uygulamalar

Quote3D için entegrasyon kodu yazarken her zaman şunları ele alın:

  • Teklif oluşturma için asenkron polling uygulayın. İlk quote oluşturma isteğinden anında fiyat dönmesini beklemeyin.
  • Şunu kontrol ederken bounded polling, exponential backoff veya sabit 2-3 saniyelik gecikme döngüsü kullanın /v2/jobs/{job_id}.
  • Hem koruyun weight &filamentWeight Mevcut widget payload'ları ve plugin'lerle uyumlu kalmak için sepet veya sipariş metadata'sında filamentWeight alanını da koruyun.
  • Production entegrasyonlarında webhook tercih edin ve retry ihtimali nedeniyle handler'ları idempotent tasarlayın.

Kritik Endpoint Özeti

Temel implementasyon için en sık kullanılan endpoint'lerin hızlı referans listesi:

Dosya Yükle: POST /v2/file
Teklif Başlat: POST /v2/file/quote/{file_id}
Durumu Kontrol Et: GET /v2/jobs/{job_id}
Asenkron İş Sonucunu Oku: job.result
Teklif Geçmişini Getir: GET /v2/quotes