Integrer l'API Sparepilot : guide pour developpeurs

Points clés à retenir

• API REST JSON authentifiée par clé API simple — 6 endpoints publics couvrent 95 % des cas d''usage : recherche par référence OEM, par machine, par marque, fiches produit, équivalences, prix multi-vendeurs
• Rate limits : 60 req/min sur le tier gratuit, 600 req/min sur Pro (500 €/mois), illimité sur Enterprise. Tier gratuit débloque tous les endpoints en lecture pour usage non-commercial
• Temps d''intégration moyen : 30 minutes pour ajouter un widget "Identifier ma pièce" sur un site existant via 3-5 appels API + 1 composant front
• Données enrichies par défaut : description, images CDN, prix temps réel sur 18 distributeurs, compatibilité machines (compat_count), cross-références OEM

Pourquoi intégrer l''API Sparepilot ?

Vous gérez un site e-commerce motoculture, un SAV professionnel, ou une plateforme ERP qui suit les pièces détachées. Vous voulez offrir à vos utilisateurs une recherche par référence OEM précise, des équivalences cross-marques automatiques, et des prix comparatifs sur 18 distributeurs en temps réel.

Constituer cette base demande 2-3 années de scraping, déduplication, enrichissement IA, et maintenance continue. Sparepilot a fait ce travail : 757 000 références OEM, 67 868 machines, 93 589 produits, 22 681 équivalences cross-brands, 3,8 millions de liens machine-pièces. Notre API REST expose cette base avec une latence médiane de 120 ms et une disponibilité 99,7 %.

Cas d''usage typiques de nos intégrateurs :

• Sites e-commerce motoculture qui ajoutent un widget "Identifier ma pièce par référence OEM"
• Distributeurs B2B qui automatisent la création de catalogue à partir d''un import OEM client
• SAV qui vérifient la compatibilité d''une pièce avec une machine sur la base de son numéro de série
• Applications mobiles de SAV terrain qui scannent une étiquette OEM et identifient la pièce + ses équivalents
• ERP qui synchronisent les prix de référence sur 18 distributeurs pour les achats

Authentification — Clé API

Toutes les requêtes API exigent une clé d''authentification passée dans le header HTTP X-API-Key. La clé s''obtient gratuitement en s''inscrivant sur sparepilot.com/developers — instantané, validation email, pas de carte bancaire pour le tier gratuit.

GET https://sparepilot.com/api/v1/search?q=11257912805
X-API-Key: spk_live_abc123def456...
Content-Type: application/json

Une clé invalide retourne HTTP 401. Une clé valide mais au-delà du rate limit retourne HTTP 429 avec header Retry-After en secondes. Conservez votre clé en variable d''environnement, jamais committé en clair dans Git.

Rate limits par tier

Tier	Prix	Requêtes/min	Requêtes/jour	Cas d''usage
Gratuit	0 €	60	10 000	Test, intégration personnelle, projet académique
Pro	500 €/mois	600	100 000	Site e-commerce, SAV pro, application mobile commerciale
Enterprise	Sur devis	Illimité	Illimité	ERP industriel, distributeur B2B, intégrateur SaaS

Tous les tiers ont accès aux mêmes endpoints en lecture. Les écritures (création de catalogue privé, scoring custom) sont réservées Enterprise.

Les 6 endpoints essentiels

1. GET /api/v1/search — Recherche par référence OEM

L''endpoint le plus utilisé. Recherche full-text avec normalization (insensible à la casse, ponctuation, espaces) + fuzzy matching + recherche sémantique pgvector.

GET /api/v1/search?q=11257912805&limit=10

Response :

{
  "items": [
    {
      "id": 12345,
      "name": "BAGUE D'ÉTANCHÉITÉ STIHL 9645 003 1190",
      "reference": "9645-003-1190",
      "brand_name": "Stihl",
      "brand_country": "DE",
      "price_ttc": 4.85,
      "compat_count": 8,
      "is_oem_original": true,
      "applies_to_brands": ["Stihl"],
      "images": [...],
      "cheapest_price": 4.20,
      "cheapest_source": "emc-motoculture.com"
    }
  ],
  "total": 1,
  "limit": 10
}

