Guide d'intégration

Démarrage

En une minute

Obtenez une clé. Créez un compte : 14 jours et 100 validations offertes, sans carte bancaire. La clé (sk_live_…) s'affiche une seule fois. Ensuite, elle se régénère depuis l'espace client.
Appelez POST /validate avec la clé dans l'en-tête X-API-Key.
Lisez le résultat : adresse standardisée, livrabilité, coordonnées, et cache_key.

POST/validatecurl

curl -sS https://kder-ai.com/validate \
  -H "X-API-Key: sk_live_VOTRE_CLE" \
  -H "content-type: application/json" \
  -d '{"address": {"street": "1 Rue de Paris", "city": "Saint-Denis", "state": "RE", "zip": "97400", "country": "RE"}}'

Dans tous les exemples, remplacez sk_live_VOTRE_CLE par votre clé.

Pas encore de compte ? Testez une adresse gratuitement : la page n'écrit rien et vous montre exactement ce que l'API renvoie.

Accès

S'authentifier

Deux portes, une seule réponse. Seuls l'en-tête envoyé et le paiement changent.

Abonnement

Une boutique

Vous envoyez: X-API-Key: sk_live_…, la clé affichée à l'inscription, ou régénérée dans l'espace client.
Vous payez: Le quota mensuel de votre plan. Rien n'est encaissé à l'appel.

Paiement à l'appel · x402

Un agent autonome

Vous envoyez: X-PAYMENT : une autorisation EIP-3009 signée, construite à partir du corps de la réponse 402 (champ accepts).
Vous payez: 0,02 USDC par validation encaissée.

La clé a la priorité. Si les deux en-têtes partent ensemble, l'abonnement tranche : un appel couvert par un compte n'est jamais encaissé en USDC. Chaque réponse dit comment elle a été payée, dans X-Payment-Mode.

Ne mettez jamais la clé dans un dépôt git, un fichier partagé ou une URL. Elle vit dans une variable d'environnement ou un gestionnaire de secrets, et ne circule qu'en https. Une clé qui a fuité se régénère en un clic : l'ancienne cesse de fonctionner immédiatement.

Référence

Le contrat

Requête

POST https://kder-ai.com/validate, corps JSON, en-tête content-type: application/json.

Corps de la requêteJSON

{"address": {
   "street": "1 Rue de Paris",   // requis
   "city": "Saint-Denis",        // requis
   "state": "RE",                // requis (region ou etat)
   "zip": "97400",               // requis
   "country": "RE"               // optionnel, "US" par defaut (ISO 2 lettres)
}}

Réponse `200`

200 OKJSON

{
  "result": {
    "validated": true,
    "standardized": {"line1": "1 RUE DE PARIS", "line2": "", "city": "SAINT-DENIS",
                     "state": "RE", "zip": "97400", "country": "RE"},
    "latitude": -20.8823, "longitude": 55.4504,
    "deliverability": "residential",
    "confidence": 0.99,
    "degraded": false,
    "cache_key": "9b7a..."
  },
  "price_paid": 0.0,
  "transaction_id": null
}

validated: Le fournisseur a reconnu l'adresse. false n'est pas toujours un verdict : lisez degraded avant d'en tirer une conclusion.
deliverability: residential, commercial, unknown ou invalid : le code du fournisseur, traduit en clair.
confidence: Indice entre 0 et 1 : un indice, pas une garantie. Choisissez votre seuil selon le taux de retour que vous acceptez.
degraded: true : le fournisseur n'a pas répondu (panne, délai dépassé, disjoncteur ouvert). La réponse ne dit rien de l'adresse. Ne l'enregistrez jamais comme « adresse invalide ».
price_paid: 0.0 pour un appel couvert par un abonnement ; le prix en USDC pour un appel payé.
cache_key: Pseudonyme de l'adresse (SHA-256). Il sert au cache et à toute demande d'effacement. Conservez-le : il ne contient pas l'adresse.

En-têtes de réponse

Ce sont les en-têtes que la route pose vraiment. Aucun autre n'est promis.

X-Payment-Mode: api_key ou x402 : comment l'appel a été payé.
X-Plan: trial, starter, pro ou enterprise. Mode clé seulement.
X-Quota-Remaining: Validations restantes ce mois-ci. Absent : plan illimité, l'absence veut dire « sans plafond ».

Référence

Les codes de retour, et quoi faire

Huit codes possibles sur /validate. Les trois refus du mode clé (401, 402, 403) sont distincts exprès : traitez-les chacun à sa façon.

Servi

200

Lisez le résultat.

À corriger chez vous

401 403 422

Relancer sans rien changer ne sert à rien.

Limite ou paiement

402 429

Pas une panne : le corps ou Retry-After dit quoi faire.

Incident côté service

500 503

Réessayez. Jamais une demande de paiement.

200Validation servie
Succès

Lisez result. Gardez cache_key : c'est votre pseudonyme de cette adresse, il sert à demander un effacement.

Rien à relancer
401Clé API inconnue
À corriger chez vous

