FastTradein

API y webhooks del widget de trade-in

Incruste el widget, sincronice estados con webhooks HMAC-SHA256 y mantenga el catálogo en FastTradein.

Inicio rápido

Integre el widget con dos líneas de HTML y añada después el dominio de la tienda a la lista de dominios permitidos. El script se comunica solo con FastTradein, no con su CMS.

Pegue el fragmento en el HTML de la página de trade-in. Sustituya la clave por la clave pública del widget, que encontrará en el panel.

<!-- FastTradein Widget -->
<script src="https://fasttradein.app/widget/fasttradein.js" async data-no-optimize="1" data-no-defer="1"></script>
<fasttradein-widget key="SU_CLAVE_PUBLICA" api="https://fasttradein.app" lang="es"></fasttradein-widget>

El snippet fija api en este host de FastTradein. Sin este atributo, el widget usa la dirección desde la que se cargó el script fasttradein.js.

Parámetros del snippet

Parámetro	Obligatorio	Significado
key	Obligatorio: Sí	Clave pública de la tienda, en «Configuración de la tienda» o en la página «Incrustación del widget». Puede leer el catálogo, pedir una valoración y enviar una solicitud de trade-in. No permite cambiar precios ni acceder a otras tiendas.
data-key	Obligatorio: No	La misma clave pública que key. React y Vue se reservan key y no la pasan al elemento, así que allí use data-key. El widget lee primero key y después data-key, y se reinicia cuando cambia cualquiera de los dos.
lang	Obligatorio: No	Idioma inicial de la interfaz hasta que el cliente lo cambie: en, de, es, pl, ru, uk.
api	Obligatorio: No	Origin de FastTradein, por ejemplo, https://fasttradein.app. Manténgalo en el snippet.
currency	Obligatorio: No	No es un atributo HTML. La moneda de la tienda online (EUR, PLN, UAH, USD y otras disponibles en el panel) se toma de los ajustes de la tienda. El catálogo se queda en euros y se convierte al tipo de cambio de la plataforma.

Eventos para medir conversiones

El elemento lanza fasttradein:quote cuando el cliente recibe una valoración y fasttradein:order cuando se envía una solicitud. Ambos se propagan hacia arriba y atraviesan el shadow DOM (composed), así que puede escucharlos en el elemento o en document. event.detail incluye device y blocked (valoración) o device y payout_method (solicitud), nunca datos del cliente.

Snippets de CMS

Instrucciones para 111 plataformas. Antes de publicar, añada el dominio de la tienda a la lista «Webs donde funciona el widget».

Mostrando plataformas: 111 de 111

WooCommerce Globales

Páginas → página de trade-in → bloque «HTML personalizado»: pegue el código en la pestaña HTML y guarde la página. Si necesita el widget en muchas páginas, cargue la línea <script> en el pie del tema (Apariencia → Editor → Patrones → Footer) o con el plugin WPCode y deje en las páginas solo la etiqueta del widget.

Guía paso a paso para WooCommerce →

OpenCart Globales

Design → Layouts → añada el módulo HTML Content con el snippet a la disposición de la página de trade-in. Si prefiere cargar el script en todo el sitio, pegue solo la línea <script> en catalog/view/theme/<tema>/template/common/footer.twig (OpenCart 3) o catalog/view/template/common/footer.twig (OpenCart 4) y deje en el módulo solo la etiqueta <fasttradein-widget …></fasttradein-widget>.

Guía paso a paso para OpenCart →

Shopify Globales

Tienda online → Editar tema: cree una plantilla de página (Páginas → Crear plantilla), añada una sección Liquid personalizado (Custom Liquid) con el código y guarde. Después, en Tienda online → Páginas, elija esa plantilla para la página de trade-in. Si su tema no tiene esa sección, pegue el código en la plantilla de la página desde el editor de código del tema.

Guía paso a paso para Shopify →

PrestaShop Globales

Instale el módulo gratuito de FastTradein: Módulos → Gestor de módulo → Subir un módulo, luego Configurar, y pegue el código o la clave. Escriba [fasttradein] en una línea aparte en el contenido de una página en Diseño → Páginas. PrestaShop no guarda <script> en el contenido de la página y elimina la etiqueta del widget, por eso el módulo coloca el widget al mostrar la página.

Guía paso a paso para PrestaShop →

Magento / Adobe Commerce Globales

Content → Elements → Blocks → Cree un bloque HTML estático y muéstrelo en Content → Pages.

