Vehicle Data API 호출

사업자(Business Users)가 Vehicle Data API를 호출하는 절차를 설명합니다.

API URL

API URL for Vehicle Data API

https://api.pleos.ai

Header

Authorization API와 Vehicle Data API 호출에 사용하는 헤더는 다음과 같습니다.

Authorization API 헤더

파라미터	타입	설명	필수 여부
Content-Type	string	application/json	Optional
Brand	string	차량 브랜드(hyundai/kia/genesis)	Required

Vehicle Data API 헤더

파라미터	타입	설명	필수 여부
Authorization	string	Bearer <ACCESS_TOKEN>	Required
Content-Type	string	application/json	Optional
Brand	string	차량 브랜드(hyundai/kia/genesis)	Required

Vehicle Data API 호출

Vehicle Data API는 별도 호출 순서 없이 개별 API를 단독으로 호출할 수 있습니다. 단, 액세스 토큰을 먼저 발급받은 후 Vehicle Data API를 호출해야 합니다.

1. 인증 문서를 참고하여 액세스 토큰 발급 API를 호출합니다.

2. 차량 선택 및 차량 데이터 공유 동의 문서를 참고하여 차량 소유자에게 차량을 선택하고 데이터 공유에 동의하도록 요청합니다.

3. API 요청에 액세스 토큰과 차량의 vin을 각각 Authorization 헤더와 경로 파라미터로 포함합니다.

4. Vehicle Data API를 호출하고 결과를 확인합니다.

   예를 들어 차량의 배터리 충전 상태를 조회하려면 다음 API를 호출합니다.

   curl

   curl -X GET "https://api.pleos.ai/v1/vehicles/{vin}/batteries" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -H "Brand: hyundai"

응답 메시지

성공

성공 응답은 다음 형식을 따릅니다.

Response Envelope

{
  "data": {
    ...
  },
  "meta": {
    "code": 200,
    "message": "Success",
    "success": true,
    "timestamp": "2026-07-03T10:00:00+09:00",
    "requestId": "835bdbd4-1105-4a8c-b438-fa0873d1b246"
  }
}

필드	타입	설명
data	object	API별 응답 데이터
meta	object	응답 메타 정보
meta.code	number	응답 코드
meta.message	string	응답 메시지
meta.success	boolean	성공 여부
meta.timestamp	string	응답 시각
meta.requestId	string	요청 ID

실패

실패 응답은 다음 형식을 따릅니다.

Error Response

{
  "error": {
    "code": "40001",
    "message": "Invalid Parameters",
    "requestId": "835bdbd4-1105-4a8c-b438-fa0873d1b246",
    "details": [
      {
        "field": "identifier",
        "issue": "공백일 수 없습니다."
      }
    ],
    "timestamp": "2026-07-03T10:00:00+09:00"
  }
}

필드	타입	설명
error	object	오류 정보
error.code	string	에러 코드
error.message	string	오류 메시지
error.requestId	string	요청 ID
error.details	array	오류 상세 목록
error.details.field	string	오류가 발생한 필드
error.details.issue	string	필드별 오류 내용
error.timestamp	string	오류 발생 시각

정보

에러 코드 목록은 에러 코드를 참조합니다.