카플랫 API 개발자 센터

v1.0

API 구성

REST API (클라이언트 → 서버)
Webhook Events (서버 → 클라이언트)

Rest API

Carplat에서 제공되는 일부 기능을 API 형태로 제공하여 개발사의 운영업무의 부담을 덜 수 있습니다.

클라이언트가 호출하는 일반적인 REST API입니다.

10개의 API 엔드포인트

• 배차를 취소합니다.

• 예약 상태가 배차출발 또는 배차완료 상태에서만 변경 가능합니다.

• 이미 등록된 배차 직원, 주차 메모, 배차 사진 등의 정보가 초기화되며 취소 후 예약완료 상태로 변경됩니다.

• 해당 예약 건에 발급 된 공유 스마트키(배차)는 사용 중지됩니다.

Tags:Rest API

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 예약 ID

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
404예약 정보를 찾을 수 없음
- codestring
  결과 코드
- messagestring
  결과 메세지
409변경 불가능한 상태
- codestring
  결과 코드
- messagestring
  결과 메세지
503시스템 오류
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Response Example

200OK

• 배차출발 상태에서만 등록 가능합니다.
• 1장당 10mb 이하의 파일만 업로드 가능합니다.
• 최대 20장까지 등록 가능합니다.

Tags:Rest API

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 조회할 예약 ID

Request Body

carImages필수array<object>(minItems: 1, maxItems: 20)
등록할 차량 이미지 리스트
Array items:
- imageSubType필수string (enum)
  • 이미지 유형
  
  F : 전면
  
  R : 운전석 옆면
  
  B : 후면
  
  L : 조수석 옆면
  
  E : 기타(추가 사진)
  
  • 업로드 규칙
  
  F, R, B, L 유형은 각각 1장만 등록 가능합니다.
  
  E 유형은 16장까지 등록 가능합니다.
  
  가능한 값: F|R|B|L|E
- attachFile필수object
  첨부할 이미지 파일 정보입니다.
  파일 자체의 데이터(base64 인코딩된 바이트)와 파일명을 포함한 객체입니다.
  - fileByte필수string
    첨부 이미지 파일을 Base64 형식으로 인코딩한 문자열입니다.
    
    • 일반적으로 "data:image/png;base64,..." 형식으로 전달됩니다.
    • 실제 파일의 바이너리 데이터를 문자열로 변환한 값
  - logicalFileName필수string
    사용자가 업로드한 파일의 원래 파일 이름(논리명)입니다.
    
    • 확장자 포함한 이름을 그대로 전달합니다. (예: parking.png, car.jpg)
    • 허용되는 파일 확장자 목록입니다. (jpeg, jpg, png, pdf, webp)

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
400Error
- codestring
  결과 코드
- messagestring
  결과 메세지
404예약 정보를 찾을 수 없음
- codestring
  결과 코드
- messagestring
  결과 메세지
409Error
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Request Body

Response Example

200OK

• 해당 예약을 배차완료 상태로 변경합니다.

• 예약 상태가 배차출발 상태에서만 변경 가능합니다.

• 배차완료 전 차량 사진과 주차 사진을 필수로 등록해야 합니다.

• 차량의 주차 위치 정보(parkingMemo)를 필수로 등록해야 합니다.

• 해당 예약 건에 발급 된 공유 스마트키(배차)는 사용 중지됩니다.

Tags:Rest API

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 예약 ID

Request Body

parkingMemo필수string
주차 위치 메모

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
400Bad Request
- codestring
  결과 코드
- messagestring
  결과 메세지
404예약 정보를 찾을 수 없음
- codestring
  결과 코드
- messagestring
  결과 메세지
409변경 불가능한 상태
- codestring
  결과 코드
- messagestring
  결과 메세지
503시스템 오류
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Request Body

Response Example

200OK

• 배차출발 상태에서만 등록 가능합니다.
• 10mb 이하의 파일만 업로드 가능합니다.

Tags:Rest API

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 조회할 예약 ID

Request Body

attachFile필수object
첨부할 이미지 파일 정보입니다. 파일 자체의 데이터(base64 인코딩된 바이트)와 파일명을 포함한 객체입니다.
- fileByte필수string
  첨부 이미지 파일을 Base64 형식으로 인코딩한 문자열입니다.
  
  • 일반적으로 "data:image/png;base64,..." 형식으로 전달됩니다.
  • 실제 파일의 바이너리 데이터를 문자열로 변환한 값
