Documentation de l'API

Démarrage rapide

1. Générez une clé dans Clés API. Elle n'est affichée qu'une seule fois : conservez-la en lieu sûr.
2. Appelez l'API avec la plaque recherchée :

curl -H "X-API-Key: VOTRE_CLE" \
  "https://siv.ckd.agency/api/v1/plaque?immat=AA-123-BC"

Vous recevez les caractéristiques du véhicule au format JSON (marque, modèle, motorisation, VIN, dimensions, pneumatiques…).

Authentification

Chaque requête doit porter votre clé API, au choix :

• en-tête X-API-Key: pk_live_… (recommandé) ;
• ou en-tête Authorization: Bearer pk_live_….

Vous pouvez créer plusieurs clés (une par application ou par environnement) et révoquer une clé à tout moment ; elle est alors refusée immédiatement. Toutes les clés d'un compte partagent la même consommation et la même facturation.

Requête

Paramètres (query string)

Réponse

Réponse 200 au format JSON, composée de deux blocs :

• data : les caractéristiques du véhicule (voir référence des champs) ;
• meta : les informations sur votre requête et votre consommation.

Bloc meta

Exemple de réponse complète

{
    "data": {
        "erreur": "",
        "immat": "AA123BC",
        "pays": "FR",
        "marque": "RENAULT",
        "modele": "MEGANE III",
        "modele_en": "MEGANE III Coupe",
        "version": "1.9 dCi",
        "debut_modele": "2008-11",
        "fin_modele": "2015-08",
        "date1erCir_us": "2009-04-18",
        "date1erCir_fr": "18-04-2009",
        "co2": "",
        "energie": "2",
        "energieNGC": "DIESEL",
        "type_moteur": "Diesel",
        "genreVCG": "1",
        "genreVCGNGC": "VP",
        "puisFisc": "7",
        "carrosserieCG": "COUPE",
        "code_carrosserie": "29",
        "carrosserie": "Coupé",
        "code_type_transmission": "1",
        "type_transmission": "Traction avant",
        "capacite_litres": "1.90",
        "code_systeme_alimentation": "11",
        "systeme_alimentation": "Injection directe",
        "valves": "2",
        "puisFiscReelKW": "96 KW",
        "puisFiscReelCH": "131 CH",
        "collection": "",
        "vin": "VF1DZ0N0641118804",
        "variante": "DZ0N06",
        "boite_vitesse": "M",
        "code_boite_vitesse": "",
        "nr_passagers": "",
        "nb_portes": "0",
        "type_mine": "MRE5531A0421",
        "cnit": "MRE5531A0421",
        "couleur": "",
        "poids": "",
        "ptac": "",
        "ccm": "1870 CM3",
        "cylindres": "4",
        "propulsion": "",
        "type_compression": "",
        "longueur": "",
        "largeur": "",
        "hauteur": "",
        "empattement": "",
        "sra_id": "",
        "sra_group": "",
        "sra_commercial": "1.9 dCi (DZ0N, DZ0J, DZ1J, DZ1K)",
        "numero_serie": "41118804",
        "prix_estime": "",
        "logo_marque": "https://siv.ckd.agency/media/vehicules/marques/93.png",
        "photo_modele": "https://siv.ckd.agency/media/vehicules/modeles/31164.jpg",
        "k_type": "31164",
        "tecdoc_manu_id": "93",
        "tecdoc_model_id": "7867",
        "tecdoc_car_id": "31164",
        "tecdoc_vehicules_compatible": "",
        "code_moteur": "F9Q_870,F9Q_872",
        "codes_platforme": "DZ0/1_",
        "liste_sra_commercial": null,
        "pneus": [
            {
                "name": "205/50 R 17",
                "width": 205,
                "height": 50,
                "diameter": 17,
                "load_index": 89,
                "speed_index": "V"
            },
            {
                "name": "205/55 R 16",
                "width": 205,
                "height": 55,
                "diameter": 16,
                "load_index": 91,
                "speed_index": "H"
            }
        ]
    },
    "meta": {
        "request_id": 18342,
        "plate": "AA123BC",
        "country": "FR",
        "source": "upstream",
        "billed": true,
        "unit_price_ht": "0.0600",
        "usage": {
            "period": "2026-11",
            "requests": 152,
            "billed_requests": 98,
            "amount_ht": "5.88"
        }
    }
}

Formats des valeurs

