Guide d'intégration

Zapier

Capture des leads depuis Facebook Lead Ads, Typeform, Webflow et 6000+ autres apps via Zapier — pas-à-pas avec captures d'écran.

Configuration

Crée un Zap avec Facebook Lead Ads en source et Webhooks by Zapier en action.

Créer un nouveau Zap

Dans Zapier, clique Create Zap. Nomme ton Zap (ex. Facebook Leads → Capturia).

Configurer le trigger Facebook Lead Ads

Comme Trigger app, choisis Facebook Lead Ads. Connecte ton compte Facebook Business, sélectionne la Page et le Lead Form que tu veux router vers Capturia. Clique Test trigger — Zapier remonte un lead test depuis le formulaire.

Configuration du trigger Facebook Lead Ads

Ajouter l'action Webhooks by Zapier

Comme Action app, choisis Webhooks by Zapier. Comme Event, sélectionne POST (pas Custom Request, pas GET).

Configurer l'URL et l'authentification

URL : https://app.capturia.io/api/v1/leads/capture

Payload Type : JSON (pas Form, pas XML)

Headers : ajoute Authorization avec la valeur Bearer cap_live_xxxxxxxx (ta clé API Capturia entière).

Mapper les champs

Dans la section Data, ajoute les champs Capturia (voir le tableau de mapping ci-dessous). Glisse les champs Facebook Lead correspondants depuis le panneau de droite.

Important : pour utm (objet imbriqué) et pipeline, utilise le format utm.source, utm.medium, pipeline.id, etc. Zapier les flatten par défaut — il faut activer Unflatten = Yes dans les options avancées.

Capturer le consentement SMS

Pattern recommandé : ajoute une question custom de consentement SMS dans ton Lead Form Facebook (Custom Question type "Yes/No" ou case à cocher). Mappe ce champ vers sms_consent.

Pattern alternatif : si la question custom n'est pas possible, hardcode sms_consent: true mais conserve une preuve de consentement (case sur la landing page, copie d'archive). Voir la section LCAP plus bas.

Tester et publier

Clique Test action pour envoyer le lead test à Capturia. Une réponse 200 OK avec status: created ou status: idempotent_replay confirme la connexion. Dans Mes Prospects sur Capturia, le lead test apparaît immédiatement. Si tout est OK, clique Publish Zap pour activer la connexion en production.

Mapping des champs

Mapping recommandé pour Facebook Lead Ads → Capturia. Adapter les noms de champ source selon ton formulaire — phone_number chez certains formulaires devient phone chez d'autres.

Champ Capturia	Obligatoire	Champ source	Notes
phone	Oui	phone_number	E.164 (+15145551234), NANP 10 ou 11 chiffres, ou formattés (514) 555-1234 / 514-555-1234. Les 10 chiffres sont auto-préfixés +1.
sms_consent	Oui	consent_yes_no (custom question)	Boolean true OU string 'true' / 'yes' / 'oui' / 'vrai' / '1' / 'on' / 'checked' (insensible à la casse). Accepté à la racine du body ou dans l'objet `customData` (webhooks GoHighLevel).
first_name	Non	first_name	Prénom du lead
last_name	Non	last_name	Nom de famille
email	Non	email	Email valide RFC 5322
source_label	Non	(littéral) fb_lead_ads	Étiquette libre (ex. 'webflow_form', 'fb_lead_ads')
utm.source	Non	(littéral) facebook	Objet utm imbriqué (pas flat)
utm.medium	Non	(littéral) cpc	Objet utm imbriqué
utm.campaign	Non	campaign_name	Objet utm imbriqué
tags	Non	[]	Tableau de strings
pipeline.id	Non	(optionnel)	UUID du pipeline cible
pipeline.stage_id	Non	(optionnel)	UUID du stage cible

Consentement SMS — LCAP / Loi 25

Le champ sms_consent est obligatoire. La loi canadienne anti-pourriel (LCAP/CASL) et la Loi 25 québécoise exigent un consentement explicite avant tout SMS commercial. Capturia conserve une trace horodatée de cette attestation pour ta protection légale.

