상품 - 카플랫 개발자 센터

카플랫 시스템에서 상품(Product) 도메인의 역할과 구성 요소를 설명합니다. 이 문서는 물리적 자산인 '차량'이 어떻게 판매 가능한 서비스 단위로 추상화되는지 이해하고 관련 API 개발에 활용하는 것을 목표로 합니다.

1. 상품(Product)이란?

카플랫에서 상품(Product)은 고객에게 실제 판매되는 렌터카 서비스 단위입니다. 이것은 물리적인 차량 목록(Car List) 에 요금(Fare Plan), 운영 정책(Policy), 보험 조건(Insurance Plan) 등을 결합한 논리적인 패키지입니다.

고객은 특정 차량(license_plate: 12가3456)을 예약하는 것이 아니라, "주중 시간당 15,000원짜리 아반떼 렌트"와 같은 상품을 보고 예약합니다.

하나의 상품(예: 아반떼 상품)은 여러 대의 동일 차종 차량(아반떼 1호기, 2호기, 3호기)을 재고(inventory)로 가질 수 있습니다. 이를 통해 렌트카 업체는 개별 차량이 아닌, 차종 기반의 재고 관리가 가능해져 운영 효율성이 극대화됩니다.

2. 상품의 데이터 모델

상품은 여러 하위 정책 객체와 관계를 맺는 복합 객체입니다.

json

idinteger
상품 일련번호
productNamestring
상품명
carTypeMakerCodeinteger
제조사코드
seaterinteger
인승
carTypeBaseModelCodeinteger
대표모델코드
carTypeDetailModelCodeinteger
세부모델코드
carTypeDetailModelNamestring
세부모델명
carTypeFuelCodeinteger
유종코드
carTypeFuelNamestring
유종명
insuranceAgeLimitstring
보험연령 (O:21세이상, S:26세이상)
licenseTypestring
면허종류 (O:1종보통, T:2종보통, H:1종 대형)
fareIdinteger
요금제 일련번호
updateNamestring
수정자 이름
updateDateTimestring
수정 시간
basicSectionFareInfoobject
요금제 정보
- fareIdinteger
  요금제 식별값
- namestring
  요금제 명
- baseFareinteger
  기본 요금
- maxFareinteger
  최대(상한) 요금
productCarOptionListarray<object>
차량옵션리스트
Array items:
- idinteger
  옵션일련번호
- optionNamestring
  옵션명
- optionStringstring
  KM 전달용 문자열
- optionValuestring
  선택여부 (Y: 설치, N:미설치)

상품 승인 상태(productApproveStatus) 유형

상태	한글명	설명
`0`	승인대기	상품 등록 후 카플랫 관리자의 승인을 대기하는 상태
`1`	승인완료	승인이 완료되어 고객이 예약할 수 있는 상태

차량 판매 상태(saleYn) 유형

상태	한글명	설명
`Y`	판매중	해당 차량이 예약 가능한 상태
`N`	판매중지	해당 차량이 일시적으로 예약 불가능한 상태

3. 상품의 생명주기

3.1 생성 (Creation)

방법: carplat.co.kr 웹사이트의 상품 관리 페이지
설명: 렌트카 업체는 카플랫 웹사이트에 로그인하여 상품 관리 메뉴에서 새로운 상품을 등록합니다. 차종 정보, 요금제, 차량 목록, 옵션 등을 웹 인터페이스를 통해 설정합니다.
초기 상태: 0(승인대기)

3.2 상품 수정 (Update)

방법: carplat.co.kr 웹사이트의 상품 관리 페이지
설명: 등록된 상품의 정보를 카플랫 웹사이트에서 수정할 수 있습니다. 차량 추가/제거, 옵션 변경, 요금제 수정 등이 가능합니다.

3.3 승인 완료 (Approval)

수행자: 카플랫 관리자
설명: 웹사이트에서 등록/수정된 상품을 카플랫 관리자가 검토한 후 승인하면 productApproveStatus가 1(승인완료)로 변경됩니다. 이 시점부터 고객이 예약할 수 있게 됩니다.

3.4 차량 판매 상태 관리

API: PUT /product/{id}/car/{carId}/sale_status
설명: 상품 내 특정 차량의 판매 상태를 개별적으로 관리할 수 있습니다. saleYn을 "Y" 또는 "N"으로 설정하여 차량별 판매 여부를 제어합니다. 이는 API를 통해서도 제어 가능합니다.

3.5 상품 삭제 (Deletion)

방법: carplat.co.kr 웹사이트의 상품 관리 페이지
설명: 더 이상 사용하지 않는 상품을 카플랫 웹사이트에서 삭제할 수 있습니다.

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

렌트카 업체 개발자

상품 관리: 상품의 생성, 수정, 삭제는 carplat.co.kr 웹사이트에서 직접 진행합니다. API를 통한 상품 등록은 지원하지 않으며, 웹 인터페이스를 통해 차종 정보, 요금제, 차량 목록, 옵션 등을 설정해야 합니다.
상품 조회: GET /product API로 등록된 상품 목록을 조회하고, GET /product/{id} API로 특정 상품의 상세 정보를 확인할 수 있습니다. 이를 통해 내부 시스템과 카플랫 상품 정보를 동기화할 수 있습니다.
판매 상태 제어: PUT /product/{id}/car/{carId}/sale_status API로 개별 차량의 판매 상태를 실시간으로 제어할 수 있습니다. 정비나 사고 등으로 특정 차량을 일시 중단해야 할 때 유용합니다.
차량 재고 관리: GET /product/{id}/relatedCar API로 상품 내 등록된 차량 목록과 각 차량의 판매 상태를 확인하여 실시간 재고 관리에 활용할 수 있습니다.

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

상품 목록 조회: GET /product API로 승인완료된 상품 목록을 조회합니다. productApproveStatus=1로 필터링하여 승인된 상품만 고객에게 노출해야 합니다.
상품 상세 조회: GET /product/{id} API로 특정 상품의 상세 정보를 조회할 수 있습니다. 요금제 정보(basicSectionFareInfo)와 옵션 정보(productCarOptionList)를 함께 제공받아 고객에게 상세한 정보를 안내할 수 있습니다.
요금제별 상품 조회: GET /product/fareId/{fareId} API로 특정 요금제에 속한 상품들을 조회할 수 있습니다. 가격대별로 상품을 분류하여 보여줄 때 유용합니다.
차량 재고 확인: 상품 내 등록된 차량 목록은 GET /product/{id}/relatedCar API로 조회할 수 있으며, 각 차량의 saleYn 상태를 확인하여 실제 예약 가능한 재고를 파악해야 합니다.

개발자 센터

카플랫 이해하기

상품