FastTradein

API виджета Trade-in и вебхуки

Встраивание виджета, синхронизация статусов вебхуками HMAC-SHA256 и каталог на стороне FastTradein.

Быстрый старт

Вставьте виджет двумя строками HTML, затем добавьте домен магазина в список разрешенных. Скрипт обращается только к FastTradein, а не к вашей CMS.

Вставьте этот код в HTML страницы Trade-in. Замените ключ публичным ключом виджета из кабинета (страница «Виджет на сайт»).

<!-- FastTradein Widget -->
<script src="https://fasttradein.app/widget/fasttradein.js" async data-no-optimize="1" data-no-defer="1"></script>
<fasttradein-widget key="ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ" api="https://fasttradein.app" lang="ru"></fasttradein-widget>

Сниппет задает api — адрес этого хоста FastTradein. Без него виджет обращается по адресу, с которого загружен скрипт fasttradein.js.

Параметры сниппета

Параметр	Обязательный	Описание
key	Обязательный: Да	Публичный ключ магазина из «Настроек магазина» или со страницы «Виджет на сайт». С ним можно читать каталог, запрашивать оценку и отправлять заявку. Менять цены и открывать чужие магазины им нельзя.
data-key	Обязательный: Нет	Тот же публичный ключ, что и key. React и Vue резервируют key и не передают его элементу, поэтому там пишите data-key. Виджет читает сначала key, потом data-key и перезапускается, когда любой из них меняется.
lang	Обязательный: Нет	Стартовый язык интерфейса, пока клиент не переключит его сам: en, de, es, pl, ru, uk.
api	Обязательный: Нет	Origin FastTradein, например https://fasttradein.app. Оставьте его в сниппете.
currency	Обязательный: Нет	Это не HTML-атрибут. Валюта витрины (EUR, PLN, UAH, USD и другие из кабинета) берется из настроек магазина. Цены каталога хранятся в евро и пересчитываются по курсу платформы.

События для учета конверсий

Элемент отправляет событие fasttradein:quote, когда клиент получает оценку, и fasttradein:order, когда заявка отправлена. Оба всплывают и проходят сквозь shadow DOM (composed), так что слушайте их на элементе или на document. В event.detail есть device и blocked (оценка) или device и payout_method (заявка), но данных клиента там никогда нет.

Сниппеты для CMS

Инструкции для 111 платформ. Перед публикацией добавьте сайт магазина в разрешенные домены виджета.

Показано платформ: 111 из 111

WooCommerce Мировые

Страницы → страница Trade-in → блок «Произвольный HTML»: вставьте код во вкладку HTML и сохраните страницу. Для многих страниц строку <script> можно подключить в подвале темы (Внешний вид → Редактор → Паттерны → Footer) или плагином WPCode, а на страницах оставить только тег виджета.

Пошаговая инструкция для WooCommerce →

OpenCart Мировые

Дизайн → Макеты: добавьте модуль «HTML-содержимое» со сниппетом в макет страницы Trade-in. Можно и так: строку <script> подключите в catalog/view/theme/<тема>/template/common/footer.twig (OpenCart 3) или catalog/view/template/common/footer.twig (OpenCart 4), а в модуле оставьте только тег <fasttradein-widget …></fasttradein-widget>, потому что подвал выводится на каждой странице.

Пошаговая инструкция для OpenCart →

Shopify Мировые

Online Store → Edit theme: создайте шаблон страницы (Pages → Create template), добавьте в него секцию Custom Liquid с кодом и сохраните. Затем в Online Store → Pages выберите этот шаблон у страницы Trade-in. Если в теме нет секции Custom Liquid, вставьте код в шаблон страницы через редактор кода темы.

Пошаговая инструкция для Shopify →

PrestaShop Мировые

Установите бесплатный модуль FastTradein: Modules → Module Manager → Upload a module, затем Configure, и вставьте код или ключ. Напишите [fasttradein] отдельной строкой в тексте страницы в Design → Pages. PrestaShop не сохраняет <script> в содержимом страницы и вырезает тег виджета, поэтому виджет подставляет модуль при показе страницы.

