Par l’équipe CertiLead
Publié le · Mis à jour le
Relier trois moments : vérifier le lead, actualiser son état, restituer la preuve. La synthèse du verdict, la correspondance du contact et le rattachement de l’entreprise se lisent séparément. Les exemples ci-dessous sont fictifs et les extraits de réponse volontairement partiels.
- POSTPour créer une vérificationVoir la référence
- 3 dimensionsVerdict, contact et destinataireVoir la référence
- Un curseurPour reprendre les événementsVoir la référence
Préparer l’intégration
- Identifier l’entreprise acheteuse et créer une clé avec les droits nécessaires.
- Conserver la clé dans un secret côté serveur, y compris si l’appel part d’un connecteur CRM ; ne pas l’exposer au navigateur.
- Définir les règles de routage, les délais d’attente et le traitement des résultats indéterminés.
- Prévoir une clé d’idempotence par opération logique et garder la même pour ses nouvelles tentatives.
Envoyer une vérification
POST /api/v1/verifications
X-API-Key: VOTRE_CLE_SERVEUR
Idempotency-Key: crm:91042:call:550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"token": "CL-26-QNOMTRPNZA5G",
"level": 2,
"identity": { "phone": "+33600000000" },
"client_ref": "crm:91042",
"context": { "purpose": "pre_call" }
}Faites défiler le tableau horizontalement pour lire toutes les colonnes.
| Champ | À transmettre |
|---|---|
| level | Entier 1, 2 ou 3, explicite dans cette requête. |
| identity | Objet contenant le téléphone et/ou l’e-mail à rapprocher. Fournir le numéro qui sera appelé. |
| client_ref | Référence interne facultative : 1 à 64 caractères, lettres, chiffres, point, tiret, soulignement ou deux-points. |
| context.purpose | pre_call. |
| Idempotency-Key | 16 à 128 caractères autorisés ; identifie une opération, pas tous les contrôles futurs du même lead. |
Lire les trois dimensions de la réponse
{
"verification_status": {
"code": "verified",
"exploitable": true
},
"identity_checked": true,
"level_1": {
"identity": { "phone": true, "email": null }
},
"recipient_match": { "status": "authorized" },
"replay": { "billed": true, "remaining": 9 }
}Faites défiler le tableau horizontalement pour lire toutes les colonnes.
| Champ | Lecture correcte |
|---|---|
| verification_status | Synthèse des contrôles disponibles ; ne garantit pas la légalité de l’appel. |
| identity_checked | Des coordonnées ont été fournies au contrôle. true ne signifie pas qu’elles correspondent. |
| level_1.identity.phone / email | true : correspond ; false : diffère ; null : comparaison non établie. |
| recipient_match.status | authorized, not_listed ou undetermined. Lire ce bloc séparément. |
| replay | Facturation de ce contrôle, quota restant et fenêtre applicable. |
Pour construire votre décision, rapprocher ces champs de la grille de contrôle d’un lead avant appel.
Recevoir et rattraper les événements
Un webhook peut être livré plusieurs fois. Vérifier sa signature selon la documentation et rendre le traitement idempotent. Le flux de rattrapage complète cette réception :
GET /api/v1/events?since=CURSEUR_PRECEDENT&limit=100Traiter les éléments de events, puis conserver next_since après réussite du traitement. Reprendre les pages suivantes lorsque nécessaire. Une date ISO est également acceptée pour une reprise initiale ; le curseur fourni convient mieux à une reprise précise.
Prévoir une correspondance locale entre fiche, jeton et vérification. Utiliser client_ref lorsqu’il est disponible, sans supposer qu’un seul champ suffit à identifier tous les événements. Le croisement webhook et rattrapage nécessite une déduplication côté CRM.
Prévoir le traitement métier décrit dans le guide de propagation du retrait, notamment pour les appels déjà en file.
Télécharger l’attestation et le dossier
Faites défiler le tableau horizontalement pour lire toutes les colonnes.
| Document | Route |
|---|---|
| Attestation PDF | GET /api/v1/verifications/:id/proof.pdf |
| Dossier de preuve ZIP | GET /api/v1/verifications/:id/dossier.zip |
Utiliser l’identifiant de votre vérification et les droits requis. Le contenu disponible dépend du contrôle et de son état ; une attestation de vérification n’est pas une attestation universelle de conformité juridique.
Le guide sur l’horodatage qualifié et la vérification des lots explique comment lire les éléments techniques du dossier.
Gérer re-vérifications et idempotence
L’offre affichée prévoit jusqu’à neuf re-vérifications incluses du même jeton au même niveau, dans la fenêtre applicable. Le devis GET /api/v1/verify/:token/replay-status?level=2 indique notamment next_free, remaining et window_ends_at.
La gratuité et l’idempotence sont deux mécanismes distincts : rejouer la même opération conserve sa clé ; une nouvelle vérification utilise une nouvelle clé. Le retour de l’API et les conditions du droit de contrôle déterminent la facturation.
La période consentie et ses échéances doit également rester visible dans les règles du CRM.
Traiter les erreurs sans masquer le résultat
Faites défiler le tableau horizontalement pour lire toutes les colonnes.
| Réponse | Action |
|---|---|
| 400 · invalid_level ou contrat invalide | Corriger le corps du POST ; un niveau invalide sur ce POST n’est pas documenté en 422. |
| 401 / 403 | Vérifier l’authentification, les droits et le compte. |
| 402 · insufficient_balance | Traiter le besoin de crédit indiqué par la réponse. |
| 404 | Identifier la ressource introuvable ; ne pas en déduire l’absence de tout consentement hors plateforme. |
| 429 · verification_too_soon | Respecter le délai renvoyé. Ne pas contourner la limite avec de nouvelles clés ni ignorer un retrait déjà connu. |
| Panne ou réponse incomplète | Laisser la décision en attente ou en revue selon votre procédure. |
Un HTTP 200 peut porter un verdict défavorable. Conserver l’identifiant, la date et le résultat utile du contrôle ; prévoir une reprise maîtrisée après erreur.
Sources et références
Références consultées le . Exemples rapprochés du contrat et des champs de l’API du projet.
- CertiLeadIntégration acheteurs et documentation API
- CertiLeadNiveaux de vérification
Synthèse informative rédigée par l’équipe CertiLead. Les textes officiels et les conditions du service font référence ; une situation particulière peut demander un examen juridique adapté.