Brancher un formulaire sur l'API de leads de WonTrail

Pour : le développeur web du site (ou le prestataire). Cas visés : un site sur mesure, ou toute plateforme où l'extension WordPress ne s'installe pas (par exemple un webhook de formulaire Webflow vers votre propre fonction serveur — plateforme non validée par WonTrail). Durée : 30 minutes à 1 heure.

Votre site est sous WordPress ? Vous n'avez rien à coder : l'extension branche Contact Form 7, WPForms, Gravity Forms et Elementor sur cette même API.

Sommaire

1. À quoi sert cette API
2. Prérequis
3. Adresse de l'API
4. Champs de la requête
5. Récupérer l'identifiant visiteur dans le navigateur
6. Méthode A — de serveur à serveur (recommandée)
7. Méthode B — directement depuis le navigateur
8. Idempotence avec lead_uuid
9. Réponses et erreurs
10. Limites de débit et nouvelles tentatives
11. Confidentialité et consentement

---

1. À quoi sert cette API

Le script WonTrail enregistre les pages vues et les clics d'un visiteur, ainsi que l'ouverture et l'envoi des formulaires, mais il ne lit jamais les valeurs saisies. Sans WordPress, un formulaire envoyé reste donc un événement anonyme dans le parcours.

L'API de leads transforme une soumission de formulaire en lead nommé (prénom, nom, e-mail, téléphone) et le rattache au parcours du visiteur grâce à son identifiant visiteur (visitor_id) : WonTrail retrouve les visites, les campagnes et les liens trackés déjà enregistrés pour ce visiteur sur ce site, et les attribue au lead.

Si un lead existe déjà dans votre organisation avec le même e-mail (ou, à défaut, le même téléphone), WonTrail met à jour ce lead au lieu d'en créer un second, et renvoie son identifiant :

• envoi signé par la clé serveur (méthode A, section 6) : la fiche est mise à jour entièrement (coordonnées, dernier contact, attribution) ;
• envoi non signé : le nouvel envoi ne fait que compléter les champs vides de la fiche existante, sans rien écraser ni déplacer l'attribution, sauf s'il vient du même navigateur que celui qui a créé la fiche (même visitor_id).

---

2. Prérequis

