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

1. 스케줄(Schedule)이란?

카플랫에서 스케줄(Schedule)은 특정 차량의 시간대별 사용 계획을 관리하는 핵심 데이터 객체입니다. 스케줄은 두 가지 유형으로 구분됩니다:

스케줄 유형

1. 예약 스케줄 (R: Reservation): 고객 예약이 확정되면 자동으로 생성되는 스케줄
2. 외부 스케줄 (S: Schedule): 정비, 점검, 기타 사유로 직접 등록하는 스케줄

스케줄이 등록된 시간대에는 해당 차량이 수요 채널에 노출되지 않아 새로운 예약을 받을 수 없습니다.

2. 스케줄의 데이터 모델

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

• idinteger

  스케줄 식별값

• carIdinteger

  차량 식별값

• startDateTimeInstantstring

  시작일시

• endDateTimeInstantstring

  종료일시

• reasonstring

  사유

스케줄 목록 응답 구조

스케줄 조회 시에는 차량별로 그룹화된 형태로 응답됩니다:

스케줄 타입별 구분

3. 스케줄 관리 기능

3.1 스케줄 조회

• API: GET /schedule
• 설명: 지정된 기간 내의 차량별 스케줄을 조회합니다. 예약 스케줄과 외부 스케줄을 모두 포함하여 차량별로 그룹화된 형태로 반환됩니다.
• 주요 파라미터: startDate, endDate (필수), carNumber, detailModelName (선택)

3.2 스케줄 상세 조회

• API: GET /schedule/{id}
• 설명: 특정 스케줄의 상세 정보를 조회합니다. 외부 스케줄(S 타입)에 대해서만 사용됩니다.

3.3 외부 스케줄 등록

• API: POST /schedule
• 설명: 정비, 점검, 기타 사유로 차량을 일시적으로 사용 불가 상태로 만들기 위한 외부 스케줄을 등록합니다.
• 요청 데이터: carId, startDateTimeStr, endDateTimeStr, reason

3.4 외부 스케줄 수정

• API: PUT /schedule/{id}
• 설명: 등록된 외부 스케줄의 정보를 수정합니다. 예약 스케줄은 수정할 수 없습니다.
• 제한사항: 종료일이 현재 날짜 기준 과거 7일 이상 지난 경우 수정이 불가합니다.

3.5 외부 스케줄 삭제

• API: DELETE /schedule/{id}
• 설명: 등록된 외부 스케줄을 삭제합니다. 예약 스케줄은 삭제할 수 없습니다.

4. 스케줄과 예약의 연동

4.1 예약 스케줄 자동 생성

고객이 예약을 확정하면 다음과 같은 프로세스로 스케줄이 생성됩니다:

1. 예약 확정: 고객이 특정 차량과 시간대로 예약을 확정
2. 차량 배정: 시스템이 해당 예약에 차량을 배정
3. 스케줄 생성: 배정된 차량에 예약 기간만큼 스케줄(R 타입) 자동 생성
4. 재고 차단: 해당 시간대에 차량이 수요 채널에 노출되지 않음

4.2 스케줄 충돌 방지

• 시간 중복 검사: 새로운 스케줄 등록 시 기존 스케줄과 시간이 겹치는지 확인
• 예약 가능성 검사: 상품 조회 시 스케줄이 등록된 차량은 해당 시간대에 예약 불가로 처리
• 실시간 재고 관리: 스케줄 변경 시 실시간으로 예약 가능 재고에 반영

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

렌트카 업체 개발자

외부 스케줄 관리

• 정비 스케줄 등록: 차량 정비나 점검이 필요할 때 POST /schedule API로 외부 스케줄을 등록하여 해당 시간대에 새로운 예약을 차단할 수 있습니다.

• 스케줄 조회: GET /schedule API로 특정 기간의 차량별 스케줄을 조회하여 차량 운영 계획을 수립할 수 있습니다. 예약 스케줄과 외부 스케줄을 함께 확인할 수 있습니다.

• 충돌 방지: 외부 스케줄 등록 시 기존 예약과 시간이 겹치지 않도록 주의해야 합니다. API에서 충돌 검사를 수행하지만, 사전에 스케줄을 조회하여 확인하는 것을 권장합니다.

예약 연동

• 예약 스케줄 확인: 예약이 확정된 후 해당 차량의 스케줄을 조회하여 예약 스케줄이 정상적으로 생성되었는지 확인할 수 있습니다.

• 재고 관리: 스케줄 정보를 통해 실시간 차량 재고 상태를 파악하고, 내부 관리 시스템과 동기화할 수 있습니다.

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

예약 가능성 확인

• 상품 조회 시: 상품 API를 통해 예약 가능한 차량을 조회할 때, 스케줄이 등록된 차량은 자동으로 해당 시간대에서 제외됩니다.

• 실시간 재고: 스케줄 변경사항이 실시간으로 상품 조회 결과에 반영되므로, 별도의 스케줄 조회 없이도 정확한 예약 가능 재고를 확인할 수 있습니다.

고객 안내

• 예약 현황: 고객에게 예약 현황을 안내할 때, 예약 스케줄 정보를 통해 차량의 사용 기간과 상태를 명확히 전달할 수 있습니다.

주요 에러 코드