2. GET /api/v1/products/{id} — Fiche produit complète

Toutes les données d''un produit : description, attributs, références croisées, compatibilités machines, équivalents adaptables, intelligence prix multi-vendeurs.

GET /api/v1/products/42

Champs notables retournés : compat_count (nombre de machines compatibles), cross_sell_count (nombre de pièces associées), applies_to_brands (cross-brand applicability), price_min/price_max/cheapest_price/cheapest_source/cheapest_url (depuis le materialized view product_pricing_intel).

3. GET /api/v1/machines — Liste de machines avec filtres

GET /api/v1/machines?brand=Husqvarna&limit=50

Retourne les machines d''une marque (paginé). Filtres disponibles : brand, machine_type (tronçonneuse, tondeuse, ...), model, pagination via page et limit.

4. GET /api/v1/machines/{id}/parts — Pièces compatibles avec une machine

GET /api/v1/machines/116213/parts?limit=200

Liste toutes les pièces compatibles avec une machine donnée, avec prix et stock temps réel. Inclut un score de confiance par compatibilité (confidence_tier : confirmed / probable / adjacent).

5. GET /api/v1/machines/{id}/compatible-machines — Machines compatibles avec un produit

GET /api/v1/products/42/compatible-machines

Inverse de l''endpoint précédent : à partir d''un produit, liste les machines qui peuvent utiliser cette pièce. Groupé par marque.

6. GET /api/v1/parts/{part_identity_id}/equivalents — Cross-références OEM

GET /api/v1/parts/12345/equivalents

Liste les pièces équivalentes (même fonction, marques différentes) avec niveau de confiance et type de match (OEM partagée, spécifications identiques, équivalence cross-marque).

Exemple d''intégration — Widget "Identifier ma pièce" en 30 minutes

Étape 1 — Inscription et obtention de la clé

1. Allez sur sparepilot.com/developers
2. Créez un compte (email + mot de passe)
3. Validez l''email — la clé API tier gratuit est générée automatiquement
4. Copiez la clé (format spk_live_...) dans votre .env

Étape 2 — Exemple Python (FastAPI / Flask)

import requests, os

API_KEY = os.environ["SPAREPILOT_API_KEY"]
BASE = "https://sparepilot.com/api/v1"

def search_oem(reference: str) -> dict:
    r = requests.get(
        f"{BASE}/search",
        params={"q": reference, "limit": 5},
        headers={"X-API-Key": API_KEY},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

# Usage
results = search_oem("11257912805")
for item in results["items"]:
    print(f"{item['name']} — {item.get('cheapest_price', '?')}€ chez {item.get('cheapest_source', '?')}")

Étape 3 — Exemple Node.js (Express)

const axios = require("axios");

const api = axios.create({
  baseURL: "https://sparepilot.com/api/v1",
  headers: { "X-API-Key": process.env.SPAREPILOT_API_KEY },
});

async function searchOem(ref) {
  const { data } = await api.get("/search", { params: { q: ref, limit: 5 } });
  return data.items;
}

// Express endpoint
app.get("/api/identify", async (req, res) => {
  try {
    const items = await searchOem(req.query.ref);
    res.json({ items });
  } catch (e) {
    res.status(500).json({ error: e.message });
  }
});

Étape 4 — Exemple PHP (Laravel / WordPress)

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://sparepilot.com/api/v1/',
    'headers'  => ['X-API-Key' => $_ENV['SPAREPILOT_API_KEY']],
    'timeout'  => 10,
]);

function search_oem($ref) {
    global $client;
    $resp = $client->get('search', ['query' => ['q' => $ref, 'limit' => 5]]);
    return json_decode($resp->getBody(), true);
}

// WordPress shortcode
add_shortcode('sparepilot_search', function ($atts) {
    $results = search_oem($atts['ref']);
    return view('sparepilot.search-results', ['items' => $results['items']]);
});

