Produktiv · Version 2.0

Vinalfa API für OEM-Kataloge

Serverseitige REST API für VIN und FRAME, Fahrzeugdaten, Katalogstruktur, Zeichnungen, Teilenummern, Schnellauswahl und Teilesuche.

API-Token anfordern OpenAPI 3.1 JSON

Basis-URL https://api.vinalfa.com/oem/v2

API V2.0 ist betriebsbereit

REST + JSONEinheitliches Antwortformat und vorhersehbare HTTP-Statuscodes.

OpenAPI 3.1Schema für Postman, SDKs und generierte Clients.

VIN + FRAMEVIN, die letzten 7 Zeichen von BMW/MINI und japanische FRAME-Nummern.

An Abonnement gebundenEin Token sieht nur die Kataloge seines aktiven Abonnements.

Schnellstart

Erstellen Sie in Ihrem Konto ein separates Server-Token. Ein öffentliches Widget-Token kann nicht auf die Server-API zugreifen.

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

Authentifizierung

Übermitteln Sie das Token im standardmäßigen Bearer-Header. Jedes Token gehört zu genau einem Abonnement.

Speichern Sie das API-Token ausschließlich im Backend. Veröffentlichen Sie es niemals in HTML, Frontend-JavaScript oder einem öffentlichen Repository.

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

API-V2.0-Endpunkte

Hashes sind undurchsichtig: Speichern Sie zurückgegebene Werte und übermitteln Sie sie unverändert.

GET/catalogs

Kataloge des aktiven Abonnements.

POST/vehicles/resolve

Fahrzeug über VIN, letzte 7 Zeichen oder FRAME.

GET/vehicles/{vehicleHash}/groups

Hauptgruppen des ausgewählten Fahrzeugs.

GET/vehicles/{vehicleHash}/quick-selection

Teileklassen und Schnellauswahl.

GET/sections/{sectionHash}/children

Unterbereiche und verfügbare Zeichnungen.

GET/sections/{sectionHash}/parts

Zeichnung, Koordinaten, Positionen und Teilenummern.

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

Fahrzeugbezogene Suche nach Bezeichnung oder Teilenummer.

POST/article-schemes/search

Abbildungen nach Teilenummer und Marke suchen. Erfolgreiche Ergebnisse werden auf das Abbildungslimit angerechnet.

POST/article-schemes/availability

Bis zu 100 Paare aus Teilenummer und Marke prüfen, ohne das Abbildungslimit zu belasten.

POST/article-relations/resolve

Aktuelle, frühere und ersetzte Teilenummern mit Herkunftsnachweis auflösen.

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"}]}'

Anfrageablauf

Durchlaufen Sie die Kataloge nicht selbst: resolve berücksichtigt WMI, zweite VIN, letzte 7 Zeichen, FRAME und Quellenprioritäten.

01Ermitteln

Senden Sie eine VIN oder FRAME-Nummer.

02Gruppen

Wählen Sie eine Ausführung und verwenden Sie deren Hash.

03Bereiche

Folgen Sie den Bereichs-Hashes bis zur Zeichnung.

04Teile

Erhalten Sie Bild, Hotspots und Teilenummern.

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"}'

Antworten und Fehler

Erfolgreiche Antworten enthalten data und meta. Fehler enthalten code, message und request_id.

200 OK

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

4xx / 429

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

Limits und Sicherheit

Limits schützen Abonnement und Infrastruktur, ohne die normale Navigation in einem geöffneten Katalog zu beeinträchtigen.

Anfragelimit	Bis zu 120 Serveranfragen pro Minute und API-Token.
VIN / FRAME	Eine Kennung wird innerhalb eines Abonnements nur einmal pro Kalendertag gezählt.
Navigation	Das Öffnen von Bereichen, Zeichnungen und Teilen belastet dieselbe VIN nicht erneut.
Token	Bei Kompromittierung erneuern Sie das Token im Konto; das vorherige Token wird sofort widerrufen.