본문으로 건너뛰기

Vehicle Data API 호출

차량 소유자(Private Users)가 Vehicle Data API를 호출하는 절차를 설명합니다.

인증 과정을 제외하면 Vehicle Data API는 Business Users용 API와 동일합니다.

API URL​

API URL for Vehicle Data API
https://api.pleos.ai

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

파라미터타입설명필수 여부
AuthorizationstringBearer <ACCESS_TOKEN>Required
Content-Typestringapplication/jsonOptional
Brandstring차량 브랜드(hyundai/kia/genesis)Required

Vehicle Data API 호출​

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

주의

Vehicle Data API를 호출할 때는 다음 값이 서로 일치해야 합니다.

  • Brand: 액세스 토큰 발급 시 선택한 차량 제조사
  • Authorization: Brand로 지정한 차량 제조사의 데이터 조회에 사용하는 액세스 토큰
  • vin: Brand로 지정한 차량 제조사에 속한 차량의 VIN

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

  2. Get Vehicles를 호출하여 조회할 차량의 vin을 확인합니다.

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

  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​

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

Response Envelope
{
  "data": {
    ...
  },
  "meta": {
    "code": 200,
    "message": "Success",
    "success": "true",
    "timestamp": "2026-07-03T10:00:00+09:00",
    "requestId": "835bdbd4-1105-4a8c-b438-fa0873d1b246"
  }
}
필드타입설명
dataobjectAPI별 응답 데이터
metaobject응답 메타 정보
meta.codenumber응답 코드
meta.messagestring응답 메시지
meta.successboolean성공 여부
meta.timestampstring응답 시각
meta.requestIdstring요청 ID

Error Response​

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

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"
  }
}
필드타입설명
errorobject오류 정보
error.codestring에러 코드
error.messagestring오류 메시지
error.requestIdstring요청 ID
error.detailsarray오류 상세 목록
error.details.fieldstring오류가 발생한 필드
error.details.issuestring필드별 오류 내용
error.timestampstring오류 발생 시각
정보

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