Comment transformer un VIN ou une liste de stock en photo pour chaque véhicule dans un logiciel de concession

Une fiche de stock dans un CRM, un ERP ou un système de gestion de concession (DMS) naît sous la forme d’un VIN, d’un numéro de stock et d’un prix. La photo arrive quand le photographe passe sur le parc, et pour certains véhicules, elle n’arrive jamais : un véhicule en transit, une reprise encore en reconditionnement, une importation dont le nom de modèle ne correspond à rien dans le flux d’images du DMS, une voiture des années 1990 dont personne n’a acquis de photo presse sous licence. Chaque écran qui affiche cette fiche — la liste du vendeur, l’estimation de l’acheteur, le devis du client — affiche à la place un espace réservé gris.

Les outils pour concessionnaires et importateurs qui utilisent l'API remplissent cet espace réservé à partir de ce que la fiche contient déjà. Si elle a un VIN, l'image n'est qu'à un décodage gratuit. Si elle n'a qu'une ligne dans une liste de stock, la résolution en texte libre fait l'affaire. Dans les deux cas, la fiche finit par contenir un identifiant de véhicule stable, et chaque écran affiche la même voiture de la même façon.

• Décoder dès la saisie. Le VIN est décodé une seule fois, à la création de la fiche, et l'identifiant du véhicule dans le catalogue est stocké à côté. Rien en aval n'écrit de marque ni de modèle.
• Une vue pour la liste, une pour la fiche. Une vue side de profil dans un cadre large pour les listes de stock ; front-3-4 pour la fiche détaillée et le devis.
• Un large historique d'années. Le stock importé et d'occasion remonte aux années 1990, et son rendu est le même que celui des nouveaux arrivages : le catalogue couvre de 1990 à l'année-modèle en cours, modèles du marché intérieur japonais inclus.
• Des URL signées dans l'application. Le CRM est un navigateur : il charge donc des URL signées sans clé, émises par le serveur, jusqu'à cinquante par appel, et renouvelées pour les fiches qui restent actives plus d'une semaine.

GET /api/v1/vin/{vin} est gratuit et ne nécessite qu'une clé API. Il renvoie l'année, la marque, le modèle, la finition, le type de carrosserie et le moteur décodés, ainsi que tous les autres attributs connus des données vPIC de la NHTSA et, lorsque le catalogue contient le véhicule, un objet vehicle avec son identifiant stable et un image_path prêt à l'emploi. Les VIN partiels fonctionnent aussi : au moins cinq caractères, * pour chaque position inconnue, plus une indication year facultative.

Les véhicules d’importation arrivent souvent sous forme de tableur : une année, une marque, un nom de modèle dans l’orthographe choisie par la maison de ventes, un code de grade ou de finition. POST /api/v1/images/resolve est gratuit et déterministe : il extrait de la phrase les mots désignant l’année, la couleur et la vue, interroge le catalogue avec le reste, et renvoie des paramètres exacts accompagnés d’un indice de confiance exploitable.

Le véhicule est le bon (le Toyota Voxy 2019), mais la confiance est low, car « ZS » est une finition que le catalogue ne connaît pas et la correspondance a dû la contourner. Lors d’un import par lots, considérez high comme acquis, et soumettez medium et low à une personne avec la liste candidates. Lorsque la feuille contient déjà l’année et la marque dans des colonnes distinctes, envoyez-les dans les champs year et make et ne laissez que le modèle dans query ; la correspondance est bien plus nette. Une phrase sans aucun terme lié à un véhicule renvoie une 400, et une marque sans modèle correspondant renvoie une 404 qui liste les années de la marque afin que vous puissiez demander le modèle.

Quelle que soit la voie empruntée, stockez vehicle.id (ou params.vehicle_id) dans la fiche de stock, dans une simple colonne de type chaîne. Il est déterministe et permanent : le même véhicule a le même identifiant à chaque déploiement et après chaque version du catalogue, il peut donc servir de clé étrangère en toute sécurité. Dès lors, chaque requête d’image est vehicle=veh_…, impossible à mal orthographier, et une marque renommée par un constructeur ou reclassée par une source ne casse jamais une URL stockée.

Les listes de stock sont larges et peu hautes, la vue de profil dans un cadre 2:1 est donc le choix habituel : chaque véhicule est orienté dans le même sens et repose sur la même ligne de base. trim=1&padding=6 recadre sur la voiture avant l’ajustement, si bien qu’un Hilux et une Yaris remplissent la ligne de la même manière ; fit=contain maintient le canevas à exactement 640×320 avec des marges transparentes. La page de détail utilise front-3-4 en 1024, et les deux partagent un cache : une peinture non spécifiée est argent sur les deux.

Le CRM s'exécute dans un navigateur, et un navigateur ne doit jamais détenir la clé API. Lorsqu'un écran affiche une page du stock, le serveur émet une URL signée par fiche avec POST /api/v1/image-urls (jusqu'à cinquante par appel, un crédit chacune) et la page les charge comme n'importe quelle image. Deux paramètres comptent pour une fiche qui reste en stock pendant des mois :

• ttl_seconds: 604800 avec renew: true : l'URL continue de fonctionner au-delà du TTL de sept jours, et chaque semaine supplémentaire au cours de laquelle quelqu'un ouvre réellement la fiche coûte un crédit de plus. Les semaines où personne ne consulte la voiture ne coûtent rien.
• Une Idempotency-Key par page de synchronisation : une requête relancée rejoue la première réponse et rien n'est émis deux fois.

Restreignez la clé émettrice à l'origine du CRM dans le tableau de bord : une URL qui fuite vers un autre site renverra 403. Révoquer la clé invalide toutes les URL qu'elle a émises. Si le solde vient à s'épuiser, un renouvellement renvoie 402 et la même URL refonctionne dès que les crédits arrivent ; le rechargement automatique élimine ce cas d'échec. Le cycle de vie complet est décrit dans la documentation des URL signées.

• SDK : client.decodeVin(vin, { year? }), client.resolve(query), client.getImage({ vehicle, … }) et client.createImageUrls(…), comme ci-dessus.
• MCP : decode_vin, resolve_vehicle, get_car_image et create_car_image_urls font partie de l’ensemble d’outils de base, de sorte qu’un assistant ayant le système de stock en contexte peut répondre à « photo du stock 4471 » à partir du VIN de la fiche. La configuration est décrite sur la page MCP ; les champs et erreurs du décodeur figurent dans la documentation VIN.