Bourses et portails d’annonces automobiles : des annonces issues du rapprochement, pas de la ressaisie

Où les données manquent dans le processus

Une annonce vaut ce que le vendeur saisit — rarement complet, pas toujours exact. Ce qui manque coûte de la visibilité dans les filtres et de la confiance chez l’acheteur ; ce qui est faux coûte des questions et des désistements. Les points typiques :

• Mise en ligne. Le vendeur recopie VIN, première immatriculation et codes de type depuis le certificat d’immatriculation. Un chiffre inversé dans le VIN n’apparaît que lorsqu’un acheteur compare le numéro avec le véhicule ; sur les documents étrangers, la correspondance des champs manque souvent déjà.
• Champs de filtre. Boîte, transmission, carrosserie et motorisation ne figurent pas entièrement sur le certificat. Ce que le vendeur ne saisit pas reste vide, et l’annonce n’apparaît pas dans la recherche.
• Texte d’annonce. Titre et description viennent de blocs de texte ou sont copiés de l’annonce précédente — y compris des équipements que ce véhicule n’a pas.
• Photos. Prises sur le parc avec les véhicules voisins en fond, hétérogènes, souvent avec une plaque lisible. Qu’une plaque soit lisible est rarement vérifié avant publication ; le masquage lui-même reste l’affaire du portail.
• État et rappels. Les indications d’état viennent du vendeur et ne sont pas étayées ; qu’une campagne de rappel existe pour la série, ni le portail ni l’acheteur ne le savent.

Ce que l’API fournit

Un déroulé de bout en bout

1. Photographier le document. Le vendeur photographie le certificat d’immatriculation ; le backend du portail stocke le fichier et transmet son adresse en fileUrl à POST /scanner/document/registration/international — pour les certificats allemands, POST /scanner/document/registration suffit. Les champs véhicule préremplissent le formulaire ; noms, adresses, plaques et VIN ne sont jamais traduits, et le portail ne reprend pas les champs du titulaire, voir Données dans un VHU : ce qui reste dans l’infodivertissement.
2. Lancer le rapprochement. Pour le fournisseur 1, GET /vin/{vin}/vehicle répond à un système tiers par redirect_required. Le backend crée donc avec POST /vin/redirect-sessions une session à partir de vin, de la returnUrl HTTPS absolue et d’un state portant son propre numéro d’annonce, puis envoie le vendeur vers la redirectUrl. Les fournisseurs 2 et 3 s’interrogent directement.
3. Traiter le retour. Après le rapprochement dans l’interface tapinoma, le vendeur revient sur la returnUrl — avec status=completed, tapiId et state, ou avec status=cancelled. Aucune donnée de véhicule, d’équipement ou d’accès ne figure dans la redirection ; la session expire après dix minutes. Le portail enregistre la tapiId sur l’annonce.
4. Remplir filtres et texte. GET /vehicles/{tapiId} fournit les données techniques dans le cadre du parcours VIN déjà facturé, sans VIN ni équipement. POST /vehicles/{tapiId}/listing avec language et des notes du vendeur facultatives dans notes fournit titre, description et points forts — sans propriété inventée, sans prix, sans mention d’état.
5. Enregistrer le tour du véhicule. Jusqu’à 8 prises vont à POST /vision/condition-report ; reviennent des constats par zone dans un ordre fixe et une note globale A, B ou C. POST /vehicles/intake réunit document, rapprochement du véhicule et rapport d’état en un seul appel — le rapprochement y passe fixement par le fournisseur 2, sans redirection, et photoUrls accepte jusqu’à cinq prises.
6. Préparer les photos. POST /vision/vehicle/remove/bg détoure le véhicule ; le modèle ne détermine que le contour, les pixels restent ceux de la photo, voir détourer sans redessiner. POST /vision/license-plate dit si une plaque est lisible sur une prise et laquelle — caractères, pays, avant ou arrière ; il ne fournit aucune coordonnée d’image et ne masque rien. S’il signale une plaque lisible, le portail suspend la mise en ligne ; le masquage reste une prestation propre du portail.
7. Afficher l’avis de rappel. GET /recalls/vehicles/{vin} confronte la série aux registres officiels — Kraftfahrt-Bundesamt, EU Safety Gate, NHTSA. Le VIN n’est résolu qu’à partir du stock existant, sans appel fournisseur. Le portail affiche l’avis sur l’annonce comme aide de travail.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UUID_PAR_OPERATION>' \
  -d '{"language": "fr", "notes": "Attelage monté en seconde monte"}' \
  'https://api.tapinomahub.com/vehicles/<TAPI_ID>/listing'

L’intégration