Wix Globales

Añadir elementos → Insertar código → Elemento personalizado (Custom Element). Origen: Server URL = https://fasttradein.app/widget/fasttradein.js, Tag Name = fasttradein-widget. Atributos: data-key = SU_CLAVE_PUBLICA, api = https://fasttradein.app, lang = es. Requiere un plan Premium con dominio conectado. No use «Insertar HTML» (Embed HTML): ese código se ejecuta en un iframe de otro dominio y el widget lo rechaza.

BigCommerce Globales

Storefront → Script Manager para el script, y coloque la etiqueta <fasttradein-widget> con Page Builder (widget HTML).

Squarespace Globales

Edite la página de trade-in → añada un bloque Code y pegue el snippet. Los bloques Code solo ejecutan JavaScript en los planes Core, Plus, Advanced o Commerce, y el widget solo se ve en el sitio publicado.

Shopware 6 Europa

Shopware 6.5 y posteriores eliminan <script> y las etiquetas desconocidas del contenido del editor. Cargue la línea <script> en footer.html.twig de su tema. Después permita la etiqueta fasttradein-widget en los ajustes de shopware.html_sanitizer (por ejemplo, en config/packages/z-shopware.yaml), abra Content → Shopping Experiences, añada un elemento de texto al diseño de la página de trade-in, cambie su editor a la vista de código HTML y pegue solo la etiqueta <fasttradein-widget …></fasttradein-widget>.

Ecwid by Lightspeed Globales

Instant Site: añada una sección de código personalizado (Custom code) en la página de trade-in (planes Venture, Business o Unlimited). En su propia web, pegue el snippet en la página de trade-in junto al código de Ecwid.

Webflow Globales

Add Elements → Components → Embed (HTML Embed Code) en la página de trade-in y publique el sitio. Los Code Embed requieren un plan de pago Site o Workspace.

Drupal Commerce Globales

Structure → Block layout → Añada un Custom Block con formato Full HTML en la región deseada o en Layout Builder.

Framer Globales

Añada el componente Embed en el lienzo, ponga el tipo HTML y pegue el script y la etiqueta <fasttradein-widget>.

nopCommerce Globales

Administration → Content Management → Topics (Pages) → Abra la página Trade-in y pegue el snippet en modo Source code.

Salesforce Commerce Cloud Globales

Merchant Tools → Content → Content Assets → Cree un asset HTML y colóquelo en Page Designer.

HubSpot CMS Globales

Content → Design Manager → cree un módulo personalizado con el snippet y añádalo a la página de trade-in, o pegue el snippet en la vista de código fuente de un módulo de texto enriquecido (rich text).

Ghost Globales

Añada una tarjeta HTML con el snippet en la página de trade-in. Si prefiere cargar el script en todo el sitio, pegue solo la línea <script> en Settings → Code injection (Site Footer) y deje en la tarjeta solo la etiqueta <fasttradein-widget …></fasttradein-widget>.

Weebly Globales

Arrastre el elemento Embed Code (HTML) a la página Trade-in y pulse Edit Custom HTML.

SAP Commerce Cloud Globales

SmartEdit → Añada un componente CMS (Paragraph o Custom HTML) en la página Trade-in dentro de WCMS.

Oracle Commerce Globales

Design Studio → Cree un widget personalizado con el snippet HTML y colóquelo en el layout de la página.

Square Online Globales

Editor del sitio → Añadir sección → Código incrustado → pegue el snippet y publique el sitio. Requiere Square Online Plus o Premium.

Volusion Globales

Design → Site Designer → añada un bloque Custom Code (HTML) con el snippet en la página de trade-in. Si carga la línea <script> mediante footer_custom.html, deje en el bloque solo la etiqueta <fasttradein-widget …></fasttradein-widget>.

Shift4Shop Globales

Content → Site Pages → Editar página → Cambie el editor al modo fuente HTML e inserte el snippet.

NetSuite SuiteCommerce Globales

SuiteCommerce Advanced → Añada un bloque CMS Custom Content o coloque el snippet en la plantilla de layout del tema.

Zoho Commerce Globales

Ajustes → Visual Builder → Añada el elemento Embed code en la página Trade-in y guarde los cambios.

VTEX Globales

VTEX IO → Cree una app/bloque personalizado o use el componente web del widget en el layout de Store Framework.

Carrd Globales

Pulse + → Embed → ponga Type en Code y Style en Inline, pegue el snippet y publique. Los Embed requieren Carrd Pro Standard o un plan superior.

