Produzione · versione 2.0

API cataloghi OEM Vinalfa

API REST lato server per VIN e FRAME, dati del veicolo, struttura del catalogo, tavole, codici ricambio, selezione rapida e ricerca dei componenti.

Ottieni un token API OpenAPI 3.1 JSON

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

API V2.0 operativa

REST + JSONFormato di risposta uniforme e stati HTTP prevedibili.

OpenAPI 3.1Schema per Postman, SDK e generazione dei client.

VIN + FRAMEVIN, ultime 7 cifre BMW/MINI e FRAME giapponese.

Legata all’abbonamentoIl token accede solo ai cataloghi inclusi nell’abbonamento attivo.

Avvio rapido

Genera nel tuo account un token server dedicato. Il token pubblico del widget non può accedere all’API server.

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

Autenticazione

Invia il token tramite l’intestazione Bearer standard. Ogni token appartiene a un solo abbonamento.

Conserva il token API esclusivamente nel backend. Non esporlo in HTML, JavaScript frontend o repository pubblici.

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

Endpoint API V2.0

Gli hash sono opachi: conserva i valori restituiti e trasmettili senza modificarli.

GET/catalogs

Cataloghi dell’abbonamento attivo.

POST/vehicles/resolve

Veicolo tramite VIN, ultime 7 cifre o FRAME.

GET/vehicles/{vehicleHash}/groups

Gruppi principali del veicolo selezionato.

GET/vehicles/{vehicleHash}/quick-selection

Classi di ricambi e selezione rapida.

GET/sections/{sectionHash}/children

Sottosezioni e tavole disponibili.

GET/sections/{sectionHash}/parts

Tavola, coordinate, posizioni e codici ricambio.

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

Ricerca per nome o codice ricambio in base al veicolo.

POST/article-schemes/search

Cerca gli schemi per codice ricambio e marca. I risultati validi consumano il limite degli schemi.

POST/article-schemes/availability

Verifica fino a 100 coppie di codice ricambio e marca senza consumare il limite degli schemi.

POST/article-relations/resolve

Risolvi codici ricambio attuali, precedenti e sostituiti con evidenza della fonte.

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

Flusso delle richieste

Non interrogare i cataloghi uno per uno: resolve applica WMI, secondo VIN, ultime 7 cifre, FRAME e priorità delle fonti.

01Identificazione

Invia un VIN o FRAME.

02Gruppi

Seleziona una variante e usa il relativo hash.

03Sezioni

Segui gli hash delle sezioni fino alla tavola.

04Ricambi

Ottieni immagine, hotspot e codici ricambio.

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

Risposte ed errori

Una risposta corretta contiene data e meta. Gli errori contengono code, message e request_id.

200 OK

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

4xx / 429

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

Limiti e sicurezza

I limiti proteggono abbonamento e infrastruttura senza penalizzare la normale navigazione in un catalogo aperto.

Limite richieste	Fino a 120 richieste server al minuto per ciascun token API.
VIN / FRAME	Ogni identificativo viene conteggiato una sola volta per giorno di calendario all’interno dello stesso abbonamento.
Navigazione	Aprire sezioni, tavole e ricambi non addebita nuovamente lo stesso VIN.
Token	In caso di compromissione, rigenera il token nell’account; quello precedente verrà revocato immediatamente.