Пошаговая инструкция для PrestaShop →

Magento / Adobe Commerce Мировые

Content → Elements → Blocks: создайте статический HTML-блок и выведите его через Content → Pages.

Wix Мировые

Добавить элементы → Встроенный код → Пользовательский элемент (Custom Element). Источник: Server URL = https://fasttradein.app/widget/fasttradein.js, Tag Name = fasttradein-widget. Атрибуты: data-key = ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ, api = https://fasttradein.app, lang = ru. Нужен премиум-план с подключенным доменом. Не используйте «Встроить HTML» (Embed HTML): этот код работает в iframe на другом домене, и виджет его не примет.

BigCommerce Мировые

Storefront → Script Manager для скрипта, а тег <fasttradein-widget> разместите через Page Builder (виджет HTML).

Squarespace Мировые

Откройте редактор страницы Trade-in, добавьте блок Code и вставьте сниппет. JavaScript в блоке Code работает только на тарифах Core, Plus, Advanced и Commerce, а виджет виден только на опубликованном сайте.

Shopware 6 Европа

Shopware 6.5 и более новые версии удаляют из содержимого редактора неизвестные теги и <script>. Подключите строку <script> в footer.html.twig вашей темы. Затем разрешите тег fasttradein-widget в настройках shopware.html_sanitizer (например, в config/packages/z-shopware.yaml), откройте Content → Shopping Experiences (Inhalte → Erlebniswelten), добавьте элемент Text в макет страницы Trade-in, переключите его редактор в режим HTML-кода и вставьте только тег <fasttradein-widget …></fasttradein-widget>.

Ecwid by Lightspeed Мировые

Instant Site: добавьте секцию Custom code на страницу Trade-in (тарифы Venture, Business или Unlimited). На своем сайте вставьте сниппет на страницу Trade-in рядом с кодом Ecwid.

Webflow Мировые

Add Elements → Components → Embed (HTML Embed Code) на страницу Trade-in, затем опубликуйте сайт. Нужен платный тариф Site или Workspace.

Drupal Commerce Мировые

Structure → Block layout: добавьте Custom Block с форматом Full HTML в нужный регион или Layout Builder.

Framer Мировые

Добавьте компонент Embed на холст, переключите тип на HTML и вставьте код скрипта и тег <fasttradein-widget>.

nopCommerce Мировые

Administration → Content Management → Topics (Pages): откройте страницу Trade-in и вставьте сниппет в режиме Source code.

Salesforce Commerce Cloud Мировые

Merchant Tools → Content → Content Assets: создайте HTML asset и разместите его в Page Designer.

HubSpot CMS Мировые

Content → Design Manager: создайте пользовательский модуль со сниппетом и добавьте его на страницу Trade-in, либо вставьте сниппет в режиме исходного кода модуля Rich Text.

Ghost Мировые

В редакторе страницы Trade-in добавьте карточку HTML со сниппетом. Можно и так: только строку <script> вставьте в Settings → Code injection → Site footer, а тег <fasttradein-widget …></fasttradein-widget> оставьте в карточке HTML.

Weebly Мировые

Перетащите элемент Embed Code (HTML-код) на страницу Trade-in и нажмите Edit Custom HTML.

SAP Commerce Cloud Мировые

SmartEdit: добавьте CMS-компонент типа Paragraph или Custom HTML на страницу Trade-in в каталоге WCMS.

Oracle Commerce Мировые

Design Studio: создайте Custom Widget с HTML-разметкой и поместите его в макет целевой страницы.

Square Online Мировые

Редактор сайта → Добавить секцию → Встраиваемый код (Embed code): вставьте сниппет и опубликуйте сайт. Встраиваемый код доступен на тарифах Square Online Plus и Premium.

Volusion Мировые

Design → Site Designer: добавьте блок Custom Code (HTML) со сниппетом на страницу Trade-in. Если строку <script> вы подключаете через footer_custom.html, в блоке оставьте только тег <fasttradein-widget …></fasttradein-widget>.

