카플랫 시스템에서 차량(Car) 도메인의 역할과 핵심 개념을 설명합니다. 이 문서를 통해 차량 관련 API를 이해하고 연동 개발을 원활하게 수행하는 것을 목표로 합니다.

1. 차량(Car)이란?

카플랫에서 차량(Car) 은 렌트카 사업자가 소유한 물리적인 자동차 자산을 의미하는 핵심 데이터 객체(Object)입니다. 시스템에 등록된 모든 차량은 고유한 식별자를 가지며, 렌트 서비스의 가장 기본적인 단위가 됩니다.

차량은 그 자체로 고객에게 판매되는 상품이 아니며, 실제 판매를 위한 상품(Product) 객체를 생성하기 위한 기반 데이터입니다.

2. 차량의 데이터 모델

차량 API를 연동할 때 주로 다루게 될 데이터 속성은 다음과 같습니다.

• idinteger

  차량 일련번호

• businessLicenseIdinteger

  사업자 일련번호

• businessLicenseNamestring

  사업자명

• carNumberstring

  차량번호

• carTypeFuelCodeinteger

  유종코드

• carTypeFuelNamestring

  유종명

• carTypeGradeCodeinteger

  등급코드

• carTypeGradeNamestring

  등급명

• carTypeNamestring

  차종명

• modelYearinteger

  연식

• carTypeDetailModelNamestring

  세부모델명

• displacementinteger

  배기량

• seaterinteger

  인승

• vinstring

  차대번호

• colorstring

  색상

• carRegisterDatestring

  차량등록일 (yyyy-MM-dd)

• updateNamestring

  수정자 이름

• updateDateTimestring

  수정 시간

• usimNumberstring

  유심번호

• attachFileobject

  차량등록증 파일

  • idinteger

    파일 일련번호

  • logicalFileNamestring

    차량등록증파일 논리명

• carOptionListarray<object>

  차량 옵션 목록

  Array items:

  • optionKey1string

    차량 옵션코드1

  • optionNm1string

    차량 옵션명1

  • optionValuestring

    설치여부 (Y:설치, N:미설치)

차량 옵션 구조

차량 옵션은 3단계 계층 구조로 관리됩니다:

• optionKey1/optionNm1: 대분류 (예: 외장, 내장, 안전)
• optionKey2/optionNm2: 중분류 (예: 헤드램프, 시트, 에어백)
• optionKey3/optionNm3: 소분류 (예: 할로겐, 가죽, 운전석)
• optionValue: 설치여부 (Y: 설치, N: 미설치)

3. 차량 관리 및 조회

3.1 차량 등록 및 관리

• 방법: carplat.co.kr 웹사이트의 차량 관리 페이지
• 설명: 차량의 등록, 수정, 삭제는 카플랫 웹사이트에서 직접 진행합니다. 차량번호와 사업자 정보를 입력하면 오토비긴즈 API와 연동하여 차종 정보를 자동으로 가져올 수 있습니다.

3.2 차량 목록 조회

• API: GET /car
• 설명: 등록된 차량 목록을 조회합니다. 사업자별, 유종별, 차량번호별 등 다양한 조건으로 필터링할 수 있습니다.
• 주요 파라미터: businessLicenseId, carTypeFuelCd, carNumber, deviceEquipYn 등

3.3 차량 상세 조회

• API: GET /car/{id}
• 설명: 특정 차량의 상세 정보를 조회합니다. 차종 정보, 옵션 목록, 차량등록증 파일 등 모든 정보를 확인할 수 있습니다.

4. 개발자를 위한 핵심 포인트

렌트카 업체 개발자

차량 관리

• 차량 등록: 차량의 등록, 수정, 삭제는 carplat.co.kr 웹사이트에서 직접 진행합니다. API를 통한 차량 등록은 지원하지 않습니다.

• 차량 목록 조회: GET /car API로 등록된 차량 목록을 조회하여 내부 시스템과 동기화할 수 있습니다. businessLicenseId, carTypeFuelCd 등의 파라미터로 필터링이 가능합니다.

• 차량 상세 조회: GET /car/{id} API로 특정 차량의 상세 정보를 확인할 수 있습니다. 차종 정보, 옵션 목록, 차량등록증 파일 정보 등을 포함합니다.

• 차량 메모 관리: GET /car/{id}/memo API로 차량별 메모를 조회하고, POST /car/{id}/memo API로 새로운 메모를 추가할 수 있습니다. 정비 이력이나 특이사항을 기록하는 용도로 활용할 수 있습니다.

수요 채널(서비스사) 개발자

차량 정보 조회

• 목록 조회: GET /car API로 차량 목록을 조회할 수 있지만, 일반적으로 상품(Product) API를 통해 예약 가능한 차량 정보를 확인하는 것이 더 적합합니다.

배정 차량 확인

• 상세 조회: 고객이 예약을 확정한 후, 예약 상세 정보의 productInfo.carId를 통해 GET /car/{id} API로 배정된 차량의 상세 정보를 조회할 수 있습니다.

• 고객 안내: 차량 정보를 통해 고객에게 "제네시스 쿠페 회색, 44가4444 차량이 배달 완료되었습니다." 와 같은 구체적인 안내를 제공할 수 있습니다.