生产环境 · 版本 2.0

Vinalfa OEM 目录 API

面向服务器端的 REST API，支持 VIN 与 FRAME、车辆数据、目录结构、图纸、零件号、快速筛选和零件搜索。

获取 API 令牌 OpenAPI 3.1 JSON

基础 URL https://api.vinalfa.com/oem/v2

API V2.0 运行正常

REST + JSON统一的响应格式和可预期的 HTTP 状态码。

OpenAPI 3.1适用于 Postman、SDK 和客户端代码生成的规范。

VIN + FRAME支持 VIN、BMW/MINI 后 7 位和日系 FRAME。

绑定订阅令牌只能访问其有效订阅中的目录。

快速开始

请在账户中创建专用的服务器令牌。公开的组件令牌不能访问服务器 API。

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

身份验证

通过标准 Bearer 请求头发送令牌。每个令牌仅属于一个订阅。

API 令牌只能保存在后端。切勿将其暴露在 HTML、前端 JavaScript 或公开代码仓库中。

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

API V2.0 接口

Hash 是不透明标识：请保存返回值，并在后续请求中原样传递。

GET/catalogs

有效订阅中可用的目录。

POST/vehicles/resolve

通过 VIN、后 7 位或 FRAME 识别车辆。

GET/vehicles/{vehicleHash}/groups

所选车辆的顶级分组。

GET/vehicles/{vehicleHash}/quick-selection

零件分类与快速筛选。

GET/sections/{sectionHash}/children

子分组和可用图纸。

GET/sections/{sectionHash}/parts

图纸、坐标、位置和零件号。

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

结合车辆信息按名称或零件号搜索。

POST/article-schemes/search

按零件号和品牌查找图纸。成功结果会计入图纸链接限额。

POST/article-schemes/availability

最多检查100组零件号和品牌，且不消耗图纸链接限额。

POST/article-relations/resolve

解析当前、旧版和替代零件号，并返回来源依据。

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

请求流程

无需自行逐个查询目录：resolve 会应用 WMI、第二 VIN、后 7 位、FRAME 和数据源优先级。

01识别

提交 VIN 或 FRAME。

02分组

选择车辆配置并使用其 Hash。

03章节

沿章节 Hash 进入对应图纸。

04零件

获取图像、热点坐标和零件号。

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

响应与错误

成功响应包含 data 和 meta。错误包含机器可读的 code、message 和 request_id。

200 OK

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

4xx / 429

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

限制与安全

限制用于保护订阅和基础设施，不会影响已打开目录中的正常浏览。

请求频率	每个 API 令牌每分钟最多 120 次服务器请求。
VIN / FRAME	在同一订阅中，同一标识符每个自然日只计数一次。
浏览	打开已识别车辆的章节、图纸和零件不会再次扣减 VIN 次数。
令牌	若令牌泄露，请在账户中重新签发；旧令牌将立即失效。