Shift4Shop Мировые

Content → Site Pages → Редактировать страницу: переключите редактор в HTML Source и вставьте код.

NetSuite SuiteCommerce Мировые

SuiteCommerce Advanced: добавьте CMS-блок типа Custom Content или разместите сниппет в layout-шаблоне темы.

Zoho Commerce Мировые

Settings → Visual Builder: добавьте элемент Embed code на страницу Trade-in и сохраните.

VTEX Мировые

VTEX IO / Site Editor: создайте собственный блок интерфейса или внедрите тег виджета в Store Framework layout.

Carrd Мировые

Нажмите + → Embed → Type: Code, Style: Inline, вставьте сниппет и опубликуйте сайт. Нужен тариф Pro Standard или выше.

Hostinger Мировые

Конструктор сайта → элемент Embed code, вставьте сниппет.

MODX Мировые

Вставьте сниппет на страницу Trade-in в режиме HTML или исходного кода. Если редактор удаляет скрипт, поместите скрипт в шапку или подвал сайта, а тег виджета оставьте на странице.

GoDaddy Мировые

Miva Мировые

Nuvemshop / Tiendanube Мировые

Cafe24 Мировые

SHOPLINE Мировые

thebase Мировые

Salla Мировые

Tray Commerce Мировые

Shoper Европа

Ustawienia → Zaawansowane → Bezpieczeństwo (Настройки → Дополнительно → Безопасность): включите «Wyłącz czyszczenie kodu HTML» (отключить очистку HTML-кода). Затем Wygląd i treści → Wygląd sklepu → Obecny szablon graficzny → Moduły → Moduł własny в режиме HTML: вставьте сниппет и разместите модуль на странице Trade-in.

IdoSell Европа

Sklep → Dodatki HTML/JS (дополнения HTML/JS): добавьте дополнение, в поле «Wyświetlaj na podstronach» (показывать на подстраницах) выберите «Wybranych» (выбранных) и укажите адрес страницы Trade-in, а сниппет вставьте в поле HTML-кода.

JTL-Shop Европа

В JTL-Shop 5 нет встроенного поля для кода. Подключите строку <script> через дочерний шаблон (layout/footer.tpl, блок layout-footer-js) или плагин из JTL-Store для кода в шапке и подвале, а тег <fasttradein-widget …></fasttradein-widget> вставьте на страницу Trade-in в режиме исходного HTML.

Gambio Европа

Inhalte (Контент) → Content Manager: создайте страницу Trade-in и переключите редактор в режим исходного HTML.

Sylius Европа

Подключите строку <script> в переопределенном шаблоне templates/bundles/SyliusShopBundle/layout.html.twig (шаблон @SyliusShop/layout.html.twig), а тег <fasttradein-widget …></fasttradein-widget> добавьте в шаблон страницы Trade-in.

Lightspeed eCom Европа

Settings → Web Extras → Custom JavaScript / HTML, либо вставьте код в шаблон темы.

Spryker Европа

Внедрите веб-компонент в Twig-шаблон витрины Yves или добавьте скрипт в базовый layout страницы.

Plentymarkets Европа

CMS → Контейнер: вставьте HTML-код виджета в шаблон Ceres или в блок пользовательского контента.

OXID eShop Европа

Customer Info → CMS Pages: создайте страницу Trade-in и вставьте сниппет в режиме исходного HTML. Если редактор вырезает скрипт, подключите строку <script> в базовом макете темы (OXID 6: Application/views/<тема>/tpl/layout/base.tpl; OXID 7: соответствующий Twig-шаблон), а на странице оставьте только тег <fasttradein-widget …></fasttradein-widget>.

Shoptet Европа

Внешний вид → HTML-коды либо HTML-блок на странице Trade-in.

Webnode Европа

Откройте страницу Trade-in и добавьте HTML-элемент со сниппетом.

Sky-Shop Европа

RedCart Европа

AtomStore Европа

Comarch e-Sklep Европа

Sote Европа

Selly Европа

Unas Европа

ShopRenter Европа

