De la référence OE à l’article prêt pour la marketplace

La référence OE est la monnaie du commerce de pièces. Elle figure sur l’étiquette, la facture, la demande client et la liste de pièces du véhicule donneur. Seulement voilà : une référence seule ne vend rien. Entre « 5Q0941773B » et un article qu’un moteur de recherche trouve et qu’un filtre de marketplace laisse passer, il y a la désignation, l’utilisation, les références croisées, la catégorie et les caractéristiques. Cette voie décrit quels appels de l’API tapinomahub couvrent cette distance.

Pourquoi normaliser la référence d’abord

La même référence circule dans une entreprise sous une demi-douzaine d’écritures : avec tirets, avec espaces, en minuscules, suivie d’un indice de couleur. GET /parts/oe/normalize contrôle l’écriture selon les règles connues et répond par un status qui détermine la suite. L’appel est peu coûteux, rapide, et évite l’erreur la plus chère : une requête impeccable sur une référence qui n’existe pas.

Le cœur : pièce, fitment, remplacement, références

GET /parts/oe/{oeNumber} est l’appel central de toute la voie. Il renvoie quatre listes distinctes par leur sens et souvent confondues en pratique — et cette séparation fait précisément la valeur de la réponse. La description du service figure dans Comparer nom de pièce OE, affectations, famille de référence et chaîne de remplacement.

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

Quand la rechange indépendante entre en jeu

Beaucoup de clients ne connaissent pas la référence OE mais celle d’un fabricant de rechange. GET /parts/oe/{oeNumber}/aftermarket-references renvoie les références IAM trouvées : par entrée partNumber dans son écriture d’origine, normalizedPartNumber sans caractères spéciaux et manufacturer. count donne le total ; limit et offset récupèrent la liste page par page, et page.hasMore indique s’il reste des entrées. En l’absence de référence, la réponse est un succès et la liste est vide — ce n’est pas une erreur, voir Déterminer les références aftermarket pour un numéro OE.

Le volet marketplace : titre, catégorie, caractéristiques

GET /parts/oe/{oeNumber}/seo est l’appel qui transforme des données techniques en texte de vente. marketplaceId choisit la place de marché — les valeurs documentées sont les marketplaces eBay EBAY_AT à EBAY_US, avec EBAY_DE par défaut. language choisit la langue produite, vehicleType distingue car et motorcycle. Décrit en détail dans Optimiser un article eBay ou marketplace (enrichissement SEO).

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/parts/oe/5Q0919275C/seo?marketplaceId=EBAY_FR&language=fr&vehicleType=car'

• `404 seo_no_exact_match` signifie qu’aucune correspondance exacte n’existe pour la référence dans le chemin véhicule choisi. La réponse nomme oeNumber, marketplaceId, language et vehicleType — vérifiez d’abord vehicleType.
• `400 unsupported_marketplace_language` signifie que la place de marché choisie ne propose pas cette langue. Cette combinaison relève de votre configuration, pas de l’appel isolé.
• `liveAvailability` avec `status: "PAUSED"` montre que l’enrichissement en direct est suspendu ; availableAt et retryAfterSeconds indiquent la prochaine tentative. La même situation en erreur : 429 seo_live_requests_paused.
• Le résultat est un contenu de publication, pas une affirmation de compatibilité. Il doit être vérifié de façon autonome quant à son exactitude et sa licéité avant publication — y compris, et surtout, les caractéristiques.

La fourchette de prix, si vous en avez besoin

GET /parts/oe/{oeNumber}/price fournit une évaluation indicative : new et used avec min, max et average, plus priceRecommendation avec confidence en HIGH, MEDIUM ou LOW. result dit où l’on en est : priced signifie que des offres exploitables ont été trouvées ; no_listings_found qu’il n’y en avait aucune — la réponse porte alors des zéros, et ce n’est pas un prix mais un constat vide. Une évaluation en LOW repose sur peu d’offres ; son milieu ne porte pas une décision d’achat. Voir Évaluer le prix d’une pièce OE et Tarification dynamique des pièces d’occasion sans perdre la main.

