구현 API 목록

카카오 i 서비스 시스템이 고객사 정보에 접근할 수 있도록 고객사가 구현하는 Adapter Agent API와 카카오 i에서 제공하는 Adapter API로 구분됩니다.

안내
API별 작업 흐름과 개발 프로세스에 대한 자세한 설명은 카카오 i 계정 개발 프로세스 문서를 참고하시기 바랍니다.

API 공통 가이드

API Request

API 호출 방식

Adapter Agent API와 Adapter API의 호출 방식은 application/json만 허용하며, 파라미터 전달은 아래의 방식을 따릅니다.

API Response

공통 상태 코드

응답 상태 코드는 API 호출에 대한 실행결과를 의미합니다. 아래의 상태 코드만 응답하고 있으며, 표현되지 않는 응답 상태 코드는 Response Body의 _code 필드에 표현합니다.

공통 Response

Response Body에는 아래의 필드가 항상 포함됩니다.

코드예제요청 헤더의 필수값이 누락된 경우(HTTP 상태 코드: 400)

{
  "_code": 400,
  "_message": "Kep-OrgLoginType is not present."
}

코드예제예기치 못한 오류가 발생한 경우(HTTP 상태 코드: 500)

{
  "_code": 500,
  "_message": "Internal server error"
}

코드예제Adapter Agent 서버가 점검 중인 경우(HTTP 상태 코드: 503)

{
  "_code": 503,
  "_message": "Service unavailable"
}

안내
응답 상태 코드와 Response Body의 _code는 각각 다음과 같은 의미로 활용되며, 일반적으로 같은 값으로 설정되어 있지만 경우에 따라 다르게 세팅해야 할 수도 있습니다.

• 응답 상태 코드: API 호출의 결과 상태 코드
• _code: API의 비즈니스 로직 수행 결과 코드

필드 타입 표기

Adapter API 와 Adapter Agent API의 요청과 응답은 기본적으로 JSON 타입을 따르며, 추가로 확장된 타입은 아래 표 | 필드 타입 표기를 따릅니다.

Adapter Agent API

다음은 고객사에서 구현해야 하는 Adapter Agent API의 공통 사항입니다.

API URL

Adapter Agent API URL 구조는 아래와 같습니다.

코드예제Adapter Agent API URL 구조

/api/{capability}/{version}/{API name}

Request

ACL 관리

Adapter 서버는 자신의 ACL(Access Control List)에 IP 주소가 등록되어 있는 Adapter Agent API 서버만 호출합니다. 따라서 Adapter Agent 서버 개발 시 Adapter Agent 서버의 공인 IP 목록을 카카오 i 계정 관리자 사이트의 계정연동설정 > OAuth 2.0 메뉴에서 Adapter 호출 정보 설정 항목에 입력해야 합니다. 또한, Adapter 서버는 AdapterAgent 서버의 포트 번호를 80과 443만 허용하고 있습니다. 80과 443 이외의 포트 번호로 AdapterAgent 서버를 구축하셔야 한다면 디케이테크인의 담당자에게 문의해주시기 바랍니다.

Adapter Agent 서버에서도 Adapter의 서버 주소를 ACL에 등록하여 관리할 수 있습니다.

안내
Adapter 서버에서 고객사 서버에 구현된 Adapter Agent API를 호출할 경우에 Default Timeout은 5초(5,000ms)입니다.

Adapter API

카카오 i 서비스 시스템에서 제공하는 Adapter API의 공통 사항입니다.

서버 도메인

Adapter API를 호출하기 위한 서버 도메인을 선택해야 하며, 서버 도메인은 https만 가능합니다.

API URL

Adapter API URL 구조는 아래와 같습니다.

코드예제API URL 구조

/api/trust/{capability}/{version}/{API name}

API 인증

Adapter API는 카카오 i 계정 관리자의 계정 연동 설정 화면에서 생성한 Secret Key와 Adapter Agent 서버의 공인 IP 기반 인증을 수행합니다. Adapter 서버는 HTTP 헤더를 통해 Secret Key와 OrgLoginTypeId를 입력받고, 카카오 i 계정 관리자 사이트에 입력된 Adapter Agent 서버의 공인 IP 주소를 확인하여 해당 요청이 어떤 Adapter Agent 서버가 보낸 요청인지 식별하고 인증을 수행합니다.

이러한 인증을 통과하기 위해 HTTP 요청의 Authorization 헤더에 생성한 Secret Key를 설정하고, Kep-OrgLoginType 헤더에 Adapter Agent API 요청으로 전달된 OrgLoginTypeId를 설정합니다. 그리고 카카오 i 계정 관리자의 계정 연동 설정 메뉴에서 Adapter Agent 서버의 공인 IP 주소를 입력합니다.

코드예제Curl 요청

  curl -X GET 'http://adapter.cbt.kakaoi.ai/api/trust/login/v0/getOrgLoginType' \
    --header 'Authorization: KAASK {YOUR_SECRET_KEY}' \
    --header 'Kep-OrgLoginType: ID {YOUR_ORG_LOGIN_TYPE_ID}' \

Request

Adapter API 호출 시 다음의 공통 Request Header가 필요합니다.

관련 문서

Adapter Agent Kakao i Account 개발 프로세스 Kakao i Account API 레퍼런스 Kakao i Account 카카오 i 계정 관리자 Kakao i Account