- logicalFileName필수string
  사용자가 업로드한 파일의 원래 파일 이름(논리명)입니다.
  
  • 확장자 포함한 이름을 그대로 전달합니다. (예: parking.png, car.jpg)
  • 허용되는 파일 확장자 목록입니다. (jpeg, jpg, png, pdf, webp)

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
400Error
- codestring
  결과 코드
- messagestring
  결과 메세지
404예약 정보를 찾을 수 없음
- codestring
  결과 코드
- messagestring
  결과 메세지
409Error
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Request Body

Response Example

200OK

• 해당 예약을 배차출발 상태로 변경합니다.

• 예약 상태가 예약완료 상태에서만 변경 가능합니다.

• 배차 담당 직원을 지정합니다.

• 카플랫 계정(account)은 필수 입력 값입니다.

• 존재하지 않는 직원 계정으로는 등록할 수 없습니다.

Tags:Rest API

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 예약 ID

Request Body

account필수string
담당자 계정 (직원 계정)

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
400Bad Request
- codestring
  결과 코드
- messagestring
  결과 메세지
404정보를 찾을 수 없음
- codestring
  결과 코드
- messagestring
  결과 메세지
409변경 불가능한 상태
- codestring
  결과 코드
- messagestring
  결과 메세지
503시스템 오류
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Request Body

Response Example

200OK

• 반납완료 상태에서만 등록 가능합니다.
• 1장당 10mb 이하의 파일만 업로드 가능합니다.
• 최대 20장까지 등록 가능합니다.

Tags:Rest API

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 조회할 예약 ID

Request Body

carImages필수array<object>(minItems: 1, maxItems: 20)
등록할 차량 이미지 리스트
Array items:
- imageSubType필수string (enum)
  • 이미지 유형
  
  E : 기타(추가 촬영 이미지)
  
  • 업로드 규칙
  
  회수(Recall) 차량 이미지 업로드는 E 유형만 허용됩니다.
  (F, R, B, L 유형은 회수 이미지로 등록할 수 없습니다.)
  
  가능한 값: E
- attachFile필수object
  첨부할 이미지 파일 정보입니다. 파일 자체의 데이터(base64 인코딩된 바이트)와 파일명을 포함한 객체입니다.
  - fileByte필수string
    첨부 이미지 파일을 Base64 형식으로 인코딩한 문자열입니다.
    
    • 일반적으로 "data:image/png;base64,..." 형식으로 전달됩니다.
    • 실제 파일의 바이너리 데이터를 문자열로 변환한 값
  - logicalFileName필수string
    사용자가 업로드한 파일의 원래 파일 이름(논리명)입니다.
    
    • 확장자 포함한 이름을 그대로 전달합니다. (예: parking.png, car.jpg)
    • 허용되는 파일 확장자 목록입니다. (jpeg, jpg, png, pdf, webp)

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
400Error
- codestring
  결과 코드
- messagestring
  결과 메세지
404예약 정보를 찾을 수 없음
- codestring
  결과 코드
- messagestring
  결과 메세지
409Error
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Request Body

Response Example

200OK

• 해당 예약을 회수완료 상태로 변경합니다.

• 예약 상태가 반납완료 상태에서만 변경 가능합니다.

• 차량 회수 담당 직원을 지정합니다.

• 카플랫 계정(account)은 필수 입력값입니다.

• 존재하지 않는 직원 계정으로는 등록할 수 없습니다.

• 해당 예약 건에 발급 된 공유 스마트키(회수)는 사용 중지됩니다.

Tags:Rest API

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 예약 ID

Request Body

account필수string
담당자 계정 (직원 계정)

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
404예약 정보를 찾을 수 없음
- codestring
  결과 코드
- messagestring
  결과 메세지
409변경 불가능한 상태
- codestring
  결과 코드
- messagestring
  결과 메세지
503시스템 오류
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Request Body

Response Example

200OK

• 새로운 스케줄을 등록합니다.
• 스케줄 시작 일시는 현재 시점을 기준으로 최대 7일 전까지만 설정할 수 있습니다.
• 시작 일시는 종료 일시보다 이후가 될 수 없습니다.
• 스케줄 기간은 최소 30분 이상이어야 합니다.

Tags:Rest API

Request Body

새로운 스케줄 정보