Hostinger Globales

Creador de sitios → añada un elemento de código incrustado (Embed code) y pegue el snippet.

MODX Globales

Pegue el snippet en la página de trade-in en modo HTML o código fuente. Si el editor elimina el script, ponga el script en la cabecera o el pie del sitio y deje la etiqueta del widget en la página.

GoDaddy Globales

Miva Globales

Nuvemshop / Tiendanube Globales

Cafe24 Globales

SHOPLINE Globales

thebase Globales

Salla Globales

Tray Commerce Globales

Shoper Europa

Ustawienia → Zaawansowane → Bezpieczeństwo (Ajustes → Avanzado → Seguridad): active «Wyłącz czyszczenie kodu HTML» (desactivar la limpieza del código HTML). Después Wygląd i treści → Wygląd sklepu → Obecny szablon graficzny → Moduły → Moduł własny en modo HTML: pegue el snippet y coloque el módulo en la página de trade-in.

IdoSell Europa

Sklep → Dodatki HTML/JS (complementos HTML/JS) → añada un complemento, en «Wyświetlaj na podstronach» (mostrar en subpáginas) elija «Wybranych» (seleccionadas) e indique la dirección de la página de trade-in, y pegue el snippet en el campo de código HTML.

JTL-Shop Europa

JTL-Shop 5 no tiene un campo propio para código: cargue la línea <script> desde su plantilla hija (layout/footer.tpl, bloque layout-footer-js) o con un plugin de código para cabecera y pie del JTL-Store, y ponga la etiqueta <fasttradein-widget …></fasttradein-widget> en la página de trade-in en modo de código HTML.

Gambio Europa

Inhalte (Contenido) → Content Manager → cree la página de trade-in y cambie el editor al modo de código fuente HTML.

Sylius Europa

Cargue la línea <script> sobrescribiendo la plantilla de la tienda online en templates/bundles/SyliusShopBundle/layout.html.twig (@SyliusShop/layout.html.twig) y coloque la etiqueta <fasttradein-widget …></fasttradein-widget> en la plantilla de la página de trade-in.

Lightspeed eCom Europa

Settings → Web Extras → Custom JavaScript / HTML, o pegue el código en la plantilla del tema.

Spryker Europa

Incruste el componente web en la plantilla Twig de su tienda online Yves o añada el script en el layout base.

Plentymarkets Europa

CMS → Contenedor → Inserte el código HTML del widget en la plantilla Ceres o en un bloque personalizado.

OXID eShop Europa

Customer Info → CMS Pages: cree la página de trade-in y pegue el snippet en modo de código fuente HTML. Si el editor quita el script, cargue la línea <script> en el layout base de su tema (OXID 6: Application/views/<tema>/tpl/layout/base.tpl; OXID 7: la plantilla Twig equivalente) y deje en la página solo la etiqueta <fasttradein-widget …></fasttradein-widget>.

Shoptet Europa

Apariencia → códigos HTML, o un bloque HTML en la página de trade-in.

Webnode Europa

Abra la página de trade-in y añada un elemento HTML con el snippet.

Sky-Shop Europa

RedCart Europa

AtomStore Europa

Comarch e-Sklep Europa

Sote Europa

Selly Europa

Unas Europa

ShopRenter Europa

CloudCart Europa

MerchantPro Europa

Gomag Europa

CCV Shop Europa

Mijnwebwinkel Europa

MyOnlineStore Europa

modified eCommerce Europa

xt:Commerce Europa

Intershop Europa

TYPO3 Europa

Añada un elemento de contenido HTML en la página de trade-in, o incluya el snippet en la plantilla del sitio.

Jimdo Europa

Añada un elemento HTML en la página de trade-in y pegue el snippet.

ePages Europa

Vilkas Europa

MyCashflow Europa

DanDomain Europa

SmartWeb Europa

Abicart Europa

Starweb Europa

Jetshop Europa

Mystore Europa

VirtueMart Europa

Artículo de Joomla de la página de trade-in → modo código fuente. Si el editor quita el script, cárguelo en la plantilla y deje la etiqueta del widget en el artículo.

Odoo Europa

JouwWeb Europa

Webador Europa

Upgates Europa

EKM Europa

Visualsoft Europa

IONOS Europa

Strato Europa

Mozello Europa

Litium Europa

Medusa.js Headless

Cargue el script del widget en el layout de la tienda online (Next.js o Remix) y añada el componente web <fasttradein-widget> en la página de trade-in. En React y Vue, pase la clave como data-key: ambos se reservan key y no la pasan al elemento.