CloudCart Европа

MerchantPro Европа

Gomag Европа

CCV Shop Европа

Mijnwebwinkel Европа

MyOnlineStore Европа

modified eCommerce Европа

xt:Commerce Европа

Intershop Европа

TYPO3 Европа

Добавьте элемент содержимого HTML на страницу Trade-in или подключите сниппет в шаблоне сайта.

Jimdo Европа

Добавьте HTML-элемент на страницу Trade-in и вставьте сниппет.

ePages Европа

Vilkas Европа

MyCashflow Европа

DanDomain Европа

SmartWeb Европа

Abicart Европа

Starweb Европа

Jetshop Европа

Mystore Европа

VirtueMart Европа

Материал Joomla для страницы Trade-in → режим исходного кода. Если редактор вырезает скрипт, подключите его в шаблоне, а тег виджета оставьте в материале.

Odoo Европа

JouwWeb Европа

Webador Европа

Upgates Европа

EKM Европа

Visualsoft Европа

IONOS Европа

Strato Европа

Mozello Европа

Litium Европа

Medusa.js Headless

Подключите скрипт виджета в layout витрины на Next.js или Remix и добавьте веб-компонент <fasttradein-widget> на страницу Trade-in. В React и Vue передавайте ключ как data-key: оба резервируют key и не передают его элементу.

Saleor Headless

Подключите скрипт виджета в витрину (React / Next.js) и используйте веб-компонент <fasttradein-widget> в JSX-разметке. В React и Vue передавайте ключ как data-key: оба резервируют key и не передают его элементу.

Vendure Headless

Подключите скрипт виджета в layout клиентской витрины и добавьте тег <fasttradein-widget> на страницу Trade-in. В React и Vue передавайте ключ как data-key: оба резервируют key и не передают его элементу.

commercetools Headless

Подключите виджет в витрину на React, Vue или Next.js, используя веб-компонент <fasttradein-widget>. В React и Vue передавайте ключ как data-key: оба резервируют key и не передают его элементу.

Swell Headless

Внедрите скрипт виджета в layout вашей витрины на Origin / Next.js и разместите тег на странице Trade-in. В React и Vue передавайте ключ как data-key: оба резервируют key и не передают его элементу.

Strapi Headless

Встройте веб-компонент в шаблон клиентского приложения (Next.js, Nuxt, Remix), подключенного к Strapi. В React и Vue передавайте ключ как data-key: оба резервируют key и не передают его элементу.

Contentful Headless

Добавьте компонент виджета в код фронтенда, который получает контент из Contentful (Next.js / Astro / Gatsby). В React и Vue передавайте ключ как data-key: оба резервируют key и не передают его элементу.

Sanity Headless

Интегрируйте веб-компонент в блоки Portable Text или напрямую в layout страниц Next.js / Remix / Svelte. В React и Vue передавайте ключ как data-key: оба резервируют key и не передают его элементу.

Next.js Storefront Headless

Подключите скрипт через <Script src="https://fasttradein.app/widget/fasttradein.js" strategy="afterInteractive" /> из next/script в app/layout. На странице Trade-in выведите <fasttradein-widget data-key="ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ" api="https://fasttradein.app" lang="ru"></fasttradein-widget>. React резервирует key и не передает его элементу, поэтому пишите data-key. В TypeScript объявите fasttradein-widget в JSX.IntrinsicElements.

Nuxt.js Storefront Headless

Подключите скрипт через useHead({ script: [{ src: "https://fasttradein.app/widget/fasttradein.js", defer: true }] }) и отметьте тег как пользовательский элемент в nuxt.config: vue.compilerOptions.isCustomElement = (tag) => tag === "fasttradein-widget". На странице Trade-in добавьте <fasttradein-widget data-key="ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ" api="https://fasttradein.app" lang="ru"></fasttradein-widget>. Vue резервирует key и не передает его элементу, поэтому пишите data-key.

Vue Storefront Headless

Подключите скрипт виджета в макете витрины и разместите тег <fasttradein-widget> на странице Trade-in. В React и Vue передавайте ключ как data-key: оба резервируют key и не передают его элементу.

