Construire un outil de cross-reference avec l'API

Points cles a retenir

• Un outil de cross-reference interroge l'API avec une reference OEM et recoit en retour les references equivalentes et les supersessions, ce qui evite a vos clients de chercher manuellement la bonne piece.
• L'authentification se fait par cle API transmise dans un en-tete HTTP, jamais dans l'URL : c'est une bonne pratique de securite standard pour les API REST.
• La base sparepilot couvre 85 000+ produits, environ 446 000 references OEM et 82 000+ equivalences, soit un socle suffisant pour enrichir un catalogue multimarque.
• La gestion du rate limit (code 429) et la mise en cache cote client sont indispensables pour une integration stable et econome en appels.
• Les exemples d'endpoints de cet article sont illustratifs : la documentation developpeurs officielle fait foi sur les chemins et parametres exacts.

Un outil de cross-reference transforme une reference que votre client connait deja en une liste de pieces equivalentes et de remplacements officiels. Pour un site e-commerce de motoculture ou un logiciel SAV, c'est la difference entre un visiteur qui trouve sa piece en deux secondes et un panier abandonne. Ce tutoriel detaille un flux d'integration complet, de l'obtention de la cle jusqu'a la mise en cache.

Qu'est-ce qu'un outil de cross-reference et pourquoi le construire ?

Un outil de cross-reference relie une reference fabricant (OEM) a ses equivalents : pieces compatibles d'autres marques, references adaptables et remplacements successifs. L'enjeu metier est simple : un client tape la reference figurant sur sa piece usee, et votre interface lui propose immediatement ce qu'il peut commander, meme si la reference d'origine n'existe plus.

Le probleme concret que ca resout

Dans la motoculture, une meme piece se decline sous des dizaines de references selon les marques et les annees. Sans cross-reference, vos agents SAV passent du temps a comparer des catalogues PDF. En automatisant via une API, vous deportez ce travail vers une base structuree. Pour le contexte sur les references, voir notre guide comprendre les references OEM et cross-references.

Ce dont vous avez besoin

Trois choses suffisent pour demarrer : une cle API valide, un client HTTP (curl, fetch, axios, requests selon votre stack) et un endroit ou stocker les reponses en cache. Aucune dependance lourde n'est requise. L'integration se fait en quelques heures pour un proof of concept, puis s'industrialise avec la gestion d'erreurs et le cache.

Comment obtenir une cle API et s'authentifier ?

L'acces a l'API passe par une cle personnelle, liee a votre compte. La cle identifie vos appels, applique votre quota et vous donne acces aux donnees. La regle de securite essentielle : la cle se transmet dans un en-tete HTTP, jamais en parametre d'URL, car les URLs sont journalisees par les serveurs et les proxys.

Authentification par en-tete

La plupart des API REST modernes attendent un en-tete du type Authorization ou un en-tete dedie X-API-Key. Le format exact est precise par la documentation officielle. Voici un exemple illustratif avec curl :

curl -H 'X-API-Key: VOTRE_CLE_API' \
     -H 'Accept: application/json' \
     'https://api.sparepilot.com/v1/search?ref=GX160-OEM-EXEMPLE'

L'en-tete Accept: application/json indique au serveur le format de reponse souhaite. Ne mettez jamais la cle dans le query string. Sur les bonnes pratiques de transport des secrets, voir OWASP API Security Project, 2023.

Stocker la cle correctement

Cote serveur, lisez la cle depuis une variable d'environnement, jamais en dur dans le code source ni dans un depot git. Cote front, ne l'exposez jamais dans le JavaScript du navigateur : faites transiter les appels par un proxy backend qui detient la cle. C'est le seul moyen d'eviter qu'un visiteur lise votre cle dans les outils developpeur.

Comment rechercher par reference OEM ?

Le coeur de l'outil est l'appel de recherche : vous envoyez une reference, l'API retourne le produit correspondant et ses relations. Le principe generique est un endpoint de recherche acceptant un parametre de reference, par exemple GET /v1/search?ref=.... Le nom precis du chemin est donne par la documentation developpeurs.

Exemple d'appel en JavaScript

Avec l'API fetch native, disponible cote navigateur et Node.js recent, l'appel reste concis. On encode toujours la reference utilisateur avec encodeURIComponent pour eviter les injections dans l'URL :

async function chercherPiece(reference) {
  const url = 'https://api.sparepilot.com/v1/search?ref='
    + encodeURIComponent(reference);

  const reponse = await fetch(url, {
    headers: {
      'X-API-Key': process.env.SPAREPILOT_KEY,
      'Accept': 'application/json'
    }
  });

  if (!reponse.ok) {
    throw new Error('Statut HTTP ' + reponse.status);
  }
  return reponse.json();
}

Sur le fonctionnement de fetch et la verification de response.ok, voir MDN Web Docs, 2024.

Forme illustrative de la reponse

La reponse JSON regroupe le produit trouve, ses equivalences cross-marque et ses supersessions. Le schema ci-dessous est un exemple pedagogique, pas un contrat d'API :

