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="uk"></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 Світові

Design → Layouts: додайте модуль HTML Content зі сніпетом у макет сторінки 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 = uk. Потрібен тариф Premium із підключеним доменом. Не використовуйте «Вбудувати 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), відкрийте Вміст → Erlebniswelten (Shopping Experiences), додайте елемент «Текст» у макет сторінки Trade-in, перемкніть його редактор у режим HTML-коду й вставте лише тег <fasttradein-widget …></fasttradein-widget>.

Ecwid by Lightspeed Світові

Instant Site: додайте на сторінку Trade-in секцію Custom code (тарифи 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-ресурс (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 або розмістіть сніпет у шаблоні макета теми.

Zoho Commerce Світові

Settings → Visual Builder → додайте елемент Embed code на сторінку Trade-in і збережіть.

VTEX Світові

VTEX IO / Site Editor → створіть власний блок інтерфейсу або додайте тег віджета в макет Store Framework.

Carrd Світові

Натисніть + → Embed → встановіть Type: Code і Style: Inline, вставте сніпет і опублікуйте. Вбудовування потребує тарифу Carrd 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) або плагін для коду в header і footer із JTL-Store, а тег <fasttradein-widget …></fasttradein-widget> вставте на сторінку Trade-in у режимі вихідного HTML.

Gambio Європа

Inhalte (Вміст) → Content Manager: створіть сторінку Trade-in і перемкніть редактор у режим вихідного HTML.

Sylius Європа

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

Lightspeed eCom Європа

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

Spryker Європа

Вбудуйте вебкомпонент у Twig-шаблон вітрини Yves або додайте скрипт у базовий макет сторінки.

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

Підключіть скрипт віджета в макет вітрини на 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

Підключіть скрипт віджета в макет клієнтської вітрини й додайте тег <fasttradein-widget> на сторінку Trade-in. У React і Vue передавайте ключ як data-key: обидва фреймворки резервують key і не передають його елементу.

commercetools Headless

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

Swell Headless

Додайте скрипт віджета в макет вашої вітрини на 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 або напряму в макет сторінок 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="uk"></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="uk"></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=uk. Поля 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=uk" \
  -H "Origin: https://shop.example" \
  -H "Accept: application/json"

Приклад відповіді 200 OK

{
    "tenant": {
        "name": "Your Store",
        "currency": "EUR",
        "locale": "uk",
        "primary_color": "#1f3a8a",
        "logo_url": null
    },
    "locale": "uk",
    "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

Створення заявки на викуп

Заявка з віджета або з вашого власного застосунку (API-клієнта). 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	Перевищено ліміт запитів. Зменшіть частоту й повторіть спробу.