개발자 센터

요청 및 응답 형식

카플랫 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 연동 관리에서 확인할 수 있습니다.

⚠️ 중요: API 키가 노출되었거나 의심되는 경우, 즉시 카플랫 API 연동 관리에서 키 재발급을 신청해주세요.

http

Loading...

요청 예시

http

Loading...

http

Loading...

응답 본문

응답 본문은 서버가 클라이언트에 보내는 데이터입니다. 카플랫 API의 성공 여부는 HTTP 상태 코드로 전달합니다. 돌아온 HTTP 상태 코드에 따라 요청이나 에러를 처리하는 로직을 구축하세요.

모든 API 응답, 요청 본문은 JSON 형식입니다. 따라서 응답 헤더에는 다음과 같이 Content-Type이 포함됩니다.

http

Loading...

응답 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

Loading...

스케줄 등록처럼 처리 결과로 돌려줄 데이터가 있는 API는 result 필드에 결과를 담아 응답합니다.

json

Loading...

에러 응답 객체

요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다. API별 에러 코드와 메시지는 에러 코드 페이지에서 살펴보세요.

json

Loading...

날짜 및 시간 형식

카플랫 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:mm2025-09-11 09:00
생년월일YYYYMMDD19900101
json

Loading...

시간대 (Timezone)

콜백 이벤트의 날짜시간에는 +09:00 오프셋이 포함되어 있으므로, 오프셋을 인식하는 파서로 읽으면 시간대 변환 없이 정확한 시각을 얻을 수 있습니다. 스케줄 등록·수정 요청의 yyyy-MM-dd HH:mm 값에는 오프셋이 없으므로 한국 표준시 기준으로 보내주세요.

javascript

Loading...

java

Loading...

유의사항

API 응답 변경 정책

API 응답에 새로운 필드가 추가되는 것과 같이 하위 호환을 지원하는 변경 사항은 버전 릴리즈 없이 기존 API에 반영됩니다. 클라이언트 코드는 이러한 변경에 유연하게 대응할 수 있도록 작성해 주세요.

JSON 파싱 권장사항

추가된 새로운 필드를 무시하거나 기본값을 설정하는 방식으로 JSON 파싱 로직을 구성해 주세요.

javascript

Loading...

java

Loading...

요청 제한

  • Rate Limiting: 분당 최대 1000회 요청
  • Timeout: 요청 타임아웃은 30초
  • Payload Size: 요청 본문 최대 크기는 10MB

보안 고려사항

  • API KEY는 안전한 곳에 저장하세요
  • HTTPS를 통해서만 API를 호출하세요
  • 민감한 정보를 URL 파라미터에 포함하지 마세요