Fabricants de pièces, équipementiers et fournisseurs de données : valider les références OE et enrichir les fiches article

Où les données manquent dans le processus

Un article d’équipementier porte sa propre référence et une liste des références OE qu’il remplace. Cette liste est l’ancre par laquelle négoce et ateliers trouvent l’article — et la partie de la fiche qui naît le plus souvent à la main, voir référence OE. Les endroits typiques :

• À la création de la liste de références. Les références OE viennent de documents d’étude, de factures de concession et de catalogues concurrents — avec espaces, avec tirets, sans lettre d’indice. Savoir si 5Q0 919 275 C et 5Q0919275C sont la même référence se décide à la lecture, par un collaborateur.
• Au classement. Le type d’article et la position VDI 4081 sont choisis par article dans un menu déroulant. Pour les pièces d’usure c’est rapide ; pour l’électronique et la carrosserie, rarement homogène.
• À la traduction. Les désignations sont traduites à la main par langue cible ou reprises d’un ancien catalogue ; les textes marketplace une fois de plus par pays.
• Au positionnement prix. La place d’un article sur le marché se déduit de prix concurrents isolés, sans date ni source.
• Après la livraison. Personne ne vérifie si une référence OE de la liste est entre-temps visée par un rappel — les registres ne sont pas reliés aux données de base.

Ce que l’API fournit

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

1. Préparer le classement une fois. GET /vdi renvoie le catalogue VDI 4081 avec groupes principaux et positions, ainsi que son état et sa valeur de contrôle. Vous y rapportez une fois votre nomenclature de familles ; le catalogue ne contient aucune attribution OE, elle vient référence par référence du recoupement.
2. Nettoyer la liste de références. Chaque référence OE de la liste passe par GET /parts/oe/normalize avec oeNumber et, si connu, manufacturer. Sur matched, vous reprenez la graphie normalisée et les remplacements documentés. unresolved, ambiguous et invalid restent tels que saisis et reçoivent une tâche — aucun cas n’est clos en devinant.
3. Classer l’article. Pour chaque référence confirmée, GET /parts/oe/{oeNumber} renvoie exactement un tapiGenArt et, lorsqu’une attribution confirmée existe, la position VDI 4081 ; si le classement VDI 4081 est vide, la famille reste ouverte. S’y ajoutent chaîne de remplacement, famille de références et compatibilité — voir numéro GenArt. Sur 404, il n’y a pas eu de correspondance confirmée : l’article reste créé, le classement reste ouvert.
4. Confronter ses références au marché. GET /parts/oe/{oeNumber}/aftermarket-references montre quelles références aftermarket sont documentées pour une référence OE — un fournisseur de données voit ainsi où sa propre liste s’écarte du marché. Une référence n’est pas une garantie de compatibilité ; une liste vide est un constat, pas une erreur — voir OE, OEM, OES et IAM.
5. Désignations et textes marketplace. La désignation passe une par une par GET /translation/translations — exactement une par appel, ni titres ni listes. GET /parts/oe/{oeNumber}/seo fournit les champs produit, contenu et caractéristiques par langue et marketplace ; le texte est relu avant publication.
6. Positionner le prix. GET /parts/oe/{oeNumber}/price renvoie une évaluation de prix indicative à partir de références comparatives et de marché. Elle entre dans la fiche comme référence de marché datée, pas comme prix catalogue — et elle n’est pas une garantie de prix.
7. Rappels en traitement nocturne. Un job envoie la liste de références par lots de 100 positions au plus à POST /recalls/parts, avec vehicle.make, vehicle.model et période de production quand ils sont connus. Par position reviennent statut, mesures et confiance ; les articles concernés reçoivent un avertissement pour les partenaires commerciaux.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/parts/oe/normalize?oeNumber=5Q0919275C&manufacturer=VOLKSWAGEN'

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 ou système batch — jamais dans le navigateur, jamais dans un script d’import transmis avec le paquet de données. Le parcours du contrat à la mise en production figure dans la documentation.
2. Commencer par un point d’entrée. Pour les données de base, c’est GET /parts/oe/normalize à l’import de la liste de références : un appel par référence, et chaque ligne a ensuite un status que l’on peut compter.
3. Définir la correspondance des champs. La référence normalisée et les remplacements dans le champ des références, tapiGenArt vers votre type d’article, le classement VDI 4081 vers votre famille, part.manufacturer et part.name dans les champs de base — et tout champ renvoyé à null reste vide.
4. Distinguer échec et résultat vide. unresolved, ambiguous et invalid à la normalisation, 404 au recoupement OE et une liste de références vide sont des résultats vides : garder la fiche, 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. Les traitements longs répondent par 202, Location, Retry-After et un identifiant de job ; le statut vient du point d’entrée .../jobs/{jobId} correspondant, au rythme de Retry-After — par exemple GET /vin/cart-check/jobs/{jobId} quand POST /vin/cart-check vérifie jusqu’à 30 positions OE contre un véhicule, ou GET /vision/part/generation-jobs/{jobId} pour les jobs d’image produit de pièces neuves issus de POST /vision/part/generate.
6. Déployer et observer. D’abord une famille, puis le stock. 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. Un traitement nocturne qui redémarre après une panne renvoie les mêmes lots à POST /recalls/parts. Avec l’en-tête Idempotency-Key, la répétition est reconnue 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. unresolved ne veut pas dire « probablement cette référence », et un null dans part.listPrice est une information. Une fiche qui comble ses lacunes de façon plausible porte l’affirmation fausse dans chaque catalogue qui reprend vos données.
• Conserver le tapiId. Si un traitement a rapproché un véhicule par un parcours VIN, gardez le tapiId ; GET /vehicles/{tapiId} en renvoie les données techniques dans le cadre de ce parcours facturé, sans VIN ni équipements.
• Stocker les résultats, ne pas réinterroger à chaque export. Ce que renvoie GET /parts/oe/{oeNumber} appartient à cette référence dans votre base ; chaque requête est facturée sur le crédit.
• Jamais la clé dans le navigateur. Un outil de contrôle pour l’équipe catalogue passe aussi par votre backend ; des quotas par sous-utilisateur contiennent un import qui revérifie tout le stock par erreur.
• Ne pas livrer 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.
• Vérifier le résultat avant livraison. Traduction, enrichissement SEO et évaluation de prix sont faits pour être relus, pas pour être transmis 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 : avec le résultat, vous n’acquérez aucun droit sur les bases sous-jacentes ni aucun catalogue que vous pourriez sous-licencier. Ce qui est dû, c’est la requête ; la vérification et l’usage des résultats vous reviennent. GET /vdi renvoie le catalogue de classement sans attribution OE, l’évaluation de prix est indicative et sans garantie de prix, une référence aftermarket n’est pas une promesse de compatibilité. 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. Les points d’entrée image fournissent des contrôles visuels, pas une expertise ; une plaque d’immatriculation sur une photo n’entraîne aucune recherche du titulaire. Et là où les données ne donnent rien, le champ reste vide.