Presuasion submissions

Soumettre un formulaire d'outil pré-suasion

Endpoint public — convention legacy pré-CAP-440. Cet endpoint s'écarte des conventions standard de l'API v1 sur plusieurs points documentés ci-dessous. Il est appelé par la gateway pré-suasion (demo.capturia.io) quand un visiteur complète un formulaire d'outil pré-suasion publié sur le custom domain d'un client Capturia.

Authentification : défense en profondeur

Pas de clé API Bearer (l'endpoint est appelé par une gateway publique, pas par un client tiers). Trois couches superposées protègent l'endpoint :

1. Rate-limit IP (RATE_LIMIT_CONFIG.LEAD_CREATION_LIMIT req par LEAD_WINDOW_SECONDS) — coupe le bruit haute fréquence.
2. Signature HMAC X-Capturia-Signature: t=<unix>,v1=<hex> — pattern Stripe webhook, SHA-256 sur ${timestamp}.${rawBody}, fenêtre replay 5 min, rotation 2-clés (PRESUASION_HMAC_SECRET + PRESUASION_HMAC_SECRET_PREVIOUS). Mode log-only par défaut, flip fail-closed via PRESUASION_HMAC_REQUIRED=true.
3. Token Cloudflare Turnstile (champ turnstile_token du body) vérifié siteverify avec idempotency_key = submission_id du body (stable entre les retries d'une même soumission — un token est à usage unique, Cloudflare rejoue le verdict original sur la même clé), avec repli sur le request_id de la requête quand la soumission ne porte pas de submission_id. Mode log-only par défaut, flip fail-closed via PRESUASION_TURNSTILE_REQUIRED=true.

En complément, un quota par proposition_slug (100 submissions par jour UTC, Upstash KV) borne le blast radius d'une attaque ciblée même si les autres couches sont contournées.

Le client cible est résolu serveur-side via proposition_slug → presuasion_instances.client_id — le client_id n'est jamais accepté depuis le body.

Body et réponse au format custom

Le body suit un schéma propre à cet endpoint (PresuasionSubmissionPayload). La réponse 200 retourne un objet plat {success, contact_id, contact_created, activity_id} au lieu de l'enveloppe v1 standard {data: ...}. Les erreurs retournent {error: "string", issues?: [...]} au lieu d'ErrorEnvelope.

Comportement

• Resolve le client cible via proposition_slug actif.
• Fiche du contact par le moteur partagé des funnels : retrouvée par le courriel (casse indifférente, courriels secondaires inclus), puis par un téléphone déjà connu chez ce client — la fiche existante est alors enrichie du courriel soumis en secondaire, jamais doublée ni mise en erreur d'unicité. Noms complétés sans écraser, téléphone posé s'il manquait (un numéro déjà porté par une autre fiche reste sur la soumission), triplet de consentement SMS implicite rafraîchi à chaque soumission (sous garde STOP). Sur le chemin tokenisé (identity_confirmed), la fiche du lien reçoit le même enrichissement additif.
• Routage de capture réglé sur l'outil : une fiche créée par la soumission naît dans la colonne d'arrivée de l'outil ; les tags automatiques de l'outil sont ajoutés à toute fiche captée (créée ou retrouvée, chemin courriel ou lien) ; une fiche retrouvée qui n'est dans aucune colonne y entre par l'outil. Une fiche déjà placée n'est jamais déplacée.
• Insère une activité presuasion_submission dans la timeline du contact avec un bloc humain Q/R formaté + metadata brute (responses, result_data, tool_name, proposition). L'outil y est identifié par son instance : metadata.tool_id et metadata.proposition_id portent l'identifiant de la proposition résolue, comme les captures des outils embarqués.

Rate limit

Émet les headers legacy X-RateLimit-* (compteur IP) — pas les headers RateLimit-* RFC 9331 du reste de l'API v1.

curl -X POST 'https://api.capturia.io/v1/presuasion-submissions' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "proposition_slug": "blueprint-ventes-2026",
  "tool_id": "calculateur-roi",
  "tool_name": "Calculateur de ROI",
  "email": "[email protected]",
  "first_name": "Alex",
  "phone": "+15145551234",
  "responses": {
    "budget": "500-1000",
    "timeline": "3-mois"
  },
  "formatted_answers": [
    {
      "question": "Quel est ton défi principal en ventes ?",
      "answer": "Je perds des leads parce que je ne suis pas assez rapide à les rappeler."
    }
  ],
  "result_data": {
    "score": 87,
    "recommendation": "premium"
  },
  "completed_at": "2026-05-04T12:34:56.789Z"
}'