Les chaînes de remplacement : le levier silencieux

Les constructeurs remplacent plusieurs fois une référence au cours d’un cycle de modèle. Un article tenu sous la seule référence la plus ancienne est invisible pour les clients qui connaissent la plus récente — et inversement. replacementChain rend ce sens visible : from est remplacé par to. Reportez la chaîne entière en mots-clés et références sur l’article, et votre stock sera trouvé sous chaque référence ayant été valide. Plus de détails dans OE, OEM, OES et IAM : la différence en un tableau et Neuf, occasion, échange standard, adaptable : quatre notions, deux dimensions.

Facturation, répétitions et limites de débit

• Un résultat vide et une non-exécution technique restent distincts. Le traitement commercial de 404 oe_part_not_found suit exclusivement les conditions affichées avant la commande et convenues au contrat.
• `422 ambiguous_oe_number` signifie que la référence n’a pu être résolue de façon univoque. Transmettez manufacturer au lieu de deviner.
• Les limites de débit s’appliquent par clé d’endpoint, pas globalement au compte. Un seul appel actif par client est admis ; les requêtes supplémentaires sont refusées avec 429 client_request_in_progress.
• Les réponses appartiennent à votre base. Données pièce, fitment et références changent rarement. Répéter l’appel à chaque affichage coûte de l’argent sans rien apporter.
• L’en-tête `X-Tapinoma-Billing-Source` nomme la décision de facturation : plan, balance, bundle, sandbox ou idempotent_replay. Pour la comptabilité, c’est une source plus fiable qu’une supposition.

Le déroulé dans la gestion commerciale

1. Normaliser la référence et consigner le status sur l’article. Seul matched poursuit sans question.
2. Récupérer les données pièce et stocker les quatre listes séparément. Mélanger références et fitment dans un champ interdit d’expliquer plus tard l’origine d’une indication.
3. Charger les références IAM si vous vendez de la rechange ou si vos clients cherchent avec ces références. Travailler page par page sur les longues listes.
4. Demander les données marketplace par canal et par langue cible. Un article pour trois pays demande trois appels, pas la traduction du texte allemand.
5. Mapper les caractéristiques sur les champs obligatoires du canal et rendre visibles ceux qui manquent, au lieu de les remplir par supposition.
6. N’appeler la fourchette de prix que là où elle porte une décision — première tarification, articles dormants — et non chaque jour pour chaque article.
7. Mesurer après publication : refus du canal, corrections, retours pour compatibilité, part d’articles sans catégorie.

Des limites à connaître

• Aucune garantie de compatibilité. Référence, fitment et remplacement sont de la documentation. Le contrôle technique sur le véhicule reste à la charge de celui qui monte la pièce.
• Les listes vides informent sur les données. Séries rares, versions spéciales et pièces très anciennes sont moins documentées. C’est une question de couverture, pas de qualité de la pièce.
• Les textes sont des propositions, pas des validations. Les noms de marques et de fabricants peuvent être des renvois mais ne doivent pas suggérer une origine ; les indications trompeuses sur des caractéristiques essentielles sont illicites.
• Une fourchette de prix n’est pas une garantie de prix. La sortie est expressément indicative et ne constitue ni offre ni engagement.
• Catégories et caractéristiques évoluent. Les marketplaces remanient leurs structures. Une requête d’il y a deux ans n’est plus l’état actuel si le canal a reconstruit ses champs.

Tous les champs, codes d’erreur et exemples de réponse figurent dans la documentation développeur. Pour partir d’une photo ou d’un véhicule entier plutôt que d’une référence, voir De la photo de pièce à l’annonce : la voie image de l’API tapinomahub et Du VIN à l’analyse de rentabilité : la voie véhicule.