Commerce Layer Headless

Django Фреймворк

Подключите скрипт в базовом шаблоне и разместите тег <fasttradein-widget> на странице Trade-in.

Laravel Фреймворк

Подключите скрипт в Blade-макете и разместите тег <fasttradein-widget> на странице Trade-in.

Ruby on Rails Фреймворк

Подключите скрипт в общем layout и разместите тег <fasttradein-widget> на странице Trade-in.

Symfony Фреймворк

Подключите скрипт в базовом Twig-шаблоне и разместите тег <fasttradein-widget> на странице Trade-in.

Horoshop Украина

Настройки → Общие настройки → Скрипты: вставьте строку <script> в поле «перед тегом </body>» и сохраните. Затем откройте страницу Trade-in, переключите редактор описания в режим HTML-кода и вставьте тег <fasttradein-widget …></fasttradein-widget>.

Cartum Украина

OkayCMS Украина

SoloMono Украина

ImageCMS Украина

Prom.ua Украина

Prom.ua не разрешает добавлять собственные скрипты на сайт компании, поэтому виджет там не заработает. Разместите виджет на своем сайте или лендинге и поставьте ссылку на эту страницу из своего магазина на Prom.

Shop-Express Украина

Панель управления → Настройки → Пользовательские скрипты / HTML: вставьте код на страницу Trade-in.

Weblium Украина

Настройки сайта → Сторонний код (Custom code) в Head/Body, либо добавьте блок «Пользовательский код» (Embed code) на страницу Trade-in. Свой код доступен на тарифе Weblium Pro.

Безопасность и разрешенные домены

API виджета намеренно сделан публичным, но привязан к вашему магазину. Он не дает доступа к кабинету, изменению цен или данным других магазинов.

Разрешенные домены (CORS / Origin)

Это адреса сайтов, на которых может работать ваш виджет. Браузер отправляет заголовок Origin или Referer. FastTradein принимает запросы только с хостов, сохраненных в «Настройках магазина» (поле «Сайт» и список «Сайты, где работает виджет»), и с самого хоста FastTradein. Запрос с чужого сайта получает 403 Forbidden.

Публичный ключ

widgetKey в URL — публичный идентификатор. Им можно читать каталог магазина и отправлять заявку. Менять цены, выгружать данные чужих клиентов или входить в кабинет этим ключом нельзя.

Ограничение частоты запросов

Маршруты виджета принимают до 120 запросов в минуту с одного IP для каждого магазина. Для поиска лимит строже (20/мин). Для создания заявки еще строже: 10 в минуту и 10 в сутки с одного IP для каждого магазина и 8 в час на email клиента. Сверх лимита API отвечает 429.

Защита от ботов

Запрос на создание заявки содержит скрытое поле-ловушку (honeypot). Спам, который его заполняет, отсекается без создания заявки. Не отправляйте из собственного клиентского приложения лишние неизвестные поля.

REST API витрины

Базовый путь: /api/widget/{widgetKey}. Это тот же публичный интерфейс, которым пользуется скрипт витрины. Маршруты кабинета и администратора платформы в этот контракт не входят.

Язык каталога, текстов виджета и сумм для показа задается параметром ?locale=ru. Поля formatted_amount и max_buyback_formatted содержат готовую строку для клиента: сумму, округленную до целых, с символом валюты и разделителем разрядов, например «1 235 €». Вид строки зависит от языка и валюты. Для расчетов берите числа в минимальных единицах валюты, для евро это центы: max_buyback и quoted_amount_cents. Например, quoted_amount_cents = 123456 означает 1234,56 евро.

GET /api/widget/{widgetKey}

Конфигурация витрины

Возвращает название магазина, цвета, валюту, локаль, включенные категории, способы выплаты и тексты виджета.

Пример cURL

curl -sS "https://fasttradein.app/api/widget/ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ?locale=ru" \
  -H "Origin: https://shop.example" \
  -H "Accept: application/json"

Пример ответа 200 OK