Pattern recommandé — consentement capturé à la source

Ajoute une question custom de consentement directement dans le formulaire source (FB Lead Form custom question, champ Typeform, case GHL form). Mappe ce champ vers sms_consent. Le consentement est explicite, daté, et lié au lead qui l'a donné.

Pattern alternatif — case sur la landing page

Si le formulaire source ne permet pas de question custom, ajoute une case à cocher de consentement sur la landing page qui précède la pub. Conserve une copie de la page (Wayback Machine, screenshot daté) en preuve.

Zone grise légale

Hardcoder sms_consent: true sans attestation réelle du lead = risque légal. En cas de plainte, Capturia peut être tenue de fournir la preuve du consentement. Sans preuve, la responsabilité revient au PO de la PME.

Test step-by-step

Dans Zapier, clique Test trigger pour récupérer un lead test depuis Facebook (utilise le mode "Lead Ads Testing Tool" de Meta). Puis Test action pour envoyer le lead à Capturia. Une réponse 200 OK avec status: created ou status: idempotent_replay confirme que ça marche. Vérifie ensuite dans Mes Prospects que le lead apparaît.

Catalogue d'erreurs

Code	Erreur	Cause	Fix
401	missing_api_key	Header Authorization absent ou mal formé	Ajouter le header `Authorization: Bearer cap_live_...`
401	invalid_api_key	Clé révoquée, expirée ou typo	Vérifier la clé dans le dashboard, en générer une nouvelle si nécessaire
403	terms_acceptance_required	CGU pas acceptées (ou bump de version forcant un ré-consent)	Le PO de la PME doit re-accepter les CGU dans le dashboard
403	insufficient_scope	La clé n'a pas le scope `leads:capture`	Créer une nouvelle clé avec le preset 'Capture de leads'
422	invalid_phone	Format téléphone non reconnu	Utiliser E.164 (+15145551234) ou NANP 10 chiffres (5145551234)
422	missing_consent	sms_consent absent, false, ou valeur non reconnue — le champ est cherché à la racine du body ET dans l'objet `customData` (GHL)	Mapper le champ de consentement vers sms_consent (true / yes / oui). Depuis GHL : valeur fixe `true` derrière une condition sur la checkbox de consentement
422	invalid_payload	Autre champ mal formé (email, utm objet vs flat, etc.)	Vérifier le format du body — voir la doc API leads:capture
429	rate_limited_key	Quota par clé dépassé (souvent 100 req/min)	Throttler côté source, ou demander un upgrade de tier au support
429	rate_limited_ip	Quota par IP dépassé	Réduire le débit ou contacter le support
400	invalid_payload	Body n'est pas du JSON valide (Form ou form-urlencoded à la place)	Configurer Payload Type = JSON / Content-Type = application/json

FAQ — pièges récurrents

Symptôme	Cause
Test plateforme vert (200 OK) mais le lead n'apparaît pas dans le pipeline	Téléphone identique à un contact existant — réponse `status: idempotent_replay`. Le lead existe déjà mais n'est pas dupliqué. Le mode test sandbox réutilise souvent le même numéro.
400 "Body is not valid JSON"	Payload Type configuré sur Form au lieu de JSON, ou body envoyé en x-www-form-urlencoded au lieu d'application/json.
Réponse 200 OK mais pas de SMS envoyé au lead	sms_consent: true mais agent IA non configuré, ou agent IA SMS désactivé, ou pas de numéro Twilio provisionné côté client.
Lead créé sans tracking UTM	Champ utm envoyé en flat (utm_source) au lieu d'objet imbriqué (utm.source). Le serveur attend un objet.
403 terms_acceptance_required après une mise à jour qui marchait avant	Bump de version CGU côté Capturia force le PO de la PME à re-accepter dans le dashboard avant que la clé refonctionne.
Lead UTM perdu malgré le mapping	Avec Zapier, l'option Unflatten = Yes est obligatoire pour que `utm.source` soit envoyé comme objet imbriqué. Sinon Zapier flatten en `utm_source` que Capturia rejette.