1. Stocker la clé côté serveur. La clé API part en en-tête X-Api-Key depuis le backend du portail et va dans sa configuration — jamais dans le formulaire du navigateur, jamais dans le code source.
2. Choisir un point d’entrée. La lecture du certificat à la mise en ligne est l’entrée naturelle, car elle remplace aussitôt les fautes de frappe. Le texte d’annonce via POST /vehicles/{tapiId}/listing suppose un déroulé VIN achevé et vient ensuite.
3. Définir la correspondance des champs. Quel champ de la réponse va dans quel champ de l’annonce ? C’est là le vrai travail. L’annonce a besoin en plus d’un champ pour la tapiId et d’une mention indiquant quelles valeurs viennent de la requête.
4. Distinguer résultat vide et erreur. 404 vehicle_not_found n’est pas une erreur mais un résultat : non trouvé. Le portail crée quand même l’annonce, laisse les champs vides et demande au vendeur de compléter — jamais sous forme de message d’erreur rouge ; status=cancelled au retour n’en est pas une non plus. Une connexion coupée, elle, peut être rejouée avec le même Idempotency-Key.
5. Récupérer les traitements longs. Si un point d’entrée répond 202, Location et Retry-After indiquent le job et le délai. Le statut se récupère sur le point d’entrée de job associé, pas par un second appel du point d’entrée initial.
6. Déployer et observer. D’abord un vendeur au stock maîtrisable, puis l’ensemble. GET /client/usage et l’en-tête de réponse X-Tapinoma-Usage-Warning montrent la consommation ; le chemin du contrat à la mise en production est décrit dans le guide d’intégration.

Points de vigilance

• Poser un `Idempotency-Key`. Recommandé : un UUID par opération métier, 8 caractères au moins, par exemple annonce-<no>-texte-<uuid> — pas le seul numéro d’annonce, car une clé compte comme achevée après le premier succès et lecture du document, session de redirection et texte d’annonce recevraient sinon la même réponse enregistrée. Après une connexion coupée, le backend rejoue l’appel avec la même clé et reçoit la même réponse, reconnaissable à l’en-tête X-Tapinoma-Idempotent-Replay ; l’enregistrement dure 24 heures et n’a lieu qu’en cas de succès. Exception : les appels qui émettent une clé secrète (sous-utilisateurs, espaces partenaires) — après un délai dépassé, rapprocher l’existant au lieu de rejouer à l’aveugle.
• Laisser vides les champs vides. Si la réponse renvoie null, le champ reste vide — ni valeur par défaut, ni bloc de texte, ni déduction à partir d’annonces similaires. Un équipement plausible dans une annonce est plus dangereux qu’un manque visible, parce que l’acheteur le lit comme une promesse.
• Enregistrer la `tapiId`. Elle est stable et donne accès à GET /vehicles/{tapiId} et POST /vehicles/{tapiId}/listing. Les résultats vont dans la base du portail, pas dans chaque affichage ; chaque requête coûte.
• Jamais la clé dans le navigateur. Le formulaire parle au backend du portail, le backend à l’API. La session de redirection pour le fournisseur 1 est elle aussi créée côté serveur ; le navigateur ne voit que la redirectUrl, et au retour le backend vérifie que state appartient à l’une de ses propres opérations.
• Fixer des limites par vendeur. PUT /client/users/{clientId}/rate-limits limite par utilisateur, clé ou point d’entrée, pour qu’un import de stock défectueux d’un négociant n’épuise pas le crédit du portail.
• Faire vérifier le résultat. Texte d’annonce, rapport d’état, image détourée et avis de rappel sont des aides de travail. Le vendeur relit le texte et contrôle les images avant publication ; l’avis de rappel vaut pour la série, pas comme preuve pour ce véhicule.

Ce que l’API ne fait pas

L’API n’évalue pas un véhicule et ne nomme aucun prix — le texte d’annonce n’en contient volontairement pas, et il n’existe aucune garantie de prix. Le rapport d’état de POST /vision/condition-report décrit le visible et n’est pas une expertise ; il ne calcule ni réparation ni valeur résiduelle, voir Véhicules accidentés : épave, valeur résiduelle et intérêt pour le centre. Pour la plaque, aucune recherche du titulaire, aucun rapprochement avec un registre et aucune anonymisation — POST /vision/license-plate rend les plaques lisibles, il ne les masque pas. Le fournisseur 1 n’est accessible aux systèmes tiers que par la redirection navigateur. Et elle ne vend aucune base de données : ce qui est dû, c’est la requête ou l’analyse avec son résultat ; la responsabilité de l’annonce reste au vendeur. Ce que le matériau ne donne pas reste un manque — pourquoi, c’est expliqué dans Requête VIN en pratique : déroulé, résultat, facturation.