# 카플랫 개발자 센터 > 카플랫에 등록된 차량·상품·예약·스케줄 데이터를 다루는 파트너용 REST API와, 카플랫이 고객사 서버로 보내는 콜백 이벤트를 안내합니다. ## 서버 - 테스트 서버: `https://test-api-partners.carplat.co.kr` - 운영 서버: `https://api-partners.carplat.co.kr` ## 핵심 규칙 - 고객사가 카플랫 API(`/developer/v1/...`)를 호출할 때는 `X-TURU-KEY: {API_KEY}` 헤더를 포함합니다. - 콜백 이벤트(`/events/...`)는 카플랫이 고객사 서버로 보내는 요청으로, 고객사 서버가 엔드포인트를 구현해 수신합니다. 콜백 요청에는 `X-TURU-KEY` 헤더가 없으므로 HTTPS와 카플랫 서버 IP 허용 목록으로 보호합니다. - 요청과 응답 본문은 JSON(`Content-Type: application/json`)입니다. - HTTPS, TLS 1.2 이상만 지원합니다. - 연동 개발과 검증은 테스트 서버에서 진행한 뒤 운영 서버로 전환합니다. - 필드 타입, 필수 여부, 길이 제한 같은 제약의 최종 기준은 OpenAPI 명세(https://developers.carplat.co.kr/openapi.json)입니다. --- # AI로 개발하기 > ChatGPT, Claude, Cursor 같은 AI 도구에 카플랫 문서를 연결해 연동 코드를 작성하는 방법을 설명합니다. 카플랫 개발자 센터는 AI 도구가 읽기 좋은 형태의 문서를 함께 제공합니다. AI에게 아래 자원을 알려주면, 학습 데이터에 없는 카플랫 API도 최신 명세를 기준으로 정확하게 답변하고 코드를 작성할 수 있습니다. ## AI를 위한 카플랫 자원 | 자원 | 주소 | 용도 | | --- | --- | --- | | llms.txt | [/llms.txt](/llms.txt) | 개발자 센터 전체 구조와 문서 링크를 정리한 인덱스입니다. 처음 연결할 때 가장 먼저 알려주세요. | | llms-full.txt | [/llms-full.txt](/llms-full.txt) | 모든 가이드와 API 레퍼런스를 한 파일로 합친 문서입니다. 파일을 첨부하거나 컨텍스트에 통째로 넣을 때 사용합니다. | | 가이드 마크다운 | `/guides/{문서}.md` | 가이드 주소 끝에 `.md`를 붙이면 마크다운 원본을 받을 수 있습니다. 예: [/guides/reservation.md](/guides/reservation.md) | | API 레퍼런스 마크다운 | [/reference.md](/reference.md) | 모든 엔드포인트의 파라미터, 요청·응답 필드, 예시를 담은 문서입니다. | | OpenAPI 명세 | [/openapi.json](/openapi.json) | OpenAPI 3.0 원본입니다. 요청·응답 타입이나 API 클라이언트 코드를 생성할 때 사용합니다. | > **참고**: 모든 자원은 개발자 센터 문서가 갱신되면 함께 갱신됩니다. 오래된 사본을 프로젝트에 저장해 두었다면 주기적으로 다시 받아주세요. ## 사용 방법 ### 채팅형 AI (ChatGPT, Claude 등) 웹 검색이나 URL 읽기를 지원하는 AI라면 `llms.txt` 주소를 프롬프트에 함께 적고, 문서를 읽은 뒤 답하도록 요청하세요. AI가 문서를 실제로 읽었는지는 도구마다 다르므로, 참조한 문서와 확인하지 못한 내용을 답변에 표시하게 하면 결과를 검증하기 쉽습니다. ```text https://developers.carplat.co.kr/llms.txt 와 거기 연결된 문서를 읽고, 카플랫 배차 완료 API를 호출하는 Node.js 코드를 작성해줘. 참조한 문서 주소를 함께 적고, 문서에서 확인하지 못한 내용은 따로 표시해줘. ``` URL을 읽지 못하는 환경이라면 `llms-full.txt`를 내려받아 파일로 첨부하세요. ### AI 코딩 도구 (Claude Code, Cursor, Codex 등) - **문서 등록**: 도구의 문서 소스 기능(예: Cursor의 `@Docs`)에 `llms.txt` 주소를 등록해 두면, 대화에서 카플랫 문서를 지정해 참조하도록 요청할 수 있습니다. - **프로젝트에 명세 저장**: `openapi.json`을 프로젝트에 저장해 두고 AI에게 해당 파일을 기준으로 타입과 클라이언트 코드를 만들도록 요청하세요. - **에이전트 지침 파일**: `AGENTS.md`나 `CLAUDE.md` 같은 지침 파일에 아래 내용을 추가해 두면, 카플랫 관련 작업에서 문서를 먼저 읽도록 안내할 수 있습니다. 지침을 따르는지는 도구마다 다르므로, 결과에 참조한 문서가 표시되는지 확인하세요. ```markdown ## 카플랫 API - 카플랫 API 연동 코드를 작성할 때는 https://developers.carplat.co.kr/llms.txt 를 먼저 읽고, 필요한 가이드의 .md 문서를 참고합니다. - 요청·응답 타입과 필드 제약은 https://developers.carplat.co.kr/openapi.json 명세를 기준으로 작성합니다. - `/developer/v1/` 경로는 고객사가 호출하는 API이고, `/events/` 경로는 고객사 서버가 수신하는 콜백입니다. - 답변에 참조한 문서를 적고, 문서에서 확인하지 못한 내용은 따로 표시합니다. ``` ## 프롬프트 예시 ### 코드 작성 - "카플랫 예약 정보 등록 콜백 이벤트를 받는 Spring Boot 컨트롤러를 만들어줘." - "openapi.json의 `/developer/v1/` 경로를 호출하는 TypeScript 클라이언트를 만들어줘. `/events/` 경로는 고객사 서버가 수신하는 콜백이므로 별도로 다뤄줘." - "차량 정비 일정이 생기면 카플랫 스케줄을 등록하고, 정비가 끝나면 삭제하는 코드를 작성해줘." ### 에러 디버깅 - "카플랫 API 호출 시 `E001` 에러가 나는데 원인과 해결 방법을 알려줘." - "배차 완료 API가 409 응답을 주는데 어떤 상태에서 호출해야 해?" ### 문서 조회 - "예약 상태 흐름을 정리하고, 각 상태에서 호출할 수 있는 API를 표로 만들어줘." - "콜백 이벤트 종류와 각 이벤트의 요청 필드를 비교해줘." ## 주의사항 - **API 키를 AI에 입력하지 마세요.** 코드에는 환경 변수 같은 자리표시자를 쓰고, 실제 키는 직접 설정하세요. - **테스트 서버에서 먼저 검증하세요.** AI가 만든 코드는 `https://test-api-partners.carplat.co.kr`에서 충분히 확인한 뒤 운영 서버 `https://api-partners.carplat.co.kr`로 전환하세요. - **결과를 문서와 대조하세요.** AI는 틀린 답변을 할 수 있습니다. 상태 전이 조건이나 필드 필수 여부·길이 제한처럼 중요한 내용은 가이드와 API 레퍼런스에서 다시 확인하세요. 필드 제약의 최종 기준은 `openapi.json`입니다. --- # 차량 > 카플랫에 차량을 등록하고 관리하는 방법을 설명합니다. 카플랫 시스템에서 차량(Car) 도메인의 역할과 핵심 개념을 설명합니다. 이 문서를 통해 예약 이벤트로 전달되는 차량 정보를 이해하고 연동 개발을 원활하게 수행하는 것을 목표로 합니다. ## 1. 차량(Car)이란? 카플랫에서 차량(Car) 은 렌트카 사업자가 소유한 물리적인 자동차 자산을 의미하는 핵심 데이터 객체(Object)입니다. 시스템에 등록된 모든 차량은 고유한 식별자를 가지며, 렌트 서비스의 가장 기본적인 단위가 됩니다. 차량은 그 자체로 고객에게 판매되는 상품이 아니며, 실제 판매를 위한 상품(Product) 객체를 생성하기 위한 기반 데이터입니다. ## 2. 차량의 데이터 모델 카플랫에 등록된 차량의 주요 데이터 속성은 다음과 같습니다. ```json { "id": 3, "businessLicenseId": 1, "businessLicenseName": "테스트 사업자", "carNumber": "44가4444", "carTypeFuelCode": 1, "carTypeFuelName": "LPG", "carTypeGradeCode": 1, "carTypeGradeName": "소형", "carTypeName": "제네시스 쿠페 380 GT P", "modelYear": 2024, "carTypeDetailModelName": "제네시스", "displacement": 1988, "seater": 5, "vin": "KAAAA99AAAA999999", "color": "회색", "carRegisterDate": "2017-01-01", "updateName": "홍길동", "updateDateTime": "2025-03-28T10:00:00.000+09:00", "usimNumber": "89821234567890123456", "attachFile": { "id": 1, "logicalFileName": "차량등록증.png" }, "carOptionList": [ { "optionKey1": "2", "optionKey2": "2", "optionKey3": "2", "optionNm1": "외장", "optionNm2": "헤드램프", "optionNm3": "할로겐", "optionValue": "N" } ] } ``` | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `id` | integer | | 차량 일련번호
예: `3` | | `businessLicenseId` | integer | | 사업자 일련번호
예: `1` | | `businessLicenseName` | string | | 사업자명
예: `테스트 사업자` | | `carNumber` | string | | 차량번호
예: `44가4444` | | `carTypeFuelCode` | integer | | 유종코드
예: `1` | | `carTypeFuelName` | string | | 유종명
예: `LPG` | | `carTypeGradeCode` | integer | | 등급코드
예: `1` | | `carTypeGradeName` | string | | 등급명
예: `소형` | | `carTypeName` | string | | 차종명
예: `제네시스 쿠페 380 GT P` | | `modelYear` | integer | | 연식
예: `2024` | | `carTypeDetailModelName` | string | | 세부모델명
예: `제네시스` | | `displacement` | integer | | 배기량
예: `1988` | | `seater` | integer | | 인승
예: `5` | | `vin` | string | | 차대번호
예: `KAAAA99AAAA999999` | | `color` | string | | 색상
예: `회색` | | `carRegisterDate` | string | | 차량등록일 (yyyy-MM-dd)
예: `2017-01-01` | | `updateName` | string | | 수정자 이름
예: `홍길동` | | `updateDateTime` | string | | 수정 시간
제약: 형식 date-time
예: `2025-03-28T10:00:00.000+09:00` | | `usimNumber` | string | | 유심번호
예: `89821234567890123456` | | `attachFile` | object | | 차량등록증 파일 | | `attachFile.id` | integer | | 파일 일련번호
예: `1` | | `attachFile.logicalFileName` | string | | 차량등록증파일 논리명
예: `차량등록증.png` | | `carOptionList` | array | | 차량 옵션 목록 | | `carOptionList[].optionKey1` | string | | 차량 옵션코드1
예: `2` | | `carOptionList[].optionNm1` | string | | 차량 옵션명1
예: `외장` | | `carOptionList[].optionValue` | string | | 설치여부 (Y:설치, N:미설치)
예: `N` | ### 차량 옵션 구조 차량 옵션은 3단계 계층 구조로 관리됩니다: - **optionKey1/optionNm1**: 대분류 (예: 외장, 내장, 안전) - **optionKey2/optionNm2**: 중분류 (예: 헤드램프, 시트, 에어백) - **optionKey3/optionNm3**: 소분류 (예: 할로겐, 가죽, 운전석) - **optionValue**: 설치여부 (Y: 설치, N: 미설치) ## 3. 차량 관리 ### 3.1 차량 등록 및 관리 - **방법**: [carplat.co.kr](https://carplat.co.kr) 웹사이트의 차량 관리 페이지 - **설명**: 차량의 등록, 수정, 삭제는 카플랫 웹사이트에서 직접 진행합니다. 차량번호와 사업자 정보를 입력하면 오토비긴즈 API와 연동하여 차종 정보를 자동으로 가져올 수 있습니다. ## 4. 개발자를 위한 핵심 포인트 ### 렌트카 업체 개발자 #### 차량 관리 - **차량 등록**: 차량의 등록, 수정, 삭제는 [carplat.co.kr](https://carplat.co.kr) 웹사이트에서 직접 진행합니다. API를 통한 차량 등록은 지원하지 않습니다. ### 수요 채널(서비스사) 개발자 #### 배정 차량 확인 - **예약 이벤트로 확인**: 차량 정보를 조회하는 API는 제공하지 않습니다. 예약에 배정된 차량은 [예약 정보 등록 이벤트](/reference#post-events-reservation)의 `carId`, `carNumber`로 확인하고, 배정 차량이 바뀌면 [예약 차량 변경 이벤트](/reference#put-events-reservation-id-car-change)로 전달받습니다. - **고객 안내**: 차량 번호를 통해 고객에게 *"44가4444 차량이 배달 완료되었습니다."* 와 같은 구체적인 안내를 제공할 수 있습니다. --- # 상품 > 카플랫에 상품을 등록하고 관리하는 방법을 설명합니다. 카플랫 시스템에서 상품(Product) 도메인의 역할과 구성 요소를 설명합니다. 이 문서는 물리적 자산인 '차량'이 어떻게 판매 가능한 서비스 단위로 추상화되는지 이해하는 것을 목표로 합니다. ## 1. 상품(Product)이란? 카플랫에서 상품(Product)은 고객에게 실제 판매되는 렌터카 서비스 단위입니다. 이것은 물리적인 차량 목록(Car List) 에 요금(Fare Plan), 운영 정책(Policy), 보험 조건(Insurance Plan) 등을 결합한 논리적인 패키지입니다. 고객은 특정 차량(`license_plate`: 12가3456)을 예약하는 것이 아니라, "주중 시간당 15,000원짜리 아반떼 렌트"와 같은 상품을 보고 예약합니다. 하나의 상품(예: 아반떼 상품)은 여러 대의 동일 차종 차량(아반떼 1호기, 2호기, 3호기)을 재고(inventory)로 가질 수 있습니다. 이를 통해 렌트카 업체는 개별 차량이 아닌, 차종 기반의 재고 관리가 가능해져 운영 효율성이 극대화됩니다. ## 2. 상품의 데이터 모델 상품은 여러 하위 정책 객체와 관계를 맺는 복합 객체입니다. ```json { "id": 3, "productName": "올 뉴 아반떼 (비대면/주중 할인)", "carTypeMakerCode": 1, "seater": 4, "carTypeBaseModelCode": 123, "carTypeDetailModelCode": 1234, "carTypeDetailModelName": "아반떼(CN7)", "carTypeFuelCode": 1, "carTypeFuelName": "가솔린", "insuranceAgeLimit": "O", "licenseType": "O", "fareId": 1, "updateName": "홍길동", "updateDateTime": "2025-03-28T10:00:00.000+09:00", "basicSectionFareInfo": { "fareId": 1, "name": "기본 요금제", "baseFare": 50000, "maxFare": 200000, "weekdayDayLevel01": 15000, "weekendDayLevel01": 18000 }, "productCarOptionList": [ { "id": 3, "optionName": "썬루프", "optionString": "SUNROOF", "optionValue": "Y" } ], "productCarCampOptionList": [ { "id": 5, "optionName": "냉장고", "optionString": "REFRIGERATOR", "optionValue": "Y" } ] } ``` | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `id` | integer | | 상품 일련번호
예: `3` | | `productName` | string | | 상품명
예: `올 뉴 아반떼 (비대면/주중 할인)` | | `carTypeMakerCode` | integer | | 제조사코드
예: `1` | | `seater` | integer | | 인승
예: `4` | | `carTypeBaseModelCode` | integer | | 대표모델코드
예: `123` | | `carTypeDetailModelCode` | integer | | 세부모델코드
예: `1234` | | `carTypeDetailModelName` | string | | 세부모델명
예: `아반떼(CN7)` | | `carTypeFuelCode` | integer | | 유종코드
예: `1` | | `carTypeFuelName` | string | | 유종명
예: `가솔린` | | `insuranceAgeLimit` | string | | 보험연령 (O:21세이상, S:26세이상)
예: `O` | | `licenseType` | string | | 면허종류 (O:1종보통, T:2종보통, H:1종 대형)
예: `O` | | `fareId` | integer | | 요금제 일련번호
예: `1` | | `updateName` | string | | 수정자 이름
예: `홍길동` | | `updateDateTime` | string | | 수정 시간
제약: 형식 date-time
예: `2025-03-28T10:00:00.000+09:00` | | `basicSectionFareInfo` | object | | 요금제 정보 | | `basicSectionFareInfo.fareId` | integer | | 요금제 식별값
예: `1` | | `basicSectionFareInfo.name` | string | | 요금제 명
예: `기본 요금제` | | `basicSectionFareInfo.baseFare` | integer | | 기본 요금
예: `50000` | | `basicSectionFareInfo.maxFare` | integer | | 최대(상한) 요금
예: `200000` | | `productCarOptionList` | array | | 차량옵션리스트 | | `productCarOptionList[].id` | integer | | 옵션일련번호
예: `3` | | `productCarOptionList[].optionName` | string | | 옵션명
예: `썬루프` | | `productCarOptionList[].optionString` | string | | KM 전달용 문자열
예: `SUNROOF` | | `productCarOptionList[].optionValue` | string | | 선택여부 (Y: 설치, N:미설치)
예: `Y` | ### 상품 승인 상태(productApproveStatus) 유형 | 상태 | 한글명 | 설명 | | --- | --- | --- | | `0` | 승인대기 | 상품 등록 후 카플랫 관리자의 승인을 대기하는 상태 | | `1` | 승인완료 | 승인이 완료되어 고객이 예약할 수 있는 상태 | ### 차량 판매 상태(saleYn) 유형 | 상태 | 한글명 | 설명 | | --- | --- | --- | | `Y` | 판매중 | 해당 차량이 예약 가능한 상태 | | `N` | 판매중지 | 해당 차량이 일시적으로 예약 불가능한 상태 | ### 관련 정책 객체 #### Fare (요금제) `basicSectionFareInfo` 객체를 통해 기본 요금, 최대 요금, 주중/주말별 일별/시간별 요금 등 복잡한 가격 구조를 정의합니다. #### Car Options (차량 옵션) `productCarOptionList`를 통해 썬루프, 네비게이션 등 차량에 포함된 옵션들을 관리합니다. #### Camping Options (캠핑카 옵션) `productCarCampOptionList`를 통해 냉장고, 싱크대 등 캠핑카 전용 옵션들을 관리합니다. ## 3. 상품의 생명주기 ### 3.1 생성 (Creation) - **방법**: [carplat.co.kr](https://carplat.co.kr) 웹사이트의 상품 관리 페이지 - **설명**: 렌트카 업체는 카플랫 웹사이트에 로그인하여 상품 관리 메뉴에서 새로운 상품을 등록합니다. 차종 정보, 요금제, 차량 목록, 옵션 등을 웹 인터페이스를 통해 설정합니다. - **초기 상태**: `0`(승인대기) ### 3.2 상품 수정 (Update) - **방법**: [carplat.co.kr](https://carplat.co.kr) 웹사이트의 상품 관리 페이지 - **설명**: 등록된 상품의 정보를 카플랫 웹사이트에서 수정할 수 있습니다. 차량 추가/제거, 옵션 변경, 요금제 수정 등이 가능합니다. ### 3.3 승인 완료 (Approval) - **수행자**: 카플랫 관리자 - **설명**: 웹사이트에서 등록/수정된 상품을 카플랫 관리자가 검토한 후 승인하면 `productApproveStatus`가 `1`(승인완료)로 변경됩니다. 이 시점부터 고객이 예약할 수 있게 됩니다. ### 3.4 차량 판매 상태 관리 - **방법**: [carplat.co.kr](https://carplat.co.kr) 웹사이트의 상품 관리 페이지 - **설명**: 상품 내 특정 차량의 판매 상태를 개별적으로 관리할 수 있습니다. `saleYn`을 "Y" 또는 "N"으로 설정하여 차량별 판매 여부를 제어합니다. ### 3.5 상품 삭제 (Deletion) - **방법**: [carplat.co.kr](https://carplat.co.kr) 웹사이트의 상품 관리 페이지 - **설명**: 더 이상 사용하지 않는 상품을 카플랫 웹사이트에서 삭제할 수 있습니다. ## 4. 개발자를 위한 핵심 포인트 ### 렌트카 업체 개발자 - **상품 관리**: 상품의 생성, 수정, 삭제는 [carplat.co.kr](https://carplat.co.kr) 웹사이트에서 직접 진행합니다. API를 통한 상품 등록은 지원하지 않으며, 웹 인터페이스를 통해 차종 정보, 요금제, 차량 목록, 옵션 등을 설정해야 합니다. ### 수요 채널(서비스사) 개발자 - **상품 정보 확인**: 상품을 조회하는 API는 제공하지 않습니다. 고객이 예약한 차량 정보는 [예약 정보 등록 이벤트](/reference#post-events-reservation)의 `carId`, `carNumber`로 전달받습니다. --- # 예약 > 카플랫에서 예약이 생성되고 예약 상태가 변경되는 과정을 설명합니다. 카플랫 시스템에서 예약(Reservation)은 도메인의 생명주기와 상태 변화를 설명합니다. 이 문서는 예약의 흐름을 이해하여 API 기반으로 예약 생성, 관리, 상태 추적 기능을 구현하는 것을 목표로 합니다. ## 1. 예약(Reservation)이란? 예약(Reservation) 은 특정 고객이 특정 상품(Product)을 정해진 기간 동안 이용하기로 확정한 트랜잭션(Transaction) 입니다. 이는 고객, 상품, 시간을 연결하는 구체적인 이벤트이며, 렌트카 비즈니스의 모든 운영 활동은 예약을 중심으로 이루어집니다. 하나의 예약 건은 생성부터 완료까지 명확한 예약 상태 변화에 따라 흐름이 관리됩니다. 개발자는 이 상태 변화를 정확히 이해하고 추적해야 합니다. ## 2. 예약의 데이터 모델 예약 정보 등록 이벤트에서 전달되는 예약 객체의 예제는 다음과 같습니다: ```json { "id": 12345, "serviceId": 1, "serviceName": "비대면 렌트", "reservationStatus": 5, "carId": 100, "carNumber": "12가3456", "companyId": 10, "companyName": "(주)피플카", "reservationCreateDateTime": "2024-01-15T10:30:00.000+09:00", "reservationStartDateTime": "2024-01-20T09:00:00.000+09:00", "reservationEndDateTime": "2024-01-22T18:00:00.000+09:00", "driveStartDateTime": "2024-01-20T09:15:00.000+09:00", "driveEndDateTime": "2024-01-22T17:45:00.000+09:00", "pickUpAddress": "서울시 강남구 테헤란로 123", "driverName": "홍길동", "driverBirthDate": "19900101", "driverPhone": "01012345678", "driverLicenseNumber": "12-34-567890-12", "driverAddress": "서울시 강남구 역삼동 123-45", "pickUpMemo": "건물 지하 주차장", "parkingMemo": "B2 주차장 A구역", "parkingImagePath": "https://carplat.co.kr/images/parking/12345.jpg", "parkingFeeType": 0, "coDriver": { "phone": "01099104510", "date_of_birth": "19931111", "name": "박해뤼", "driver_license_number": "11-17-174133-01" } } ``` 예약 객체의 스키마는 다음과 같습니다: | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `id` | integer | Y | 예약 ID
제약: 형식 int64
예: `12345` | | `serviceId` | integer | Y | 서비스 ID
제약: 형식 int64
예: `1` | | `serviceName` | string | Y | 서비스명
예: `비대면 렌트` | | `reservationStatus` | integer | Y | 예약 상태 코드(예약 등록시에는 예약완료("5") 고정, 예약 수정시에는 모든 스테이터스가 전달 가능)
- 5: 예약완료
- 10: 배차출발
- 15: 배차완료
- 20: 이용 중
- 30: 반납완료
- 35: 회수완료
- 40: 예약취소
- 45: 노쇼취소
- 50: 예약실패(시스템취소)
예: `5` | | `carId` | integer | Y | 차량 ID
제약: 형식 int64
예: `100` | | `carNumber` | string | Y | 차량 번호
예: `12가3456` | | `companyId` | integer | Y | 업체 ID
제약: 형식 int64
예: `10` | | `companyName` | string | Y | 업체명
예: `(주)피플카` | | `reservationCreateDateTime` | string | Y | 예약 생성 일시(yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-15T10:30:00.000+09:00` | | `reservationStartDateTime` | string | Y | 예약 시작 일시(yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-20T09:00:00.000+09:00` | | `reservationEndDateTime` | string | Y | 예약 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-22T18:00:00.000+09:00` | | `driveStartDateTime` | string | | 운행 시작 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-20T09:15:00.000+09:00` | | `driveEndDateTime` | string | | 운행 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-22T17:45:00.000+09:00` | | `pickUpAddress` | string | Y | 픽업 주소
예: `서울시 강남구 테헤란로 123` | | `driverName` | string | Y | 운전자 이름
예: `홍길동` | | `driverBirthDate` | string | Y | 운전자 생년월일 (YYYYMMDD)
예: `19900101` | | `driverPhone` | string | Y | 운전자 전화번호("-" 없이 등록)
예: `01012345678` | | `driverLicenseNumber` | string | Y | 운전자 면허번호
예: `12-34-567890-12` | | `driverAddress` | string | Y | 운전자 주소
예: `서울시 강남구 역삼동 123-45` | | `pickUpMemo` | string | | 픽업 메모
예: `건물 지하 주차장` | | `parkingMemo` | string | | 주차 메모
예: `B2 주차장 A구역` | | `parkingImagePath` | string | | 주차 이미지 경로 URL
예: `https://carplat.co.kr/images/parking/12345.jpg` | | `parkingFeeType` | integer | | 주차장 유형(1: 유료, 0: 불명)
예: `0` | | `coDriver` | object | | **동승자 정보**
해당 예약에 동승자가 등록된 경우에만 전송됩니다. 동승자가 없으면 이 필드 자체가 응답에 포함되지 않습니다.
제약: nullable | | `coDriver.phone` | string | | 동승자 전화번호("-" 없이 등록)
예: `01099104510` | | `coDriver.date_of_birth` | string | | 동승자 생년월일 (YYYYMMDD)
예: `19931111` | | `coDriver.name` | string | | 동승자명
예: `박해뤼` | | `coDriver.driver_license_number` | string | | 동승자 면허번호
예: `11-17-174133-01` | ## 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/start` - 주차 사진 등록: `POST /developer/v1/reservation/{id}/dispatch/parkingImage` - 차량 사진 등록: `POST /developer/v1/reservation/{id}/dispatch/carImage` - 배차 완료: `PUT /developer/v1/reservation/{id}/dispatch/complete` - **회수 프로세스**: - 차량 사진 등록: `POST /developer/v1/reservation/{id}/recall/carImage` - 회수 완료: `PUT /developer/v1/reservation/{id}/recall/complete` ### 수요 채널(서비스사) 개발자 #### 핵심 책임 고객의 예약 상태 추적과 전체 고객 경험을 관리합니다. #### 주요 개발 포인트 - **예약 이벤트 수신 (콜백 이벤트)**: - **예약 생성**: 예약이 생성될 때 `/events/reservation` 콜백 이벤트를 통해 실시간으로 알림을 받습니다. - **예약 수정**: 예약 정보가 수정될 때 `/events/reservation/{id}` 콜백 이벤트로 알림을 받습니다. - **차량 변경**: 예약에 할당된 차량이 변경될 때 `/events/reservation/{id}/car-change` 콜백 이벤트로 알림을 받습니다. - **반납 연장**: 예약 반납 일시가 연장될 때 `/events/reservation/{id}/extension` 콜백 이벤트로 알림을 받습니다. - 자세한 웹훅 구독 방법은 [콜백 이벤트 가이드](/guides/callback-event)를 참고하세요. - 예약 생성 이벤트의 상세 스펙은 [API 레퍼런스의 예약 정보 등록 이벤트](/reference#post-events-reservation)를 참고하세요. - **실시간 상태 추적**: - 예약 상태(`reservationStatus`) 변경을 추적하여 고객에게 적절한 정보를 제공합니다. - 카플랫이 제공하는 상태 변경 웹훅을 구독하는 방식을 사용합니다. - **상태별 UI/UX**: - `배차완료(15)` 상태가 되면 고객에게 배정된 차량 정보와 주차 위치를 안내 - `이용중(20)` 상태가 되면 '이용 중' 화면을 제공 - `반납완료(30)` 상태가 되면 이용 완료 안내 --- # 스케줄 > 카플랫에서 차량 스케줄을 관리하고 예약과 연동하는 방법을 설명합니다. 카플랫 시스템에서 스케줄(Schedule) 도메인의 역할과 핵심 개념을 설명합니다. 이 문서를 통해 외부 스케줄 관리 API를 이해하고 연동 개발을 원활하게 수행하는 것을 목표로 합니다. ## 1. 스케줄(Schedule)이란? 카플랫에서 스케줄(Schedule)은 특정 차량의 시간대별 사용 계획을 관리하는 핵심 데이터 객체입니다. 스케줄은 두 가지 유형으로 구분됩니다: ### 스케줄 유형 1. **예약 스케줄 (R: Reservation)**: 고객 예약이 확정되면 자동으로 생성되는 스케줄 2. **외부 스케줄 (S: Schedule)**: 정비, 점검, 기타 사유로 직접 등록하는 스케줄 스케줄이 등록된 시간대에는 해당 차량이 수요 채널에 노출되지 않아 새로운 예약을 받을 수 없습니다. ## 2. 스케줄의 데이터 모델 외부 스케줄을 등록할 때 전달하는 데이터 속성은 다음과 같습니다. ```json { "carNumber": "106호3074", "startDateTimeStr": "2025-09-11 09:00", "endDateTimeStr": "2025-09-12 17:00", "reason": "사고차량 수리" } ``` | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `carNumber` | string | Y | 차량 번호
예: `106호3074` | | `startDateTimeStr` | string | Y | 스케줄 시작일시(yyyy-MM-dd HH:mm 형식)
예: `2025-09-11 09:00` | | `endDateTimeStr` | string | Y | 스케줄 종료일시(yyyy-MM-dd HH:mm 형식)
예: `2025-09-12 17:00` | | `reason` | string | Y | 사유
예: `사고차량 수리` | 등록에 성공하면 응답의 `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일 이상 지난 경우 수정이 불가합니다. | 과거 스케줄 수정 제한 | --- # 방화벽 및 보안 프로토콜 > 카플랫 API 연동 시 필요한 방화벽 설정과 보안 프로토콜을 설명합니다. 카플랫 API를 안전하게 연동하기 위한 방화벽 설정과 보안 프로토콜 요구사항을 설명합니다. ## 방화벽 설정 방화벽은 외부의 신뢰할 수 없는 네트워크가 내부 네트워크에 접근하지 못하도록 하는 보안 시스템입니다. 카플랫 API를 정상적으로 사용하려면 다음 방화벽 설정이 필요합니다. ### 포트 번호 허용 #### 1. API 요청을 위한 443 포트 고객사 서버에서 카플랫 서버에 요청을 보내려면 HTTPS로 접근할 수 있는 **443 포트**가 허용되어 있어야 합니다. #### 2. 웹훅 URL 포트 예약 상태 변경, 차량 상태 업데이트와 같은 변경 사항을 받아볼 수 있는 웹훅 이벤트를 등록하면 카플랫 서버에서 고객사 서버로 필요한 데이터를 전송합니다. 방화벽 설정에서 웹훅 URL에 지정된 포트 번호로 **인바운드 트래픽(Inbound Traffic)** 을 허용해주세요. ### IP 접근 제어 목록 설정 **중요**: 고객사 서버에서 IP 접근 제어 목록(ACL, Access Control List)으로 트래픽을 분류해 허용하거나 거부하는 경우, 카플랫의 IP 주소를 반드시 허용해주세요. 다음 IP에 접근할 수 있도록 허용해주면 정상적으로 인바운드 요청이 전송됩니다. | IP 주소 | 용도 | 방향 | | --- | --- | --- | | **카플랫 서버 IP** | 콜백 이벤트 수신 | 인바운드 | | **카플랫 서버 IP** | API 호출, 콜백 이벤트 응답 허용 | 아웃바운드 | > **참고**: 카플랫 서버의 정확한 IP 주소는 API 키 발급 시 별도로 안내드립니다. [카플랫 API 연동 관리](https://carplat.co.kr/developers/developer)에서 확인하실 수 있습니다. ### 아웃바운드 방화벽 설정 고객사에서 아웃바운드 방화벽을 사용하고 있다면 카플랫 API 서버로의 접근을 허용해주세요. - **도메인**: `api-partners.carplat.co.kr` (운영), `test-api-partners.carplat.co.kr` (테스트) - **포트**: 443 (HTTPS) - **프로토콜**: HTTPS ## HTTP 프로토콜 보안 ### HTTPS 필수 사용 카플랫 API는 **HTTPS로만** 호출할 수 있습니다. HTTPS는 HTTP의 보안(Secured) 버전입니다. HTTP로 주고받는 데이터는 암호화되지 않은 평문(plaintext)이기 때문에 개인 정보가 유출될 수 있습니다. 따라서 임차인의 개인 정보와 예약 정보를 보호하는 보안을 강화한 프로토콜인 HTTPS를 사용해야 합니다. ```http ✅ 올바른 사용 PUT https://api-partners.carplat.co.kr/developer/v1/reservation/123/dispatch/start HTTP/1.1 ❌ 잘못된 사용 PUT http://api-partners.carplat.co.kr/developer/v1/reservation/123/dispatch/start HTTP/1.1 ``` ### TLS 버전 1.2 이상 지원 TLS(전송 계층 보안)은 안전한 통신 프로토콜입니다. 카플랫 API는 **TLS 버전 1.2 이상**만 지원합니다. TLS 1.2 미만의 SSL/TLS 버전은 보안이 취약하여 지원하지 않습니다. 고객사 서버의 HTTP 클라이언트 환경이 TLS 1.2 이상을 지원하는지 확인해주세요. #### TLS 버전 확인 방법 ```bash # OpenSSL을 사용한 TLS 버전 확인 openssl s_client -connect api-partners.carplat.co.kr:443 -tls1_2 # curl을 사용한 TLS 버전 확인 curl -v --tlsv1.2 https://api-partners.carplat.co.kr ``` ### 지원되는 Cipher Suite 보안에 취약한 Cipher Suite는 지원되지 않습니다. 아래의 Cipher Suite 또는 이보다 보안이 강한 알고리즘만 지원됩니다. > **Cipher Suite**: TLS/SSL 통신에서 키 교환·암호화·무결성 검사에 어떤 알고리즘을 조합해 쓸지 정해 놓은 세트입니다. | Cipher Suite | 보안 수준 | | --- | --- | | TLS_AES_128_GCM_SHA256 | 높음 | | TLS_AES_256_GCM_SHA384 | 높음 | | TLS_CHACHA20_POLY1305_SHA256 | 높음 | | ECDHE-ECDSA-AES128-GCM-SHA256 | 높음 | | ECDHE-RSA-AES128-GCM-SHA256 | 높음 | | ECDHE-ECDSA-AES128-SHA256 | 중간 | | ECDHE-RSA-AES128-SHA256 | 중간 | | ECDHE-ECDSA-AES256-GCM-SHA384 | 높음 | | ECDHE-RSA-AES256-GCM-SHA384 | 높음 | | ECDHE-ECDSA-AES256-SHA384 | 중간 | | ECDHE-RSA-AES256-SHA384 | 중간 | ## 문제 해결 ### 연결 오류 시 확인사항 1. **방화벽 설정 확인** ```bash # 443 포트 연결 테스트 telnet api-partners.carplat.co.kr 443 # HTTPS 연결 테스트 curl -I https://api-partners.carplat.co.kr ``` 2. **TLS 버전 확인** ```bash # 지원되는 TLS 버전 확인 nmap --script ssl-enum-ciphers -p 443 api-partners.carplat.co.kr ``` 3. **DNS 해석 확인** ```bash # DNS 해석 확인 nslookup api-partners.carplat.co.kr ``` ### 일반적인 오류 및 해결방법 | 오류 | 원인 | 해결방법 | | --- | --- | --- | | Connection timeout | 방화벽에서 443 포트 차단 | 아웃바운드 443 포트 허용 | | SSL handshake failed | TLS 버전 불일치 | TLS 1.2 이상 사용 | --- # 요청 및 응답 형식 > 카플랫 API 요청 및 응답 형식을 설명합니다. 카플랫 API와 통신할 때 사용하는 요청과 응답 형식을 설명합니다. 이 문서를 통해 API 요청을 올바르게 구성하고 응답을 정확하게 해석할 수 있습니다. ## API 서버 주소 카플랫 API는 환경별로 서버 주소가 다릅니다. 연동 개발과 검증은 테스트 서버에서 진행한 뒤, 운영 서버로 전환하세요. | 환경 | Base URL | | --- | --- | | 테스트 | `https://test-api-partners.carplat.co.kr` | | 운영 | `https://api-partners.carplat.co.kr` | ## 요청 본문 요청 본문은 클라이언트가 카플랫 API를 호출할 때 보내는 데이터입니다. 카플랫 API에 요청할 때는 **JSON 형식**을 사용하세요. ### 인증 헤더 모든 API 요청에는 발급한 API Key를 헤더에 포함해야 합니다. API KEY는, [카플랫 API 연동 관리](https://carplat.co.kr/developers/developer)에서 확인할 수 있습니다. > **⚠️ 중요**: API 키가 노출되었거나 의심되는 경우, 즉시 [카플랫 API 연동 관리](https://carplat.co.kr/developers/developer)에서 키 재발급을 신청해주세요. ```http X-TURU-KEY: {API_KEY} Content-Type: application/json ``` ### 요청 예시 ```http POST /developer/v1/schedule HTTP/1.1 Host: api-partners.carplat.co.kr X-TURU-KEY: your-api-key-here Content-Type: application/json { "carNumber": "106호3074", "startDateTimeStr": "2025-09-11 09:00", "endDateTimeStr": "2025-09-12 17:00", "reason": "사고차량 수리" } ``` ```http PUT /developer/v1/reservation/123/dispatch/complete HTTP/1.1 Host: api-partners.carplat.co.kr X-TURU-KEY: your-api-key-here Content-Type: application/json { "parkingMemo": "지하3층 B구역" } ``` ## 응답 본문 응답 본문은 서버가 클라이언트에 보내는 데이터입니다. 카플랫 API의 성공 여부는 HTTP 상태 코드로 전달합니다. 돌아온 HTTP 상태 코드에 따라 요청이나 에러를 처리하는 로직을 구축하세요. 모든 API 응답, 요청 본문은 **JSON 형식**입니다. 따라서 응답 헤더에는 다음과 같이 Content-Type이 포함됩니다. ```http Content-Type: application/json; charset=utf-8 ``` ### 응답 HTTP 상태 코드 | HTTP 상태 코드 | 설명 | | --- | --- | | **200 - OK** | 요청이 성공적으로 처리되었습니다. | | **400 - Bad Request** | 요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되었을 때 돌아오는 응답입니다. 요청 파라미터를 확인해주세요. | | **401 - Unauthorized** | 인증이 필요합니다. API 키가 없거나 만료되었을 때 발생합니다. | | **403 - Forbidden** | 접근 권한이 없습니다. 유효한 API 키이지만 해당 리소스에 대한 권한이 없을 때 발생합니다. | | **404 - Not Found** | 요청한 리소스가 존재하지 않습니다. 요청한 API 주소나 리소스 ID를 다시 한번 확인해보세요. | | **409 - Conflict** | 요청이 현재 서버 상태와 충돌합니다. 예를 들어, 이미 배차 출발한 예약을 다시 배차 출발시키려 할 때 발생합니다. | | **429 - Too Many Requests** | 비정상적으로 많은 요청을 보냈습니다. 잠시 후 다시 시도해주세요. | | **500 - Server Error** | 카플랫 서버에서 에러가 발생했습니다. | ### 성공 응답 객체 카플랫 API는 일관된 응답 구조를 제공합니다. 모든 성공 응답은 다음과 같은 기본 구조를 따릅니다. ```json { "code": "S000", "message": "성공" } ``` 스케줄 등록처럼 처리 결과로 돌려줄 데이터가 있는 API는 `result` 필드에 결과를 담아 응답합니다. ```json { "code": "S000", "message": "성공", "result": { "id": 1 } } ``` ### 에러 응답 객체 요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다. API별 에러 코드와 메시지는 [에러 코드](/guides/error-code) 페이지에서 살펴보세요. ```json { "code": "E001", "message": "필수 파라미터가 누락되었습니다." } ``` ## 날짜 및 시간 형식 카플랫 API의 날짜와 시간은 모두 **한국 표준시(KST, UTC+09:00)** 기준입니다. ### 날짜 형식 | 구분 | 형식 | 예시 | | --- | --- | --- | | 날짜시간 (콜백 이벤트) | `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` (ISO 8601) | `2024-01-20T09:00:00.000+09:00` | | 날짜시간 (스케줄 등록·수정 요청) | `yyyy-MM-dd HH:mm` | `2025-09-11 09:00` | | 생년월일 | `YYYYMMDD` | `19900101` | ```json { "reservationCreateDateTime": "2024-01-15T10:30:00.000+09:00", "reservationStartDateTime": "2024-01-20T09:00:00.000+09:00", "reservationEndDateTime": "2024-01-22T18:00:00.000+09:00" } ``` ### 시간대 (Timezone) 콜백 이벤트의 날짜시간에는 `+09:00` 오프셋이 포함되어 있으므로, 오프셋을 인식하는 파서로 읽으면 시간대 변환 없이 정확한 시각을 얻을 수 있습니다. 스케줄 등록·수정 요청의 `yyyy-MM-dd HH:mm` 값에는 오프셋이 없으므로 한국 표준시 기준으로 보내주세요. ```javascript // +09:00 오프셋이 포함된 값은 그대로 파싱 const startAt = new Date("2024-01-20T09:00:00.000+09:00"); startAt.toISOString(); // "2024-01-20T00:00:00.000Z" ``` ```java // Java에서는 OffsetDateTime으로 파싱 OffsetDateTime startAt = OffsetDateTime.parse("2024-01-20T09:00:00.000+09:00"); ``` ## 유의사항 ### API 응답 변경 정책 **API 응답에 새로운 필드가 추가되는 것과 같이 하위 호환을 지원하는 변경 사항은 버전 릴리즈 없이 기존 API에 반영됩니다.** 클라이언트 코드는 이러한 변경에 유연하게 대응할 수 있도록 작성해 주세요. ### JSON 파싱 권장사항 추가된 새로운 필드를 무시하거나 기본값을 설정하는 방식으로 JSON 파싱 로직을 구성해 주세요. ```javascript // 새로운 필드가 추가되어도 오류가 발생하지 않도록 처리 const reservation = { reservationId: response.result.reservationId, driverName: response.result.driverName, // 새로운 필드는 무시되거나 기본값 사용 newField: response.result.newField || null }; ``` ```java // ObjectMapper 설정으로 알 수 없는 속성 무시 ObjectMapper mapper = new ObjectMapper(); mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); // 또는 @JsonIgnoreProperties 어노테이션 사용 @JsonIgnoreProperties(ignoreUnknown = true) public class ReservationResponse { // 필드 정의 } ``` ### 요청 제한 - **Rate Limiting**: 분당 최대 1000회 요청 - **Timeout**: 요청 타임아웃은 30초 - **Payload Size**: 요청 본문 최대 크기는 10MB ### 보안 고려사항 - API KEY는 안전한 곳에 저장하세요 - HTTPS를 통해서만 API를 호출하세요 - 민감한 정보를 URL 파라미터에 포함하지 마세요 --- # 콜백 이벤트 > 카플랫 API 콜백 이벤트 종류와 처리 방법을 설명합니다. 카플랫에서는 예약 또는 차량 상태가 변경될 때 **콜백** 을 통해 실시간 알림을 받아볼 수 있습니다. 콜백은 데이터 변경 시 서버 간에 이벤트를 실시간으로 전달하는 메커니즘입니다. ## 1. 콜백 이벤트 종류 카플랫이 전송하는 콜백 이벤트는 다음과 같습니다. 이벤트별 요청 본문 스펙은 각 이벤트의 API 레퍼런스를 참고해주세요. | 이벤트 | HTTP 메서드 | 경로 | | --- | --- | --- | | [예약 정보 등록 이벤트](/reference#post-events-reservation) | `POST` | `/events/reservation` | | [예약 정보 업데이트 이벤트](/reference#put-events-reservation-id) | `PUT` | `/events/reservation/{id}` | | [예약 차량 변경 이벤트](/reference#put-events-reservation-id-car-change) | `PUT` | `/events/reservation/{id}/car-change` | | [예약 반납 연장 이벤트](/reference#put-events-reservation-id-extension) | `PUT` | `/events/reservation/{id}/extension` | | [하이패스 결제 정보 전달](/reference#post-events-hipass) | `POST` | `/events/hipass` | ## 2. 콜백 URL 등록하기 ### 2.1 API 키 신청 1. **API 키 신청**: [카플랫 API 연동 관리](https://carplat.co.kr/developers/developer) 페이지에서 API 키 신청을 진행합니다. 2. **승인 대기**: 승인 결과는 관리자 검토 후 신청 시 입력한 이메일로 알려드립니다. ### 2.2 콜백 URL 및 이벤트 설정 API 키 신청 승인 완료 후, 상세정보 페이지에서 콜백 설정을 등록 및 관리할 수 있습니다: 1. **상세정보 페이지 접속**: [카플랫 API 연동 관리](https://carplat.co.kr/developers/developer) 페이지에서 승인된 API 키의 상세정보로 이동합니다. 2. **콜백 베이스 URL 등록**: 콜백을 받을 서버의 베이스 주소를 입력합니다. - 형식: `https://서버주소` - 예시: `https://api.yourservice.com` 3. **콜백 이벤트 선택**: 수신하고자 하는 콜백 이벤트를 선택합니다. - 필요한 이벤트만 선택하여 불필요한 콜백 수신을 방지할 수 있습니다. > **참고**: > - 콜백 URL은 HTTPS 프로토콜을 사용해야 하며, 외부에서 접근 가능한 공개 URL이어야 합니다. > - 등록한 베이스 URL에 각 이벤트별 경로가 추가되어 전송됩니다. (예: `{베이스URL}/events/{이벤트타입}`) > - 선택하지 않은 이벤트는 콜백이 전송되지 않습니다. > - 콜백 URL과 이벤트 설정은 상세정보 페이지에서 언제든지 수정할 수 있습니다. > - 사용 가능한 모든 콜백 이벤트와 경로는 [API 레퍼런스의 콜백 이벤트 섹션](/reference#category-callback-events)에서 확인할 수 있습니다. ## 3. 콜백 수신 및 처리 가이드 ### 3.1 콜백 요청 형식 > **중요**: 클라이언트는 각 콜백 이벤트의 엔드포인트를 구현하여 Carplat으로부터 실시간 정보를 수신해야 합니다. 카플랫에서 전송하는 콜백은 **이벤트별로 다른 엔드포인트**로 전송됩니다. 각 이벤트 타입에 따라 등록한 콜백 베이스 URL에 해당 이벤트 경로가 추가되어 요청이 전달됩니다. #### 요청 구조 모든 콜백 이벤트는 다음과 같은 공통 구조를 따릅니다. 예약 정보 등록 이벤트는 새 예약을 전달하므로 `POST`로, 이미 전달된 예약의 변경 사항은 예약 ID를 경로에 담아 `PUT`으로 전송됩니다. ```http POST /events/reservation HTTP/1.1 Host: {등록한_베이스_URL의_호스트} Content-Type: application/json { // 예약 정보 (JSON 형식) } ``` ```http PUT /events/reservation/12345/car-change HTTP/1.1 Host: {등록한_베이스_URL의_호스트} Content-Type: application/json { // 변경된 차량 정보 (JSON 형식) } ``` #### 주요 특징 - **HTTP 메서드**: 새 데이터를 전달하는 이벤트(예약 정보 등록, 하이패스 결제 정보 전달)는 `POST`, 기존 예약의 변경을 전달하는 이벤트(예약 정보 업데이트, 차량 변경, 반납 연장)는 `PUT` 메서드를 사용합니다. - **Content-Type**: `application/json` 형식으로 전송됩니다. - **엔드포인트**: 각 이벤트는 `/events/`로 시작하는 고유한 경로를 가지며, 예약 변경 이벤트는 경로에 예약 ID(`{id}`)를 포함합니다. - **요청 본문**: 이벤트 타입에 따라 다른 JSON 스키마를 가집니다. > **참고**: > - 사용 가능한 모든 콜백 이벤트 목록과 각 이벤트의 상세한 요청 스키마는 [API 레퍼런스의 콜백 이벤트 섹션](/reference#category-callback-events)에서 확인할 수 있습니다. ### 3.2 콜백 응답 처리 콜백을 정상적으로 수신했다면 **HTTP 200 OK** 응답과 아래 객체를 Response Body로 반환해야 합니다: ```http HTTP/1.1 200 OK Content-Type: application/json { "code": "S000", "message": "성공" } ``` ### 3.3 방화벽 설정 (필수) > 콜백을 정상적으로 수신하려면 **카플랫 서버 IP에 대한 방화벽 설정이 필수**입니다. > 방화벽 설정 방법은 [방화벽 및 보안 프로토콜](/guides/security) 페이지를 참고해주세요 콜백 URL로 등록한 서버에서 다음 방화벽 규칙을 설정해야 합니다: 1. **인바운드 규칙**: 카플랫 서버에서 콜백 서버로의 HTTP/HTTPS 요청 허용 2. **아웃바운드 규칙**: 콜백 서버에서 카플랫 서버로의 응답 허용 #### 방화벽 설정 예시 ```bash # AWS Security Group 예시 # 인바운드: 카플랫 서버 IP에서 HTTPS(443) 포트 허용 aws ec2 authorize-security-group-ingress \ --group-id sg-xxxxxxxxx \ --protocol tcp \ --port 443 \ --cidr {카플랫_서버_IP}/32 # 아웃바운드: 모든 HTTPS 트래픽 허용 (기본값) aws ec2 authorize-security-group-egress \ --group-id sg-xxxxxxxxx \ --protocol tcp \ --port 443 \ --cidr 0.0.0.0/0 ``` > **참고**: 정확한 카플랫 서버 IP 주소는 API 키 발급 시 함께 안내됩니다. ### 3.4 보안 고려사항 1. **HTTPS 필수**: 콜백 URL은 반드시 HTTPS를 사용해야 합니다. 2. **IP 화이트리스트**: 카플랫 서버 IP만 허용하도록 방화벽을 설정하세요. --- # 에러 코드 > 카플랫 API가 응답하는 에러 코드를 설명합니다. 카플랫 API에서 발생할 수 있는 모든 에러 코드와 처리 방법을 설명합니다. ## 에러 응답 구조 API 요청이 실패하면 다음과 같은 구조로 에러 정보가 응답됩니다: ```json { "code": "E001", "message": "name: 길이가 6에서 20 사이여야 합니다", "result": { // optional: 추가 정보가 필요한 경우에만 포함 ... } } ``` ### 응답 필드 설명 - **`code`** (필수): 성공 또는 실패 여부를 나타내는 에러 코드 - **`message`** (필수): 에러 발생 사유를 설명하는 메시지 - **`result`** (선택): 에러 원인에 대한 추가 정보가 필요한 경우 포함 ## 일반 에러 코드 ### 400 Bad Request | 에러 코드 | 메시지 예시 | 원인 | 처리 | | --- | --- | --- | --- | | `E001` | deleteYn: 'a'는 형식이 맞지 않습니다 | HTTP 메시지 변환 불가할 때 | 데이터 포맷 및 유효 값 확인 | | `E001` | name: 길이가 6에서 20 사이여야 합니다
name: 널이어서는 안됩니다 | 유효성 검사가 실패할 때 | 데이터 포맷 및 유효 값 확인 | | `E001` | deleteYn: 'a'는 형식이 맞지 않습니다 | HTTP 메시지 변환 불가할 때 | 데이터 포맷 및 유효 값 확인 | | `E001` | name: 필수 요청 인자값 입니다. | 유효성 검사가 실패할 때 | 데이터 포맷 및 유효 값 확인 | | `E001` | 평일 - 운영 시작/종료시를 설정해야 합니다. | 비즈니스 로직 상 유효성 검사 실패 | 데이터 포맷 및 유효 값 확인 | | `E004` | 최대 7일 조회 가능합니다.
종료일은 시작일 이후로 선택 가능합니다.
날짜 범위를 지정해야 합니다. | 기간 검색이 불가할 때 | 데이터 포맷 및 유효 값 확인 | ### 401 Unauthorized | 에러 코드 | 메시지 예시 | 원인 | 처리 | | --- | --- | --- | --- | | `A001` | 유효하지 않은 토큰입니다. | 인증 실패 | 인증 확인 | | `A002` | 만료된 토큰입니다. | 인증 실패 | 인증 확인 | | `A004` | 입력하신 정보와 일치하는 계정이 없습니다. | 잘못된 인증 정보 | 인증 확인 | ### 404 Not Found | 에러 코드 | 메시지 예시 | 원인 | 처리 | | --- | --- | --- | --- | | `E002` | 해당 기능은 지원되지 않습니다. | HTTP 리소스를 찾을 수 없을 때 | API 확인 (path) | | `E002` | 해당 기능은 지원되지 않습니다. | HTTP 메소드를 지원하지 않을 때 | API 확인 (method) | | `E003` | 조회된 데이터가 없습니다. | 특정 리소스를 찾을 수 없을 때 | 식별값 (Id 값) 유효성 확인 | ### 409 Conflict | 에러 코드 | 메시지 예시 | 원인 | 처리 | | --- | --- | --- | --- | | `E010` | 데이터 정합성 위반으로 해당 기능을 처리할 수 없습니다. | 데이터에 국한되지 않고 무결성 제약 조건을 위반 | 식별값 (Id 값) 정합성 확인 | | `E011` | 이미 등록된 카테고리 명이 있습니다. | 비즈니스 로직 상 특정 리소스 충돌 | 중복 확인 | | `E012` | 업체 관리자는 삭제할 수 없습니다. | 요청한 기준을 준수하는 리소스를 찾지 못할 때 | 요청 조건 확인 | ### 500 Internal Server Error | 에러 코드 | 메시지 예시 | 원인 | 처리 | | --- | --- | --- | --- | | `E051` | 해당 기능을 처리할 수 없습니다. 관리자에게 문의하세요. | 지정된 SQL이 유효하지 않은 경우 | Database Mapper 확인 | | `E052` | 해당 기능을 처리할 수 없습니다. 관리자에게 문의하세요. | RDBMS를 사용할 때 잘못된 SQL을 지정할 때 발생 | Database Mapper 확인 | | `E053` | 해당 기능을 처리할 수 없습니다. 관리자에게 문의하세요. | 일시적이지 않은 것으로 간주되는 데이터 액세스 예외 | Database Mapper 확인 | | `E055` | 해당 기능을 처리할 수 없습니다. 관리자에게 문의하세요. | 적절한 Exception 핸들링 미처리 | Handler 확인 | | `E050` | 일시적인 장애로 서비스를 이용하실 수 없습니다. | JDBC 오류 | Database 접속 상태 확인 | ### 503 Service Unavailable | 에러 코드 | 메시지 예시 | 원인 | 처리 | | --- | --- | --- | --- | | `E060` | 잠시 후 다시 시도해 주세오. 증상이 반복될 경우 관리자에게 문의하세요. | 드물게 발생 할 수도 있는 알 수 없는 예외 | Handler 확인 | | `E061` | sms 전송에 실패했습니다. | 외부 메시징 연동 서비스 예외 | 인포뱅크 연동 이력 확인 | | `E062` | {오토비긴즈 전달값}
통신에 문제가 있어 정보를 불러오지 못했습니다. 잠시 후 다시 시도해 주세요. | 오토비긴즈 연동 에러 | | | `E063` | {아이나비 전달값}
Error : 주소 변환에 실패하였습니다. 다시 시도해주세요. | 아이나비 연동 에러 | | | `E064` | | Kakao T rent 연동 서비스 에러 | Kakao 연동 이력 확인 | | `E065` | 통신에 문제가 있어 정보를 불러오지 못했습니다. 잠시 후 다시 시도해 주세요. | Legacy(C# API 서버) 연동 에러 | | | `E066` | Rental 서비스 통신에 문제가 있습니다. | Carplat Rental 서비스 에러 | Carplat Rental 연동 이력 확인 | | `E067` | 면허 검증에 실패했습니다. | Legacy(Rims API 서버) 연동 에러 | | | `E068` | 해당기능을 처리할 수 없습니다: | SGIS 연동 에러 | SGIS 연동 이력 확인 | | `E069` | | 수요 채널 연동 서비스 에러 | 각 수요 채널 연동 이력 확인 | ## 특수 에러 코드 특정 API 요청에서만 나타날 수 있는 실패 응답 코드입니다. ### 400 Bad Request (특수) | 에러 코드 | 메시지 예시 | 원인 | 처리 | | --- | --- | --- | --- | | `C001` | 비밀번호가 일치하지 않습니다. | 비밀번호 변경 시 기존 비밀번호 불일치 예외 | | | `C002` | 차량을 제외하고 등록해 주세요.
해당 차량으로 등록된 상품이 있습니다. | 상품 등록시 다른 상품에 등록되어 있는 차량을 등록하려는 경우 | 메시지 표시 + 데이터 리스트를 전달하여 표시 | | `C003` | 대여 요금이 올바르지 않습니다. | 예약생성시 계산된 요금과 입력된 요금이 틀릴 경우(KM에서 예약 등록시 E012와 분리해달라는 요청으로 생성) | | | `C004` | 허용되지 않은 확장자입니다. | 허용되지 않은 확장자로 업로드할 경우(프론트 파일 업로드시 E012 에러코드와 분리해달라는 요청으로 생성) | | | `C005` | 유효하지 않은 상품 입니다. | 예약 등록시 입력받은 조건에 해당하는 차량이 없는 경우(검색과 예약 사이에 다른 예약으로 등록된 경우 등)(KM에서 예약 등록시 E012와 분리해달라는 요청으로 생성) | | | `C006` | 단말기가 이미 다른 차량에 연동되어 있습니다. | 단말기 연동 시, 연결 하려는 TID가 다른차량에 이미 연동 되어 있는지 유무를 확인. | | | `C008` | 차량정보 조회에 실패했습니다. 자동차등록증의 소유자와 차량번호가 정확히 일치하는지 확인해 주세요. | 오토비긴즈 차량정보 조회 실패시 사용. Carplat DB 의 데이터가 아니라 오토비긴즈 조회 결과가 없을 경우에 한해서만 사용. 기존에 별도의 로직으로 ResourceNotFoundException을 사용중이여서 별개 코드로 분리. | | | `E8000` | 단말 연동 에러. | Otoplug 단말기 연동 에러 오류 발생 시 출력(KM API Response에 Otoplug 오류 코드를 그대로 전송, KM과 협의 완료) | | | `C009` | 선택한 차량에 필요한 연료탱크 또는 이미지 정보가 등록되어 있지 않습니다. 관리자에게 문의해 주세요. | 상품 등록시 차종정보가 미등록 되어 있는 경우(하나의 인터페이스로 다른 체크로직에서 C002 를 사용하고 있어 구분을 위해 별도 생성) | 메시지 표시 + 데이터 리스트를 전달하여 표시 | ### 409 Conflict (특수) | 에러 코드 | 메시지 예시 | 원인 | 처리 | | --- | --- | --- | --- | | `C007` | 단말기 연동에 실패 하였습니다. 단말기 정보가 변경 되었습니다. | 단말기 연동 시, 연동 시도 시의 정보와 현재 갱신 된 정보를 비교 하여 변경 유무를 확인 | | | `C010` | 선택한 일시는 다음과 같은 사유로 연장 조건에서 벗어납니다.
- 운영시간 외
- 휴무일 포함
- 다음 예약과의 간격 미확보
그래도 연장을 진행하시겠습니까? | 예약 연장시 운영시간, 휴무일, 예약간 간격을 각각 체크하고 위반일 경우 에러 메시지 리스트에 해당하는 메시지를 저장하여 보내야함. | 메시지 표시 + 데이터 리스트를 전달하여 표시 | ## 에러 처리 가이드 ### 1. 클라이언트 에러 (4xx) - **원인**: 잘못된 요청 데이터, 인증 실패, 리소스 없음 - **처리**: 요청 데이터 검증, 인증 정보 확인, API 문서 참조 ### 2. 서버 에러 (5xx) - **원인**: 서버 내부 오류, 외부 서비스 연동 실패 - **처리**: 잠시 후 재시도, 지속 시 관리자 문의 ### 3. 특수 에러 (Cxxx) - **원인**: 특정 비즈니스 로직 위반 - **처리**: 에러 메시지에 따른 데이터 수정 후 재시도 --- # 카플랫 개발자 센터 API 레퍼런스 ## Rest API Carplat에서 제공되는 일부 기능을 API 형태로 제공하여 개발사의 운영업무의 부담을 덜 수 있습니다. 클라이언트가 호출하는 일반적인 REST API입니다. ### 배차 취소 `PUT /developer/v1/reservation/{id}/dispatch/cancel` • 배차를 취소합니다. • 예약 상태가 **배차출발** 또는 **배차완료** 상태에서만 변경 가능합니다. • 이미 등록된 배차 직원, 주차 메모, 배차 사진 등의 정보가 초기화되며 취소 후 예약완료 상태로 변경됩니다. • 해당 예약 건에 발급 된 공유 스마트키(배차)는 사용 중지됩니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 예약 ID
제약: 형식 int64
예: `1` | #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` #### 응답 404 예약 정보를 찾을 수 없음 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "해당 예약을 찾을 수 없습니다." } ``` #### 응답 409 변경 불가능한 상태 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E012", "message": "변경 불가능한 상태입니다." } ``` #### 응답 503 시스템 오류 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E060", "message": "요청 실패. 증상이 반복될 시 관리자에게 문의하세요." } ``` ### 배차완료 전 차량 사진 일괄 등록 `POST /developer/v1/reservation/{id}/dispatch/carImage` • **배차출발** 상태에서만 등록 가능합니다. • 1장당 10mb 이하의 파일만 업로드 가능합니다. • 최대 20장까지 등록 가능합니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 조회할 예약 ID
제약: 형식 int64
예: `1` | #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `carImages` | array | Y | 등록할 차량 이미지 리스트
제약: 개수 1–20 | | `carImages[].imageSubType` | string (enum) | Y | • 이미지 유형
- F : 전면
- R : 운전석 옆면
- B : 후면
- L : 조수석 옆면
- E : 기타(추가 사진)
• 업로드 규칙
- F, R, B, L 유형은 각각 **1장만 등록 가능합니다.**
- E 유형은 **16장까지 등록 가능합니다.**
가능한 값: `F`, `R`, `B`, `L`, `E`
예: `F` | | `carImages[].attachFile` | object | Y | 첨부할 이미지 파일 정보입니다.
파일 자체의 데이터(base64 인코딩된 바이트)와 파일명을 포함한 객체입니다. | | `carImages[].attachFile.fileByte` | string | Y | 첨부 이미지 파일을 Base64 형식으로 인코딩한 문자열입니다.
• 일반적으로 "data:image/png;base64,..." 형식으로 전달됩니다.
• 실제 파일의 바이너리 데이터를 문자열로 변환한 값
제약: 형식 byte
예: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==` | | `carImages[].attachFile.logicalFileName` | string | Y | 사용자가 업로드한 파일의 **원래 파일 이름**(논리명)입니다.
• 확장자 포함한 이름을 그대로 전달합니다. (예: parking.png, car.jpg)
• 허용되는 파일 확장자 목록입니다. (jpeg, jpg, png, pdf, webp)
예: `front.png` | #### 요청 예시 ```json { "carImages": [ { "imageSubType": "F", "attachFile": { "fileByte": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "logicalFileName": "front.png" } } ] } ``` #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` #### 응답 400 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "C004", "message": "허용되지 않은 확장자입니다." } ``` ```json { "code": "C004", "message": "올바르지 않은 이미지 형식입니다. Base64로 인코딩된 이미지 데이터를 전송해주세요." } ``` #### 응답 404 예약 정보를 찾을 수 없음 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "예약 정보를 찾을 수 없습니다." } ``` #### 응답 409 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E012", "message": "예약 상태가 변경되었습니다." } ``` ```json { "code": "E012", "message": "파일 크기가 10mb 를 초과할 수 없습니다." } ``` ```json { "code": "E012", "message": "정면, 운전석 옆면, 후면, 조수석 옆면 사진을 모두 등록해 주세요." } ``` ```json { "code": "E012", "message": "요청한 이미지 유형의 허용 업로드 개수를 초과하여 등록할 수 없습니다." } ``` ### 배차 완료 `PUT /developer/v1/reservation/{id}/dispatch/complete` • 해당 예약을 배차완료 상태로 변경합니다. • 예약 상태가 **배차출발** 상태에서만 변경 가능합니다. • 배차완료 전 차량 사진과 주차 사진을 필수로 등록해야 합니다. • 차량의 주차 위치 정보(parkingMemo)를 필수로 등록해야 합니다. • 해당 예약 건에 발급 된 공유 스마트키(배차)는 사용 중지됩니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 예약 ID
제약: 형식 int64
예: `1` | #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `parkingMemo` | string | Y | 주차 위치 메모
제약: 길이 1–50
예: `건물 지하 주차장 A구역` | #### 요청 예시 ```json { "parkingMemo": "건물 지하 주차장 A구역" } ``` #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` #### 응답 400 Bad Request | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E001", "message": "parkingMemo: 주차 메모를 입력해 주세요., parkingMemo: 최소 1자에서 최대 50자까지 입력 가능합니다." } ``` #### 응답 404 예약 정보를 찾을 수 없음 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "예약을 찾을 수 없습니다." } ``` ```json { "code": "E003", "message": "주차 사진을 등록해주세요." } ``` #### 응답 409 변경 불가능한 상태 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E012", "message": "배차 사진을 등록해주세요." } ``` ```json { "code": "E012", "message": "변경 불가능한 상태입니다." } ``` #### 응답 503 시스템 오류 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E060", "message": "요청 실패. 증상이 반복될 시 관리자에게 문의하세요." } ``` ### 배차완료 전 주차 사진 등록 `POST /developer/v1/reservation/{id}/dispatch/parkingImage` • **배차출발** 상태에서만 등록 가능합니다. • 10mb 이하의 파일만 업로드 가능합니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 조회할 예약 ID
제약: 형식 int64
예: `1` | #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `attachFile` | object | Y | 첨부할 이미지 파일 정보입니다.
파일 자체의 데이터(base64 인코딩된 바이트)와 파일명을 포함한 객체입니다. | | `attachFile.fileByte` | string | Y | 첨부 이미지 파일을 Base64 형식으로 인코딩한 문자열입니다.
• 일반적으로 "data:image/png;base64,..." 형식으로 전달됩니다.
• 실제 파일의 바이너리 데이터를 문자열로 변환한 값
제약: 형식 byte
예: `data:image/png;base64,iVB` | | `attachFile.logicalFileName` | string | Y | 사용자가 업로드한 파일의 **원래 파일 이름**(논리명)입니다.
• 확장자 포함한 이름을 그대로 전달합니다. (예: parking.png, car.jpg)
• 허용되는 파일 확장자 목록입니다. (jpeg, jpg, png, pdf, webp)
예: `parking.png` | #### 요청 예시 ```json { "attachFile": { "fileByte": "data:image/png;base64,iVB", "logicalFileName": "parking.png" } } ``` #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` #### 응답 400 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "C004", "message": "허용되지 않은 확장자입니다." } ``` ```json { "code": "C004", "message": "올바르지 않은 이미지 형식입니다. Base64로 인코딩된 이미지 데이터를 전송해주세요." } ``` #### 응답 404 예약 정보를 찾을 수 없음 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "예약 정보를 찾을 수 없습니다." } ``` #### 응답 409 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E012", "message": "예약 상태가 변경되었습니다." } ``` ```json { "code": "E012", "message": "파일 크기가 10mb 를 초과할 수 없습니다." } ``` ```json { "code": "E012", "message": "사진이 이미 등록되어 추가 등록 할 수 없습니다." } ``` ### 배차 출발 `PUT /developer/v1/reservation/{id}/dispatch/start` • 해당 예약을 배차출발 상태로 변경합니다. • 예약 상태가 **예약완료** 상태에서만 변경 가능합니다. • 배차 담당 직원을 지정합니다. • 카플랫 계정(account)은 필수 입력 값입니다. • 존재하지 않는 직원 계정으로는 등록할 수 없습니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 예약 ID
제약: 형식 int64
예: `1` | #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `account` | string | Y | 담당자 계정 (직원 계정)
제약: 길이 6–100
예: `specialist` | #### 요청 예시 ```json { "account": "specialist" } ``` #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` #### 응답 400 Bad Request | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E001", "message": "account: 직원 계정 정보는 필수입니다., account: 직원 계정은 최소 6자, 최대 100자여야 합니다." } ``` #### 응답 404 정보를 찾을 수 없음 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "예약 정보를 찾을 수 없습니다." } ``` ```json { "code": "E003", "message": "직원 정보를 찾을 수 없습니다." } ``` #### 응답 409 변경 불가능한 상태 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E012", "message": "변경 불가능한 상태입니다." } ``` #### 응답 503 시스템 오류 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E060", "message": "요청 실패. 증상이 반복될 시 관리자에게 문의하세요." } ``` ### 회수완료 전 차량 사진 일괄 등록 `POST /developer/v1/reservation/{id}/recall/carImage` • **반납완료** 상태에서만 등록 가능합니다. • 1장당 10mb 이하의 파일만 업로드 가능합니다. • 최대 20장까지 등록 가능합니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 조회할 예약 ID
제약: 형식 int64
예: `1` | #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `carImages` | array | Y | 등록할 차량 이미지 리스트
제약: 개수 1–20 | | `carImages[].imageSubType` | string (enum) | Y | • 이미지 유형
- E : 기타(추가 촬영 이미지)
• 업로드 규칙
- 회수(Recall) 차량 이미지 업로드는 **E 유형만 허용됩니다.**
(F, R, B, L 유형은 회수 이미지로 등록할 수 없습니다.)
가능한 값: `E`
예: `E` | | `carImages[].attachFile` | object | Y | 첨부할 이미지 파일 정보입니다.
파일 자체의 데이터(base64 인코딩된 바이트)와 파일명을 포함한 객체입니다. | | `carImages[].attachFile.fileByte` | string | Y | 첨부 이미지 파일을 Base64 형식으로 인코딩한 문자열입니다.
• 일반적으로 "data:image/png;base64,..." 형식으로 전달됩니다.
• 실제 파일의 바이너리 데이터를 문자열로 변환한 값
제약: 형식 byte
예: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==` | | `carImages[].attachFile.logicalFileName` | string | Y | 사용자가 업로드한 파일의 **원래 파일 이름**(논리명)입니다.
• 확장자 포함한 이름을 그대로 전달합니다. (예: parking.png, car.jpg)
• 허용되는 파일 확장자 목록입니다. (jpeg, jpg, png, pdf, webp)
예: `front.png` | #### 요청 예시 ```json { "carImages": [ { "imageSubType": "E", "attachFile": { "fileByte": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "logicalFileName": "front.png" } } ] } ``` #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` #### 응답 400 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "C004", "message": "허용되지 않은 확장자입니다." } ``` ```json { "code": "C004", "message": "올바르지 않은 이미지 형식입니다. Base64로 인코딩된 이미지 데이터를 전송해주세요." } ``` #### 응답 404 예약 정보를 찾을 수 없음 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "예약 정보를 찾을 수 없습니다." } ``` #### 응답 409 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E012", "message": "예약 상태가 변경되었습니다." } ``` ```json { "code": "E012", "message": "파일 크기가 10mb 를 초과할 수 없습니다." } ``` ```json { "code": "E012", "message": "정면, 운전석 옆면, 후면, 조수석 옆면 사진을 모두 등록해 주세요." } ``` ```json { "code": "E012", "message": "요청한 이미지 유형의 허용 업로드 개수를 초과하여 등록할 수 없습니다." } ``` ### 회수 완료 `PUT /developer/v1/reservation/{id}/recall/complete` • 해당 예약을 **회수완료** 상태로 변경합니다. • 예약 상태가 **반납완료** 상태에서만 변경 가능합니다. • 차량 회수 담당 직원을 지정합니다. • 카플랫 계정(account)은 필수 입력값입니다. • 존재하지 않는 직원 계정으로는 등록할 수 없습니다. • 해당 예약 건에 발급 된 공유 스마트키(회수)는 사용 중지됩니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 예약 ID
제약: 형식 int64
예: `1` | #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `account` | string | Y | 담당자 계정 (직원 계정)
제약: 길이 6–100
예: `specialist` | #### 요청 예시 ```json { "account": "specialist" } ``` #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` #### 응답 404 예약 정보를 찾을 수 없음 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "해당 예약을 찾을 수 없습니다." } ``` #### 응답 409 변경 불가능한 상태 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E012", "message": "변경 불가능한 상태입니다." } ``` #### 응답 503 시스템 오류 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E060", "message": "요청 실패. 증상이 반복될 시 관리자에게 문의하세요." } ``` ### 스케줄 등록 `POST /developer/v1/schedule` • 새로운 스케줄을 등록합니다. • 스케줄 시작 일시는 현재 시점을 기준으로 최대 7일 전까지만 설정할 수 있습니다. • 시작 일시는 종료 일시보다 이후가 될 수 없습니다. • 스케줄 기간은 최소 30분 이상이어야 합니다. #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `carNumber` | string | Y | 차량 번호
예: `106호3074` | | `startDateTimeStr` | string | Y | 스케줄 시작일시(yyyy-MM-dd HH:mm 형식)
예: `2025-09-11 09:00` | | `endDateTimeStr` | string | Y | 스케줄 종료일시(yyyy-MM-dd HH:mm 형식)
예: `2025-09-12 17:00` | | `reason` | string | Y | 사유
제약: 길이 ≤ 50
예: `사고차량 수리` | #### 요청 예시 ```json { "carNumber": "106호3074", "startDateTimeStr": "2025-09-11 09:00", "endDateTimeStr": "2025-09-12 17:00", "reason": "사고차량 수리" } ``` #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | | `result` | object | Y | | | `result.id` | integer | Y | 등록된 스케줄 ID (스케줄 수정/삭제 시 사용)
제약: 형식 int64
예: `1` | ```json { "code": "S000", "message": "성공", "result": { "id": 1 } } ``` #### 응답 400 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E004", "message": "시작 일시는 종료 일시보다 늦을 수 없습니다." } ``` ```json { "code": "E004", "message": "시작 일시는 일주일 전까지만 선택할 수 있습니다." } ``` ```json { "code": "E004", "message": "스케줄 기간은 최소 30분 이상이어야 합니다." } ``` #### 응답 404 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "대상 데이터가 존재하지 않습니다." } ``` #### 응답 409 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E011", "message": "스케줄 기간이 중복 됩니다." } ``` ### 스케줄 수정 `PUT /developer/v1/schedule/{id}` • 지정된 스케줄 ID에 해당하는 스케줄 정보를 수정합니다. • 스케줄 시작 일시는 현재 시점을 기준으로 최대 7일 전까지만 설정할 수 있습니다. • 시작 일시는 종료 일시보다 이후가 될 수 없습니다. • 스케줄 기간은 최소 30분 이상이어야 합니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 스케줄 ID
제약: 형식 int64
예: `1` | #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `startDateTimeStr` | string | Y | 스케줄 시작일시(yyyy-MM-dd HH:mm 형식)
예: `2025-09-11 09:00` | | `endDateTimeStr` | string | Y | 스케줄 종료일시(yyyy-MM-dd HH:mm 형식)
예: `2025-09-12 17:00` | | `reason` | string | Y | 사유
제약: 길이 ≤ 50
예: `사고차량 수리` | #### 요청 예시 ```json { "startDateTimeStr": "2025-09-11 09:00", "endDateTimeStr": "2025-09-12 17:00", "reason": "사고차량 수리" } ``` #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` #### 응답 400 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E004", "message": "시작 일시는 종료 일시보다 늦을 수 없습니다." } ``` ```json { "code": "E004", "message": "시작 일시는 일주일 전까지만 선택할 수 있습니다." } ``` ```json { "code": "E004", "message": "스케줄 기간은 최소 30분 이상이어야 합니다." } ``` #### 응답 404 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "대상 데이터가 존재하지 않습니다." } ``` #### 응답 409 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E011", "message": "스케줄 기간이 중복 됩니다." } ``` ```json { "code": "E012", "message": "종료 일시가 7일 이상 지난 경우 수정이 불가합니다." } ``` ### 스케줄 삭제 `DELETE /developer/v1/schedule/{id}` • 지정된 스케줄 ID에 해당하는 스케줄을 삭제합니다. • 삭제 처리 후에는 해당 스케줄 정보와 연관된 데이터가 더 이상 조회되지 않습니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 스케줄 ID
제약: 형식 int64
예: `1` | #### 응답 200 OK | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` #### 응답 404 Error | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "E003", "message": "대상 데이터가 존재하지 않습니다." } ``` ## Callback Events ⚠️ **이 섹션의 API들은 테스트할 수 없습니다.** 서버에서 예약 상태 변경등의 정보를 자동으로 클라이언트에서 전달하는 이벤트 입니다. 해당 이벤트의 URL은 Carplat 에서 연동 신청 시 등록한 콜백 URL과 연결되어 정보가 전송됩니다. ### 예약 정보 등록 이벤트 `POST /events/reservation` **서버 → 클라이언트 Webhook 이벤트** • 예약이 생성되었을 때 발생합니다. • 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 예약 정보를 수신해야 합니다. #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `id` | integer | Y | 예약 ID
제약: 형식 int64
예: `12345` | | `serviceId` | integer | Y | 서비스 ID
제약: 형식 int64
예: `1` | | `serviceName` | string | Y | 서비스명
예: `비대면 렌트` | | `reservationStatus` | integer | Y | 예약 상태 코드(예약 등록시에는 예약완료("5") 고정, 예약 수정시에는 모든 스테이터스가 전달 가능)
- 5: 예약완료
- 10: 배차출발
- 15: 배차완료
- 20: 이용 중
- 30: 반납완료
- 35: 회수완료
- 40: 예약취소
- 45: 노쇼취소
- 50: 예약실패(시스템취소)
예: `5` | | `carId` | integer | Y | 차량 ID
제약: 형식 int64
예: `100` | | `carNumber` | string | Y | 차량 번호
예: `12가3456` | | `companyId` | integer | Y | 업체 ID
제약: 형식 int64
예: `10` | | `companyName` | string | Y | 업체명
예: `(주)피플카` | | `reservationCreateDateTime` | string | Y | 예약 생성 일시(yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-15T10:30:00.000+09:00` | | `reservationStartDateTime` | string | Y | 예약 시작 일시(yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-20T09:00:00.000+09:00` | | `reservationEndDateTime` | string | Y | 예약 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-22T18:00:00.000+09:00` | | `driveStartDateTime` | string | | 운행 시작 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-20T09:15:00.000+09:00` | | `driveEndDateTime` | string | | 운행 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-22T17:45:00.000+09:00` | | `pickUpAddress` | string | Y | 픽업 주소
예: `서울시 강남구 테헤란로 123` | | `driverName` | string | Y | 운전자 이름
예: `홍길동` | | `driverBirthDate` | string | Y | 운전자 생년월일 (YYYYMMDD)
예: `19900101` | | `driverPhone` | string | Y | 운전자 전화번호("-" 없이 등록)
예: `01012345678` | | `driverLicenseNumber` | string | Y | 운전자 면허번호
예: `12-34-567890-12` | | `driverAddress` | string | Y | 운전자 주소
예: `서울시 강남구 역삼동 123-45` | | `pickUpMemo` | string | | 픽업 메모
예: `건물 지하 주차장` | | `parkingMemo` | string | | 주차 메모
예: `B2 주차장 A구역` | | `parkingImagePath` | string | | 주차 이미지 경로 URL
예: `https://carplat.co.kr/images/parking/12345.jpg` | | `parkingFeeType` | integer | | 주차장 유형(1: 유료, 0: 불명)
예: `0` | | `coDriver` | object | | **동승자 정보**
해당 예약에 동승자가 등록된 경우에만 전송됩니다. 동승자가 없으면 이 필드 자체가 응답에 포함되지 않습니다.
제약: nullable | | `coDriver.phone` | string | | 동승자 전화번호("-" 없이 등록)
예: `01099104510` | | `coDriver.date_of_birth` | string | | 동승자 생년월일 (YYYYMMDD)
예: `19931111` | | `coDriver.name` | string | | 동승자명
예: `박해뤼` | | `coDriver.driver_license_number` | string | | 동승자 면허번호
예: `11-17-174133-01` | #### 요청 예시 ```json { "id": 12345, "serviceId": 1, "serviceName": "비대면 렌트", "reservationStatus": 5, "carId": 100, "carNumber": "12가3456", "companyId": 10, "companyName": "(주)피플카", "reservationCreateDateTime": "2024-01-15T10:30:00.000+09:00", "reservationStartDateTime": "2024-01-20T09:00:00.000+09:00", "reservationEndDateTime": "2024-01-22T18:00:00.000+09:00", "driveStartDateTime": "2024-01-20T09:15:00.000+09:00", "driveEndDateTime": "2024-01-22T17:45:00.000+09:00", "pickUpAddress": "서울시 강남구 테헤란로 123", "driverName": "홍길동", "driverBirthDate": "19900101", "driverPhone": "01012345678", "driverLicenseNumber": "12-34-567890-12", "driverAddress": "서울시 강남구 역삼동 123-45", "pickUpMemo": "건물 지하 주차장", "parkingMemo": "B2 주차장 A구역", "parkingImagePath": "https://carplat.co.kr/images/parking/12345.jpg", "parkingFeeType": 0, "coDriver": { "phone": "01099104510", "date_of_birth": "19931111", "name": "박해뤼", "driver_license_number": "11-17-174133-01" } } ``` #### 응답 200 이벤트를 성공적으로 수신했음을 알립니다. | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` ### 예약 정보 업데이트 이벤트 `PUT /events/reservation/{id}` **서버 → 클라이언트 Webhook 이벤트** • 예약 정보가 변경되었을 때 발생합니다. • 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 예약 변경 정보를 수신해야 합니다. • 연동 신청 시 등록한 콜백 URL로 전송됩니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 예약 ID
제약: 형식 int64
예: `1` | #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `id` | integer | Y | 예약 ID
제약: 형식 int64
예: `12345` | | `serviceId` | integer | Y | 서비스 ID
제약: 형식 int64
예: `1` | | `serviceName` | string | Y | 서비스명
예: `비대면 렌트` | | `reservationStatus` | integer | Y | 예약 상태 코드(예약 등록시에는 예약완료("5") 고정, 예약 수정시에는 모든 스테이터스가 전달 가능)
- 5: 예약완료
- 10: 배차출발
- 15: 배차완료
- 20: 이용 중
- 30: 반납완료
- 35: 회수완료
- 40: 예약취소
- 45: 노쇼취소
- 50: 예약실패(시스템취소)
예: `5` | | `carId` | integer | Y | 차량 ID
제약: 형식 int64
예: `100` | | `carNumber` | string | Y | 차량 번호
예: `12가3456` | | `companyId` | integer | Y | 업체 ID
제약: 형식 int64
예: `10` | | `companyName` | string | Y | 업체명
예: `(주)피플카` | | `reservationCreateDateTime` | string | Y | 예약 생성 일시(yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-15T10:30:00.000+09:00` | | `reservationStartDateTime` | string | Y | 예약 시작 일시(yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-20T09:00:00.000+09:00` | | `reservationEndDateTime` | string | Y | 예약 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-22T18:00:00.000+09:00` | | `driveStartDateTime` | string | | 운행 시작 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-20T09:15:00.000+09:00` | | `driveEndDateTime` | string | | 운행 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-22T17:45:00.000+09:00` | | `pickUpAddress` | string | Y | 픽업 주소
예: `서울시 강남구 테헤란로 123` | | `driverName` | string | Y | 운전자 이름
예: `홍길동` | | `driverBirthDate` | string | Y | 운전자 생년월일 (YYYYMMDD)
예: `19900101` | | `driverPhone` | string | Y | 운전자 전화번호("-" 없이 등록)
예: `01012345678` | | `driverLicenseNumber` | string | Y | 운전자 면허번호
예: `12-34-567890-12` | | `driverAddress` | string | Y | 운전자 주소
예: `서울시 강남구 역삼동 123-45` | | `pickUpMemo` | string | | 픽업 메모
예: `건물 지하 주차장` | | `parkingMemo` | string | | 주차 메모
예: `B2 주차장 A구역` | | `parkingImagePath` | string | | 주차 이미지 경로 URL
예: `https://carplat.co.kr/images/parking/12345.jpg` | | `parkingFeeType` | integer | | 주차장 유형(1: 유료, 0: 불명)
예: `0` | | `coDriver` | object | | **동승자 정보**
해당 예약에 동승자가 등록된 경우에만 전송됩니다. 동승자가 없으면 이 필드 자체가 응답에 포함되지 않습니다.
제약: nullable | | `coDriver.phone` | string | | 동승자 전화번호("-" 없이 등록)
예: `01099104510` | | `coDriver.date_of_birth` | string | | 동승자 생년월일 (YYYYMMDD)
예: `19931111` | | `coDriver.name` | string | | 동승자명
예: `박해뤼` | | `coDriver.driver_license_number` | string | | 동승자 면허번호
예: `11-17-174133-01` | #### 요청 예시 ```json { "id": 12345, "serviceId": 1, "serviceName": "비대면 렌트", "reservationStatus": 5, "carId": 100, "carNumber": "12가3456", "companyId": 10, "companyName": "(주)피플카", "reservationCreateDateTime": "2024-01-15T10:30:00.000+09:00", "reservationStartDateTime": "2024-01-20T09:00:00.000+09:00", "reservationEndDateTime": "2024-01-22T18:00:00.000+09:00", "driveStartDateTime": "2024-01-20T09:15:00.000+09:00", "driveEndDateTime": "2024-01-22T17:45:00.000+09:00", "pickUpAddress": "서울시 강남구 테헤란로 123", "driverName": "홍길동", "driverBirthDate": "19900101", "driverPhone": "01012345678", "driverLicenseNumber": "12-34-567890-12", "driverAddress": "서울시 강남구 역삼동 123-45", "pickUpMemo": "건물 지하 주차장", "parkingMemo": "B2 주차장 A구역", "parkingImagePath": "https://carplat.co.kr/images/parking/12345.jpg", "parkingFeeType": 0, "coDriver": { "phone": "01099104510", "date_of_birth": "19931111", "name": "박해뤼", "driver_license_number": "11-17-174133-01" } } ``` #### 응답 200 이벤트를 성공적으로 수신했음을 알립니다. | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` ### 예약 차량 변경 이벤트 `PUT /events/reservation/{id}/car-change` **서버 → 클라이언트 Webhook 이벤트** • 예약의 차량 정보가 변경되었을 때 발생합니다. • 차량 변경시 "예약 정보 업데이트 이벤트" 와 해당 이벤트 "예약 차량 변경 이벤트" 가 연속으로 호출되도록 설계되어 있습니다.(신청시) • 차량 변경시 차량관리에 사용할 경우에만 사용신청을 부탁드립니다. • 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 차량 변경 정보를 수신해야 합니다. • 연동 신청 시 등록한 콜백 URL로 전송됩니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 예약 ID
제약: 형식 int64
예: `1` | #### 응답 200 이벤트를 성공적으로 수신했음을 알립니다. | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `id` | integer | Y | 예약 ID
제약: 형식 int64
예: `12345` | | `beforeCarId` | integer | Y | 변경 전 차량 ID
제약: 형식 int64
예: `100` | | `beforeCarNumber` | string | Y | 변경 전 차량 번호
예: `12가3456` | | `updateCarId` | integer | Y | 변경 후 차량 ID
제약: 형식 int64
예: `101` | | `updateCarNumber` | string | Y | 변경 후 차량 번호
예: `34나5678` | ```json { "id": 12345, "beforeCarId": 100, "beforeCarNumber": "12가3456", "updateCarId": 101, "updateCarNumber": "34나5678" } ``` ### 예약 반납 연장 이벤트 `PUT /events/reservation/{id}/extension` **서버 → 클라이언트 Webhook 이벤트** • 예약의 반납(종료) 일시가 연장되었을 때 발생합니다. • 예약 반납 연장시 "예약 정보 업데이트 이벤트" 와 해당 이벤트 "예약 반납 연장 이벤트" 가 연속으로 호출되도록 설계되어 있습니다.(신청시) • 예약 반납 연장시 예약관리에 사용할 경우에만 사용신청을 부탁드립니다. • 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 반납 연장 정보를 수신해야 합니다. • 연동 신청 시 등록한 콜백 URL로 전송됩니다. #### 파라미터 | 이름 | 위치 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | --- | | `id` | path | integer | Y | 예약 ID
제약: 형식 int64
예: `1` | #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `id` | integer | Y | 예약 ID
제약: 형식 int64
예: `12345` | | `beforeReservationEndDateTime` | string | Y | 연장 전 반납(종료) 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
예: `2025-09-12T17:00:00.000+09:00` | | `afterReservationEndDateTime` | string | Y | 연장 후 반납(종료) 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
예: `2025-09-12T20:00:00.000+09:00` | #### 요청 예시 ```json { "id": 12345, "beforeReservationEndDateTime": "2025-09-12T17:00:00.000+09:00", "afterReservationEndDateTime": "2025-09-12T20:00:00.000+09:00" } ``` #### 응답 200 이벤트를 성공적으로 수신했음을 알립니다. | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ``` ### 하이패스 결제 정보 전달 `POST /events/hipass` **서버 → 클라이언트 Webhook 이벤트** • 차량의 하이패스 통행 내역이 발생했을 때 전송됩니다. • 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 하이패스 통행 정보를 수신해야 합니다. • 연동 신청 시 등록한 콜백 URL로 전송됩니다. #### 요청 본문 | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `carId` | integer | Y | 차량 ID
제약: 형식 int64
예: `100` | | `carNumber` | string | Y | 차량 번호
예: `12가3456` | | `amount` | integer | Y | 통행료 (원)
예: `3500` | | `transactedDateTime` | string | Y | 통행 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSXXX 형식)
제약: 형식 date-time
예: `2024-01-20T10:30:00.000+09:00` | | `comment` | string | | 통행 정보 메모. 투루카 연동일 경우 사용. "서비스명(#예약번호)"
제약: nullable
예: `투루카 카셰어링(#12345)` | #### 요청 예시 ```json { "carId": 100, "carNumber": "12가3456", "amount": 3500, "transactedDateTime": "2024-01-20T10:30:00.000+09:00", "comment": "투루카 카셰어링(#12345)" } ``` #### 응답 200 이벤트를 성공적으로 수신했음을 알립니다. | 필드 | 타입 | 필수 | 설명 | | --- | --- | --- | --- | | `code` | string | Y | 결과 코드
예: `S000` | | `message` | string | Y | 결과 메세지
예: `성공` | ```json { "code": "S000", "message": "성공" } ```