API de plaques France, Espagne et Italie : créer une recherche multi-pays

Accepter des plaques françaises, espagnoles et italiennes dans un même formulaire semble trivial : un champ, un appel, un résultat. En pratique, trois questions déterminent la qualité de l'expérience : comment choisir le pays, comment valider la saisie et comment présenter des réponses qui ne contiennent pas les mêmes champs.

Cet article propose une architecture simple pour y répondre, en s'appuyant sur un endpoint unique et le paramètre pays.

Un seul endpoint, un paramètre pays

D'après notre référence API, l'API plaque utilise le même endpoint GET /get-vehicule-info pour tous les pays couverts. Le paramètre pays indique le pays d'immatriculation : FR (valeur par défaut), ES, IT, ainsi que d'autres pays européens. Les conditions d'accès sont décrites sur la page découvrir l'API de recherche par immatriculation.

Cette conception a un avantage : votre code d'appel, votre gestion d'erreurs et votre cache sont communs. Seules la validation et la présentation varient d'un pays à l'autre.

Choisir le pays : ne pas deviner

La tentation est grande de détecter le pays à partir du format. C'est une fausse bonne idée :

Les formats français et italien sont structurellement identiques. Une plaque AB123CD peut exister dans les deux pays et désigner deux véhicules différents. Toute détection automatique finira par se tromper.

Les sources fiables pour présélectionner le pays :

• la langue ou le domaine de la page (.es, /it/) ;
• l'adresse de livraison ou de facturation du client ;
• le choix précédent de l'utilisateur, mémorisé.

Dans tous les cas, affichez le pays sélectionné à côté du champ (un drapeau et un libellé) et laissez l'utilisateur le changer en un clic.

Valider les entrées par pays

Centralisez les règles dans une table de configuration plutôt que de multiplier les if :

const PLATE_RULES = {
  FR: {
    label: "France",
    // SIV uniquement : les plaques FNI, plus variables, sont envoyées sans contrôle strict.
    pattern: /^[A-HJ-NP-TV-Z]{2}\d{3}[A-HJ-NP-TV-Z]{2}$/,
    euPrefix: "F",
  },
  ES: {
    label: "Espagne",
    pattern: /^\d{4}[BCDFGHJKLMNPRSTVWXYZ]{3}$/,
    euPrefix: "E",
  },
  IT: {
    label: "Italie",
    pattern: /^[A-HJ-NPR-TV-Z]{2}\d{3}[A-HJ-NPR-TV-Z]{2}$/,
    euPrefix: "I",
  },
};
 
export function preparePlate(input, country) {
  const rule = PLATE_RULES[country];
  if (!rule) throw new Error(`Pays non pris en charge : ${country}`);
 
  let plate = input.toUpperCase().replace(/[\s.-]/g, "");
  // Retire l'identifiant pays recopié depuis la bande bleue, si le reste correspond au format.
  if (plate.startsWith(rule.euPrefix) && rule.pattern.test(plate.slice(rule.euPrefix.length))) {
    plate = plate.slice(rule.euPrefix.length);
  }
  return { plate, warning: rule.pattern.test(plate) ? null : "Format inhabituel pour ce pays" };
}

Le principe reste le même que pour un pays unique : la validation avertit mais ne bloque pas. Les anciens formats (FNI en France, plaques provinciales en Espagne) ne correspondent pas aux motifs actuels et peuvent pourtant être légitimes. Les détails de chaque pays sont traités dans nos articles sur la matrícula espagnole et la targa italienne.

Harmoniser les réponses

Même structure, remplissage différent

La réponse a la même forme pour tous les pays, mais le nombre de champs renseignés varie selon les sources disponibles. Les réponses d'exemple publiées l'illustrent :

Ces trois exemples ne constituent pas une mesure de couverture : ils montrent seulement qu'une interface multi-pays doit supporter des fiches partielles.

Un modèle interne commun

Plutôt que de manipuler la réponse brute partout, convertissez-la en un objet interne stable, avec null pour les valeurs absentes :

const EMPTY = new Set(["", "INCONNU"]);
const clean = (value) => (value == null || EMPTY.has(String(value).trim()) ? null : String(value).trim());
 
export function toVehicle(data, country) {
  return {
    country,
    plate: clean(data.immat),
    make: clean(data.marque),
    model: clean(data.modele),
    version: clean(data.version),
    fuel: clean(data.energieNGC),
    powerHp: clean(data.puisFiscReelCH),
    firstRegistration: clean(data.date1erCir_fr),
    kType: clean(data.k_type),
    vin: clean(data.vin),
    // Champs propres à la carte grise française : ignorés hors de France.
    fiscalPower: country === "FR" ? clean(data.puisFisc) : null,
    typeMine: country === "FR" ? clean(data.type_mine) : null,
  };
}

Les noms de champs source (marque, energieNGC, k_type…) sont ceux de la réponse documentée ; les noms de destination sont libres et propres à votre application.

Une présentation par pays

Définissez, pour chaque pays, la liste des champs affichés. Un champ null est masqué ou affiché « non renseigné » selon son importance. Évitez d'afficher la puissance fiscale française pour une voiture espagnole : l'information n'aurait pas de sens.

Les détails qui font la différence

• Clé de cache : indexez sur le couple pays + plaque normalisée, jamais sur la plaque seule, puisque la même chaîne peut exister dans deux pays.
• Journalisation : enregistrez le pays envoyé. En cas de réclamation (« ce n'est pas mon véhicule »), c'est la première chose à vérifier.
• Messages d'erreur : « Aucun véhicule trouvé pour cette plaque italienne » est plus utile que « Véhicule introuvable », car il invite à vérifier le pays.
• Alternative : en cas d'échec, proposez la recherche par VIN, indépendante du pays d'immatriculation.

Cas concret : un comparateur de pièces européen

Un comparateur sert des clients en France, en Espagne et en Italie. Son parcours :

1. le pays est présélectionné selon la version linguistique du site ;
2. preparePlate normalise la saisie et signale un format inhabituel ;
3. le serveur appelle l'API avec pays et met en cache le résultat sur pays + plaque ;
4. toVehicle convertit la réponse ; la fiche n'affiche que les champs prévus pour ce pays ;
5. le K-Type, quand il est présent, interroge le catalogue commun ; sinon, le client choisit son modèle.

Le même code sert les trois pays ; seules deux tables de configuration (validation et affichage) changent.

Conclusion

Une recherche multi-pays réussie repose moins sur l'appel API que sur ce qui l'entoure : un pays choisi explicitement, une validation par pays qui avertit sans bloquer, un modèle interne qui absorbe les différences de remplissage. Avec ces trois briques, ajouter un pays revient à compléter deux tables de configuration.

FAQ

Peut-on détecter automatiquement le pays d'une plaque ?

Pas de manière fiable : les formats français et italien sont identiques dans leur structure. Le pays doit être choisi ou déduit du contexte (langue, adresse).

Les réponses ont-elles les mêmes champs pour tous les pays ?

La structure est la même, mais le nombre de champs renseignés dépend des sources disponibles dans chaque pays. Prévoyez des fiches partielles.

Faut-il une clé API par pays ?

Non. Le même abonnement et le même endpoint servent tous les pays couverts ; seul le paramètre pays change.

Comment éviter de mélanger deux véhicules dans le cache ?

Utilisez une clé composée du pays et de la plaque normalisée, par exemple IT:FB587VF.