{
    "tenant": {
        "name": "Your Store",
        "currency": "EUR",
        "locale": "ru",
        "primary_color": "#1f3a8a",
        "logo_url": null
    },
    "locale": "ru",
    "accepting_orders": true,
    "payout_methods": [
        {
            "value": "bank_transfer",
            "label": "Банковский перевод"
        },
        {
            "value": "store_credit",
            "label": "Зачет в счет покупки в магазине"
        }
    ],
    "categories": [
        {
            "id": 1,
            "slug": "smartphones",
            "name": "Смартфоны"
        }
    ],
    "catalog_version": "3f9a1c0b7e"
}

GET /api/widget/{widgetKey}/search?q=iPhone+13

Поиск моделей

Ищет модели по названию. Если q короче двух символов, в ответе до 6 популярных моделей с "popular": true. Для каждой модели указана текущая максимальная сумма выкупа в этом магазине. В выдаче не больше 8 результатов. Скрытые варианты не попадают в поиск.

Пример cURL

curl -sS "https://fasttradein.app/api/widget/ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ/search?q=iPhone+13" \
  -H "Origin: https://shop.example" \
  -H "Accept: application/json"

Пример ответа 200 OK

{
    "results": [
        {
            "model_id": 42,
            "name": "iPhone 13",
            "brand": "Apple",
            "max_buyback": 42000,
            "max_buyback_formatted": "420 €"
        }
    ]
}

POST /api/widget/{widgetKey}/orders

Отправка заявки на выкуп

Заявка из виджета или вашего собственного приложения. POST без заголовка Origin или Referer получает 403, поэтому сервер или приложение должны отправлять Origin: https://<ваш разрешенный домен>. Сначала соберите variant_id и answer_ids. Успех — HTTP 201 с полем order_number.

JSON-тело

Поле	Обязательный	Описание
variant_id	Обязательный: Да	Активный вариант из каталога.
answer_ids	Обязательный: Да	ID ответов опросника категории. На вопрос один ответ; на вопрос с multiple: true можно несколько, а ответ с exclusive: true передается без других ответов на этот вопрос.
customer_name	Обязательный: Да	Имя клиента.
customer_email	Обязательный: Да	Email клиента.
customer_phone	Обязательный: Нет	Телефон, необязательно.
payout_method	Обязательный: Нет	bank_transfer или store_credit; store_voucher, если магазин включил выплату сертификатом. Без этого поля заявка получает bank_transfer.

Пример cURL

curl -sS -X POST "https://fasttradein.app/api/widget/ВАШ_ПУБЛИЧНЫЙ_КЛЮЧ/orders" \
  -H "Origin: https://shop.example" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"variant_id":101,"answer_ids":[11,24],"customer_name":"Ada Lovelace","customer_email":"ada@example.com","customer_phone":"+49 170 000000","payout_method":"bank_transfer"}'

Замените https://shop.example на один из разрешенных доменов виджета.

Пример ответа 201 Created

{
    "order_number": "TF-8PGPFFNLM6",
    "quoted_amount_cents": 38000,
    "formatted_amount": "380 €",
    "currency": "EUR",
    "status": "submitted"
}

Другие публичные маршруты виджета

Нужны, чтобы собрать variant_id и answer_ids до POST /orders. Тот же ключ, те же правила CORS.

GET /api/widget/{widgetKey}/catalog/{category} Бренды, модели и объемы памяти категории (id или slug).
GET /api/widget/{widgetKey}/questionnaire/{category} Группы чек-листа, вопросы и ID ответов этой категории. Флаг multiple отмечает вопрос с несколькими ответами, флаг exclusive отмечает ответ, который не сочетается с другими.
POST /api/widget/{widgetKey}/quotes Расчет цены по варианту и ответам до создания заявки. JSON: variant_id, answer_ids.

Вебхуки

Вебхуки доступны на тарифах Business и Pro. В кабинете откройте «Настройки» → «Заявки в CRM», укажите HTTPS URL и сгенерируйте секретный ключ. После этого FastTradein отправляет туда JSON о событиях ниже, так что можно синхронизировать любую CRM или ERP.

