Producción · versión 2.0

API de catálogos OEM Vinalfa

API REST para servidor con VIN y FRAME, datos del vehículo, estructura del catálogo, esquemas, referencias, selección rápida y búsqueda de repuestos.

Obtener token de API OpenAPI 3.1 JSON

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

API V2.0 operativa

REST + JSONFormato de respuesta unificado y estados HTTP previsibles.

OpenAPI 3.1Esquema para Postman, SDK y generación de clientes.

VIN + FRAMEVIN, últimos 7 caracteres de BMW/MINI y FRAME japonés.

Vinculada a la suscripciónEl token solo accede a los catálogos de su suscripción activa.

Inicio rápido

Emita un token de servidor independiente desde su cuenta. El token público del widget no permite acceder a la API de servidor.

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

Autenticación

Envíe el token mediante el encabezado Bearer estándar. Cada token pertenece a una sola suscripción.

Guarde el token de API únicamente en el backend. No lo exponga en HTML, JavaScript del frontend ni en repositorios públicos.

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

Métodos de API V2.0

Los hash son opacos: conserve los valores devueltos y envíelos sin modificarlos.

GET/catalogs

Catálogos de la suscripción activa.

POST/vehicles/resolve

Vehículo por VIN, últimos 7 caracteres o FRAME.

GET/vehicles/{vehicleHash}/groups

Grupos principales del vehículo seleccionado.

GET/vehicles/{vehicleHash}/quick-selection

Clases de repuestos y selección rápida.

GET/sections/{sectionHash}/children

Subsecciones y esquemas disponibles.

GET/sections/{sectionHash}/parts

Esquema, coordenadas, posiciones y referencias.

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

Búsqueda por nombre o referencia teniendo en cuenta el vehículo.

POST/article-schemes/search

Buscar diagramas por referencia y marca. Los resultados correctos consumen el límite de diagramas.

POST/article-schemes/availability

Comprobar hasta 100 pares de referencia y marca sin consumir el límite de diagramas.

POST/article-relations/resolve

Resolver referencias actuales, anteriores y sustituidas con evidencia de origen.

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

Flujo de solicitudes

No recorra los catálogos manualmente: resolve aplica WMI, segundo VIN, últimos 7 caracteres, FRAME y prioridades de fuentes.

01Identificar

Envíe un VIN o FRAME.

02Grupos

Seleccione una variante y utilice su hash.

03Secciones

Siga los hash de sección hasta llegar al esquema.

04Repuestos

Obtenga la imagen, los puntos interactivos y las referencias.

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

Respuestas y errores

Una respuesta correcta contiene data y meta. Los errores contienen code, message y request_id.

200 OK

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

4xx / 429

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

Límites y seguridad

Los límites protegen la suscripción y la infraestructura sin penalizar la navegación normal por un catálogo abierto.

Límite de solicitudes	Hasta 120 solicitudes al servidor por minuto y por token de API.
VIN / FRAME	Cada identificador se contabiliza una sola vez por día natural dentro de una suscripción.
Navegación	Abrir secciones, esquemas y repuestos no vuelve a descontar el mismo VIN.
Token	Si se ve comprometido, vuelva a emitir el token desde su cuenta; el anterior se revocará de inmediato.