{"openapi":"3.0.3","info":{"title":"카플랫 API 개발자 센터","description":"## API 구성\n\n1. REST API (클라이언트 → 서버)\n\n2. Webhook Events (서버 → 클라이언트)\n","version":"v1.0"},"servers":[{"url":"https://test-api-partners.carplat.co.kr","description":"테스트 서버"},{"url":"https://api-partners.carplat.co.kr","description":"운영 서버"}],"tags":[{"name":"Rest API","description":"Carplat에서 제공되는 일부 기능을 API 형태로 제공하여 개발사의 운영업무의 부담을 덜 수 있습니다.\n\n클라이언트가 호출하는 일반적인 REST API입니다.\n"},{"name":"Callback Events","description":"⚠️ **이 섹션의 API들은 테스트할 수 없습니다.**\n\n서버에서 예약 상태 변경등의 정보를 자동으로 클라이언트에서 전달하는 이벤트 입니다.\n\n해당 이벤트의 URL은 Carplat 에서 연동 신청 시 등록한 콜백 URL과 연결되어 정보가 전송됩니다.\n"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/developer/v1/reservation/{id}/dispatch/cancel":{"put":{"tags":["Rest API"],"summary":"배차 취소","description":"• 배차를 취소합니다.\n\n• 예약 상태가 **배차출발** 또는 **배차완료** 상태에서만 변경 가능합니다.\n\n• 이미 등록된 배차 직원, 주차 메모, 배차 사진 등의  정보가 초기화되며 취소 후 예약완료 상태로 변경됩니다.\n\n• 해당 예약 건에 발급 된 공유 스마트키(배차)는 사용 중지됩니다.\n","parameters":[{"name":"id","in":"path","description":"예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"S000","message":"성공"}}}},"404":{"description":"예약 정보를 찾을 수 없음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E003","message":"해당 예약을 찾을 수 없습니다."}}}},"409":{"description":"변경 불가능한 상태","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E012","message":"변경 불가능한 상태입니다."}}}},"503":{"description":"시스템 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E060","message":"요청 실패. 증상이 반복될 시 관리자에게 문의하세요."}}}}}}},"/developer/v1/reservation/{id}/dispatch/carImage":{"post":{"tags":["Rest API"],"summary":"배차완료 전 차량 사진 일괄 등록","description":"• **배차출발** 상태에서만 등록 가능합니다.        \n• 1장당 10mb 이하의 파일만 업로드 가능합니다.  \n• 최대 20장까지 등록 가능합니다.\n","parameters":[{"name":"id","in":"path","description":"조회할 예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DispatchCarImageBulkRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"S000","message":"성공"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"invalidExtension":{"summary":"허용되지 않은 확장자","value":{"code":"C004","message":"허용되지 않은 확장자입니다."}},"invalidImageFormat":{"summary":"잘못된 이미지 형식","value":{"code":"C004","message":"올바르지 않은 이미지 형식입니다. Base64로 인코딩된 이미지 데이터를 전송해주세요."}}}}}},"404":{"description":"예약 정보를 찾을 수 없음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E003","message":"예약 정보를 찾을 수 없습니다."}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"changeReservation":{"summary":"예약상태 변경","value":{"code":"E012","message":"예약 상태가 변경되었습니다."}},"fileSizeExceeded":{"summary":"파일 크기 초과","value":{"code":"E012","message":"파일 크기가 10mb 를 초과할 수 없습니다."}},"missingRequiredPhotos":{"summary":"필수 사진 누락","value":{"code":"E012","message":"정면, 운전석 옆면, 후면, 조수석 옆면 사진을 모두 등록해 주세요."}},"duplicatePhoto":{"summary":"사진 중복 등록","value":{"code":"E012","message":"요청한 이미지 유형의 허용 업로드 개수를 초과하여 등록할 수 없습니다."}}}}}}}}},"/developer/v1/reservation/{id}/dispatch/complete":{"put":{"tags":["Rest API"],"summary":"배차 완료","description":"• 해당 예약을 배차완료 상태로 변경합니다.\n\n• 예약 상태가 **배차출발** 상태에서만 변경 가능합니다.\n\n• 배차완료 전 차량 사진과 주차 사진을 필수로 등록해야 합니다.\n\n• 차량의 주차 위치 정보(parkingMemo)를 필수로 등록해야 합니다.\n\n• 해당 예약 건에 발급 된 공유 스마트키(배차)는 사용 중지됩니다.\n","parameters":[{"name":"id","in":"path","description":"예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParkingInformation"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"S000","message":"성공"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E001","message":"parkingMemo: 주차 메모를 입력해 주세요., parkingMemo: 최소 1자에서 최대 50자까지 입력 가능합니다."}}}},"404":{"description":"예약 정보를 찾을 수 없음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"ResourceNotFound-1":{"summary":"예약을 찾을 수 없음","value":{"code":"E003","message":"예약을 찾을 수 없습니다."}},"ResourceNotFound-2":{"summary":"주차 사진을 찾을 수 없음","value":{"code":"E003","message":"주차 사진을 등록해주세요."}}}}}},"409":{"description":"변경 불가능한 상태","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"ResourceNotAcceptable-1":{"summary":"배차 사진이 없음","value":{"code":"E012","message":"배차 사진을 등록해주세요."}},"ResourceNotAcceptable-2":{"summary":"변경 불가능한 상태","value":{"code":"E012","message":"변경 불가능한 상태입니다."}}}}}},"503":{"description":"시스템 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E060","message":"요청 실패. 증상이 반복될 시 관리자에게 문의하세요."}}}}}}},"/developer/v1/reservation/{id}/dispatch/parkingImage":{"post":{"tags":["Rest API"],"summary":"배차완료 전 주차 사진 등록","description":"• **배차출발** 상태에서만 등록 가능합니다.      \n• 10mb 이하의 파일만 업로드 가능합니다.\n","parameters":[{"name":"id","in":"path","description":"조회할 예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParkingImageRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"S000","message":"성공"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"invalidExtension":{"summary":"허용되지 않은 확장자","value":{"code":"C004","message":"허용되지 않은 확장자입니다."}},"invalidImageFormat":{"summary":"잘못된 이미지 형식","value":{"code":"C004","message":"올바르지 않은 이미지 형식입니다. Base64로 인코딩된 이미지 데이터를 전송해주세요."}}}}}},"404":{"description":"예약 정보를 찾을 수 없음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E003","message":"예약 정보를 찾을 수 없습니다."}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"changeReservation":{"summary":"예약상태 변경","value":{"code":"E012","message":"예약 상태가 변경되었습니다."}},"fileSizeExceeded":{"summary":"파일 크기 초과","value":{"code":"E012","message":"파일 크기가 10mb 를 초과할 수 없습니다."}},"duplicatePhoto":{"summary":"사진 중복 등록","value":{"code":"E012","message":"사진이 이미 등록되어 추가 등록 할 수 없습니다."}}}}}}}}},"/developer/v1/reservation/{id}/dispatch/start":{"put":{"tags":["Rest API"],"summary":"배차 출발","description":"• 해당 예약을 배차출발 상태로 변경합니다.\n\n• 예약 상태가 **예약완료** 상태에서만 변경 가능합니다.\n\n• 배차 담당 직원을 지정합니다.\n\n• 카플랫 계정(account)은 필수 입력 값입니다.\n\n• 존재하지 않는 직원 계정으로는 등록할 수 없습니다.\n","parameters":[{"name":"id","in":"path","description":"예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffAssignmentRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"S000","message":"성공"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E001","message":"account: 직원 계정 정보는 필수입니다., account: 직원 계정은 최소 6자, 최대 100자여야 합니다."}}}},"404":{"description":"정보를 찾을 수 없음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"ReservationNotFound":{"summary":"예약 정보를 찾을 수 없습니다.","value":{"code":"E003","message":"예약 정보를 찾을 수 없습니다."}},"StaffNotFound":{"summary":"직원 정보를 찾을 수 없습니다.","value":{"code":"E003","message":"직원 정보를 찾을 수 없습니다."}}}}}},"409":{"description":"변경 불가능한 상태","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E012","message":"변경 불가능한 상태입니다."}}}},"503":{"description":"시스템 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E060","message":"요청 실패. 증상이 반복될 시 관리자에게 문의하세요."}}}}}}},"/developer/v1/reservation/{id}/recall/carImage":{"post":{"tags":["Rest API"],"summary":"회수완료 전 차량 사진 일괄 등록","description":"• **반납완료** 상태에서만 등록 가능합니다.  \n• 1장당 10mb 이하의 파일만 업로드 가능합니다.  \n• 최대 20장까지 등록 가능합니다.\n","parameters":[{"name":"id","in":"path","description":"조회할 예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecallCarImageBulkRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"S000","message":"성공"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"invalidExtension":{"summary":"허용되지 않은 확장자","value":{"code":"C004","message":"허용되지 않은 확장자입니다."}},"invalidImageFormat":{"summary":"잘못된 이미지 형식","value":{"code":"C004","message":"올바르지 않은 이미지 형식입니다. Base64로 인코딩된 이미지 데이터를 전송해주세요."}}}}}},"404":{"description":"예약 정보를 찾을 수 없음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E003","message":"예약 정보를 찾을 수 없습니다."}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"changeReservation":{"summary":"예약상태 변경","value":{"code":"E012","message":"예약 상태가 변경되었습니다."}},"fileSizeExceeded":{"summary":"파일 크기 초과","value":{"code":"E012","message":"파일 크기가 10mb 를 초과할 수 없습니다."}},"missingRequiredPhotos":{"summary":"필수 사진 누락","value":{"code":"E012","message":"정면, 운전석 옆면, 후면, 조수석 옆면 사진을 모두 등록해 주세요."}},"duplicatePhoto":{"summary":"사진 중복 등록","value":{"code":"E012","message":"요청한 이미지 유형의 허용 업로드 개수를 초과하여 등록할 수 없습니다."}}}}}}}}},"/developer/v1/reservation/{id}/recall/complete":{"put":{"tags":["Rest API"],"summary":"회수 완료","description":"• 해당 예약을 **회수완료** 상태로 변경합니다.\n\n• 예약 상태가 **반납완료** 상태에서만 변경 가능합니다.\n\n• 차량 회수 담당 직원을 지정합니다.\n\n• 카플랫 계정(account)은 필수 입력값입니다.\n\n• 존재하지 않는 직원 계정으로는 등록할 수 없습니다.\n\n• 해당 예약 건에 발급 된 공유 스마트키(회수)는 사용 중지됩니다.\n","parameters":[{"name":"id","in":"path","description":"예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffAssignmentRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"S000","message":"성공"}}}},"404":{"description":"예약 정보를 찾을 수 없음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E003","message":"해당 예약을 찾을 수 없습니다."}}}},"409":{"description":"변경 불가능한 상태","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E012","message":"변경 불가능한 상태입니다."}}}},"503":{"description":"시스템 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E060","message":"요청 실패. 증상이 반복될 시 관리자에게 문의하세요."}}}}}}},"/developer/v1/schedule":{"post":{"tags":["Rest API"],"summary":"스케줄 등록","description":"• 새로운 스케줄을 등록합니다.  \n• 스케줄 시작 일시는 현재 시점을 기준으로 최대 7일 전까지만 설정할 수 있습니다.  \n• 시작 일시는 종료 일시보다 이후가 될 수 없습니다.  \n• 스케줄 기간은 최소 30분 이상이어야 합니다.\n","requestBody":{"required":true,"description":"새로운 스케줄 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Schedule"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleCreateResponse"},"example":{"code":"S000","message":"성공","result":{"id":1}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"invalidDateRange":{"summary":"종료 일시가 시작 일시보다 이전","value":{"code":"E004","message":"시작 일시는 종료 일시보다 늦을 수 없습니다."}},"pastStartDateTime":{"summary":"시작 일시가 7일 이전","value":{"code":"E004","message":"시작 일시는 일주일 전까지만 선택할 수 있습니다."}},"insufficientDuration":{"summary":"스케줄 기간 30분 미만","value":{"code":"E004","message":"스케줄 기간은 최소 30분 이상이어야 합니다."}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E003","message":"대상 데이터가 존재하지 않습니다."}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E011","message":"스케줄 기간이 중복 됩니다."}}}}}}},"/developer/v1/schedule/{id}":{"put":{"tags":["Rest API"],"summary":"스케줄 수정","description":"• 지정된 스케줄 ID에 해당하는 스케줄 정보를 수정합니다.  \n• 스케줄 시작 일시는 현재 시점을 기준으로 최대 7일 전까지만 설정할 수 있습니다.  \n• 시작 일시는 종료 일시보다 이후가 될 수 없습니다.  \n• 스케줄 기간은 최소 30분 이상이어야 합니다.\n","parameters":[{"name":"id","in":"path","description":"스케줄 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"requestBody":{"description":"수정대상 스케줄 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleWithOutCarId"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"S000","message":"성공"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"invalidDateRange":{"summary":"종료 일시가 시작 일시보다 이전","value":{"code":"E004","message":"시작 일시는 종료 일시보다 늦을 수 없습니다."}},"pastStartDateTime":{"summary":"시작 일시가 7일 이전","value":{"code":"E004","message":"시작 일시는 일주일 전까지만 선택할 수 있습니다."}},"insufficientDuration":{"summary":"스케줄 기간 30분 미만","value":{"code":"E004","message":"스케줄 기간은 최소 30분 이상이어야 합니다."}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E003","message":"대상 데이터가 존재하지 않습니다."}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"examples":{"duplicationSchedule":{"summary":"스케줄 기간 중복 오류","value":{"code":"E011","message":"스케줄 기간이 중복 됩니다."}},"overtime":{"summary":"종료 일시 경과로 인한 수정 불가","value":{"code":"E012","message":"종료 일시가 7일 이상 지난 경우 수정이 불가합니다."}}}}}}}},"delete":{"tags":["Rest API"],"summary":"스케줄 삭제","description":"• 지정된 스케줄 ID에 해당하는 스케줄을 삭제합니다.  \n• 삭제 처리 후에는 해당 스케줄 정보와 연관된 데이터가 더 이상 조회되지 않습니다.\n","parameters":[{"name":"id","in":"path","description":"스케줄 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"S000","message":"성공"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"},"example":{"code":"E003","message":"대상 데이터가 존재하지 않습니다."}}}}}}},"/events/reservation":{"post":{"tags":["Callback Events"],"summary":"예약 정보 등록 이벤트","description":"**서버 → 클라이언트 Webhook 이벤트**   \n• 예약이 생성되었을 때 발생합니다.  \n• 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 예약 정보를 수신해야 합니다.  \n","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationEventRequest"}}}},"responses":{"200":{"description":"이벤트를 성공적으로 수신했음을 알립니다.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"}}}}}}},"/events/reservation/{id}":{"put":{"tags":["Callback Events"],"summary":"예약 정보 업데이트 이벤트","description":"**서버 → 클라이언트 Webhook 이벤트**   \n• 예약 정보가 변경되었을 때 발생합니다.  \n• 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 예약 변경 정보를 수신해야 합니다.  \n• 연동 신청 시 등록한 콜백 URL로 전송됩니다.\n","security":[],"parameters":[{"name":"id","in":"path","description":"예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationEventRequest"}}}},"responses":{"200":{"description":"이벤트를 성공적으로 수신했음을 알립니다.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"}}}}}}},"/events/reservation/{id}/car-change":{"put":{"tags":["Callback Events"],"summary":"예약 차량 변경 이벤트","description":"**서버 → 클라이언트 Webhook 이벤트**   \n• 예약의 차량 정보가 변경되었을 때 발생합니다.  \n• 차량 변경시 \"예약 정보 업데이트 이벤트\" 와 해당 이벤트 \"예약 차량 변경 이벤트\" 가 연속으로 호출되도록 설계되어 있습니다.(신청시)   \n• 차량 변경시 차량관리에 사용할 경우에만 사용신청을 부탁드립니다.   \n• 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 차량 변경 정보를 수신해야 합니다.     \n• 연동 신청 시 등록한 콜백 URL로 전송됩니다.\n","security":[],"parameters":[{"name":"id","in":"path","description":"예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"responses":{"200":{"description":"이벤트를 성공적으로 수신했음을 알립니다.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperCarChangeRequest"}}}}}}},"/events/reservation/{id}/extension":{"put":{"tags":["Callback Events"],"summary":"예약 반납 연장 이벤트","description":"**서버 → 클라이언트 Webhook 이벤트**   \n• 예약의 반납(종료) 일시가 연장되었을 때 발생합니다.  \n• 예약 반납 연장시 \"예약 정보 업데이트 이벤트\" 와 해당 이벤트 \"예약 반납 연장 이벤트\" 가 연속으로 호출되도록 설계되어 있습니다.(신청시)  \n• 예약 반납 연장시 예약관리에 사용할 경우에만 사용신청을 부탁드립니다.  \n• 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 반납 연장 정보를 수신해야 합니다.  \n• 연동 신청 시 등록한 콜백 URL로 전송됩니다.\n","security":[],"parameters":[{"name":"id","in":"path","description":"예약 ID","required":true,"schema":{"type":"integer","format":"int64","example":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperReservationExtensionRequest"}}}},"responses":{"200":{"description":"이벤트를 성공적으로 수신했음을 알립니다.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"}}}}}}},"/events/hipass":{"post":{"tags":["Callback Events"],"summary":"하이패스 결제 정보 전달","description":"**서버 → 클라이언트 Webhook 이벤트**  \n• 차량의 하이패스 통행 내역이 발생했을 때 전송됩니다.  \n• 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 하이패스 통행 정보를 수신해야 합니다.  \n• 연동 신청 시 등록한 콜백 URL로 전송됩니다.\n","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HipassEventRequest"}}}},"responses":{"200":{"description":"이벤트를 성공적으로 수신했음을 알립니다.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonResponse"}}}}}}}},"components":{"schemas":{"CommonResponse":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"결과 코드","example":"S000"},"message":{"type":"string","description":"결과 메세지","example":"성공"}}},"DispatchCarImageBulkRequest":{"type":"object","required":["carImages"],"description":"**차량 이미지 일괄 등록 요청 객체**입니다.\n여러 장의 차량 이미지를 한 번에 등록할 수 있습니다.\n","properties":{"carImages":{"type":"array","description":"등록할 차량 이미지 리스트","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/DispatchCarImageItem"}}}},"RecallCarImageBulkRequest":{"type":"object","required":["carImages"],"description":"**차량 이미지 일괄 등록 요청 객체**입니다.  \n여러 장의 차량 이미지를 한 번에 등록할 수 있습니다.\n","properties":{"carImages":{"type":"array","description":"등록할 차량 이미지 리스트","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/RecallCarImageItem"}}}},"DispatchCarImageItem":{"type":"object","required":["attachFile","imageSubType"],"description":"개별 차량 이미지 정보입니다.\n","properties":{"imageSubType":{"type":"string","description":"• 이미지 유형  \n- F : 전면  \n- R : 운전석 옆면  \n- B : 후면  \n- L : 조수석 옆면  \n- E : 기타(추가 사진)  \n\n• 업로드 규칙  \n- F, R, B, L 유형은 각각 **1장만 등록 가능합니다.**  \n- E 유형은 **16장까지 등록 가능합니다.**\n","enum":["F","R","B","L","E"],"example":"F"},"attachFile":{"type":"object","description":"첨부할 이미지 파일 정보입니다.  \n파일 자체의 데이터(base64 인코딩된 바이트)와 파일명을 포함한 객체입니다.\n","required":["fileByte","logicalFileName"],"properties":{"fileByte":{"type":"string","format":"byte","description":"첨부 이미지 파일을 Base64 형식으로 인코딩한 문자열입니다. \n\n• 일반적으로 \"data:image/png;base64,...\" 형식으로 전달됩니다.  \n• 실제 파일의 바이너리 데이터를 문자열로 변환한 값\n","example":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="},"logicalFileName":{"type":"string","description":"사용자가 업로드한 파일의 **원래 파일 이름**(논리명)입니다.\n\n• 확장자 포함한 이름을 그대로 전달합니다. (예: parking.png, car.jpg)          \n• 허용되는 파일 확장자 목록입니다. (jpeg, jpg, png, pdf, webp)\n","example":"front.png"}}}}},"RecallCarImageItem":{"type":"object","required":["attachFile","imageSubType"],"description":"개별 차량 이미지 정보입니다.\n","properties":{"imageSubType":{"type":"string","description":"• 이미지 유형  \n- E : 기타(추가 촬영 이미지) \n\n• 업로드 규칙  \n- 회수(Recall) 차량 이미지 업로드는 **E 유형만 허용됩니다.**  \n(F, R, B, L 유형은 회수 이미지로 등록할 수 없습니다.)\n","enum":["E"],"example":"E"},"attachFile":{"type":"object","description":"첨부할 이미지 파일 정보입니다.\n파일 자체의 데이터(base64 인코딩된 바이트)와 파일명을 포함한 객체입니다.\n","required":["fileByte","logicalFileName"],"properties":{"fileByte":{"type":"string","format":"byte","description":"첨부 이미지 파일을 Base64 형식으로 인코딩한 문자열입니다. \n\n• 일반적으로 \"data:image/png;base64,...\" 형식으로 전달됩니다.  \n• 실제 파일의 바이너리 데이터를 문자열로 변환한 값\n","example":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="},"logicalFileName":{"type":"string","description":"사용자가 업로드한 파일의 **원래 파일 이름**(논리명)입니다.\n\n• 확장자 포함한 이름을 그대로 전달합니다. (예: parking.png, car.jpg)          \n• 허용되는 파일 확장자 목록입니다. (jpeg, jpg, png, pdf, webp)\n","example":"front.png"}}}}},"ParkingImageRequest":{"type":"object","required":["attachFile"],"description":"사용자가 업로드하는 **주차 이미지 첨부 요청 객체**입니다.\n이미지 파일에 대한 실제 데이터(바이트 정보)와 업로드 당시 파일명을 포함합니다.\n","properties":{"attachFile":{"type":"object","description":"첨부할 이미지 파일 정보입니다.\n파일 자체의 데이터(base64 인코딩된 바이트)와 파일명을 포함한 객체입니다.\n","required":["fileByte","logicalFileName"],"properties":{"fileByte":{"type":"string","format":"byte","description":"첨부 이미지 파일을 Base64 형식으로 인코딩한 문자열입니다.\n\n• 일반적으로 \"data:image/png;base64,...\" 형식으로 전달됩니다.  \n• 실제 파일의 바이너리 데이터를 문자열로 변환한 값\n","example":"data:image/png;base64,iVB"},"logicalFileName":{"type":"string","description":"사용자가 업로드한 파일의 **원래 파일 이름**(논리명)입니다.\n\n• 확장자 포함한 이름을 그대로 전달합니다. (예: parking.png, car.jpg)      \n• 허용되는 파일 확장자 목록입니다. (jpeg, jpg, png, pdf, webp)\n","example":"parking.png"}}}}},"ReservationEventRequest":{"type":"object","required":["id","serviceId","serviceName","reservationStatus","carId","carNumber","companyId","companyName","reservationCreateDateTime","reservationStartDateTime","reservationEndDateTime","pickUpAddress","driverName","driverBirthDate","driverPhone","driverLicenseNumber","driverAddress"],"description":"**예약 정보 변경 이벤트 요청 객체**\n\n서버에서 클라이언트로 전송되는 예약 정보입니다.\nnull 값을 가질 수 있는 필드는 해당 정보가 없을 경우 전송되지 않습니다.\n","properties":{"id":{"type":"integer","format":"int64","description":"예약 ID","example":12345},"serviceId":{"type":"integer","format":"int64","description":"서비스 ID","example":1},"serviceName":{"type":"string","description":"서비스명","example":"비대면 렌트"},"reservationStatus":{"type":"integer","description":"예약 상태 코드(예약 등록시에는 예약완료(\"5\") 고정, 예약 수정시에는 모든 스테이터스가 전달 가능)\n- 5: 예약완료\n- 10: 배차출발\n- 15: 배차완료\n- 20: 이용 중\n- 30: 반납완료\n- 35: 회수완료\n- 40: 예약취소\n- 45: 노쇼취소\n- 50: 예약실패(시스템취소)\n","example":5},"carId":{"type":"integer","format":"int64","description":"차량 ID","example":100},"carNumber":{"type":"string","description":"차량 번호","example":"12가3456"},"companyId":{"type":"integer","format":"int64","description":"업체 ID","example":10},"companyName":{"type":"string","description":"업체명","example":"(주)피플카"},"reservationCreateDateTime":{"type":"string","format":"date-time","description":"예약 생성 일시(yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)","example":"2024-01-15T10:30:00.000+09:00"},"reservationStartDateTime":{"type":"string","format":"date-time","description":"예약 시작 일시(yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)","example":"2024-01-20T09:00:00.000+09:00"},"reservationEndDateTime":{"type":"string","format":"date-time","description":"예약 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)","example":"2024-01-22T18:00:00.000+09:00"},"driveStartDateTime":{"type":"string","format":"date-time","description":"운행 시작 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)","example":"2024-01-20T09:15:00.000+09:00"},"driveEndDateTime":{"type":"string","format":"date-time","description":"운행 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)","example":"2024-01-22T17:45:00.000+09:00"},"pickUpAddress":{"type":"string","description":"픽업 주소","example":"서울시 강남구 테헤란로 123"},"driverName":{"type":"string","description":"운전자 이름","example":"홍길동"},"driverBirthDate":{"type":"string","description":"운전자 생년월일 (YYYYMMDD)","example":"19900101"},"driverPhone":{"type":"string","description":"운전자 전화번호(\"-\" 없이 등록)","example":"01012345678"},"driverLicenseNumber":{"type":"string","description":"운전자 면허번호","example":"12-34-567890-12"},"driverAddress":{"type":"string","description":"운전자 주소","example":"서울시 강남구 역삼동 123-45"},"pickUpMemo":{"type":"string","description":"픽업 메모","example":"건물 지하 주차장"},"parkingMemo":{"type":"string","description":"주차 메모","example":"B2 주차장 A구역"},"parkingImagePath":{"type":"string","description":"주차 이미지 경로 URL","example":"https://carplat.co.kr/images/parking/12345.jpg"},"parkingFeeType":{"type":"integer","description":"주차장 유형(1: 유료, 0: 불명)","example":0},"coDriver":{"$ref":"#/components/schemas/CoDriver"}}},"CoDriver":{"type":"object","description":"**동승자 정보**\n\n해당 예약에 동승자가 등록된 경우에만 전송됩니다. 동승자가 없으면 이 필드 자체가 응답에 포함되지 않습니다.\n","nullable":true,"properties":{"phone":{"type":"string","description":"동승자 전화번호(\"-\" 없이 등록)","example":"01099104510"},"date_of_birth":{"type":"string","description":"동승자 생년월일 (YYYYMMDD)","example":"19931111"},"name":{"type":"string","description":"동승자명","example":"박해뤼"},"driver_license_number":{"type":"string","description":"동승자 면허번호","example":"11-17-174133-01"}}},"HipassEventRequest":{"type":"object","required":["carId","carNumber","amount","transactedDateTime"],"description":"**하이패스 통행 정보 이벤트 요청 객체**\n\n서버에서 클라이언트로 전송되는 하이패스 통행 내역입니다.\nrequired에 명시되지 않은 필드는 선택 필드이며, 값이 없을 경우 전송되지 않습니다.\n","properties":{"carId":{"type":"integer","format":"int64","description":"차량 ID","example":100},"carNumber":{"type":"string","description":"차량 번호","example":"12가3456"},"amount":{"type":"integer","description":"통행료 (원)","example":3500},"transactedDateTime":{"type":"string","format":"date-time","description":"통행 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)","example":"2024-01-20T10:30:00.000+09:00"},"comment":{"type":"string","description":"통행 정보 메모. 투루카 연동일 경우 사용. \"서비스명(#예약번호)\"","nullable":true,"example":"투루카 카셰어링(#12345)"}}},"StaffAssignmentRequest":{"type":"object","required":["account"],"description":"배차/회수 담당자 등록 요청 계정입니다.\n","properties":{"account":{"type":"string","maxLength":100,"minLength":6,"description":"담당자 계정 (직원 계정)","example":"specialist"}}},"ParkingInformation":{"type":"object","description":"주차위치를 표시하기위한 메모 입니다.\n","required":["parkingMemo"],"properties":{"parkingMemo":{"type":"string","maxLength":50,"minLength":1,"description":"주차 위치 메모","example":"건물 지하 주차장 A구역"}}},"Schedule":{"description":"스케줄","required":["carNumber","startDateTimeStr","endDateTimeStr","reason"],"allOf":[{"type":"object","properties":{"carNumber":{"type":"string","description":"차량 번호","example":"106호3074"}}},{"$ref":"#/components/schemas/ScheduleWithOutCarId"}]},"ScheduleWithOutCarId":{"type":"object","description":"스케줄","required":["startDateTimeStr","endDateTimeStr","reason"],"properties":{"startDateTimeStr":{"type":"string","description":"스케줄 시작일시(yyyy-MM-dd HH:mm 형식)","example":"2025-09-11 09:00"},"endDateTimeStr":{"type":"string","description":"스케줄 종료일시(yyyy-MM-dd HH:mm 형식)","example":"2025-09-12 17:00"},"reason":{"type":"string","description":"사유","maxLength":50,"example":"사고차량 수리"}}},"DeveloperCarChangeRequest":{"type":"object","required":["id","beforeCarId","beforeCarNumber","updateCarId","updateCarNumber"],"description":"**예약 차량 변경 이벤트 응답 객체**\n\n서버에서 클라이언트로 전송되는 차량 변경 정보입니다.\nnull 값을 가질 수 있는 필드는 해당 정보가 없을 경우 전송되지 않습니다.\n","properties":{"id":{"type":"integer","format":"int64","description":"예약 ID","example":12345},"beforeCarId":{"type":"integer","format":"int64","description":"변경 전 차량 ID","example":100},"beforeCarNumber":{"type":"string","description":"변경 전 차량 번호","example":"12가3456"},"updateCarId":{"type":"integer","format":"int64","description":"변경 후 차량 ID","example":101},"updateCarNumber":{"type":"string","description":"변경 후 차량 번호","example":"34나5678"}}},"DeveloperReservationExtensionRequest":{"type":"object","required":["id","beforeReservationEndDateTime","afterReservationEndDateTime"],"description":"**예약 반납 연장 이벤트 요청 객체**\n\n서버에서 클라이언트로 전송되는 반납 연장 정보입니다.\n","properties":{"id":{"type":"integer","format":"int64","description":"예약 ID","example":12345},"beforeReservationEndDateTime":{"type":"string","description":"연장 전 반납(종료) 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)","example":"2025-09-12T17:00:00.000+09:00"},"afterReservationEndDateTime":{"type":"string","description":"연장 후 반납(종료) 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)","example":"2025-09-12T20:00:00.000+09:00"}}},"ScheduleCreateResponse":{"allOf":[{"$ref":"#/components/schemas/CommonResponse"},{"type":"object","required":["result"],"properties":{"result":{"type":"object","required":["id"],"properties":{"id":{"type":"integer","format":"int64","description":"등록된 스케줄 ID (스케줄 수정/삭제 시 사용)","example":1}}}}}]}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-TURU-KEY","description":"API KEY"}}}}