startDateTimeStr필수string
스케줄 시작일시(yyyy-MM-dd HH:mm 형식)
endDateTimeStr필수string
스케줄 종료일시(yyyy-MM-dd HH:mm 형식)
reason필수string
사유

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
400Error
- codestring
  결과 코드
- messagestring
  결과 메세지
404Error
- codestring
  결과 코드
- messagestring
  결과 메세지
409Error
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Request Body

Response Example

200OK

• 지정된 스케줄 ID에 해당하는 스케줄 정보를 수정합니다.
• 스케줄 시작 일시는 현재 시점을 기준으로 최대 7일 전까지만 설정할 수 있습니다.
• 시작 일시는 종료 일시보다 이후가 될 수 없습니다.
• 스케줄 기간은 최소 30분 이상이어야 합니다.

Tags:Rest API

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 스케줄 ID

Request Body

수정대상 스케줄 정보

startDateTimeStr필수string
스케줄 시작일시(yyyy-MM-dd HH:mm 형식)
endDateTimeStr필수string
스케줄 종료일시(yyyy-MM-dd HH:mm 형식)
reason필수string
사유

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
400Error
- codestring
  결과 코드
- messagestring
  결과 메세지
404Error
- codestring
  결과 코드
- messagestring
  결과 메세지
409Error
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Request Body

Response Example

200OK

• 지정된 스케줄 ID에 해당하는 스케줄을 삭제합니다.
• 삭제 처리 후에는 해당 스케줄 정보와 연관된 데이터가 더 이상 조회되지 않습니다.

Tags:Rest API

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 스케줄 ID

200OK
- codestring
  결과 코드
- messagestring
  결과 메세지
404Error
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Response Example

200OK

Callback Events

⚠️ 이 섹션의 API들은 테스트할 수 없습니다.

서버에서 예약 상태 변경등의 정보를 자동으로 클라이언트에서 전달하는 이벤트 입니다.

해당 이벤트의 URL은 Carplat 에서 연동 신청 시 등록한 콜백 URL과 연결되어 정보가 전송됩니다.

4개의 API 엔드포인트

서버 → 클라이언트 Webhook 이벤트
• 예약이 생성되었을 때 발생합니다.
• 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 예약 정보를 수신해야 합니다.

Tags:Callback Events

Request Body

id필수integer
예약 ID
serviceId필수integer
서비스 ID. 현재는 비대면렌트(1) 고정으로 전달됩니다.
reservationStatus필수integer
예약 상태 코드(예약 등록시에는 예약완료("5") 고정, 예약 수정시에는 모든 스테이터스가 전달 가능)

5: 예약완료

10: 배차출발

15: 배차완료

20: 이용 중

30: 반납완료

35: 회수완료

40: 예약취소

45: 노쇼취소