La clé est incomplète, révoquée (régénérée) ou destinée à un autre service. Corrigez la variable d'environnement. Ne réessayez pas en boucle.

Non : corrigez la clé
402Quota du mois consommé, ou aucun paiement valide
Limite ou paiement

Lisez le corps de la réponse : il dit lequel des deux cas s'applique. Un 402 de quota n'est pas une panne.

Selon le corps

{"reason": "quota_atteint"}Plafond d'usage atteint. Ce n'est pas une panne. Le compteur repart le 1er du mois (UTC).

{"x402Version": 1}Le paiement manque pour cet appel. Le prix est dans le champ accepts.
403Compte expiré
À corriger chez vous

L'essai gratuit est terminé et le compte est resté sur le plan d'essai. Passez à un plan payant : rien n'est prélevé automatiquement.

Non : changez de plan
422Requête mal formée
À corriger chez vous

Un champ est absent ou vide. street, city, state et zip sont obligatoires ; country vaut US par défaut.

Après correction
429Plafond d'essais gratuits atteint
Limite

Concerne /validate-form, l'essai sans compte, pas l'API payante. Attendez le délai annoncé dans Retry-After, ou créez un compte.

Après Retry-After
500Paiement encaissé, mais registre injoignable
Incident côté service

Le service refuse de servir une validation qu'il ne peut pas inscrire. Réessayez. Si l'appel était payé, citez transaction_id : le rapprochement se fait à la main.

Oui, gardez transaction_id
503Comptes clients ou base injoignable
Incident côté service

La clé n'a pas pu être vérifiée (ce n'est pas un refus), ou la base ne répond pas. Réessayez dans quelques minutes : rien n'a été consommé.
Un 503 n'est jamais une demande de paiement.

Oui, dans quelques minutes

Facturation

Ce qui n'est pas repayé, et ce qui est plafonné

Cache (verdict): Une même adresse normalisée ne réinterroge pas le fournisseur pendant 30 jours. C'est cache_key qui le garantit.; À faireAppelez sans craindre de payer deux fois la même question. Pour forcer un nouvel appel, changez l'adresse : l'API ne devine pas.
Cache (dégradé): Un résultat degraded est gardé 5 minutes, pas 30 jours : « le fournisseur n'a pas répondu » n'est pas un verdict.; À faireTraitez degraded: true comme « réessayez plus tard ». Après cette fenêtre courte, le même appel obtient une vraie réponse.
Quota: Mensuel, sur le mois calendaire UTC : il repart le 1er du mois, pas 30 jours après votre premier appel.; À faireSurveillez X-Quota-Remaining. Écrivez-nous avant la limite plutôt qu'après.
Prix à l'appel: 0,02 USDC par validation encaissée (mode x402). Un appel couvert par un abonnement annonce price_paid: 0.0.; À faireUn agent qui paie lit le corps 402 (accepts) : le prix y figure, il n'est jamais à deviner.
Essai sans compte: 10 validations par jour et par visiteur sur /validate-form.; À fairePour un usage régulier, créez un compte : 100 validations offertes, puis un plan mensuel.

Exemples

Cas pratiques

Quatre façons de brancher l'API. Chaque exemple lit la clé dans une variable d'environnement.

1. Appel direct (PowerShell)

POST/validatePowerShell

$cle = $env:ADDRESS_VALIDATOR_KEY
$corps = '{"address":{"street":"1 Rue de Paris","city":"Saint-Denis","state":"RE","zip":"97400","country":"RE"}}'
$r = Invoke-WebRequest -Uri https://kder-ai.com/validate -Method POST `
     -Headers @{ "X-API-Key" = $cle } -ContentType "application/json" -Body $corps
$r.StatusCode
$r.Headers["X-Payment-Mode"], $r.Headers["X-Plan"], $r.Headers["X-Quota-Remaining"]
($r.Content | ConvertFrom-Json).result

2. Import CSV (Python)

verifier_colis.pyPython

"""Verifie un CSV d'adresses et ecrit le verdict a cote.

Le fournisseur n'est interroge qu'une fois par adresse : la reponse est mise en
cache (30 jours pour un verdict), donc une seconde execution sur le meme fichier
ne coute rien de plus.
"""
import csv
import os
import time

import requests

CLE = os.environ["ADDRESS_VALIDATOR_KEY"]  # jamais dans le code, jamais dans git
API = "https://kder-ai.com/validate"

