Руководство по интеграции LLM и подсказки для AI-агентов

Эта страница содержит контекстные инструкции, разработанные специально для чтения большими языковыми моделями (LLM), такими как GPT-4, Claude или Gemini. Вы можете передать эту страницу напрямую вашему AI-помощнику, чтобы помочь ему быстро интегрировать API Quote3D в ваш проект.

Системное сообщение

Используйте текст ниже, чтобы объяснить архитектуру Quote3D вашему AI-ассистенту или инструменту генерации кода (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.

Контекст LLM для интеграции виджетов

Вы можете попросить своего LLM-ассистента выполнить следующие задачи, связанные с виджетами:

Настройка JS SDK: Сгенерируйте Quote3D.init с использованием токена, локали, темы, цвета, необязательного quoteId и redirectUrl.
Прослушивание событий: Напишите обработчики событий на хост-странице для QUOTE3D_RESULT, QUOTE3D_ADD_TO_CART и QUOTE3D_RESIZE.
Сопоставление полезной нагрузки: сохраните поля возвращаемой полезной нагрузки котировки, такие как quoteId, totalPrice, currency, technology, quantity, thumbnailUrl, fileName, weight и filamentWeight.

Логика обработки Webhook

Предоставьте эти детали, чтобы ваш бот написал код для безопасности webhook и обработки событий:

Проверка подписи: Напишите функции для проверки заголовка X-Webhook-Signature с использованием HMAC-SHA256, сравните его с форматом sha256=<hex> и используйте сравнение, устойчивое ко временным атакам.
Обработка событий: Обрабатывайте события quote.completed, quote.failed, job.status_changed и widget.added_to_cart с помощью идемпотентных обработчиков.

Лучшие практики для агентов

При написании интеграционного кода для Quote3D всегда учитывайте следующее:

Реализуйте асинхронный опрос для генерации расчетов. Не ожидайте немедленного возврата цены после первоначального POST.
Используйте экспоненциальную задержку или фиксированный цикл задержки 2-3 секунды при опросе /v2/jobs/{job_id}.
Сохраните оба weight &filamentWeight и вес нити в метаданных корзины или заказа, чтобы обеспечить совместимость с текущими полезными данными виджетов и плагинов.
Предпочитайте веб-хуки для производственных интеграций и делайте обработчики идемпотентными, так как возможны повторные попытки.

Краткий обзор критически важных конечных точек

Быстрый справочный индекс наиболее часто используемых конечных точек, необходимых для базовой реализации:

Загрузить файл: POST /v2/file

Начать расчет стоимости: POST /v2/file/quote/{file_id}

Проверить статус: GET /v2/jobs/{job_id}

Прочитать результат асинхронной задачи: job.result

Получить историю расчетов стоимости: GET /v2/quotes