Données SIV via API : le guide complet des champs

Une réponse d'API plaque contient des dizaines de champs aux noms parfois cryptiques : puisFisc, genreVCGNGC, carrosserieCG, k_type… Pour en tirer le meilleur, il faut savoir ce que chacun représente, d'où il vient et comment l'exploiter.

Ce guide passe en revue les champs principaux, en les reliant aux rubriques du certificat d'immatriculation et en indiquant leurs usages typiques.

Lire la carte grise pour comprendre l'API

La plupart des champs renvoyés correspondent à une rubrique codifiée du certificat d'immatriculation. Connaître ces codes aide énormément à comprendre la réponse.

Les champs d'identification

• immat : la plaque normalisée, sans tirets. Utilisez-la comme clé de cache.
• vin : le numéro de châssis de 17 caractères. C'est l'identifiant le plus stable du véhicule ; stockez-le systématiquement.
• type_mine et cnit : codes d'homologation qui identifient précisément le type de véhicule. Ils servent notamment aux assureurs et aux experts.
• numero_serie : partie séquentielle du VIN attribuée par le constructeur.

Les informations générales

• marque, modele : identité commerciale, en majuscules.
• sra_commercial : libellé complet de la version, souvent le plus parlant pour l'utilisateur (ex. « 1.9 DCI 130 XV DE FRANCE »).
• couleur : couleur dominante déclarée.
• genreVCGNGC : genre national, par exemple VP (véhicule particulier), CTTE (camionnette), MTL (motocyclette légère).
• carrosserieCG : code carrosserie, par exemple CI (conduite intérieure), BREAK, COUPE.
• collection : indique si le véhicule est immatriculé en collection.

Les données moteur et transmission

• energieNGC : énergie en clair (ESSENCE, DIESEL, ÉLECTRIQUE, hybrides…). Le champ energie en donne le code numérique.
• puisFisc : puissance fiscale en chevaux fiscaux, base du calcul de la taxe régionale de la carte grise.
• puisFiscReelKW et puisFiscReelCH : puissance réelle en kilowatts et en chevaux, avec leur unité (ex. "66 KW", "90 CH").
• type_moteur, systeme_alimentation, valves : type de motorisation, système d'injection et nombre de soupapes par cylindre.
• ccm : cylindrée, avec son unité (ex. "1560 CM3") ; capacite_litres la donne en litres.
• cylindres : nombre de cylindres.
• code_moteur : code(s) moteur constructeur, précieux pour les pièces moteur et l'entretien. Plusieurs codes peuvent être renvoyés, séparés par des virgules.
• boite_vitesse : M pour manuelle, A pour automatique ; code_boite_vitesse précise le modèle de boîte.
• type_transmission : roues motrices (ex. « Traction avant »).

Gabarit, poids et environnement

• nb_portes et nr_passagers : nombre de portes et de places assises.
• poids : masse du véhicule, avec unité.
• ptac : poids total autorisé en charge, en kilogrammes. Il détermine notamment le permis nécessaire.
• co2 : émissions en grammes par kilomètre, utiles pour le malus, la fiscalité des véhicules de société ou les analyses environnementales.

Les références techniques

Ces champs ne figurent pas sur la carte grise mais proviennent de référentiels professionnels :

• k_type et tecdoc_car_id : identifiant TecDoc du véhicule, clé d'accès aux catalogues de pièces.
• tecdoc_manu_id et tecdoc_model_id : identifiants constructeur et gamme dans TecDoc.
• pneus : tableau des dimensions de pneus homologuées (largeur, série, diamètre, indices de charge et de vitesse).
• photo_modele et logo_marque : URL d'une photo du modèle et du logo de la marque, pratiques pour l'affichage.
• sra_id et sra_group : classification SRA utilisée par les assureurs pour la tarification et la réparation.

Pour exploiter le K-Type, consultez notre tutoriel Intégrer Ktype avec TecDoc.

Formats, unités et valeurs manquantes

Quelques règles à intégrer dans votre code :

1. Les valeurs scalaires sont des chaînes, y compris les nombres (seul le tableau pneus contient des nombres). Convertissez-les explicitement.
2. Certaines valeurs incluent leur unité ("1741 KG", "66 KW", "1560 CM3"). Extrayez la partie numérique avec une expression régulière si vous devez calculer.
3. Les dates existent en deux formats : JJ-MM-AAAA et AAAA-MM-JJ. Préférez le second pour les traitements.
4. Une donnée indisponible peut être absente, vide ou valoir INCONNU. Affichez alors un tiret. Le nombre de portes peut valoir "0" lorsqu'il n'est pas renseigné.
5. Vérifiez code_erreur à la racine de la réponse : il vaut 200 en cas de succès.

const kw = Number.parseInt(data.puisFiscReelKW ?? "", 10); // 66
const afficher = (v?: string) => (!v || v === "INCONNU" ? "—" : v);

Conclusion

Les champs d'une API plaque reprennent pour l'essentiel les rubriques de la carte grise, enrichies de références techniques comme le K-Type ou les codes SRA. En comprenant leur origine, leur format et leurs limites, vous exploitez la réponse en toute confiance. La liste exhaustive est disponible dans la documentation de l'API.

FAQ

Tous les véhicules ont-ils tous les champs ?

Non. Selon l'âge et le type de véhicule, certains champs peuvent manquer ; votre code doit le prévoir.

Quelle est la différence entre puissance fiscale et puissance réelle ?

La puissance fiscale (CV) est une valeur administrative servant aux taxes ; la puissance réelle (kW) est la puissance mécanique maximale du moteur.

Le K-Type figure-t-il sur la carte grise ?

Non, c'est un identifiant du référentiel TecDoc, ajouté par le croisement avec les données techniques.