with open("colis.csv", newline="", encoding="utf-8") as source, open(
    "colis-verifies.csv", "w", newline="", encoding="utf-8"
) as cible:
    lecteur = csv.DictReader(source)
    champs = list(lecteur.fieldnames) + [
        "validated", "deliverability", "degraded", "note",
    ]
    sortie = csv.DictWriter(cible, fieldnames=champs)
    sortie.writeheader()
    for ligne in lecteur:
        reponse = requests.post(
            API,
            headers={"X-API-Key": CLE},
            timeout=30,
            json={
                "address": {
                    "street": ligne["adresse"],
                    "city": ligne["ville"],
                    "state": ligne["region"],
                    "zip": ligne["code_postal"],
                    "country": ligne.get("pays") or "US",
                }
            },
        )
        if reponse.status_code in (500, 503):
            time.sleep(5)  # panne cote service : rien n'a ete consomme
            continue
        if reponse.status_code == 429:
            time.sleep(int(reponse.headers.get("Retry-After", "60")))
            continue
        if reponse.status_code != 200:
            sortie.writerow({**ligne, "note": f"refus {reponse.status_code}"})
            continue
        resultat = reponse.json()["result"]
        sortie.writerow(
            {
                **ligne,
                "validated": resultat["validated"],
                "deliverability": resultat["deliverability"],
                "degraded": resultat["degraded"],
                "note": "a reverifier (fournisseur injoignable)"
                if resultat["degraded"]
                else "",
            }
        )

Ce que l'exemple illustre, et rien d'autre : la clé vient d'une variable d'environnement, le 429 est respecté (le délai est lu, pas deviné), et un résultat degraded est marqué « à re-vérifier » au lieu d'être écrit comme une adresse invalide.

Ni application Shopify, ni extension WooCommerce. Rien n'est à installer dans votre boutique : l'API est le contrat, et l'appel part de votre service. C'est ce qui vous laisse choisir votre seuil de confiance.

3. Shopify

Déclencheur: Un webhook orders/create (ou votre étape de préparation de colis) appelle votre service, qui interroge /validate avec l'adresse de livraison de la commande.
Correspondance des champs: shipping_address.address1 → street (ajoutez address2 à line2 côté résultat)
city → city
province_code → state
zip → zip
country_code → country
Décision: validated: false : signalez la commande dans votre back-office avant l'expédition. degraded: true : ne bloquez rien, reprogrammez un contrôle.
Ce que nous ne fournissons pas: Aucune application Shopify prête à installer : l'appel vient de votre service.

4. WooCommerce

Déclencheur: L'action woocommerce_checkout_order_processed (commande payée), ou un cron qui parcourt les commandes en préparation (wc_get_orders( ['status' => 'processing'] )).
Correspondance des champs: $order->get_shipping_address_1() → street
$order->get_shipping_city() → city
$order->get_shipping_state() → state
$order->get_shipping_postcode() → zip
$order->get_shipping_country() → country
Traçabilité: Enregistrez cache_key avec la commande : c'est le seul identifiant de l'adresse valable pour une demande d'effacement.
Ce que nous ne fournissons pas: Aucune extension WooCommerce : l'appel vient de votre service.

Dans tous les cas : un seul appel par adresse et par commande, jamais dans une boucle qui ignore les codes de retour. Un 402 de quota n'est pas une panne : c'est une limite, et elle se lit dans la réponse.

Développeurs et agents IA

Paiement à l'appel, sans compte

Un agent autonome n'a besoin ni de compte ni de clé. Chaque validation encaissée coûte 0,02 USDC, payée avec x402 sur le réseau Base.

1Appelez POST /validate avec le corps habituel. Sans paiement, la réponse est un 402 dont le corps porte {"x402Version": 1} et le champ accepts : le prix y figure.
2Signez l'autorisation. Construisez une autorisation EIP-3009 à partir de accepts, et renvoyez la requête avec l'en-tête X-PAYMENT.
3Lisez la réponse. X-Payment-Mode vaut x402, price_paid donne le prix en USDC, et transaction_id est la référence à citer en cas de 500.

Pour vos agents, tout se découvre sans payer :

À savoir avant d'intégrer

Limites

États-Unis Optimisé: Le fournisseur est optimisé pour les adresses des États-Unis : adresse standardisée, coordonnées, livrabilité et indice de confiance.
France et outre-mer Vérifié (BAN): Les adresses françaises et d'outre-mer sont vérifiées par la Base Adresse Nationale : score, code postal et ville doivent concorder. Les autres pays restent partiellement vérifiés.
degraded: true À re-vérifier: Le fournisseur n'a pas répondu. La réponse ne dit rien de l'adresse : ce n'est pas un refus. Relancez plus tard.
Intégrations: Ni application Shopify, ni extension WooCommerce : l'appel part de votre propre service.

Ce que nous conservons, et ce que nous ne conservons pas. Pour un appel payant ou abonné : une empreinte de l'adresse (cache_key) et l'issue, jamais l'adresse elle-même. Pour l'essai gratuit sans compte : rien, seulement un compteur anonyme qui fait respecter le plafond. Une demande d'effacement se fait avec le cache_key.

Passer à la pratique

Créez un compte pour obtenir votre clé, ou testez d'abord une adresse sans compte.

Créer un compte Voir les tarifs Tester une adresse

En une minute

S'authentifier

Une boutique

Un agent autonome

Le contrat

Requête

Réponse 200

En-têtes de réponse

Les codes de retour, et quoi faire

200Validation servie

401Clé API inconnue

402Quota du mois consommé, ou aucun paiement valide

403Compte expiré

422Requête mal formée

429Plafond d'essais gratuits atteint

500Paiement encaissé, mais registre injoignable

503Comptes clients ou base injoignable