• Toutes les valeurs de data sont des chaînes, sauf les listes pneus et liste_sra_commercial.
• Une valeur inconnue est une chaîne vide "" ; certaines valeurs numériques inconnues valent "0".
• Dates : date1erCir_fr au format JJ-MM-AAAA, date1erCir_us au format AAAA-MM-JJ. debut_modele / fin_modele au format AAAA-MM.
• Certaines valeurs incluent leur unité ("1995 CM3", "200 KW", "2472 KG") : pensez à les nettoyer si vous les traitez comme des nombres.
• De nouveaux champs peuvent être ajoutés à data sans préavis : ignorez les champs que vous ne connaissez pas.

Facturation

• Chaque véhicule est facturé une seule fois par compte, lors de votre première consultation (0,06 € HT au tarif actuel).
• Les consultations suivantes du même véhicule par votre compte sont gratuites, quelle que soit la clé utilisée.
• Les véhicules introuvables (404), les requêtes invalides (422) et les erreurs ne sont jamais facturés.
• Le prix appliqué est celui en vigueur au moment de la requête ; il est indiqué dans meta.unit_price_ht.
• La facturation est mensuelle. Le détail de chaque requête est consultable et exportable (CSV) dans Requêtes.

Erreurs

En cas d'erreur, la réponse contient un bloc error et, dès que la clé est reconnue, le bloc meta :

{
  "error": { "code": "not_found", "message": "Véhicule introuvable" },
  "meta": { "request_id": 18343, "plate": "ZZ999ZZ", "country": "FR", "source": "not_found",
            "billed": false, "unit_price_ht": "0.0000",
            "usage": { "period": "2026-11", "requests": 153, "billed_requests": 98, "amount_ht": "5.88" } }
}

Limites

• 60 requêtes par minute par compte, toutes clés confondues (limite ajustable sur demande). Au-delà : réponse 429. Les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et Retry-After indiquent où vous en êtes.
• Temps de réponse : quelques millisecondes pour un véhicule déjà connu, jusqu'à quelques secondes pour une première recherche. Prévoyez un délai d'attente (timeout) d'au moins 20 secondes.
• Volume mensuel : illimité.

Exemples de code

curl -s -H "X-API-Key: $PLAQUE_API_KEY" \
  "https://siv.ckd.agency/api/v1/plaque?immat=AA-123-BC&pays=FR"

// Laravel
$response = Http::withHeaders(['X-API-Key' => env('PLAQUE_API_KEY')])
    ->timeout(20)
    ->get('https://siv.ckd.agency/api/v1/plaque', ['immat' => 'AA-123-BC', 'pays' => 'FR']);

if ($response->successful()) {
    $vehicule = $response->json('data');      // marque, modele, vin…
    $facture  = $response->json('meta.billed');
} elseif ($response->status() === 404) {
    // véhicule introuvable (non facturé)
}

// PHP natif
$ch = curl_init('https://siv.ckd.agency/api/v1/plaque?' . http_build_query(['immat' => 'AA-123-BC']));
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('PLAQUE_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 20,
]);
$json = json_decode(curl_exec($ch), true);

const url = new URL('https://siv.ckd.agency/api/v1/plaque');
url.searchParams.set('immat', 'AA-123-BC');

const res = await fetch(url, {
  headers: { 'X-API-Key': process.env.PLAQUE_API_KEY },
  signal: AbortSignal.timeout(20000),
});
const body = await res.json();

if (res.ok) {
  console.log(body.data.marque, body.data.modele, body.meta.billed);
} else {
  console.error(res.status, body.error.code, body.error.message);
}

import os, requests

r = requests.get(
    "https://siv.ckd.agency/api/v1/plaque",
    params={"immat": "AA-123-BC", "pays": "FR"},
    headers={"X-API-Key": os.environ["PLAQUE_API_KEY"]},
    timeout=20,
)
body = r.json()
if r.ok:
    print(body["data"]["marque"], body["data"]["modele"], body["meta"]["billed"])
else:
    print(r.status_code, body["error"]["code"])

Référence des champs data

Liste des champs renvoyés, avec un exemple réel. Les champs vides ne sont pas renseignés pour tous les véhicules.

Identification

Modèle

Motorisation

Transmission et carrosserie

Dimensions et poids

Références techniques

Visuels et listes

Bonnes pratiques

• Normalisez et validez la plaque côté client avant l'appel pour éviter les 422.
• Enregistrez meta.request_id avec vos données : il permet de retrouver chaque requête dans votre relevé.
• En cas de 429 ou 502, réessayez avec un délai croissant (1 s, 2 s, 4 s…), au maximum 3 fois.
• Ne réessayez pas automatiquement un 404 : le résultat sera le même.
• Utilisez une clé par application ; révoquez immédiatement une clé compromise et générez-en une nouvelle.
• Les URL logo_marque et photo_modele sont stables : vous pouvez les afficher directement ou les mettre en cache.