Corrections de la documentation
La documentation a été entièrement réécrite le 15 octobre 2026 à partir du code de l'API. L'API elle-même n'a pas changé à cette occasion : ce sont les descriptions qui étaient fausses. Si votre intégration a été écrite d'après l'ancienne version, vérifiez les points ci-dessous.
À vérifier en priorité
| Ancienne documentation | Comportement réel |
|---|---|
Le verdict est dans status | Le verdict est dans result |
Envoyer "smtp": true déclenche la vérification SMTP | Avec une clé API, smtp dans le corps est ignoré : seule la configuration de la clé décide |
Blocs syntax.valid, dns.hasMxRecords, disposable.isDisposable, typo.hasTypo, smtp.deliverable… | Chaque contrôle est sous features, avec result / score / message / reasonCode / details. Dans features, result: "invalid" signifie « signal détecté ». Raccourcis à la racine : disposable, alias, freeProvider, businessEmail |
metadata.creditsUsed, metadata.creditsRemaining, metadata.processingTimeMs | metadata.credits.used, metadata.credits.remaining (renseigné seulement après un SMTP), metadata.processingTime |
| Le widget s'intègre avec une clé API dans le JavaScript de la page | Le widget s'installe avec une balise <script> sans aucun secret (data-ywc-widget) |
| Batch, gestion des clés et solde de crédits sont appelables avec un JWT d'intégration | Ces routes sont réservées au tableau de bord ; elles ne font pas partie de l'API publique |
Autres corrections
| Sujet | Ancienne documentation | Comportement réel |
|---|---|---|
| Erreurs de validation du corps | 422 Unprocessable Entity | 400 Bad Request, message sous forme de tableau |
Corps de l'erreur 402 | Champs reason, required, balance | Seuls statusCode, message, code, timestamp, path sont renvoyés |
429 par IP | Corps JSON | Corps en texte brut |
RateLimit-Reset | Horodatage | Nombre de secondes avant la réinitialisation |
| Limites par clé | « Requêtes par minute, heure et jour configurables par clé » | Aucune limite de débit par clé ; la limite est de 100 requêtes/min par IP. Une clé peut en revanche avoir un plafond de crédits journalier et mensuel (429 API_KEY_BUDGET_EXCEEDED) |
| Domaine accept-all | deliverable: true avec catchAllDetected: true | Verdict unknown, features.catchAll, avertissement CATCH_ALL_DOMAIN |
Clés ywc_test_ | Clés de développement local | Même comportement et même facturation que ywc_live_ |
Restriction allowedDomains sur une clé serveur | Recommandée | Bloque tous les appels serveur (pas d'en-tête Origin) ; restreignez par IP |
| Expiration des crédits | « Les crédits n'expirent pas » | L'allocation mensuelle expire au renouvellement ; les packs achetés n'expirent jamais |
| Traitement par lots | Excel accepté, 10 Mo, ~200 000 lignes | CSV ou TXT, 15 Mo, 500 000 lignes |
| Exports | CSV, XLSX, PDF | CSV, Excel, texte, JSON, NDJSON, plus le rapport PDF |
| Score | Barème de points fixe | Barème à plafonds et pénalités cumulées ; valid sous 70 devient risky |
/v2/credits/balance | Exemple avec clé API dans le démarrage rapide | Réservé au tableau de bord |
Ajouts
Sujets qui n'étaient pas documentés : warnings[], finalDecision et les politiques de validation, la correction vérifiée typoCorrection, le signal typosquat, network et ses effets en appel serveur, les restrictions allowedIps, la rotation avec période de grâce, les plafonds de crédits par clé, le mode audit du traitement par lots, POST /v2/email/enrich et les endpoints d'autocomplétion de prénom, de nom et de partie locale.