Marketplaces et boutiques en ligne de pièces : enrichir les annonces à partir de la référence OE

Où les données manquent dans le processus

Une marketplace vaut ce que valent les fiches de ses vendeurs, et elles arrivent rarement complètes. Ce que le vendeur ne fournit pas, la plateforme doit le compléter ou le laisser vide — et les champs vides coûtent de la visibilité, voir données de stock pour marketplaces. Les endroits typiques :

• À la mise en ligne. Le vendeur saisit une référence OE mais ni type d’article ni références antérieures. La catégorie sort d’un menu déroulant, et les acheteurs cherchent avec la référence de leur pièce déposée — souvent plus ancienne que celle annoncée.
• Dans les annonces multilingues. La désignation de la pièce est traduite à la main par langue ou reste dans la langue d’origine.
• Dans les images. Les photos prises à l’atelier ont des fonds chargés, et l’état figure à côté en texte libre que personne n’attribue de façon homogène.
• Après la mise en ligne. Personne ne vérifie si une pièce proposée est visée par un rappel, parce que les registres ne sont pas reliés au stock.
• Côté acheteur. Savoir si la pièce convient au véhicule de l’acheteur se règle par une question ou pas du tout — et le retour survient après l’expédition.

Ce que l’API fournit

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

1. Le vendeur met une pièce en ligne. Votre logiciel appelle GET /parts/oe/{oeNumber}. Sur 200, vous reprenez la référence normalisée, le tapiGenArt comme base de la catégorie et la chaîne de remplacement dans le champ des références — voir numéro GenArt. Sur 404, il n’y a pas eu de correspondance confirmée : l’annonce est créée quand même, les champs restent vides.
2. Champs de recherche et versions linguistiques. GET /parts/oe/{oeNumber}/seo fournit les champs produit, contenu et caractéristiques pour la langue et la marketplace. La désignation passe une par une par GET /translation/translations.
3. Préparer les images. Chaque photo du vendeur passe par POST /vision/part/remove/bg ; le modèle ne détermine que le contour, la composition se fait dans le code. Une à trois photos de la même pièce vont à POST /vision/part/quality et renvoient un niveau que vous signalez comme contrôle visuel — voir photos de pièces.
4. Pièces neuves sans photo. Pour les pièces neuves sans photo propre, POST /vision/part/generate lance un job d’image produit. Le mode par défaut est references_required ; qui choisit knowledge_only reçoit basis=knowledge et partIdentityVerified=false et affiche l’image comme représentation, pas comme photo.
5. Passage nocturne des rappels. Un job envoie le stock actif par lots de 100 positions au plus à POST /recalls/parts, avec vehicle.make et vehicle.model quand ils sont connus. Les annonces concernées reçoivent un avertissement et une tâche pour le vendeur.
6. L’acheteur ajoute au panier. S’il indique son VIN, POST /vin/cart-check vérifie jusqu’à 30 positions — mode=type pour le type de véhicule, mode=vehicle pour le véhicule précis. fits=false avec complete=true est un non définitif ; complete=false reste une question ouverte — voir vendre des pièces d’occasion en ligne.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/parts/oe/5Q0919275C'

L’intégration

1. Stocker la clé côté serveur. La clé de l’en-tête X-Api-Key va dans la configuration de votre backend — jamais dans le navigateur, jamais dans un flux, jamais dans un compte vendeur. Le parcours du contrat à la mise en production figure dans la documentation.
2. Commencer par un point d’entrée. Pour une marketplace, c’est GET /parts/oe/{oeNumber} à la mise en ligne : un appel, trois champs remplis, mesurable aussitôt sur la recherche par référence.
3. Définir la correspondance des champs. tapiGenArt vers votre catégorie, la chaîne de remplacement dans le champ des références, part.manufacturer et part.name dans les champs de l’annonce — et tout champ renvoyé à null reste vide chez vous.
4. Distinguer échec et résultat vide. 404 au recoupement OE, found=false au détourage et gradable=false au classement sont des résultats vides : créer l’annonce, laisser le champ vide, générer une tâche. Seule une erreur technique est relancée.
5. Récupérer les réponses 202. POST /vin/cart-check et POST /vision/part/generate répondent aux traitements plus longs par 202, Location, Retry-After et un identifiant de job. Le statut vient de GET /vin/cart-check/jobs/{jobId} et de GET /vision/part/generation-jobs/{jobId} — au rythme de Retry-After.
6. Déployer et observer. D’abord un groupe de vendeurs, puis tous. GET /client/usage montre quels appels tournent et à quelle fréquence ; l’en-tête X-Tapinoma-Usage-Warning prévient avant l’épuisement du crédit.

Points de vigilance

• Poser un Idempotency-Key. Si un appel tourne deux fois après un redémarrage, la répétition est reconnue via l’en-tête Idempotency-Key et signalée dans l’en-tête de réponse X-Tapinoma-Idempotent-Replay. Exception : les appels qui délivrent une clé une seule fois — après un délai dépassé, rapprocher l’existant au lieu de recréer.
• Ne pas combler les champs vides. Un null dans part.listPrice est une information. En faire un texte de substitution produit les retours qui consomment la visibilité.
• Ne pas afficher le contenu SEO comme compatibilité. L’enrichissement SEO crée les textes de publication et les caractéristiques. Une affirmation de compatibilité doit venir du contrôle de pièce ou de VIN prévu à cet effet.
• Conserver le tapiId. Dès qu’un compte acheteur a rapproché un véhicule par un parcours VIN, gardez le tapiId ; GET /vehicles/{tapiId} en renvoie les données techniques dans le cadre du parcours VIN déjà facturé, sans VIN et sans équipements.
• Stocker les résultats, ne pas interroger à chaque affichage. Ce que renvoie GET /parts/oe/{oeNumber} appartient à la référence dans votre base ; chaque requête est facturée sur le crédit.
• Jamais la clé dans le navigateur. Le contrôle du panier passe aussi par votre backend ; le VIN de l’acheteur ne figure jamais dans une URL de page. Des quotas par espace contiennent un flux qui republie tout chaque nuit.
• Vérifier avant publication. L’enrichissement SEO est fait pour être relu, pas pour être diffusé sans regard. L’usage des résultats revient au client.

Ce que l’API ne fait pas

L’API fournit des recoupements et des analyses, pas un jeu de données : ce qui est dû, c’est la requête ; l’usage et la vérification des résultats vous reviennent, à vous et à vos vendeurs. L’évaluation de prix de GET /parts/oe/{oeNumber}/price est indicative et ne constitue pas une garantie de prix. Le niveau d’état est un contrôle visuel, pas une expertise ; une plaque d’immatriculation sur une image n’entraîne aucune recherche du titulaire. Les données véhicule du fournisseur 1 ne sont pas récupérées directement par des systèmes tiers — il existe pour cela la redirection navigateur via POST /vin/redirect-sessions, dont la session expire après dix minutes et ne contient ni données véhicule ni données d’accès. Et là où les sources ne donnent rien, le champ reste vide — une référence n’est pas une compatibilité, et une photo sans constat fiable ne reçoit pas de niveau.