Bourses aux épaves et plateformes d’enchères : mise en ligne, enchère et calcul via l’API

Où les données manquent dans le processus

Une bourse aux épaves repose sur la confiance des deux côtés dans l’annonce : le vendeur doit décrire un véhicule complètement en peu de temps, l’enchérisseur décider pendant la période d’enchères ce qu’il vaut pour lui. Des manques apparaissent régulièrement à cinq endroits :

• À la mise en ligne. Le VIN est recopié depuis le rapport d’expertise ou depuis une photo ; un caractère inversé n’apparaît que lorsqu’un enchérisseur a calculé le mauvais véhicule.
• Dans la description du dommage. Chaque vendeur photographie et formule différemment. Deux annonces pour le même dommage ne sont pas comparables.
• Dans les images. Personne ne vérifie systématiquement avant la publication si une photo montre encore une plaque lisible ; dans les enchères de pièces, les images montrent des numéros de série et autres identifiants propres à l’exemplaire que le vendeur ne veut pas divulguer avant l’adjudication.
• Dans le texte de l’annonce. Titre, description et liste d’équipements sont rédigés à la main pour chaque véhicule — et une seconde fois dans une autre langue pour les enchérisseurs étrangers.
• Au moment de l’offre. Le démolisseur calcule d’expérience pendant la période d’enchères : quelles pièces rapportent, quels équipements le véhicule possède, peut-il être transporté comme marchandise ? L’équipement ne figure pas sur les photos, et la qualification de VHU reste une estimation.

Ce que l’API fournit

Un déroulé du début à la fin

1. Identifier le véhicule. Le vendeur charge les photos ; le backend lit le VIN sur la photo du véhicule avec POST /scanner/vin/extract. S’il est illisible, vin vaut null — le champ reste vide et devient une reprise. Si le certificat d’immatriculation est disponible, POST /vehicles/intake avec fileUrl traite cette étape et la suivante en un appel.
2. Recouper le véhicule et obtenir un `tapiId`. Avec provider 2 ou 3, GET /vin/{vin}/vehicle répond directement. Un système tiers ne peut pas interroger directement le fournisseur 1 : le backend crée une session à partir de vin, returnUrl et state avec POST /vin/redirect-sessions et envoie l’utilisateur vers redirectUrl ; après le recoupement dans l’interface tapinoma, il revient sur returnUrl avec status=completed, tapiId et state — ou avec status=cancelled. Aucune donnée véhicule ne figure dans la redirection ; la session expire après dix minutes. Le déroulé VIN et les appels d’annonce ultérieurs passent par la même clé, car le tapiId est lié au client qui l’a obtenu.
3. Documenter état et dommage. Le tour du véhicule avec jusqu’à 8 vues part vers POST /vision/condition-report et revient sous forme de constat par zone avec note globale A/B/C. Le dommage lui-même est décrit par POST /vision/damage/describe à partir de 1 à 5 vues en six sections fixes ; les sections sans constat sont indiquées comme telles, et seul le visible est décrit — voir Véhicules accidentés.
4. Vérifier les images avant la publication. POST /vision/license-plate lit, à partir de 3 vues au plus, caractères, pays, confiance et position sur le véhicule (vorne/hinten) ; avec les caractères, votre logiciel recoupe le véhicule avec le mandat, et un plates non vide montre avant la publication qu’une image contient encore une plaque lisible. Le masquage lui-même n’est pas assuré par l’API. Dans les enchères de pièces, POST /vision/identifiers/redact anonymise les identifiants propres à l’exemplaire dans l’image de la pièce avant sa mise en ligne ; les identifiants de type et OE restent visibles — voir Photos de pièces.
5. Générer le texte de l’annonce. POST /vehicles/{tapiId}/listing avec language par marché cible et les indications du vendeur dans notes renvoie titre, description et points forts d’équipement à partir des données véhicule documentées. Le texte n’invente aucune caractéristique et ne mentionne ni prix ni état.
6. Côté enchérisseur : calculer avant d’enchérir. Avant l’analyse, l’enchérisseur achève le recoupement véhicule du fournisseur 1 via POST /vin/redirect-sessions avec sa propre clé. Alors seulement GET /vin/{vin}/economic-evaluation tourne avec provider=1 : elle répond 200 si la liste de pièces et les évaluations de prix de marché sont déjà disponibles, sinon 202 avec Location, Retry-After et un identifiant de tâche ; le résultat est alors récupéré par GET /vin/economic-evaluation/jobs/{jobId}. Il contient le potentiel de recettes des pièces en min/average/max, un classement de démontage trié par recette et une recommandation d’achat. Les petites pièces sont écartées, et les évaluations de prix de marché sont réutilisées jusqu’à 30 jours — voir Achat de véhicules et Profondeur de démontage.
7. Côté enchérisseur : qualifier en VHU. Que le véhicule soit transporté après l’adjudication comme marchandise ou comme déchet décide de la logistique et des documents. POST /vision/vehicle/elv-classification fournit, à partir de 1 à 10 vues, le niveau kein_altfahrzeug_verdacht, gutachten_empfohlen ou altfahrzeug ; altfahrzeug n’est attribué que sur un critère fortement étayé ou par l’arithmétique avec une valeur de marché et une estimation de réparation fournies. La distinction juridique est traitée dans Véhicule d’occasion ou VHU.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/vin/<VIN>/economic-evaluation?provider=1'

