개발자 센터

스케줄

카플랫에서 차량 스케줄을 관리하고 예약과 연동하는 방법을 설명합니다.

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

1. 스케줄(Schedule)이란?

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

스케줄 유형

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

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

2. 스케줄의 데이터 모델

외부 스케줄을 등록할 때 전달하는 데이터 속성은 다음과 같습니다.

json

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 예약 스케줄 자동 생성

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

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

4.2 스케줄 충돌 방지

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

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

렌트카 업체 개발자

외부 스케줄 관리

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

  • 충돌 방지: 외부 스케줄 등록 시 기존 예약과 시간이 겹치지 않도록 주의해야 합니다. 시간이 겹치면 API가 E011 에러를 응답합니다.

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

고객 안내

  • 예약 현황: 고객에게 예약 현황을 안내할 때, 예약 이벤트로 전달받은 예약 시작·종료 일시와 예약 상태를 통해 차량의 사용 기간과 상태를 명확히 전달할 수 있습니다.

주요 에러 코드

코드메시지설명
E011스케줄 기간이 중복 됩니다.등록하려는 스케줄이 기존 스케줄과 시간이 겹침
E012종료일이 현재 날짜 기준 과거 7일 이상 지난 경우 수정이 불가합니다.과거 스케줄 수정 제한