요청 및 응답 형식
카플랫 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 연동 관리에서 키 재발급을 신청해주세요.
Loading...
요청 예시
Loading...
Loading...
응답 본문
응답 본문은 서버가 클라이언트에 보내는 데이터입니다. 카플랫 API의 성공 여부는 HTTP 상태 코드로 전달합니다. 돌아온 HTTP 상태 코드에 따라 요청이나 에러를 처리하는 로직을 구축하세요.
모든 API 응답, 요청 본문은 JSON 형식입니다. 따라서 응답 헤더에는 다음과 같이 Content-Type이 포함됩니다.
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는 일관된 응답 구조를 제공합니다. 모든 성공 응답은 다음과 같은 기본 구조를 따릅니다.
Loading...
스케줄 등록처럼 처리 결과로 돌려줄 데이터가 있는 API는 result 필드에 결과를 담아 응답합니다.
Loading...
에러 응답 객체
요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다. API별 에러 코드와 메시지는 에러 코드 페이지에서 살펴보세요.
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:mm | 2025-09-11 09:00 |
| 생년월일 | YYYYMMDD | 19900101 |
Loading...
시간대 (Timezone)
콜백 이벤트의 날짜시간에는 +09:00 오프셋이 포함되어 있으므로, 오프셋을 인식하는 파서로 읽으면 시간대 변환 없이 정확한 시각을 얻을 수 있습니다. 스케줄 등록·수정 요청의 yyyy-MM-dd HH:mm 값에는 오프셋이 없으므로 한국 표준시 기준으로 보내주세요.
Loading...
Loading...
유의사항
API 응답 변경 정책
API 응답에 새로운 필드가 추가되는 것과 같이 하위 호환을 지원하는 변경 사항은 버전 릴리즈 없이 기존 API에 반영됩니다. 클라이언트 코드는 이러한 변경에 유연하게 대응할 수 있도록 작성해 주세요.
JSON 파싱 권장사항
추가된 새로운 필드를 무시하거나 기본값을 설정하는 방식으로 JSON 파싱 로직을 구성해 주세요.
Loading...
Loading...
요청 제한
- Rate Limiting: 분당 최대 1000회 요청
- Timeout: 요청 타임아웃은 30초
- Payload Size: 요청 본문 최대 크기는 10MB
보안 고려사항
- API KEY는 안전한 곳에 저장하세요
- HTTPS를 통해서만 API를 호출하세요
- 민감한 정보를 URL 파라미터에 포함하지 마세요