사용자 정보 API 개발

고객사의 계정 정보를 카카오 i 계정 서버에 동기화하고, 사용자 정보 메타데이터 및 동기화 관련 옵션을 카카오 i 계정 관리자 사이트에서 제어하기 위해 Adapter Agent API의 User Capability를 구현해야 합니다.

사용자 정보 동기화

고객사의 계정 정보를 카카오 i 계정 서버의 계정 정보에 동기화하기 위해 getValidUsers API 또는 getChangedUsers API를 구현해야 합니다. 사용자 정보 동기화는 카카오 i의 Adapter 서버에서 주기적으로 Adapter Agent API를 호출하는 방식으로 이루어집니다.

안내
사용자 정보 동기화 시, 카카오 i 계정 서버에 고객사의 계정 정보를 단방향으로만 동기화하여 업데이트만 가능합니다.

카카오 i 서비스 시스템이 사용자 정보 동기화 API를 호출하는 시점은 다음과 같습니다.

• getValidUsers API: 최초 동기화 실행 시 또는 그 외 특정 시점의 전체 사용자 목록이 필요한 경우
• getChangedUsers API: 설정된 동기화 주기에 따라 호출(동기화 주기는 카카오 i 계정 관리자 사이트에서 설정 가능)

API 작업 흐름

카카오 i 서비스 시스템에서 getVaildUsers(또는 getChangedUsers) API를 호출하는 작업 흐름은 다음과 같습니다.

그림사용자 정보 동기화 작업 흐름

1. 카카오 i 계정 시스템에서 사용자 동기화가 필요한 시점에 동기화를 실행합니다.

2. 카카오 i 계정 시스템이 getVaildUsers(또는 getChangedUsers) 요청을 Adapter 서버로 전송합니다.

3. Adapter 서버가 Adapter Agent 서버에 구현되어 있는 getValidUsers(또는 getChangedUsers) API를 호출합니다.

4. Adapter Agent 서버가 동기화 대상 사용자 목록을 연동된 계정 시스템에 요청합니다.

getValidUsers 구현

getValidUsers API는 API 호출 시점을 기준으로 카카오 i 서비스 시스템을 사용할 수 있는 사용자 목록(ex. 현재 재직자 목록)을 카카오 i 서비스 시스템에 제공합니다.
이 API는 카카오 i 계정 서버와 고객사의 Adapter Agent 서버가 연동되어 최초로 사용자 동기화를 수행할 경우와 같이 카카오 i 에서 고객사의 활성화된 전체 사용자 목록이 필요할 경우에 사용합니다. 카카오 i 계정 서버는 사용자 목록을 전달받으면 자신의 계정 정보에 정보를 등록 또는 갱신합니다.

Adapter Agent 서버 동작 예제

1. Adapter Agent 서버가 자신과 연동된 계정 시스템에 활성화된 사용자 목록을 요청합니다.

   안내
   카카오 i 계정 관리자 사이트에서 등록한 법인별 정보 또는 인증값이 필요한 경우에는 Adapter API의 getOrgLoginType API를 호출하여 해당 정보를 획득할 수 있습니다.

2. 카카오 i 계정 관리자에 동기화 옵션을 등록한 경우에는 설정값을 획득하기 위해 getOrgLoginType API를 호출합니다.

3. 획득한 동기화 옵션에 따라 사용자 목록을 적절히 필터링합니다.

4. API 레퍼런스의 응답 포맷에 맞춰 사용자 목록을 반환합니다.

getChangedUsers 구현

getChangedUsers API는 특정 시점부터 API 호출 시점까지 정보가 추가, 변경, 비활성화가 발생한 사용자 목록을 제공합니다. 카카오 i 계정 서버는 사용자 목록을 최신 상태로 유지하기 위해 해당 API를 정해진 주기에 따라 호출합니다.

Adapter Agent 서버 동작 예제

1. Adapter Agent 서버가 자신과 연동된 계정 시스템에 특정 시간 이후에 변경이 일어난 사용자 목록을 요청합니다.

   안내
   카카오 i 계정 관리자 사이트에 등록한 법인별 정보 또는 인증값이 필요한 경우 Adapter API의 getOrgLoginType API를 호출해서 정보를 획득할 수 있습니다.

2. 카카오 i 계정 관리자 사이트에 동기화 옵션을 등록한 경우, 설정값을 획득하기 위해 Adapter API의 getOrgLoginType API를 호출합니다.

3. 획득한 동기화 옵션에 따라 사용자 목록을 적절히 필터링합니다.

4. 각 사용자의 상태에 맞춰서 status 필드를 적절히 세팅합니다.

   • status 필드값은 {REGISTERED | UPDATED | DELETED | HARD_DELETE}에서 선택합니다.

