스케줄
카플랫에서 차량 스케줄을 관리하고 예약과 연동하는 방법을 설명합니다.
카플랫 시스템에서 스케줄(Schedule) 도메인의 역할과 핵심 개념을 설명합니다. 이 문서를 통해 외부 스케줄 관리 API를 이해하고 연동 개발을 원활하게 수행하는 것을 목표로 합니다.
1. 스케줄(Schedule)이란?
카플랫에서 스케줄(Schedule)은 특정 차량의 시간대별 사용 계획을 관리하는 핵심 데이터 객체입니다. 스케줄은 두 가지 유형으로 구분됩니다:
스케줄 유형
- 예약 스케줄 (R: Reservation): 고객 예약이 확정되면 자동으로 생성되는 스케줄
- 외부 스케줄 (S: Schedule): 정비, 점검, 기타 사유로 직접 등록하는 스케줄
스케줄이 등록된 시간대에는 해당 차량이 수요 채널에 노출되지 않아 새로운 예약을 받을 수 없습니다.
2. 스케줄의 데이터 모델
외부 스케줄을 등록할 때 전달하는 데이터 속성은 다음과 같습니다.
Loading...
- carNumber필수string
차량 번호
- startDateTimeStr필수string
스케줄 시작일시(yyyy-MM-dd HH:mm 형식)
- endDateTimeStr필수string
스케줄 종료일시(yyyy-MM-dd HH:mm 형식)
- reason필수string
사유
등록에 성공하면 응답의 result.id로 스케줄 ID가 전달됩니다. 이 ID는 스케줄을 수정하거나 삭제할 때 사용합니다.
스케줄 타입별 구분
| 타입 | 한글명 | 설명 | 생성 방식 |
|---|---|---|---|
R | 예약 스케줄 | 고객 예약으로 생성된 스케줄 | 예약 확정 시 자동 생성 |
S | 외부 스케줄 | 정비, 점검 등으로 직접 등록한 스케줄 | 수동 등록 |
3. 스케줄 관리 기능
API로는 외부 스케줄(S 타입)만 등록, 수정, 삭제할 수 있습니다. 예약 스케줄(R 타입)은 예약에 따라 자동으로 관리되며, 스케줄을 조회하는 API는 제공하지 않습니다.
3.1 외부 스케줄 등록
- API:
POST /developer/v1/schedule - 설명: 정비, 점검, 기타 사유로 차량을 일시적으로 사용 불가 상태로 만들기 위한 외부 스케줄을 등록합니다.
- 요청 데이터:
carNumber,startDateTimeStr,endDateTimeStr,reason - 제한사항: 시작 일시는 현재 시점 기준 최대 7일 전까지만 설정할 수 있고, 스케줄 기간은 최소 30분 이상이어야 합니다.
3.2 외부 스케줄 수정
- API:
PUT /developer/v1/schedule/{id} - 설명: 등록된 외부 스케줄의 정보를 수정합니다. 예약 스케줄은 수정할 수 없습니다.
- 제한사항: 종료일이 현재 날짜 기준 과거 7일 이상 지난 경우 수정이 불가합니다.
3.3 외부 스케줄 삭제
- API:
DELETE /developer/v1/schedule/{id} - 설명: 등록된 외부 스케줄을 삭제합니다. 예약 스케줄은 삭제할 수 없습니다.
4. 스케줄과 예약의 연동
4.1 예약 스케줄 자동 생성
고객이 예약을 확정하면 다음과 같은 프로세스로 스케줄이 생성됩니다:
- 예약 확정: 고객이 특정 차량과 시간대로 예약을 확정
- 차량 배정: 시스템이 해당 예약에 차량을 배정
- 스케줄 생성: 배정된 차량에 예약 기간만큼 스케줄(R 타입) 자동 생성
- 재고 차단: 해당 시간대에 차량이 수요 채널에 노출되지 않음
4.2 스케줄 충돌 방지
- 시간 중복 검사: 새로운 스케줄 등록 시 기존 스케줄과 시간이 겹치는지 확인
- 예약 가능성 검사: 상품 조회 시 스케줄이 등록된 차량은 해당 시간대에 예약 불가로 처리
- 실시간 재고 관리: 스케줄 변경 시 실시간으로 예약 가능 재고에 반영
5. 개발자를 위한 핵심 포인트
렌트카 업체 개발자
외부 스케줄 관리
-
정비 스케줄 등록: 차량 정비나 점검이 필요할 때
POST /developer/v1/scheduleAPI로 외부 스케줄을 등록하여 해당 시간대에 새로운 예약을 차단할 수 있습니다. -
충돌 방지: 외부 스케줄 등록 시 기존 예약과 시간이 겹치지 않도록 주의해야 합니다. 시간이 겹치면 API가
E011에러를 응답합니다.
수요 채널(서비스사) 개발자
고객 안내
- 예약 현황: 고객에게 예약 현황을 안내할 때, 예약 이벤트로 전달받은 예약 시작·종료 일시와 예약 상태를 통해 차량의 사용 기간과 상태를 명확히 전달할 수 있습니다.
주요 에러 코드
| 코드 | 메시지 | 설명 |
|---|---|---|
E011 | 스케줄 기간이 중복 됩니다. | 등록하려는 스케줄이 기존 스케줄과 시간이 겹침 |
E012 | 종료일이 현재 날짜 기준 과거 7일 이상 지난 경우 수정이 불가합니다. | 과거 스케줄 수정 제한 |