Saleor Headless

Cargue el script del widget en la tienda online (React / Next.js) y use el componente web <fasttradein-widget> en JSX. En React y Vue, pase la clave como data-key: ambos se reservan key y no la pasan al elemento.

Vendure Headless

Cargue el script del widget en el layout de la tienda online y añada la etiqueta <fasttradein-widget> en la página Trade-in. En React y Vue, pase la clave como data-key: ambos se reservan key y no la pasan al elemento.

commercetools Headless

Incluya el script del widget en su tienda online en React, Vue o Next.js y use la etiqueta <fasttradein-widget>. En React y Vue, pase la clave como data-key: ambos se reservan key y no la pasan al elemento.

Swell Headless

Añada el script del widget al layout de su tienda online Swell y coloque la etiqueta en la página Trade-in. En React y Vue, pase la clave como data-key: ambos se reservan key y no la pasan al elemento.

Strapi Headless

Use el componente web en el frontend (Next.js, Nuxt, Remix) que consume la API de Strapi. En React y Vue, pase la clave como data-key: ambos se reservan key y no la pasan al elemento.

Contentful Headless

Coloque el componente del widget en el cliente frontend (Next.js, Astro, Gatsby) conectado a Contentful. En React y Vue, pase la clave como data-key: ambos se reservan key y no la pasan al elemento.

Sanity Headless

Integre el componente web directamente en el layout Next.js / Remix o en sus bloques de Portable Text. En React y Vue, pase la clave como data-key: ambos se reservan key y no la pasan al elemento.

Next.js Storefront Headless

Cargue el script con <Script src="https://fasttradein.app/widget/fasttradein.js" strategy="afterInteractive" /> de next/script en app/layout. En la página de trade-in muestre <fasttradein-widget data-key="SU_CLAVE_PUBLICA" api="https://fasttradein.app" lang="es"></fasttradein-widget>. React se reserva key y no la pasa al elemento, así que use data-key. En TypeScript, declare fasttradein-widget en JSX.IntrinsicElements.

Nuxt.js Storefront Headless

Cargue el script con useHead({ script: [{ src: "https://fasttradein.app/widget/fasttradein.js", defer: true }] }) y marque la etiqueta como elemento personalizado en nuxt.config: vue.compilerOptions.isCustomElement = (tag) => tag === "fasttradein-widget". En la página de trade-in añada <fasttradein-widget data-key="SU_CLAVE_PUBLICA" api="https://fasttradein.app" lang="es"></fasttradein-widget>. Vue se reserva key y no la pasa al elemento, así que use data-key.

Vue Storefront Headless

Cargue el script del widget en el layout de la tienda y coloque la etiqueta <fasttradein-widget> en la página de trade-in. En React y Vue, pase la clave como data-key: ambos se reservan key y no la pasan al elemento.

Commerce Layer Headless

Django Framework

Añada el script en la plantilla base y coloque la etiqueta <fasttradein-widget> en la página de trade-in.

Laravel Framework

Añada el script en el layout Blade y coloque la etiqueta <fasttradein-widget> en la vista de trade-in.

Ruby on Rails Framework

Añada el script en el application layout y coloque la etiqueta <fasttradein-widget> en la vista de trade-in.

Symfony Framework

Añada el script en la plantilla base de Twig y coloque la etiqueta <fasttradein-widget> en la plantilla de trade-in.

Horoshop Ucrania

Settings → General settings → Scripts: pegue la línea <script> en el campo «before the </body> tag» y guarde. Después abra la página de trade-in, cambie el editor de la descripción a código HTML y pegue la etiqueta <fasttradein-widget …></fasttradein-widget>.

Cartum Ucrania

OkayCMS Ucrania

SoloMono Ucrania

ImageCMS Ucrania

Prom.ua Ucrania

Prom.ua no permite añadir scripts propios al sitio de la empresa, así que el widget no funciona allí. Ponga el widget en su propia web o landing page y enlace esa página desde su tienda de Prom.

Shop-Express Ucrania

Panel de control → Ajustes → Scripts / HTML personalizados → Pegue el código en la página Trade-in.

Weblium Ucrania

Ajustes del sitio → Código personalizado en Head/Body, o añada un bloque Código incrustado (Embed code) en la página de trade-in. El código personalizado requiere el plan Pro de Weblium.

Seguridad y dominios permitidos

