Production · version 2.0

Vinalfa OEM Catalog API

A server-side REST API for VIN and FRAME, vehicle data, catalog structure, diagrams, part numbers, quick selection and parts search.

Trial: 5 days / 10 VINs Get an API token OpenAPI 3.1 JSON

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

API V2.0 is operational

REST + JSONOne response format and predictable HTTP statuses.

OpenAPI 3.1Schema for Postman, SDKs and generated clients.

VIN + FRAMEVIN, BMW/MINI last 7 and Japanese FRAME.

Subscription-boundA token only sees catalogs in its active subscription.

Quick start

Issue a dedicated server token in your account. A public widget token cannot access the server API.

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

Authentication

Send the token using the standard Bearer header. Each token belongs to one subscription.

Keep the API token on your backend. Never expose it in HTML, frontend JavaScript or a public repository.

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

API V2.0 endpoints

Hashes are opaque: keep returned values and pass them unchanged.

GET/catalogs

Catalogs in the active subscription.

POST/vehicles/resolve

Vehicle by VIN, last 7 or FRAME.

GET/vehicles/{vehicleHash}/groups

Top-level groups for the selected vehicle.

GET/vehicles/{vehicleHash}/quick-selection

Part classes and quick selection.

GET/sections/{sectionHash}/children

Child sections and available diagrams.

GET/sections/{sectionHash}/parts

Diagram, coordinates, positions and part numbers.

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

Vehicle-aware search by name or part number.

POST/article-schemes/search

Find diagrams by article and brand. Successful results count against the scheme limit.

POST/article-schemes/availability

Check up to 100 article and brand pairs without consuming the scheme limit.

POST/article-relations/resolve

Resolve current, previous and replacement part numbers with source evidence.

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

Request workflow

Do not iterate through catalogs yourself: resolve applies WMI, second VIN, last 7, FRAME and source priorities.

01Resolve

Send a VIN or FRAME.

02Groups

Select a modification and use its hash.

03Sections

Follow section hashes to a diagram.

04Parts

Receive the image, hotspots and part numbers.

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

Responses and errors

Success contains data and meta. Errors contain a machine code, message and request_id.

200 OK

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

4xx / 429

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

Limits and security

Limits protect the subscription and infrastructure without penalizing normal navigation in an opened catalog.

Rate limit	Up to 120 server requests per minute per API token.
VIN / FRAME	One identifier is counted once per calendar day within one subscription.
Navigation	Opening sections, diagrams and parts does not charge the same VIN again.
Token	If compromised, rotate the token in your account; the previous token is revoked immediately.