{
  'reference': 'GX160-OEM-EXEMPLE',
  'designation': 'Filtre a air moteur',
  'equivalences': [
    { 'ref': 'EQ-12345', 'marque': 'Adaptable', 'confiance': 'haute' },
    { 'ref': 'EQ-67890', 'marque': 'AutreMarque', 'confiance': 'moyenne' }
  ],
  'supersessions': [
    { 'ancienne': 'GX160-OEM-EXEMPLE', 'nouvelle': 'GX160-V2', 'statut': 'remplacee' }
  ]
}

Comment exploiter equivalences et supersessions ?

Une fois la reponse recue, deux types de relations comptent. Les equivalences listent les pieces interchangeables d'autres marques. Les supersessions decrivent les remplacements officiels : quand une reference est barree, le fabricant designe celle a commander a la place. Les deux doivent etre presentes a l'utilisateur de facon distincte.

Suivre une chaine de supersession

Une reference peut etre remplacee plusieurs fois (A vers B vers C). Votre outil doit suivre la chaine jusqu'a la reference active finale, puis l'afficher comme recommandation principale. Pour comprendre ce mecanisme, lisez trouver un equivalent cross-marque a partir d'une reference OEM.

Distinguer les niveaux de confiance

Toutes les equivalences ne se valent pas : une equivalence OEM officielle est plus sure qu'une piece adaptable. Si l'API fournit un indicateur de confiance, refletez-le dans l'interface (badge, tri) pour que l'utilisateur arbitre en connaissance de cause. Ne masquez jamais une incertitude derriere une presentation trop affirmative.

Quels endpoints utiliser selon le besoin ?

Le tableau ci-dessous resume des usages types et l'endpoint generique correspondant. Ces chemins sont des exemples illustratifs destines a clarifier la logique d'integration ; reportez-vous toujours a la documentation officielle pour les noms et parametres reels.

Penser pagination

Les listes d'equivalences peuvent etre longues. Une API REST bien concue pagine ses resultats : verifiez les parametres de pagination (page, limite, curseur) dans la documentation et gerez le cas ou plusieurs pages existent. Sur les conventions REST, voir RFC 9110 HTTP Semantics, 2022.

Comment gerer le rate limit et les erreurs ?

Toute API serieuse limite le nombre d'appels par minute. Quand vous depassez ce quota, le serveur repond avec le code 429 Too Many Requests. Votre code doit detecter ce cas, respecter le delai indique et reessayer plutot que de marteler le serveur. C'est la condition d'une integration qui ne casse pas en production.

Backoff et en-tete Retry-After

Lorsqu'un 429 survient, le serveur renvoie souvent un en-tete Retry-After indiquant le nombre de secondes a attendre. Respectez-le, et a defaut appliquez un backoff exponentiel (1s, 2s, 4s) :

async function appelAvecRetry(url, options, essais = 3) {
  for (let i = 0; i < essais; i++) {
    const r = await fetch(url, options);
    if (r.status !== 429) return r;
    const attente = Number(r.headers.get('Retry-After')) || (2 ** i);
    await new Promise(res => setTimeout(res, attente * 1000));
  }
  throw new Error('Rate limit persistant');
}

Sur la semantique du code 429, voir RFC 6585, 2012.

Traiter les autres codes

Distinguez clairement les familles d'erreurs : un 401 signale une cle invalide ou absente, un 404 que la reference est inconnue (a presenter sobrement a l'utilisateur), un 5xx un probleme cote serveur (reessayable). Ne traitez jamais toutes les erreurs de la meme facon : l'utilisateur SAV n'a pas besoin de la meme reponse selon le cas.

Comment mettre en cache pour rester performant ?

Les references et leurs equivalences changent rarement d'un jour a l'autre. Mettre en cache les reponses reduit drastiquement vos appels API, accelere l'affichage et vous protege du rate limit. Une strategie simple suffit pour la majorite des integrations e-commerce et SAV.

Strategie de cache cote serveur

Stockez chaque reponse de recherche dans un cache cle-valeur (Redis, ou meme une table avec horodatage) en utilisant la reference normalisee comme cle. Definissez une duree de vie raisonnable, par exemple 24 heures. A reception d'une requete, servez le cache s'il est frais, sinon interrogez l'API et rafraichissez. Pensez aussi a invalider le cache de facon ciblee lorsqu'une supersession majeure est connue, afin de ne pas proposer une reference qui vient d'etre remplacee. Sur les en-tetes de cache HTTP, voir MDN HTTP Caching, 2024.

Normaliser les references avant de chercher

Les utilisateurs saisissent les references avec des espaces, des tirets ou des casses variables. Normalisez la saisie (majuscules, suppression des separateurs superflus) avant l'appel et avant la mise en cache : vous augmentez le taux de hit du cache et reduisez les recherches infructueuses dues a une simple difference de formatage.

Recapitulatif du flux d'integration

De bout en bout, l'integration suit toujours la meme sequence : obtenir la cle, l'injecter dans un en-tete, normaliser la reference saisie, verifier le cache, appeler l'endpoint de recherche, gerer le rate limit et les erreurs, exploiter equivalences et supersessions, puis afficher le resultat trie par confiance. Pour une vue d'ensemble du demarrage, consultez notre guide developpeurs pour integrer l'API sparepilot.

Pour aller plus loin, vous pouvez demander une cle API et consulter la documentation developpeurs sur sparepilot.com : elle precise les chemins, parametres et quotas reels qui font foi sur les exemples illustratifs de cet article.