L’intégration

1. Conserver la clé côté serveur. L’en-tête X-Api-Key n’est posé que depuis le backend. Ni l’interface vendeur ni l’application enchérisseur ne parlent directement à l’API ; la session de redirection est elle aussi créée sur le serveur.
2. Commencer par un point d’entrée. Côté vendeur : POST /vision/condition-report, car il rend les annonces comparables ; côté enchérisseur : le recoupement véhicule du fournisseur 1 via POST /vin/redirect-sessions avec sa propre clé, puis seulement GET /vin/{vin}/economic-evaluation avec provider=1. Plaque, annonce et qualification VHU suivent comme étapes distinctes.
3. Définir la correspondance des champs. Quelles zones du rapport d’état et quelles valeurs de l’analyse vont dans quels champs de l’annonce et de la vue enchérisseur ? C’est là le vrai travail ; la référence figure dans le guide d’intégration.
4. Distinguer échec et résultat vide. 404 vehicle_not_found et vin à null sont des résultats vides, pas des erreurs : créer l’annonce, laisser le champ vide, garder le recoupement en reprise. Une analyse d’image effectuée est facturée même sans constat ; on ne relance que si elle n’a pas pu être effectuée du tout.
5. Intégrer la récupération sur `202`. L’analyse de rentabilité répond 200 si la liste de pièces et les évaluations de prix de marché sont déjà disponibles, sinon 202 avec Location, Retry-After et un identifiant de tâche ; le résultat est alors récupéré par GET /vin/economic-evaluation/jobs/{jobId} depuis une file d’attente de votre backend — pas depuis le navigateur de l’enchérisseur. Votre logiciel doit traiter les deux réponses.
6. Déployer par étapes. D’abord un groupe de vendeurs, puis les enchérisseurs. GET /client/usage montre quels appels tournent et à quelle fréquence ; X-Tapinoma-Usage-Warning signale un crédit faible.

Points de vigilance

• Poser `Idempotency-Key`. Un téléversement envoyé deux fois ne doit pas déclencher une seconde analyse ; l’en-tête rend la répétition reconnaissable (X-Tapinoma-Idempotent-Replay), et la facturation n’a lieu qu’une fois. Exception : les appels qui émettent une clé ne sont pas rejoués — après un délai dépassé, vérifier l’existant.
• Laisser vides les champs vides. Un VIN illisible, une zone sans constat, une position sans référence de marché : le résultat nomme le manque, l’annonce le montre — ni valeur par défaut ni complément tiré d’un véhicule semblable.
• Conserver le `tapiId` sur l’annonce — avec le client. C’est l’identifiant stable pour le texte d’annonce et les données véhicule ; GET /vehicles/{tapiId} fournit plus tard les données techniques dans le cadre du parcours VIN initial déjà facturé, mais seulement avec la clé du client qui a obtenu le tapiId dans ce parcours. Avec toute autre clé, l’API répond 404.
• Jamais la clé dans le navigateur. Ni dans l’interface vendeur ni dans l’application enchérisseur. Chaque appel et chaque session de redirection passent par votre backend.
• Prévoir les limites de débit. Avant la clôture d’une enchère, de nombreux enchérisseurs consultent les mêmes annonces ; les analyses vont dans une file d’attente, pas dans le clic. Les limites par utilisateur, clé ou point d’entrée se fixent via PUT /client/users/{clientId}/rate-limits.
• Faire vérifier le résultat. Rapport d’état, texte de dommage et recommandation d’achat sont des aides de travail ; l’offre reste une décision de l’enchérisseur, la publication de l’annonce une décision du vendeur.

Ce que l’API ne fait pas

Le rapport d’état et le texte de dommage ne sont pas des expertises et ne contiennent aucun calcul de réparation ni de valeur résiduelle ; ils décrivent ce qui est visible sur les vues. La plaque est lue, pas vérifiée contre un registre ; il n’y a aucune recherche de titulaire. L’analyse de rentabilité est une recommandation d’achat issue de références de marché, ni une valeur résiduelle ni une garantie de prix — la valeur résiduelle naît sur votre plateforme des offres déposées. Les données véhicule du fournisseur 1 ne peuvent pas être obtenues directement par un système tiers via GET /vin/{vin}/vehicle ; ce recoupement passe par le navigateur de l’utilisateur via POST /vin/redirect-sessions. Aucune base de données n’est vendue : ce qui est dû est l’exécution de la requête ou de l’analyse ; le résultat est vérifié et utilisé par vous, vos vendeurs et vos enchérisseurs.