Étape 5 — Composant front HTML/JS minimal

<form id="sp-search">
  <input type="text" name="ref" placeholder="Référence OEM..." required>
  <button type="submit">Identifier</button>
</form>
<div id="sp-results"></div>

<script>
document.getElementById("sp-search").addEventListener("submit", async (e) => {
  e.preventDefault();
  const ref = e.target.ref.value;
  const r = await fetch(`/api/identify?ref=${encodeURIComponent(ref)}`);
  const { items } = await r.json();
  document.getElementById("sp-results").innerHTML = items
    .map(i => `<div>${i.name} — ${i.cheapest_price || "?"}€</div>`)
    .join("");
});
</script>

Total : 30 lignes de code côté backend + 15 lignes côté frontend = widget fonctionnel.

Bonnes pratiques d''intégration

Caching côté client

Les fiches produit changent rarement (prix et stock toutes les heures, données structurelles tous les jours). Mettez en cache vos appels API avec un TTL :

• Search par référence OEM : TTL 1h (résultats stables)
• Fiche produit /products/{id} : TTL 30 min (les prix peuvent changer)
• Liste machines : TTL 24h (structure stable)
• Cross-références équivalents : TTL 24h

Redis ou Memcached suffit. Un système de cache local divise par 10-20 votre consommation de requêtes API.

Gestion des erreurs

HTTP 200 — Succès, parser le JSON
HTTP 400 — Paramètres invalides (lire le champ "detail" du body)
HTTP 401 — Clé API invalide ou absente
HTTP 404 — Ressource non trouvée
HTTP 429 — Rate limit dépassé (header Retry-After = secondes à attendre)
HTTP 500 — Erreur serveur Sparepilot (relancer la requête)
HTTP 503 — Maintenance planifiée

Implémentez un exponential backoff sur 429 et 5xx : tentative 1 immédiate, tentative 2 à +1s, tentative 3 à +4s, tentative 4 à +16s, puis abandon.

Webhook pour les changements de prix

Sur tier Pro et Enterprise, configurez un webhook qui reçoit une notification HTTP POST quand un prix change pour les références que vous suivez. Plus efficace que polling toutes les heures pour 1 000 références.

POST https://sparepilot.com/api/v1/webhooks
{
  "url": "https://votre-site.com/sparepilot-webhook",
  "events": ["price.changed", "stock.changed"],
  "filter": { "product_ids": [42, 100, 200] }
}

Limitations à connaître

• Pas de POST/PUT/DELETE sur tier gratuit — lecture seule
• Pas d''accès aux raw observations (source_observations) — exposé en Enterprise uniquement
• Images servies via CDN externe — pas notre infrastructure mais des distributeurs (URLs hotlinkables, mais respectez les droits d''image en cas d''usage commercial)
• Géolocalisation des prix non disponible — les prix sont en EUR France métropolitaine
• SLA 99,7 % uptime garanti sur Pro et Enterprise (best-effort sur gratuit)

Roadmap API 2026

• T2 2026 — Endpoint /api/v1/repair-guides/{machine_id} exposant les chunks RAG des manuels d''entretien
• T3 2026 — Webhook stock pour pré-commandes B2B (notification quand une pièce repasse en stock chez un distributeur partenaire)
• T4 2026 — API GraphQL en complément du REST

Comment tester sans clé ?

Le playground interactif sur /developers permet d''essayer chaque endpoint sans authentification (limité à 10 requêtes/heure depuis votre IP). Idéal pour explorer le format des réponses avant de coder.

La documentation OpenAPI/Swagger est servie sur /docs — schémas complets, paramètres, exemples cURL, génération automatique de SDK pour 40+ langages.

Support développeur

Pour toute question technique : developers@sparepilot.com (réponse sous 24 h ouvrées). Pour les tier Pro et Enterprise, support prioritaire avec SLA réponse 4 h ouvrées et accès Slack partagé.

Issues, requêtes de fonctionnalités et changelog API : github.com/sparepilot/api-public.