요청 및 응답 형식

카플랫 API와 통신할 때 사용하는 요청과 응답 형식을 설명합니다. 이 문서를 통해 API 요청을 올바르게 구성하고 응답을 정확하게 해석할 수 있습니다.

요청 본문

요청 본문은 클라이언트가 카플랫 API를 호출할 때 보내는 데이터입니다. 카플랫 API에 요청할 때는 JSON 형식을 사용하세요.

모든 API 요청에는 발급한 API Key를 헤더에 포함해야 합니다.
API KEY는, 카플랫 API 연동 관리에서 확인할 수 있습니다.

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

http

전체 요청 본문을 인코딩할 필요는 없습니다. 특수 문자가 요청 본문이나 쿼리 파라미터 값에 포함되어 있다면 URL 인코딩을 해야 합니다. 데이터를 안전하게 전송하고, 서버에서 정확하게 해석되도록 하는 중요한 단계입니다.

URL 인코딩은 웹에서 안전하게 데이터를 전송하기 위해 특정 문자를 % 기호와 두 개의 16진수 숫자로 변환하는 과정입니다.

javascript

http

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

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

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	카플랫 서버에서 에러가 발생했습니다.