Guide d'intégration

Zapier

Capture des leads depuis Facebook Lead Ads, Typeform, Webflow et 6000+ autres apps via Zapier, pas à pas.

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.

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://api.capturia.io/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.

Champs imbriqués : pour utm et pipeline, écris la clé à plat avec un point, telle quelle : utm.source, utm.medium, pipeline.pipeline_slug, pipeline.stage_slug. Capturia range chaque clé dans son bloc.

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 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 formatés (514) 555-1234 / 514-555-1234. Les 10 chiffres sont auto-préfixés +1.
sms_consent	Oui	consent_yes_no (question personnalisée)	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é, ou clé à plat `utm.source`
utm.medium	Non	(littéral) cpc	Objet `utm` imbriqué, ou clé à plat `utm.medium`
utm.campaign	Non	campaign_name	Objet `utm` imbriqué, ou clé à plat `utm.campaign`
tags	Non	(littéral) tag1, tag2 — ou laisser vide	Tableau de strings, ou une chaîne à virgules
pipeline.pipeline_slug	Non	(littéral) identifiant copié dans Capturia	Identifiant texte du pipeline cible (pas son UUID). À copier dans Capturia : Administration, Clés API, section « Identifiants de tes pipelines et étapes ». Sans lui, le pipeline par défaut est visé. Objet `pipeline` imbriqué, ou clé à plat.
pipeline.stage_slug	Non	(littéral) identifiant copié dans Capturia	Identifiant texte de l'étape cible, à copier au même endroit. Sans lui, l'étape marquée « Étape par défaut » à côté des identifiants. Envoyé sans `pipeline_slug`, il est cherché dans ton pipeline par défaut. Objet `pipeline` imbriqué, ou clé à plat.

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 à l'entreprise qui envoie le lead.

Tester pas à pas

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 Prospects que le lead apparaît.

Catalogue d'erreurs

Code	Erreur	Cause	Correction
400	invalid_payload	Body vide ou JSON mal formé (virgule en trop, guillemet manquant)	Valider le JSON envoyé, puis renvoyer
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 mal copiée	Vérifier la clé dans Capturia, en générer une nouvelle si nécessaire
403	terms_acceptance_required	Conditions d'utilisation de l'API pas acceptées (ou nouvelle version à accepter)	Le propriétaire du compte accepte les conditions dans Capturia, à la page Clés API
403	insufficient_scope	La clé n'a pas le scope `leads:capture`	Créer une nouvelle clé avec le preset « Capture de leads »
415	invalid_content_type	Body envoyé en formulaire (Form, x-www-form-urlencoded) au lieu de JSON	Régler l'envoi en JSON (Payload Type = JSON, Encoding = JSON, Body content type = application/JSON)
422	invalid_phone	Téléphone absent ou format non reconnu	Utiliser E.164 (+15145551234) ou NANP 10 chiffres (5145551234)
422	invalid_email	Courriel mal formé	Envoyer une adresse valide, ou ne pas envoyer le champ
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 refusé (texte trop long, date mal formée, valeur négative, etc.) — `details` nomme le champ	Corriger le champ nommé dans `details`, puis renvoyer
422	pipeline_not_found	`pipeline.pipeline_slug` ne correspond à aucun pipeline du compte	Recopier l'identifiant texte du pipeline depuis la page Clés API (ce n'est pas son UUID)
422	stage_not_found	`pipeline.stage_slug` ne correspond à aucune étape du pipeline visé	Recopier l'identifiant texte de l'étape depuis la page Clés API, sous le bon pipeline
429	rate_limit_exceeded	Quota de requêtes de la clé dépassé	Espacer les envois côté source (l'en-tête `Retry-After` donne le délai)
429	rate_limited_ip	Plus de 100 requêtes par minute depuis la même adresse IP	Réduire le débit ou contacter le support

FAQ — pièges récurrents

Symptôme	Cause
Test plateforme vert (200 OK) mais le lead n'apparaît pas dans le pipeline	Le même contact a déjà été envoyé dans les 5 dernières minutes — réponse `status: idempotent_replay`, aucun doublon (les tests réutilisent souvent le même numéro). Si la fiche existait déjà, elle garde sa colonne : voir l'entrée « pas dans le bon pipeline » plus bas.
415 « Unsupported Content-Type » ou 400 « Body is not valid JSON »	415 : l'outil envoie un formulaire (Payload Type sur Form, Encoding form-encoded) au lieu de JSON. 400 : le JSON est mal formé, souvent une virgule en trop ou un guillemet manquant autour d'une variable.
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.
Réponse 200 OK mais le lead n'est pas dans le bon pipeline ou la bonne colonne	Lis `ignored_fields` dans la réponse : elle nomme chaque champ reçu qui n'a pas été pris. `unknown_field` : le champ porte un nom que l'API ne connaît pas (`pipeline.id` au lieu de `pipeline.pipeline_slug`, par exemple). `existing_contact_kept` : la fiche existait déjà, elle garde son pipeline et son étape. `duplicate_field` : le même champ est arrivé deux fois (racine et Custom Data, par exemple) et l'autre valeur a été retenue.
Lead créé sans tracking UTM	Champ envoyé sous un nom que l'API ne connaît pas (`utm_source`). Envoie l'objet `utm` imbriqué ou la clé à plat `utm.source` ; `ignored_fields` nomme le champ qui n'a pas été pris.
403 terms_acceptance_required après une mise à jour qui marchait avant	Une nouvelle version des conditions d'utilisation de l'API est à accepter : le propriétaire du compte l'accepte dans Capturia, à la page Clés API, et la clé refonctionne.
Lead UTM perdu malgré le mapping	La clé ne porte pas un nom que l'API connaît (`utm_source` avec un seul tiret bas, par exemple). Écris `utm.source` (clé à plat), ou `utm__source` avec Unflatten = Yes. La réponse de Capturia nomme le champ qui n'a pas été pris dans `ignored_fields`.