Production · version 2.0

API de catalogues OEM Vinalfa

API REST côté serveur pour VIN et FRAME, données véhicule, structure du catalogue, schémas, références, sélection rapide et recherche de pièces.

Obtenir un jeton API OpenAPI 3.1 JSON

URL de base https://api.vinalfa.com/oem/v2

API V2.0 opérationnelle

REST + JSONFormat de réponse unique et statuts HTTP prévisibles.

OpenAPI 3.1Schéma pour Postman, les SDK et la génération de clients.

VIN + FRAMEVIN, 7 derniers caractères BMW/MINI et FRAME japonais.

Liée à l’abonnementLe jeton accède uniquement aux catalogues de son abonnement actif.

Démarrage rapide

Créez un jeton serveur dédié dans votre compte. Le jeton public du widget ne permet pas d’accéder à l’API serveur.

curl --request GET \
  --url "https://api.vinalfa.com/oem/v2/catalogs" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Authentification

Envoyez le jeton dans l’en-tête Bearer standard. Chaque jeton appartient à un seul abonnement.

Conservez le jeton API uniquement sur le backend. Ne l’exposez jamais dans le HTML, le JavaScript frontend ou un dépôt public.

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
Content-Type: application/json
X-Request-ID: your-trace-id

Méthodes de l’API V2.0

Les hash sont opaques : conservez les valeurs renvoyées et transmettez-les sans modification.

GET/catalogs

Catalogues de l’abonnement actif.

POST/vehicles/resolve

Véhicule par VIN, 7 derniers caractères ou FRAME.

GET/vehicles/{vehicleHash}/groups

Groupes principaux du véhicule sélectionné.

GET/vehicles/{vehicleHash}/quick-selection

Classes de pièces et sélection rapide.

GET/sections/{sectionHash}/children

Sous-sections et schémas disponibles.

GET/sections/{sectionHash}/parts

Schéma, coordonnées, positions et références.

GET/vehicles/{vehicleHash}/search?q=...

Recherche par nom ou référence adaptée au véhicule.

POST/article-schemes/search

Rechercher des schémas par référence et marque. Un résultat valide est décompté de la limite de schémas.

POST/article-schemes/availability

Vérifier jusqu’à 100 paires référence et marque sans consommer la limite de schémas.

POST/article-relations/resolve

Résoudre les références actuelles, anciennes et remplacées avec leur preuve source.

curl --request POST \
  --url "https://api.vinalfa.com/oem/v2/article-schemes/availability" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"items":[{"article":"5K0698151H8","brand":"VAG"},{"article":"A6421800010","brand":"Mercedes-Benz"}]}'

Flux des requêtes

Ne parcourez pas les catalogues vous-même : resolve applique le WMI, le second VIN, les 7 derniers caractères, le FRAME et les priorités de sources.

01Identification

Envoyez un VIN ou un FRAME.

02Groupes

Sélectionnez une variante et utilisez son hash.

03Sections

Suivez les hash de section jusqu’au schéma.

04Pièces

Récupérez l’image, les zones interactives et les références.

curl --request POST \
  --url "https://api.vinalfa.com/oem/v2/vehicles/resolve" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"identifier":"TMBJF25LXC6071337"}'

Réponses et erreurs

Une réponse réussie contient data et meta. Les erreurs contiennent code, message et request_id.

200 OK

{
  "data": { "catalogs": [] },
  "meta": {
    "api_version": "2.0",
    "request_id": "..."
  }
}

4xx / 429

{
  "error": {
    "code": "validation_failed",
    "message": "..."
  },
  "meta": { "request_id": "..." }
}

Limites et sécurité

Les limites protègent l’abonnement et l’infrastructure sans pénaliser la navigation normale dans un catalogue ouvert.

Limite de requêtes	Jusqu’à 120 requêtes serveur par minute et par jeton API.
VIN / FRAME	Un identifiant est comptabilisé une seule fois par jour calendaire dans le cadre d’un abonnement.
Navigation	L’ouverture des sections, schémas et pièces ne décompte pas une seconde fois le même VIN.
Jeton	En cas de compromission, régénérez le jeton dans votre compte ; le précédent sera immédiatement révoqué.