События

order.created Клиент оформил заявку на сайте.
order.received Магазин отметил, что устройство поступило на склад.
order.counter_offered После проверки на складе сумма изменилась. Клиенту отправлена защищенная ссылка на новое предложение.
order.paid Магазин отметил заявку как выплаченную.
order.accepted Клиент принял новую цену после проверки.
order.declined Заявка завершилась без сделки: клиент отклонил новую цену, устройство оказалось заблокированным при проверке или магазин отказал в приемке. data.status — declined или cancelled.

Полезная нагрузка JSON

Тело — компактный JSON без экранирования слешей и Unicode. HMAC-SHA256 считайте по этим байтам как есть. order_number — строка вида TF-8PGPFFNLM6, event_id — evt_ и UUID. Поля voucher_* заполняются для заявок с сертификатом магазина после его выпуска, иначе в них null.

{
  "event": "order.created",
  "event_id": "evt_c800a9c7-b11c-4b75-810e-e667544d825d",
  "timestamp": 1788550000,
  "tenant_id": 12,
  "data": {
    "order_number": "TF-8PGPFFNLM6",
    "status": "submitted",
    "currency": "EUR",
    "quoted_amount_cents": 38000,
    "inspected_amount_cents": null,
    "final_amount_cents": null,
    "device": "Apple iPhone 13 128GB",
    "customer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "phone": "+49 170 000000"
    },
    "parcel_tracking_number": null,
    "payout_method": "bank_transfer",
    "voucher_code": null,
    "voucher_amount_cents": null,
    "voucher_url": null,
    "voucher_expires_at": null
  }
}

Заголовки

X-FastTradein-Event: имя события, то же, что payload.event.
X-FastTradein-Signature: HMAC-SHA256, HMAC сырого тела с префиксом sha256=.
User-Agent: FastTradein-Webhook/1.0

Отвечайте любым статусом 2xx в течение 10 секунд. Другой статус, тайм-аут или редирект считаются сбоем, и мы повторяем запрос дважды, через 10 и через 60 секунд, с тем же event_id и подписью. Редиректы не выполняются, поэтому сохраняйте конечный адрес https. По event_id отбрасывайте дубликаты.

Проверка подписи HMAC-SHA256

Посчитайте HMAC-SHA256 сырого POST-тела секретом из кабинета. Сравните результат с X-FastTradein-Signature за постоянное время (constant-time). Значение заголовка начинается с sha256=.

PHP

$signature = $_SERVER['HTTP_X_FASTTRADEIN_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');
$expected = 'sha256='.hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

Node.js

const crypto = require('crypto');
const express = require('express');
const app = express();

// express.raw keeps the exact POST bytes; JSON.stringify(req.body) would not match the signature.
app.post('/fasttradein-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = String(req.get('X-FastTradein-Signature') || '');
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.FASTTRADEIN_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  if (
    signature.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  ) {
    return res.status(401).end('Invalid signature');
  }
  const event = JSON.parse(req.body.toString('utf8'));
  // Skip an event_id you have already processed: a retry sends the same one.
  res.status(200).end();
});

Коды ответов

Код	Описание
200	OK. GET возвращает конфигурацию, результаты поиска, каталог и опросник, а POST /quotes возвращает расчет.
201	Created. POST /orders прошел; номер заявки в поле order_number.
402	Магазин сейчас не принимает новые заявки виджета: пробный период закончился или подписка отменена (TENANT_BILLING_INACTIVE), либо месячный лимит заявок исчерпан (TENANT_LIMIT_EXCEEDED).
403	Домен не разрешен: Origin / Referer нет среди разрешенных доменов магазина (ошибка WIDGET_DOMAIN_DENIED), или POST пришел без обоих заголовков.
404	Ключ виджета (ошибка WIDGET_NOT_FOUND), категория или номер заявки не найдены.
422	Ошибка валидации: нет ответов, неактивный вариант или выключенная категория.
429	Too Many Requests. Снизьте частоту запросов и повторите попытку.