개발자 센터

예약

카플랫에서 예약이 생성되고 예약 상태가 변경되는 과정을 설명합니다.

카플랫 시스템에서 예약(Reservation)은 도메인의 생명주기와 상태 변화를 설명합니다. 이 문서는 예약의 흐름을 이해하여 API 기반으로 예약 생성, 관리, 상태 추적 기능을 구현하는 것을 목표로 합니다.

1. 예약(Reservation)이란?

예약(Reservation) 은 특정 고객이 특정 상품(Product)을 정해진 기간 동안 이용하기로 확정한 트랜잭션(Transaction) 입니다. 이는 고객, 상품, 시간을 연결하는 구체적인 이벤트이며, 렌트카 비즈니스의 모든 운영 활동은 예약을 중심으로 이루어집니다.

하나의 예약 건은 생성부터 완료까지 명확한 예약 상태 변화에 따라 흐름이 관리됩니다. 개발자는 이 상태 변화를 정확히 이해하고 추적해야 합니다.

2. 예약의 데이터 모델

예약 정보 등록 이벤트에서 전달되는 예약 객체의 예제는 다음과 같습니다:

json

Loading...

예약 객체의 스키마는 다음과 같습니다:

  • 필수integer

    예약 ID

  • 필수integer

    서비스 ID. 현재는 비대면렌트(1) 고정으로 전달됩니다.

  • 필수integer

    예약 상태 코드(예약 등록시에는 예약완료("5") 고정, 예약 수정시에는 모든 스테이터스가 전달 가능)

    • 5: 예약완료
    • 10: 배차출발
    • 15: 배차완료
    • 20: 이용 중
    • 30: 반납완료
    • 35: 회수완료
    • 40: 예약취소
    • 45: 노쇼취소
    • 50: 예약실패(시스템취소)
  • 필수integer

    차량 ID

  • 필수string

    차량 번호

  • 필수integer

    업체 ID

  • 필수string

    업체명

  • 필수string

    예약 생성 일시(yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)

  • 필수string

    예약 시작 일시(yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)

  • 필수string

    예약 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)

  • string

    운행 시작 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)

  • string

    운행 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)

  • 필수string

    픽업 주소

  • 필수string

    운전자 이름

  • 필수string

    운전자 생년월일 (YYYYMMDD)

  • 필수string

    운전자 전화번호("-" 없이 등록)

  • 필수string

    운전자 면허번호

  • 필수string

    운전자 주소

  • string

    픽업 메모

  • string

    주차 메모

  • string

    주차 이미지 경로 URL

3. 예약의 생명주기 및 상태 머신

예약의 상태(status) 변화는 예약 흐름의 핵심입니다. 각 상태 변경은 특정 API 호출이나 이벤트에 의해 트리거됩니다.

예약 상태 흐름도

예약 상태 흐름도

상태별 상세 설명

상태한글명트리거
5예약 완료고객이 예약을 생성하고 결제를 완료
10배차 출발렌트카 업체가 배차 담당자를 지정하고 담당자가 차량을 고객에게 전달 시작
15배차 완료렌트카 업체가 고객이 요청한 위치까지 차량 배차 완료
20이용 중고객이 차량을 이용 시작
25반납지연예약 종료 시간을 지나도 반납하지 않은 경우
30반납완료고객이 차량을 지정된 위치에 주차하고 반납
35회수완료렌트카 업체가 차량 상태 확인 후 최종 처리
40예약취소고객이 예약을 취소
45노쇼취소예약완료, 배차출발, 배차완료상태에서 예약 종료 일시를 지나도 차량을 반납하지 않은 경우 노쇼로 취소
50예약실패(시스템취소)예약 생성 후 수요 채널(서비스사)에서 응답 실패한 경우

중요 상태 전환점

3.1 배차 시작 (예약완료 → 배차출발)

  • 트리거: 배차 담당자 지정 및 배차 시작
  • API: PUT /developer/v1/reservation/{id}/dispatch/start
  • 중요도: 매우 높음 (배차 프로세스 시작점)

3.2 배차 완료 (배차출발 → 배차완료)

  • 트리거: 차량 배달 완료 및 주차 정보 등록
  • API: PUT /developer/v1/reservation/{id}/dispatch/complete
  • 중요도: 매우 높음 (고객 차량 인수 가능)

3.3 이용 시작 (배차완료 → 이용중)

  • 트리거: 고객의 차량 이용 시작
  • 방법: 스마트키 제어
  • 중요도: 높음 (고객 경험)

3.4 회수 완료 (반납완료 → 회수완료)

  • 트리거: 렌트카 업체의 회수 확인
  • API: PUT /developer/v1/reservation/{id}/recall/complete
  • 중요도: 매우 높음 (정산 및 재고 해제)

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

렌트카 업체 개발자

핵심 책임

예약완료(5) 상태의 예약을 회수완료(35)까지 진행시키는 것이 핵심 업무입니다.

주요 개발 포인트

  • 배차 프로세스:

    • 배차 담당자 지정: PUT /developer/v1/reservation/{id}/dispatch/staff
    • 배차 시작: PUT /developer/v1/reservation/{id}/dispatch/start
    • 주차 사진 등록: POST /developer/v1/reservation/{id}/dispatch/parkingImage
    • 차량 사진 등록: POST /developer/v1/reservation/{id}/dispatch/carImage
    • 배차 완료: PUT /developer/v1/reservation/{id}/dispatch/complete

  • 회수 프로세스:

    • 회수 담당자 지정: PUT /developer/v1/reservation/{id}/recall/staff
    • 차량 사진 등록: POST /developer/v1/reservation/{id}/recall/carImage
    • 회수 완료: PUT /developer/v1/reservation/{id}/recall/complete

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

핵심 책임

고객의 예약 상태 추적과 전체 고객 경험을 관리합니다.

주요 개발 포인트

  • 예약 이벤트 수신 (콜백 이벤트):

    • 예약 생성: 예약이 생성될 때 /events/reservation 콜백 이벤트를 통해 실시간으로 알림을 받습니다.
    • 예약 수정: 예약 정보가 수정될 때 콜백 이벤트로 알림을 받습니다. (엔드포인트 추후 제공 예정)
    • 차량 변경: 예약에 할당된 차량이 변경될 때 콜백 이벤트로 알림을 받습니다. (엔드포인트 추후 제공 예정)
    • 자세한 웹훅 구독 방법은 콜백 이벤트 가이드를 참고하세요.
    • 예약 생성 이벤트의 상세 스펙은 API 레퍼런스의 예약 정보 등록 이벤트를 참고하세요.

  • 실시간 상태 추적:

    • 예약 상태(reservationStatus) 변경을 추적하여 고객에게 적절한 정보를 제공합니다.
    • 카플랫이 제공하는 상태 변경 웹훅을 구독하는 방식을 사용합니다.

  • 상태별 UI/UX:

    • 배차완료(15) 상태가 되면 고객에게 배정된 차량 정보와 주차 위치를 안내
    • 이용중(20) 상태가 되면 '이용 중' 화면을 제공
    • 반납완료(30) 상태가 되면 이용 완료 안내