本番環境 · バージョン2.0

Vinalfa OEMカタログ API

VINとFRAME、車両情報、カタログ構造、図面、部品番号、クイック選択、部品検索に対応するサーバーサイドREST APIです。

APIトークンを取得 OpenAPI 3.1 JSON

ベースURL https://api.vinalfa.com/oem/v2

API V2.0 稼働中

REST + JSON統一されたレスポンス形式と予測可能なHTTPステータス。

OpenAPI 3.1Postman、SDK、クライアント生成用のスキーマ。

VIN + FRAMEVIN、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ヘッダーでトークンを送信します。各トークンは1つのサブスクリプションに属します。

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、第2VIN、末尾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トークン1つにつき1分あたり最大120件のサーバーリクエスト。
VIN / FRAME	同じサブスクリプションでは、1つの識別子は暦日ごとに1回だけカウントされます。
ナビゲーション	特定済み車両のセクション、図面、部品を開いても同じVINは再度消費されません。
トークン	漏えいした場合はアカウントで再発行してください。以前のトークンは直ちに無効になります。