운영 환경 · 버전 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 헤더로 토큰을 전송합니다. 각 토큰은 하나의 구독에 속합니다.

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이 다시 차감되지 않습니다.
토큰	토큰이 유출된 경우 계정에서 재발급하세요. 이전 토큰은 즉시 폐기됩니다.