50: 예약실패(시스템취소)
carId필수integer
차량 ID
carNumber필수string
차량 번호
companyId필수integer
업체 ID
companyName필수string
업체명
reservationCreateDateTime필수string
예약 생성 일시(yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
reservationStartDateTime필수string
예약 시작 일시(yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
reservationEndDateTime필수string
예약 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
driveStartDateTimestring
운행 시작 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
driveEndDateTimestring
운행 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
pickUpAddress필수string
픽업 주소
driverName필수string
운전자 이름
driverBirthDate필수string
운전자 생년월일 (YYYYMMDD)
driverPhone필수string
운전자 전화번호("-" 없이 등록)
driverLicenseNumber필수string
운전자 면허번호
driverAddress필수string
운전자 주소
pickUpMemostring
픽업 메모
parkingMemostring
주차 메모
parkingImagePathstring
주차 이미지 경로 URL

200이벤트를 성공적으로 수신했음을 알립니다.
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Request Body

Response Example

200이벤트를 성공적으로 수신했음을 알립니다.

서버 → 클라이언트 Webhook 이벤트
• 예약 정보가 변경되었을 때 발생합니다.
• 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 예약 변경 정보를 수신해야 합니다.
• 연동 신청 시 등록한 콜백 URL로 전송됩니다.

Tags:Callback Events

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 예약 ID

Request Body

id필수integer
예약 ID
serviceId필수integer
서비스 ID. 현재는 비대면렌트(1) 고정으로 전달됩니다.
reservationStatus필수integer
예약 상태 코드(예약 등록시에는 예약완료("5") 고정, 예약 수정시에는 모든 스테이터스가 전달 가능)

5: 예약완료

10: 배차출발

15: 배차완료

20: 이용 중

30: 반납완료

35: 회수완료

40: 예약취소

45: 노쇼취소

50: 예약실패(시스템취소)
carId필수integer
차량 ID
carNumber필수string
차량 번호
companyId필수integer
업체 ID
companyName필수string
업체명
reservationCreateDateTime필수string
예약 생성 일시(yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
reservationStartDateTime필수string
예약 시작 일시(yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
reservationEndDateTime필수string
예약 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
driveStartDateTimestring
운행 시작 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
driveEndDateTimestring
운행 종료 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
pickUpAddress필수string
픽업 주소
driverName필수string
운전자 이름
driverBirthDate필수string
운전자 생년월일 (YYYYMMDD)
driverPhone필수string
운전자 전화번호("-" 없이 등록)
driverLicenseNumber필수string
운전자 면허번호
driverAddress필수string
운전자 주소
pickUpMemostring
픽업 메모
parkingMemostring
주차 메모
parkingImagePathstring
주차 이미지 경로 URL

200이벤트를 성공적으로 수신했음을 알립니다.
- codestring
  결과 코드
- messagestring
  결과 메세지

Request Example

URL

Path Parameters

Request Body

Response Example

200이벤트를 성공적으로 수신했음을 알립니다.

서버 → 클라이언트 Webhook 이벤트
• 예약의 차량 정보가 변경되었을 때 발생합니다.
• 차량 변경시 "예약 정보 업데이트 이벤트" 와 해당 이벤트 "예약 차량 변경 이벤트" 가 연속으로 호출되도록 설계되어 있습니다.(신청시)
• 차량 변경시 차량관리에 사용할 경우에만 사용신청을 부탁드립니다.
• 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 차량 변경 정보를 수신해야 합니다.
• 연동 신청 시 등록한 콜백 URL로 전송됩니다.

Tags:Callback Events

Path Parameters

이름	타입	설명
id	integer	int64 예시: `1` 예약 ID

200이벤트를 성공적으로 수신했음을 알립니다.
- idinteger
  예약 ID
- beforeCarIdinteger
  변경 전 차량 ID
- beforeCarNumberstring
  변경 전 차량 번호
- updateCarIdinteger
  변경 후 차량 ID
- updateCarNumberstring
  변경 후 차량 번호

Request Example

URL

Path Parameters

Response Example

200이벤트를 성공적으로 수신했음을 알립니다.

서버 → 클라이언트 Webhook 이벤트
• 차량의 하이패스 통행 내역이 발생했을 때 전송됩니다.
• 클라이언트는 이 엔드포인트를 구현하여 Carplat으로부터 하이패스 통행 정보를 수신해야 합니다.
• 연동 신청 시 등록한 콜백 URL로 전송됩니다.

Tags:Callback Events

Request Body

carId필수integer
차량 ID
carNumber필수string
차량 번호
amount필수integer
통행료 (원)
transactedDateTime필수string
통행 일시 (yyyy-MM-dd'T'HH:mm:ss.SSSZ 형식)
commentstring
통행 정보 메모. 투루카 연동일 경우 사용. "서비스명(#예약번호)"

200이벤트를 성공적으로 수신했음을 알립니다.
- codestring
  결과 코드
- messagestring
  결과 메세지

Rest API

Request

Path Parameters

Responses

Responses

200OK

404예약 정보를 찾을 수 없음

409변경 불가능한 상태

503시스템 오류

Request Example

Path Parameters

Response Example

Request

Path Parameters

Request Body

Responses

Responses

200OK

400Error

404예약 정보를 찾을 수 없음

409Error

Request Example

Path Parameters

Request Body

Response Example

Request

Path Parameters

Request Body

Responses

Responses

200OK

400Bad Request

404예약 정보를 찾을 수 없음

409변경 불가능한 상태

503시스템 오류

Request Example

Path Parameters

Request Body

Response Example

Request

Path Parameters

Request Body

Responses

Responses

200OK

400Error

404예약 정보를 찾을 수 없음

409Error

Request Example

Path Parameters

Request Body

Response Example

Request

Path Parameters

Request Body

Responses

Responses

200OK

400Bad Request

404정보를 찾을 수 없음

409변경 불가능한 상태

503시스템 오류

Request Example

Path Parameters

Request Body

Response Example

Request

Path Parameters

Request Body

Responses

Responses

200OK

400Error

404예약 정보를 찾을 수 없음

409Error

Request Example

Path Parameters

Request Body

Response Example

Request