Canlı · sürüm 2.0

Vinalfa OEM Katalog API

VIN ve FRAME, araç bilgileri, katalog yapısı, şemalar, parça numaraları, hızlı seçim ve parça araması için sunucu taraflı REST API.

API tokeni al OpenAPI 3.1 JSON

Temel URL https://api.vinalfa.com/oem/v2

API V2.0 çalışıyor

REST + JSONTek tip yanıt biçimi ve öngörülebilir HTTP durum kodları.

OpenAPI 3.1Postman, SDK ve istemci üretimi için şema.

VIN + FRAMEVIN, BMW/MINI son 7 karakter ve Japon FRAME desteği.

Aboneliğe bağlıToken yalnızca aktif aboneliğindeki katalogları görür.

Hızlı başlangıç

Hesabınızdan ayrı bir sunucu tokeni oluşturun. Genel widget tokeni sunucu API’sine erişemez.

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

Kimlik doğrulama

Tokeni standart Bearer başlığında gönderin. Her token tek bir aboneliğe aittir.

API tokenini yalnızca backend üzerinde saklayın. HTML, frontend JavaScript veya herkese açık bir depoda paylaşmayın.

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

API V2.0 uç noktaları

Hash değerleri opaktır: dönen değerleri saklayın ve değiştirmeden iletin.

GET/catalogs

Aktif abonelikteki kataloglar.

POST/vehicles/resolve

VIN, son 7 karakter veya FRAME ile araç.

GET/vehicles/{vehicleHash}/groups

Seçilen aracın ana grupları.

GET/vehicles/{vehicleHash}/quick-selection

Parça sınıfları ve hızlı seçim.

GET/sections/{sectionHash}/children

Alt bölümler ve kullanılabilir şemalar.

GET/sections/{sectionHash}/parts

Şema, koordinatlar, pozisyonlar ve parça numaraları.

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

Araç bilgisine göre ad veya parça numarasıyla arama.

POST/article-schemes/search

Parça numarası ve markaya göre şema bulun. Başarılı sonuçlar şema limitinden düşülür.

POST/article-schemes/availability

Şema limitini kullanmadan en fazla 100 parça numarası ve marka çiftini kontrol edin.

POST/article-relations/resolve

Güncel, eski ve değiştirilen parça numaralarını kaynak kanıtıyla çözümleyin.

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

İstek iş akışı

Katalogları tek tek denemeyin: resolve WMI, ikinci VIN, son 7 karakter, FRAME ve kaynak önceliklerini uygular.

01Araç bulma

VIN veya FRAME gönderin.

02Gruplar

Bir araç varyantı seçin ve hash değerini kullanın.

03Bölümler

Şemaya ulaşana kadar bölüm hash değerlerini izleyin.

04Parçalar

Görseli, hotspot noktalarını ve parça numaralarını alın.

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

Yanıtlar ve hatalar

Başarılı yanıt data ve meta içerir. Hatalar makine kodu, message ve request_id içerir.

200 OK

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

4xx / 429

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

Limitler ve güvenlik

Limitler, açık bir katalogdaki normal gezinmeyi etkilemeden aboneliği ve altyapıyı korur.

İstek limiti	API tokeni başına dakikada en fazla 120 sunucu isteği.
VIN / FRAME	Aynı abonelikte bir tanımlayıcı her takvim gününde yalnızca bir kez sayılır.
Gezinme	Bulunan aracın bölümlerini, şemalarını ve parçalarını açmak aynı VIN’i yeniden düşmez.
Token	Token ele geçirilirse hesabınızdan yenileyin; önceki token hemen iptal edilir.