La API del widget es pública a propósito, pero está vinculada a su tienda. No da acceso al panel, a la edición de precios ni a los datos de otras tiendas.

Dominios permitidos (CORS / Origin)

Son las direcciones de los sitios donde puede funcionar su widget. El navegador envía Origin o Referer. FastTradein solo admite los dominios guardados en «Configuración de la tienda» (el campo «Sitio web» y la lista «Webs donde funciona el widget»), más este host de FastTradein. Una petición desde un sitio ajeno recibe 403 Forbidden.

Clave pública del widget

El parámetro widgetKey de la URL es un identificador público. Sirve para leer el catálogo de la tienda y enviar una solicitud de trade-in. No permite cambiar precios, exportar clientes ajenos ni abrir el panel.

Límites de peticiones

Las rutas del widget admiten hasta 120 peticiones por minuto por IP para cada tienda. La búsqueda es más estricta (20/min). Crear una solicitud, todavía más: 10 por minuto y 10 al día por IP para cada tienda, y 8 por hora por email del cliente. Por encima del límite la API responde 429.

Protección frente a bots

La creación de una solicitud incluye un campo honeypot oculto. El spam que lo rellena se descarta sin crear ninguna solicitud. Desde un cliente propio no envíe campos extra desconocidos.

API REST de la tienda online

Ruta base: /api/widget/{widgetKey}. Es la misma superficie pública que usa el script de la tienda online. Las rutas del panel y del admin de plataforma no forman parte de este contrato.

El idioma del catálogo, de los textos del widget y de los importes para mostrar se pasa con ?locale=es. Los campos formatted_amount y max_buyback_formatted son textos listos para el cliente: el importe redondeado a unidades enteras, con el símbolo de la moneda y separador de miles, por ejemplo, «1 235 €». Su aspecto depende del idioma y de la moneda. Para cálculos use los números en la unidad mínima de la moneda, céntimos en el caso del euro: max_buyback y quoted_amount_cents. Por ejemplo, quoted_amount_cents = 123456 significa 1234,56 euros.

GET /api/widget/{widgetKey}

Configuración de la tienda

Devuelve nombre, colores, moneda, locale, categorías activas, métodos de pago y textos del widget.

Ejemplo con cURL

curl -sS "https://fasttradein.app/api/widget/SU_CLAVE_PUBLICA?locale=es" \
  -H "Origin: https://shop.example" \
  -H "Accept: application/json"

Ejemplo de respuesta 200 OK

{
    "tenant": {
        "name": "Your Store",
        "currency": "EUR",
        "locale": "es",
        "primary_color": "#1f3a8a",
        "logo_url": null
    },
    "locale": "es",
    "accepting_orders": true,
    "payout_methods": [
        {
            "value": "bank_transfer",
            "label": "Transferencia bancaria"
        },
        {
            "value": "store_credit",
            "label": "Saldo para una compra en la tienda"
        }
    ],
    "categories": [
        {
            "id": 1,
            "slug": "smartphones",
            "name": "Móviles"
        }
    ],
    "catalog_version": "3f9a1c0b7e"
}

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

Búsqueda de modelos

Busca modelos por nombre. Si q tiene menos de 2 caracteres, la respuesta incluye hasta 6 modelos populares con "popular": true. Los resultados incluyen el máximo de recompra actual de esa tienda. Devuelve como máximo 8 coincidencias. Las variantes ocultas no se muestran.

Ejemplo con cURL

curl -sS "https://fasttradein.app/api/widget/SU_CLAVE_PUBLICA/search?q=iPhone+13" \
  -H "Origin: https://shop.example" \
  -H "Accept: application/json"

Ejemplo de respuesta 200 OK

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

POST /api/widget/{widgetKey}/orders

Enviar una solicitud de trade-in

Crea una solicitud de trade-in desde el widget o desde su propio cliente. Un POST sin cabecera Origin ni Referer se rechaza con 403, así que un servidor o una app debe enviar Origin: https://<un dominio de su lista de dominios permitidos>. Primero reúna variant_id y answer_ids. Si la petición tiene éxito, la respuesta es HTTP 201 con order_number.

Cuerpo JSON

