이 문서는 카카오 API 플랫폼에서 제공하는 REST API의 규격 정보를 안내합니다.
카카오 플랫폼의 API 요청 규격을 구성하는 요소는 아래와 같습니다.
구성 요소 | 설명 |
---|---|
메서드(Method) | 카카오 API 호출 시 사용해야 할 HTTP 요청 메서드입니다. (예: GET , POST , PUT , DELETE ) |
호스트(Host) | 요청을 받는 카카오 API 서버의 도메인입니다. (예: kapi.kakao.com ) |
URL | API로 제공하는 리소스마다 지정된 요청 경로입니다. 호스트와 함께 각 API의 엔드포인트(Endpoint)를 구성합니다. (예: /v2/user/me ) |
헤더(Header) | 카카오 API 호출 시 필요한 인증 정보(Authorization)나 기타 추가 정보를 전달하는 데 사용합니다. 인증 정보는 액세스 토큰 또는 앱 키를 사용합니다. 일부 카카오모먼트 API는 인증 정보와 함께 광고계정 ID를 헤더에 포함하여 호출해야 합니다. (예: Authorization: Bearer ${ACCESS_TOKEN} ) |
경로 변수(Path variable) | 카카오 API 호출 시, 사용자가 전달한 값을 포함해 URL을 구성할 때 사용합니다. 카카오모먼트 등 일부 카카오 API는 URL에 경로 변수를 포함합니다. (예: /openapi/v4/campaigns/${id} ) |
파라미터(Parameter) | 요청 처리에 필요한 데이터를 전달하는 데 사용합니다. 파라미터는 키와 값의 쌍으로 구성되며, 쿼리 문자열(Query string) 또는 본문으로 전달합니다. 각 파라미터는 자료형(Data type)과 필수 전달 여부가 지정돼 있습니다. |
각 API의 요청 규격이 다르므로, API별 개발 문서에서 상세 정보를 확인하고 호출해야 합니다. 요구 사양을 함께 참고합니다.
서비스의 필요에 따라 보안 강화 요소로 허용 IP 주소나 클라이언트 시크릿(Client Secret) 설정을 사용할 수 있습니다.
카카오 플랫폼은 API 요청에 대해 응답 코드와 응답 필드로 구성된 응답을 제공합니다. 응답 필드는 각 API의 호스트 및 요청 성공 여부에 따라 구성이 다릅니다.
JSON
형식의 에러 응답 필드 반환, 에러 응답 필드에 에러 코드 및 메시지 포함아래는 주요 호스트의 에러 응답 필드 구성 및 예시입니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
error | String |
에러 코드 에러 코드에서 상세 정보 확인 가능 |
X |
error_description | String |
실패 원인을 나타내는 에러 메시지 에러 원인에 대한 참고 정보로써 변경될 수 있으므로, 예외 처리 시에는 에러 코드를 사용해야 함 |
X |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
code | Int |
에러 코드 | X |
msg | String |
에러 메시지 에러 원인에 대한 참고 정보로써 변경될 수 있으므로, 예외 처리 시에는 에러 코드를 사용해야 함 |
X |
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error=invalid_token
{
"code":-401,
"msg":"InvalidTokenException"
}
HTTP/1.1 400 Bad Request
{
"code":-10,
"msg":"API limit has been exceeded."
}
HTTP/1.1 403 Forbidden
{
"msg": "insufficient scopes.",
"code": -402,
"api_type": "TALK_MEMO_DEFAULT_SEND",
"required_scopes": [
"talk_message"
],
"allowed_scopes": [
"profile",
"account_email"
]
}
code
는 특별한 규칙을 가지고 있지 않은 음수의 숫자이고, 실패 원인을 나타내는 msg
는 요청에 따라 의미가 바뀌지 않는 범위에서 내용이 바뀔 수 있습니다. 예를 들어, code
가 -401일 경우 전달되는 msg
의 내용은 아래와 같이 다양하게 전달됩니다.
"this access token does not exist", "this access token is already expired", "appKey(xxxxxxxx) is already deactivated"
"domain mismatched! caller=xxxxxxxx. check out registered web domains."
"android keyhash mismatched! caller=xxxxxxxx. check out registered keyhash."
"ios bundle id mismatched! caller=xxxxxxxx. check out registered bundle id."
"ip mismatched! callerIp=xxxxxxxx. check out registered ips."
응답 코드는 요청에 대한 상태를 나타내는 HTTP 상태 코드(Status code), 에러에 대한 정보를 담은 에러 코드(Error code)로 나뉩니다. 요청 성공 시 HTTP 상태 코드 200과 함께 요청에 대한 응답 본문(response body)이 반환되고, 요청이 실패한 경우 code
와 msg
로 이루어진 에러 코드를 반환합니다.
HTTP 상태 코드(HTTP Status code)란 응답 메시지의 첫 번째 줄에 나타나는 세 자리 숫자의 코드로 요청에 대한 상태 정보(성공 또는 실패)를 나타냅니다. 상태 코드는 크게 5가지로 분류되며, 상태 코드의 첫 번째 숫자로 응답의 종류를 파악할 수 있습니다. 자세한 정보는 RFC 2616을 참고합니다.
아래는 카카오 플랫폼이 API 요청에 대해 응답하는 상태 코드의 종류와 의미입니다.
상태 코드 | 상태 | 설명 |
---|---|---|
200 OK |
성공 | 서버가 클라이언트의 요청을 성공적으로 수행 응답 본문의 경우 각 API별로 응답 본문의 형식이 다를 수 있으므로, 자세한 내용은 각 API별 상세 설명을 참고합니다. |
400 Bad Request |
실패 | 일반적인 오류 주로 API에 필요한 필수 파라미터와 관련하여 서버가 클라이언트 오류를 감지해 요청을 처리하지 못한 상태입니다. |
401 Unauthorized |
실패 | 인증 오류(주로 토큰 관련) 해당 리소스에 유효한 인증 자격 증명이 없어 요청에 실패한 상태입니다. 응답은 OAuth 2.0 RFC6750 표준 규격에 따라 헤더에 오류 정보를 포함합니다. 토큰 사용 시: WWW-Authenticate: Bearer error=invalid_token 서비스 앱 어드민 키 사용 시: WWW-Authenticate: KakaoAK error=invalid_token 상세 오류 정보는 응답 본문에서 확인할 수 있습니다. |
403 Forbidden |
실패 | 권한 오류 서버에 요청이 전달되었지만, 권한 때문에 거절된 상태입니다. |
429 Too Many Request |
실패 | 쿼터 초과(Daum 검색, 로컬, 모먼트, 키워드광고 API에만 해당) 정해진 사용량이나 초당 요청 한도를 초과한 경우 |
500 Internal Server Error |
실패 | 시스템 오류 서버 에러를 총칭하는 에러 코드로, 요청을 처리하는 과정에서 서버가 예상하지 못한 상황에 놓인 상태입니다. |
502 Bad Gateway |
실패 | 시스템 오류 서로 다른 프로토콜을 연결해주는 게이트웨이가 잘못된 프로토콜을 연결하거나 연결된 프로토콜에 문제가 있어 통신이 제대로 되지 않은 상태입니다. |
503 Service Unavailable |
실패 | 서비스 점검중 서버가 요청을 처리할 준비가 되지 않은 상태입니다. |
에러 코드를 참고합니다.
카카오 플랫폼에서 REST API로 제공하는 API 목록과 기본적인 요청 규격 정보입니다.
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/oauth/authorize | https://kauth.kakao.com |
GET | 인가 코드 요청 동의항목 추가 동의 요청 서비스 약관 선택해 동의 요청 카카오톡에서 자동 로그인 |
/oauth/token | https://kauth.kakao.com |
POST | 토큰 요청, 토큰 갱신 |
/.well-known/openid-configuration | https://kauth.kakao.com |
GET | OIDC: 메타데이터 조회 |
/.well-known/jwks.json | https://kauth.kakao.com |
GET | OIDC: 공개키 목록 조회 |
/oauth/tokeninfo | https://kauth.kakao.com |
POST | OIDC: ID 토큰 정보 조회 |
/v1/user/logout | https://kapi.kakao.com |
POST | 로그아웃 |
/v1/user/signup | https://kapi.kakao.com |
POST | 수동 연결 |
/v1/user/unlink | https://kapi.kakao.com |
POST | 연결 해제 |
/v1/user/access_token_info | https://kapi.kakao.com |
GET | 액세스 토큰 정보 조회 |
/v2/user/me | https://kapi.kakao.com |
GET/POST | 사용자 정보 조회 |
/v1/user/update_profile | https://kapi.kakao.com |
POST | 사용자 프로퍼티 저장 |
/v1/user/shipping_address | https://kapi.kakao.com |
GET | 배송지 조회 |
/v1/user/ids | https://kapi.kakao.com |
GET/POST | 사용자 목록 조회 |
/v2/app/users | https://kapi.kakao.com |
GET | 여러 사용자 정보 조회 |
/v2/user/scopes | https://kapi.kakao.com |
GET | 동의항목 동의 내역 조회 |
/v2/user/revoke/scopes | https://kapi.kakao.com |
POST | 동의항목 동의 철회 |
/v2/user/service_terms | https://kapi.kakao.com |
GET | 서비스 약관 동의 내역 조회 |
/v2/user/revoke/service_terms | https://kapi.kakao.com |
POST | 서비스 약관 동의 철회 |
/v2/user/upgrade/service_terms | https://kapi.kakao.com |
POST | 서비스 약관에 동의 |
/v1/oidc/userinfo | https://kapi.kakao.com |
GET | OIDC: 사용자 정보 조회 |
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/v1/api/talk/profile | https://kapi.kakao.com |
GET | 카카오톡 프로필 조회 |
/v1/api/talk/friends | https://kapi.kakao.com |
GET | 카카오톡 친구 목록 조회 |
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/v2/api/talk/memo/default/send | https://kapi.kakao.com |
POST | 나에게 기본 템플릿으로 메시지 발송 |
/v2/api/talk/memo/send | https://kapi.kakao.com |
POST | 나에게 사용자 정의 템플릿으로 메시지 발송 |
/v2/api/talk/memo/scrap/send | https://kapi.kakao.com |
POST | 나에게 스크랩 메시지 발송 |
/v1/api/talk/friends/message/default/send | https://kapi.kakao.com |
POST | 기본 템플릿으로 메시지 발송 |
/v1/api/talk/friends/message/send | https://kapi.kakao.com |
POST | 사용자 정의 템플릿으로 메시지 발송 |
/v1/api/talk/friends/message/scrap/send | https://kapi.kakao.com |
POST | 스크랩 메시지 발송 |
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/v2/api/talk/channels | https://kapi.kakao.com |
GET | 카카오톡 채널 관계 조회 |
/v2/api/talk/channels/multi | https://kapi.kakao.com |
GET | 여러 사용자 카카오톡 채널 관계 조회 |
/v1/talkchannel/create/target_user_file | https://kapi.kakao.com |
POST | 고객 관리: 고객파일 등록 |
/v1/talkchannel/target_user_file | https://kapi.kakao.com |
GET | 고객 관리: 고객파일 조회 |
/v1/talkchannel/update/target_users | https://kapi.kakao.com |
POST | 고객 관리: 고객파일에 사용자 추가 |
/v1/talkchannel/delete/target_users | https://kapi.kakao.com |
POST | 고객 관리: 고객파일의 사용자 삭제 |
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/oauth/business/authorize | https://kauth.kakao.com |
GET | 비즈니스 인가 코드 요청 |
/oauth/business/token | https://kauth.kakao.com |
POST | 비즈니스 토큰 요청 |
/oauth/business/tokeninfo | https://kauth.kakao.com |
GET | 비즈니스 토큰 정보 조회 |
/oauth/business/userinfo | https://kauth.kakao.com |
GET | 비즈니스 사용자 정보 조회 |
/oauth/business/revoke | https://kauth.kakao.com |
POST | 비즈니스 토큰 발급 철회 |
카카오모먼트 API 레퍼런스를 참고합니다.
카카오 키워드광고 API 레퍼런스를 참고합니다.
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/v2/push/register | https://kapi.kakao.com |
POST | 푸시 토큰 등록 |
/v2/push/tokens | https://kapi.kakao.com |
GET | 푸시 토큰 조회 |
/v2/push/deregister | https://kapi.kakao.com |
POST | 푸시 토큰 폐기 |
/v2/push/send | https://kapi.kakao.com |
POST | 푸시 알림 발송 |
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/v2/api/calendar/calendars | https://kapi.kakao.com |
GET | 사용자 캘린더 > 목록 조회 |
/v2/api/calendar/create/calendar | https://kapi.kakao.com |
POST | 사용자 캘린더 > 서브 캘린더 생성 |
/v2/api/calendar/update/calendar | https://kapi.kakao.com |
POST | 사용자 캘린더 > 서브 캘린더 수정 |
/v2/api/calendar/delete/calendar | https://kapi.kakao.com |
DELETE | 사용자 캘린더 > 서브 캘린더 삭제 |
/v2/api/calendar/create/event | https://kapi.kakao.com |
POST | 일반 일정 > 생성 |
/v2/api/calendar/events | https://kapi.kakao.com |
GET | 일반 일정 > 목록 조회 |
/v2/api/calendar/event | https://kapi.kakao.com |
GET | 일반 일정 > 상세 조회 |
/v2/api/calendar/update/event/host | https://kapi.kakao.com |
POST | 일반 일정 > 수정 |
/v2/api/calendar/delete/event | https://kapi.kakao.com |
DELETE | 일반 일정 > 삭제 |
/v2/api/calendar/public/create/event | https://kapi.kakao.com |
POST | 공개 일정 > 생성 |
/v2/api/calendar/public/events | https://kapi.kakao.com |
GET | 공개 일정 > 목록 조회 |
/v2/api/calendar/public/event | https://kapi.kakao.com |
GET | 공개 일정 > 상세 조회 |
/v2/api/calendar/public/update/event | https://kapi.kakao.com |
POST | 공개 일정 > 수정 |
/v2/api/calendar/public/delete/event | https://kapi.kakao.com |
DELETE | 공개 일정 > 삭제 |
/v2/api/calendar/public/follow | https://kapi.kakao.com |
POST | 공개 일정 > 사용자 캘린더에 추가 |
/v2/api/calendar/subscribable/calendars | https://kapi.kakao.com |
GET | 구독 캘린더 > 구독 가능 캘린더 목록 조회 |
/v2/api/calendar/subscribe | https://kapi.kakao.com |
POST | 구독 캘린더 > 구독 |
/v2/api/calendar/unsubscribe | https://kapi.kakao.com |
DELETE | 구독 캘린더 > 구독 해제 |
/v2/api/calendar/update/event/guest | https://kapi.kakao.com |
POST | 게스트 일정 > 수정 |
/v2/api/calendar/holidays | https://kapi.kakao.com |
GET | 공휴일 및 주요 기념일 조회 |
/v1/api/calendar/create/task | https://kapi.kakao.com |
POST | 할 일 > 생성 |
/v1/api/calendar/tasks | https://kapi.kakao.com |
GET | 할 일 > 조회 |
/v1/api/calendar/task/records | https://kapi.kakao.com |
GET | 할 일 > 도전 기록 조회 |
/v1/api/calendar/update/task | https://kapi.kakao.com |
POST | 할 일 > 수정 |
/v1/api/calendar/complete/task | https://kapi.kakao.com |
POST | 할 일 > 완료 여부 설정 |
/v1/api/calendar/delete/task | https://kapi.kakao.com |
DELETE | 할 일 > 삭제 |
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/v2/local/search/address.{format} |
https://dapi.kakao.com |
GET | 주소로 좌표 변환 |
/v2/local/geo/coord2regioncode.{format} |
https://dapi.kakao.com |
GET | 좌표로 행정구역정보 변환 |
/v2/local/geo/coord2address.{format} |
https://dapi.kakao.com |
GET | 좌표로 주소 변환 |
/v2/local/geo/transcoord.{format} |
https://dapi.kakao.com |
GET | 좌표계 변환 |
/v2/local/search/keyword.{format} |
https://dapi.kakao.com |
GET | 키워드로 장소 검색 |
/v2/local/search/category.{format} |
https://dapi.kakao.com |
GET | 카테고리로 장소 검색 |
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/v2/search/web | https://dapi.kakao.com |
GET | 웹문서 검색 |
/v2/search/vclip | https://dapi.kakao.com |
GET | 동영상 검색 |
/v2/search/image | https://dapi.kakao.com |
GET | 이미지 검색 |
/v2/search/blog | https://dapi.kakao.com |
GET | 블로그 검색 |
/v3/search/book | https://dapi.kakao.com |
GET | 책 검색 |
/v2/search/cafe | https://dapi.kakao.com |
GET | 카페 검색 |
URL | 호스트 | 메서드 | 기능 |
---|---|---|---|
/v1/system/ips | kapi.kakao.com |
GET | 카카오 IP 목록 조회 |
/api/health/current | api-status.kakao.com |
GET | 현재 상태 조회 |
api/health/history | api-status.kakao.com |
GET | 이력 조회 |