• Le site est créé dans WonTrail (Sites → Ajouter un site) et il est actif. Son domaine est celui de votre site public.
• Le script de suivi est installé sur toutes les pages, y compris celle du formulaire : voir Installer WonTrail sans WordPress. Sans lui, il n'existe pas d'identifiant visiteur et le lead n'est relié à aucun parcours.
• L'abonnement est valide : actif, en période d'essai non expirée, ou en impayé en cours de relance par le prestataire de paiement. Sinon, l'API refuse le lead (403, subscription_inactive). Le quota mensuel d'événements ne s'applique pas à cette API. Les envois non signés sont plafonnés par jour : 300 par site et par adresse IP, 30 par site et par visiteur, et 10 000 par site (section 10) ; les envois signés n'ont pas de plafond journalier.
• La clé du site (wt_site_…) : Sites → votre site, carte Clé du site. Elle est publique par conception.
• Facultatif, pour la méthode A : la clé serveur (wt_srv_…). Sites → votre site, carte Clé serveur, bouton Générer une clé serveur (propriétaire ou administrateur de l'organisation). Elle s'affiche une seule fois : copiez-la aussitôt dans la configuration secrète de votre serveur (variable d'environnement, coffre de secrets). Renouveler la clé serveur invalide immédiatement l'ancienne.

La carte Clé serveur est intitulée « extension WordPress 1.3.1 ou plus récente », mais la clé signe n'importe quel envoi fait depuis un serveur, selon le procédé décrit à la section 6.

---

3. Adresse de l'API

POST https://wontrail.fr/api/tracking/leads
Content-Type: application/json

• Le corps est un objet JSON encodé en UTF-8, de 24 000 octets au plus (au-delà : 413).
• Aucune authentification par jeton : le site est désigné par site_key, et l'envoi peut être signé par la clé serveur (section 6).
• Chaque réponse porte un en-tête X-Request-ID : notez-le si vous contactez le support au sujet d'un envoi.

---

4. Champs de la requête

Toutes les valeurs sont des chaînes de caractères. Les espaces en début et en fin sont retirés ; une chaîne vide (ou une valeur qui n'est pas une chaîne) compte comme absente.

Note — au moins une information de contact : parmi first_name, last_name, email et phone, au moins un doit être renseigné, sinon 400.

source : choisissez une valeur stable et parlante par formulaire, par exemple site_contact, webflow_devis. L'extension WordPress utilise wordpress_contact_form_7, wordpress_wpforms, wordpress_gravity_forms et wordpress_elementor.

tracking_slug : identifiant du lien tracké ou du lien partenaire par lequel le visiteur est arrivé. Pour qu'un lead soit rattaché à un partenaire (lien wontrail.fr/t/… ou lien direct https://votre-site.fr/?wt_partner=<identifiant>), envoyez la valeur de WonTrail.getTrackingSlug(), lue dans le navigateur au moment de l'envoi (script 2.3.0) ; c'est ce que fait l'extension WordPress 1.4.4. Cette fonction renvoie une chaîne vide tant que le visiteur n'a pas donné son consentement (attribut data-consent="required") ou s'il n'est passé par aucun lien : n'envoyez alors pas le champ, le lead arrive sans partenaire. N'inventez jamais cette valeur et ne la reprenez pas de l'adresse de la page vous-même : elle ne serait pas soumise au consentement. S'il désigne un lien inconnu pour ce site ou désactivé, le lead est quand même enregistré, sans attribution par ce lien (la réponse contient alors "link_ignored": true).

lead_uuid : une valeur qui n'a pas la forme d'un UUID est refusée (400, lead_uuid doit être un UUID.).

Tout autre champ est ignoré. N'envoyez rien d'autre que ces champs (voir section 11).

Exemple de corps :

{
  "site_key": "wt_site_VOTRE_CLE",
  "visitor_id": "3f1c2b7e-8a4d-4c1e-9b2a-6d5e4f3a2b1c",
  "first_name": "Camille",
  "last_name": "Martin",
  "email": "camille.martin@example.com",
  "phone": "+33 6 12 34 56 78",
  "source": "site_contact",
  "lead_uuid": "0b6f7a52-5c3e-4d8b-a1f2-9e8d7c6b5a41"
}

---

5. Récupérer l'identifiant visiteur dans le navigateur

Le script WonTrail expose window.WonTrail. La méthode WonTrail.getVisitorId() renvoie l'identifiant du visiteur courant (une chaîne). Elle renvoie une chaîne vide si le site demande le consentement (data-consent="required") et que le visiteur ne l'a pas donné.

Si votre formulaire est envoyé à votre serveur (méthode A), ajoutez un champ caché et remplissez-le au moment de l'envoi :

<form id="contact" method="post" action="/contact">
  <!-- … vos champs … -->
  <input type="hidden" name="wontrail_visitor_id" value="">
  <button type="submit">Envoyer</button>
</form>

<script>
  document.getElementById("contact").addEventListener("submit", function (event) {
    var api = window.WonTrail;
    var visitorId =
      api && typeof api.getVisitorId === "function" ? api.getVisitorId() : "";

    event.target.elements.wontrail_visitor_id.value = visitorId || "";
  });
</script>

• Lisez l'identifiant au moment de l'envoi, pas au chargement de la page : le script peut se charger après votre code, et le visiteur peut consentir entre-temps.
• Testez toujours la présence de window.WonTrail : le script peut être bloqué (bloqueur de publicité, consentement refusé, panne réseau). Le formulaire doit fonctionner sans lui.
• N'allez pas lire vous-même le stockage du navigateur (clé localStorage wontrail_visitor_id) : getVisitorId() respecte le consentement, une lecture directe non.
• Sur Webflow, le champ caché s'ajoute dans le formulaire (élément « Embed » de code personnalisé) ; le script ci-dessus se place dans le code de pied de page. Le webhook de formulaire transmet alors ce champ avec les autres à votre fonction serveur, qui appelle l'API.

Côté serveur, traitez cette valeur comme une donnée venue du navigateur : acceptez-la seulement si elle correspond à ^[A-Za-z0-9_.:-]{1,255}$ (le filtre de l'extension WordPress). Si elle est vide ou invalide, envoyez quand même le lead avec un identifiant unique à usage unique, par exemple wt_ext_ suivi d'un UUID : l'extension WordPress fait de même (wt_wp_…). Le lead est créé, sans parcours. N'utilisez jamais une valeur fixe : deux leads sans e-mail ni téléphone portant le même visitor_id seraient fusionnés.

---

6. Méthode A — de serveur à serveur (recommandée)

Le navigateur envoie le formulaire à votre serveur (ou Webflow à votre fonction serveur) ; votre serveur appelle WonTrail. Avantages : la clé serveur reste secrète, les échecs passagers peuvent être retentés, et la limite par site est plus haute pour un envoi signé (300 par minute au lieu de 60).

Origine. Une requête de serveur à serveur n'envoie normalement pas d'en-tête Origin : elle est alors acceptée quel que soit le domaine. Si votre code relaie l'en-tête Origin du navigateur, il doit correspondre au domaine du site (sinon 403) : ne le relayez pas.

Signature par la clé serveur (facultative)

Sans les en-têtes de signature, l'envoi est accepté sans signature, sauf si l'option Exiger la signature est activée sur le site (carte Clé serveur). Avec eux, la signature doit être valide.

1. Sérialisez le corps JSON une fois, en une chaîne : corps.
2. horodatage = l'heure Unix actuelle en secondes (ex. 1790000000).
3. signature = HMAC-SHA256 avec la clé serveur wt_srv_… comme secret, calculé sur la chaîne horodatage + "." + corps (UTF-8), en hexadécimal (64 caractères).
4. Envoyez exactement la même chaîne corps, avec les en-têtes :
   • X-WonTrail-Timestamp: <horodatage>
   • X-WonTrail-Signature: <signature>

Règles vérifiées par WonTrail :

• l'horodatage doit être à 5 minutes au plus de l'heure du serveur WonTrail (dans un sens ou dans l'autre) : gardez l'horloge de votre serveur synchronisée (NTP) ;
• la signature porte sur les octets exacts envoyés : ne re-sérialisez pas le JSON entre la signature et l'envoi ;
• à chaque nouvelle tentative, recalculez l'horodatage et la signature (le corps et le lead_uuid restent identiques) ;
• envoyer un seul des deux en-têtes, ou les envoyer alors qu'aucune clé serveur n'a été générée pour le site, est refusé (401).

Activez Exiger la signature seulement une fois que tous vos envois sont signés : tout lead non signé est alors refusé (401, signature_required), y compris ceux d'un formulaire appelant l'API depuis le navigateur.

Exemple — curl (shell)

WONTRAIL_SERVER_KEY='wt_srv_…'   # secret, à lire depuis votre configuration
LEAD_UUID=$(uuidgen)              # une fois par soumission, réutilisé aux tentatives

BODY=$(printf '{"site_key":"wt_site_VOTRE_CLE","visitor_id":"%s","first_name":"Camille","email":"camille.martin@example.com","source":"site_contact","lead_uuid":"%s"}' \
  "3f1c2b7e-8a4d-4c1e-9b2a-6d5e4f3a2b1c" "$LEAD_UUID")

TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$WONTRAIL_SERVER_KEY" -hex | sed 's/^.* //')

curl -sS -X POST 'https://wontrail.fr/api/tracking/leads' \
  -H 'Content-Type: application/json' \
  -H "X-WonTrail-Timestamp: $TS" \
  -H "X-WonTrail-Signature: $SIG" \
  --data-binary "$BODY"

--data-binary envoie le corps tel quel (-d pourrait le modifier). Sans clé serveur, retirez les deux lignes X-WonTrail-….

Exemple — PHP (extension curl)

<?php
function wontrail_send_lead(array $lead, string $leadUuid): array
{
    $serverKey = getenv('WONTRAIL_SERVER_KEY') ?: ''; // wt_srv_… ; vide = envoi non signé

    $visitorId = (string) ($lead['visitor_id'] ?? '');
    if (!preg_match('/^[A-Za-z0-9_.:-]{1,255}$/', $visitorId)) {
        $visitorId = 'wt_ext_' . bin2hex(random_bytes(16)); // identifiant à usage unique
    }

    $payload = [
        'site_key'   => 'wt_site_VOTRE_CLE',
        'visitor_id' => $visitorId,
        'first_name' => (string) ($lead['first_name'] ?? ''),
        'last_name'  => (string) ($lead['last_name'] ?? ''),
        'email'      => (string) ($lead['email'] ?? ''),
        'phone'      => (string) ($lead['phone'] ?? ''),
        'source'     => 'site_contact',
        'lead_uuid'  => $leadUuid,
    ];

    $body = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    $headers = ['Content-Type: application/json', 'Accept: application/json'];

    if ($serverKey !== '') {
        $timestamp = (string) time();
        $headers[] = 'X-WonTrail-Timestamp: ' . $timestamp;
        $headers[] = 'X-WonTrail-Signature: ' . hash_hmac('sha256', $timestamp . '.' . $body, $serverKey);
    }

    $ch = curl_init('https://wontrail.fr/api/tracking/leads');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $body,   // la chaîne signée, telle quelle
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
    ]);
    $response = curl_exec($ch);
    $status = $response === false ? 0 : (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    return [
        'status' => $status,                 // 0 = erreur réseau ou délai dépassé
        'body'   => $response === false ? null : json_decode($response, true),
        'retry'  => $status === 0 || $status === 408 || $status === 429 || $status >= 500,
    ];
}

Le $leadUuid se crée une fois par soumission (par exemple wp_generate_uuid4(), Ramsey\Uuid\Uuid::uuid4(), ou votre bibliothèque habituelle) et se conserve avec le lead en attente pour les nouvelles tentatives. Une valeur null n'étant pas une chaîne, les champs vides peuvent être envoyés en "" : ils comptent comme absents.

Exemple — Node.js (18 ou plus)

import { createHmac, randomUUID } from "node:crypto";

const ENDPOINT = "https://wontrail.fr/api/tracking/leads";
const SITE_KEY = "wt_site_VOTRE_CLE";
const SERVER_KEY = process.env.WONTRAIL_SERVER_KEY || ""; // wt_srv_… ; vide = non signé
const VISITOR_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,255}$/;

export async function sendLead(fields, leadUuid = randomUUID()) {
  const visitorId = VISITOR_ID_PATTERN.test(fields.visitorId || "")
    ? fields.visitorId
    : `wt_ext_${randomUUID()}`; // identifiant à usage unique

  const body = JSON.stringify({
    site_key: SITE_KEY,
    visitor_id: visitorId,
    first_name: fields.firstName || "",
    last_name: fields.lastName || "",
    email: fields.email || "",
    phone: fields.phone || "",
    source: "site_contact",
    lead_uuid: leadUuid,
  });

  const headers = { "Content-Type": "application/json", Accept: "application/json" };

  if (SERVER_KEY) {
    const timestamp = Math.floor(Date.now() / 1000).toString();
    headers["X-WonTrail-Timestamp"] = timestamp;
    headers["X-WonTrail-Signature"] = createHmac("sha256", SERVER_KEY)
      .update(`${timestamp}.${body}`, "utf8")
      .digest("hex");
  }

  try {
    const response = await fetch(ENDPOINT, {
      method: "POST",
      headers,
      body, // la chaîne signée, telle quelle
      signal: AbortSignal.timeout(10_000),
    });
    const status = response.status;
    return {
      status,
      body: await response.json().catch(() => null),
      retry: status === 408 || status === 429 || status >= 500,
      retryAfter: Number(response.headers.get("retry-after")) || 0,
      leadUuid,
    };
  } catch {
    return { status: 0, body: null, retry: true, retryAfter: 0, leadUuid }; // réseau ou délai
  }
}

Le visitorId d'un nouvel envoi est choisi une fois : lors d'une nouvelle tentative, renvoyez le même corps (même visitor_id, même lead_uuid), seuls l'horodatage et la signature changent.

---

7. Méthode B — directement depuis le navigateur

À réserver aux sites sans serveur à vous. Le navigateur appelle WonTrail lui-même, sans aucun secret : n'utilisez jamais la clé serveur dans une page.

Conditions :

• la page doit être servie depuis le domaine du site enregistré dans WonTrail (exemple.fr et www.exemple.fr valent pour le même site ; un sous-domaine ou une préproduction, non) : sinon 403 « Origine non autorisée » ;
• l'envoi n'est pas signé : l'option Exiger la signature doit rester désactivée, et la limite est de 60 leads par minute pour le site ;
• si votre site a une politique de sécurité du contenu (CSP), wontrail.fr doit être autorisé en connect-src.

<script>
  document.getElementById("contact").addEventListener("submit", function (event) {
    var api = window.WonTrail;
    var visitorId =
      api && typeof api.getVisitorId === "function" ? api.getVisitorId() : "";

    var form = event.target;
    var payload = {
      site_key: "wt_site_VOTRE_CLE",
      visitor_id: visitorId || "wt_ext_" + crypto.randomUUID(),
      first_name: form.elements.first_name.value,
      last_name: form.elements.last_name.value,
      email: form.elements.email.value,
      phone: form.elements.phone.value,
      source: "site_contact",
      lead_uuid: crypto.randomUUID()
    };

    fetch("https://wontrail.fr/api/tracking/leads", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload),
      keepalive: true // l'envoi survit au changement de page
    }).catch(function () { /* ne jamais bloquer le formulaire */ });
  });
</script>

Limites de cette méthode :

• seuls les en-têtes Content-Type et X-Request-ID sont autorisés par WonTrail depuis un navigateur : impossible (et inutile) d'y signer ;
• les en-têtes Retry-After et X-RateLimit-… de la réponse sont lisibles par votre code ;
• un envoi perdu (visiteur hors ligne, page fermée) n'est pas retenté. Pour ne perdre aucun lead, préférez la méthode A.

---

8. Idempotence avec lead_uuid

Un envoi peut échouer après que WonTrail a enregistré le lead (réponse perdue, délai dépassé). Pour qu'une nouvelle tentative ne crée pas de doublon :

1. générez un UUID v4 par soumission de formulaire, avant le premier envoi ;
2. conservez-le avec le lead en attente ;
3. renvoyez-le inchangé à chaque nouvelle tentative.

Si WonTrail a déjà enregistré ce lead_uuid pour ce site, il répond 200 avec "duplicate": true et l'identifiant du lead déjà créé, sans rien modifier. Traitez cette réponse comme un succès.

• Ne réutilisez jamais un lead_uuid pour une autre soumission : elle serait prise pour un doublon et ignorée.
• WonTrail conserve les lead_uuid 7 jours : ne retentez pas un envoi au-delà.
• Les majuscules sont acceptées (la valeur est mise en minuscules).

---

9. Réponses et erreurs

Les réponses sont en JSON. Les messages d'erreur (error) sont toujours en français et peuvent évoluer : fiez-vous au code HTTP et, quand il existe, au champ code.

Succès

Erreurs définitives — ne pas retenter tel quel

Corps : {"success": false, "error": "…"}, plus code quand indiqué.

Pour une requête OPTIONS (pré-vérification d'un navigateur), WonTrail répond 204, ou 403 « Origine non autorisée. » si l'origine ne correspond à aucun site actif.

Erreurs passagères — à retenter

---

10. Limites de débit et nouvelles tentatives

Au-delà : 429, avec les en-têtes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (heure Unix, en secondes).

Règles de nouvelle tentative (celles de l'extension WordPress) :

• retenter seulement : erreur réseau, délai dépassé, 408, 429 et 5xx ;
• ne pas retenter les autres 4xx : la même requête serait refusée de la même façon. Journalisez l'erreur et corrigez la cause ;
• espacer les tentatives, par exemple 1 min, 5 min, 15 min, 1 h, puis 6 h, et jamais moins que Retry-After ;
• garder le même corps et le même lead_uuid, re-signer à chaque tentative, et abandonner avant 7 jours ;
• ne jamais faire attendre le visiteur : confirmez son envoi sur votre site, et laissez une file d'attente (tâche planifiée, file de messages) s'occuper des nouvelles tentatives.

---

11. Confidentialité et consentement

• N'envoyez que les quatre informations de contact : prénom, nom, e-mail, téléphone, plus les champs techniques (site_key, visitor_id, source, lead_uuid). Jamais le contenu du message, un champ libre, une pièce jointe ou une donnée sensible. C'est la règle suivie par l'extension WordPress.
• Consentement au suivi : si votre site demande le consentement avant la mesure d'audience, WonTrail.getVisitorId() renvoie une chaîne vide tant que le visiteur n'a pas accepté. Envoyez alors le lead avec un identifiant à usage unique (section 5) : le prospect est transmis, puisqu'il a lui-même rempli le formulaire, mais il n'est relié à aucun parcours. Ne contournez pas ce choix en lisant le stockage du navigateur.
• Information des personnes : votre formulaire doit indiquer, dans votre mention d'information, que les coordonnées sont transmises à WonTrail pour le suivi commercial de votre entreprise.
• Secrets : la clé serveur wt_srv_… ne doit apparaître ni dans une page, ni dans un dépôt de code, ni dans un journal. En cas de fuite, renouvelez-la depuis la carte Clé serveur.

Une question : support@wontrail.fr.