Campo	Obligatorio	Significado
variant_id	Obligatorio: Sí	Variante activa del catálogo.
answer_ids	Obligatorio: Sí	ID de respuestas del cuestionario de la categoría. Una respuesta por pregunta; una pregunta con multiple: true admite varias y una respuesta con exclusive: true va sola.
customer_name	Obligatorio: Sí	Nombre del cliente.
customer_email	Obligatorio: Sí	Email del cliente.
customer_phone	Obligatorio: No	Teléfono, opcional.
payout_method	Obligatorio: No	bank_transfer o store_credit; store_voucher si la tienda tiene activados los vales de tienda. Sin este campo, la solicitud recibe bank_transfer.

Ejemplo con cURL

curl -sS -X POST "https://fasttradein.app/api/widget/SU_CLAVE_PUBLICA/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"}'

Sustituya https://shop.example por un dominio de la lista «Webs donde funciona el widget».

Ejemplo de respuesta 201 Created

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

Otras rutas públicas del widget

Hacen falta para reunir variant_id y answer_ids antes de POST /orders. Misma clave, mismas reglas CORS.

GET /api/widget/{widgetKey}/catalog/{category} Marcas, modelos y capacidades de almacenamiento de una categoría (id o slug).
GET /api/widget/{widgetKey}/questionnaire/{category} Grupos de la lista de comprobación, preguntas e ID de respuesta de esa categoría. multiple marca una pregunta que admite varias respuestas, exclusive una respuesta que va sola.
POST /api/widget/{widgetKey}/quotes Tasa la variante con las respuestas elegidas antes de crear la solicitud. JSON: variant_id, answer_ids.

Webhooks

Los webhooks están disponibles en los planes Business y Pro. En el panel abra «Configuración» → «Solicitudes al CRM», indique su URL HTTPS y genere la clave secreta. Después FastTradein envía allí JSON con los eventos de abajo, así que puede sincronizar cualquier CRM o ERP.

Eventos

order.created El cliente ha enviado una solicitud desde el widget.
order.received La tienda ha marcado el dispositivo como recibido en el almacén.
order.counter_offered La revisión en el almacén ha cambiado el pago. El cliente ha recibido un enlace de oferta protegido.
order.paid La tienda ha marcado la solicitud como pagada.
order.accepted El cliente ha aceptado el nuevo precio tras la revisión.
order.declined La solicitud ha terminado sin acuerdo: el cliente ha rechazado el nuevo precio, el dispositivo estaba bloqueado en la revisión o la tienda lo ha rechazado en la recepción. data.status es declined o cancelled.

Payload JSON

El cuerpo es JSON compacto, sin escape de barras ni Unicode. Calcule HMAC-SHA256 sobre esos bytes tal cual. order_number es una cadena como TF-8PGPFFNLM6 y event_id es evt_ seguido de un UUID. Los campos voucher_* se rellenan en las solicitudes con vale de la tienda cuando se emite el vale; si no, son 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
  }
}

Cabeceras

X-FastTradein-Event: nombre del evento, igual que payload.event.
X-FastTradein-Signature: HMAC-SHA256, HMAC del cuerpo crudo con prefijo sha256=.
User-Agent: FastTradein-Webhook/1.0

Responda con cualquier estado 2xx en menos de 10 segundos. Cualquier otro estado, un tiempo de espera agotado o una redirección cuenta como fallo, y reintentamos dos veces, a los 10 y a los 60 segundos, con el mismo event_id y la misma firma. No seguimos redirecciones, así que guarde la dirección https final. Use event_id para descartar duplicados.

Verificar HMAC-SHA256

Calcule HMAC-SHA256 del cuerpo POST crudo con el secreto del panel. Compare con X-FastTradein-Signature en tiempo constante. El valor de la cabecera empieza por 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();
});

Códigos de respuesta

Código	Significado
200	OK. GET devuelve la configuración, los resultados de búsqueda, el catálogo y el cuestionario; POST /quotes devuelve la valoración.
201	Created. POST /orders correcto; el número de solicitud está en order_number.
402	La tienda no acepta ahora nuevas solicitudes del widget: ha terminado la prueba o la suscripción está cancelada (TENANT_BILLING_INACTIVE), o se ha agotado el límite mensual de solicitudes (TENANT_LIMIT_EXCEEDED).
403	Dominio no permitido: Origin / Referer no está en la lista de dominios permitidos de la tienda (error WIDGET_DOMAIN_DENIED), o un POST ha llegado sin ninguna de las dos cabeceras.
404	Clave de widget desconocida (error WIDGET_NOT_FOUND), o categoría o número de solicitud desconocidos.
422	Error de validación: faltan respuestas, variante inactiva o categoría desactivada.
429	Límite de peticiones superado. Baje la frecuencia y reintente.