5. API 레퍼런스의 응답 포맷에 맞춰 사용자 목록을 반환합니다.

사용자 정보 메타데이터 및 동기화 옵션 제공

카카오 i 서비스는 고객사 사용자 정보의 메타데이터를 필요로 하는 경우, 프로필 정보 변경 화면에서 닉네임은 변경 가능하지만 생일은 변경하지 못하도록 설정해야 합니다. 카카오 i 서비스 시스템에 이러한 사용자 정보 메타데이터를 적절히 제공하기 위해 getUserMetadata API를 구현해야 합니다.

getUserMetadata API의 응답에는 사용자 동기화 옵션 정보가 포함되어 있으며, 카카오 i 서비스 시스템에 해당 정보를 제공함으로써 고객사의 담당자가 카카오 i 계정 관리자 사이트를 통해 동기화 옵션을 조정할 수 있는 기능을 구현할 수 있습니다.

카카오 i 서비스 시스템이 getUserMetadata API를 호출하는 시점은 다음과 같습니다.

• 카카오 i 서비스 내의 사용자 정보 변경 화면 접근 시(사용자 정보 메타데이터)
• 카카오 i 계정 관리자 사이트 접근 시(사용자 동기화 옵션 정보)
• 그 외 사용자 정보 메타데이터 또는 사용자 동기화 옵션 정보가 필요한 경우

API 작업 흐름

카카오 i 서비스 시스템이 getUserMetadata API를 호출하는 작업 흐름은 다음과 같습니다.

그림사용자 메타데이터 제공 흐름

1. 고객사의 관리자가 카카오 i 계정 관리자의 계정 연동 설정 메뉴에 접근합니다.

2. 카카오 i 계정 서버가 계정 연동 설정 화면에 노출할 사용자 메타데이터를 Adapter 서버에 요청합니다.

3. Adapter 서버가 Adapter Agent 서버에 구현되어 있는 getUserMetadata API를 호출합니다.

4. Adapter Agent 서버가 getUserMetadata 응답 스펙에 필요한 사용자 메타정보를 연동된 계정 시스템에 요청합니다.

getUserMetadata 구현

getUserMetadata API 요청을 받았을 때 Adapter Agent 서버의 동작 예제는 다음과 같습니다.

1. Adapter Agent 서버와 연동된 계정 시스템에서 특정 사용자 정보의 메타데이터와 동기화 옵션 정보를 조회합니다.

2. 정보를 적절하게 조합하여 반환합니다.

3. 만약 여러 법인이 하나의 Adapter Agent 서버에서 처리될 경우(ex. 그룹사의 Adapter Agent 서버를 통합하여 구현 시), orgLoginTypeId에 따라 적절히 분기하여 해당하는 법인의 정보만 반환합니다.

getUserMetadata에서 다음과 같이 응답한 경우에는 아래 동기화 옵션 정보가 아래 카카오 i 계정 관리자 화면 예제에서 제공하는 화면과 동일하게 노출됩니다.

코드예제getUserMetadata Response

{
  "_code": 200,
  "_message": "ok",
  "profile": {
    "editability": {
      "name": false,
      "nickname": true,
      "email": false,
      "telephone": true,
      "birthday": false,
      "is_lunar": false,
      "gender": false,
      "photo_url": true
    }
  },
  "synchronize_options": [
    {
      "display_name": "정직원 제외",
      "value": "except_full_time_employee"
    },
    {
      "display_name": "계약 제외",
      "value": "except_contract"
    },
    {
      "display_name": "협력업체 제외",
      "value": "except_subcontract"
    },
    {
      "display_name": "업무용 계정 제외",
      "value": "except_business_account"
    }
  ]
}

카카오 i 계정 관리자 화면 예제

동기화 옵션 정보(synchronize_options 배열)가 카카오 i 계정의 관리자 화면에 다음과 같이 노출됩니다. 이후 카카오 i 계정 관리자 사이트에 접근할 수 있는 고객사의 담당자가 옵션의 활성화 여부에 따라 적절하게 체크박스를 선택할 수 있습니다. 각 항목별 체크 여부는 카카오 i 계정 서버에 저장되며, Adapter API의 getOrgLoginType API를 호출하여 조회할 수 있습니다.

그림카카오 i 계정 관리자 시스템 동기화 옵션

사용자 정보 메타데이터

카카오워크, 카카오클라우드 등의 프로필 정보 설정 화면에 정보 수정 가능 여부가 반영되어 표시됩니다.

안내
API별 상세 레퍼런스는 카카오 i 계정 API 레퍼런스 문서를 참고하시기 바랍니다.