> For the complete documentation index, see [llms.txt](https://workspace-help.nhn-commerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://workspace-help.nhn-commerce.com/contents/recommended/prm_kakao-sync_login.md).

# \[엔터프라이즈] 카카오싱크 회원가입 API 화면가이드

## 간단소개

* 기능요약
  * 카카오싱크 연동을 통해 쇼핑몰 회원이 카카오 계정을 이용하여 간편 회원 가입을 할 수 있도록 제공합니다.
  * 대상 솔루션: 샵바이 엔터프라이즈 전용
  * 기능 배포일자: 2022-12-07

{% hint style="warning" %}
기존 카카오 간편가입(카카오 로그인)을 사용중인 쇼핑몰인 경우, 기존에 사용하고 있던 디벨로퍼스 앱을 동일하게 사용해 주세요.

다른 앱으로 연동을 진행할 경우 기존 카카오 간편가입(카카오 로그인) 회원은 로그인할 수 없으며, 신규 회원으로 가입 처리됩니다.
{% endhint %}

***

## (예시) API소개 및 화면 가이드 <a href="#undefined" id="undefined"></a>

아래 API들을 활용하여 카카오싱크 기능을 활용한 화면을 구현할 수 있습니다.

{% hint style="info" %}
카카오싱크는

**① 카카오싱크 신규 회원으로 최초 가입하는 경우**

**② 기존 일반 회원으로 가입되어 있던 경우**

**③ 기존 일반 회원이 카카오싱크로 신규 가입하는 경우**로 구분됩니다.

회원가입 화면에서 카카오로 시작하기 버튼 출력 및 카카오로 로그인 팝업 출력은 경우와 관계없이 동일하게 구현할 수 있습니다.
{% endhint %}

#### ① 카카오싱크 신규 회원 최초 가입 프로세스

<figure><img src="/files/Cj5VFG99mVT90sgiqYqd" alt=""><figcaption></figcaption></figure>

#### ② 기존 일반 회원 카카오싱크 회원으로 전환 프로세스

<figure><img src="/files/1jQYebqH5TuyiiIqexp9" alt=""><figcaption></figcaption></figure>

#### ③ 기존 일반 회원 카카오싱크 신규 회원가입 프로세스

<figure><img src="/files/GfPoeRqGznCyAeYTUja1" alt=""><figcaption></figcaption></figure>

***

### **1)  회원가입 화면 (공통)**

<figure><img src="/files/nAvHImIOmCh2N0omdG94" alt=""><figcaption></figcaption></figure>

1. **카카오로 시작하기 버튼 출력**

> **▶ 몰 정보 조회하기**
>
> GET /malls [**API 보기>**](https://docs.shopby.co.kr/#/Mall/get-malls)
>
> 몰 정보를 조회하는 API입니다.

* 해당 API 호출하여 받은 응답 값 중 openIdJoinConfig > providers에서 kakao-sync 값이 있는 경우 카카오로 시작하기 버튼 생성 후 kakao-sync 값을 매핑 시킵니다.
* 카카오싱크 버튼 디자인 가이드는 카카오싱크 리소스에서 확인 가능합니다.

***

2. **카카오 로그인 팝업 출력**

> **▶ OpenID 로그인 url 조회하기**
>
> GET /oauth/login-url [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/get-oauth-login-url)
>
> OpenId 로그인 url 조회하기 위한 API 입니다.

* 들어가야 하는 provider : ncp\_kakao-sync ( ncp\_ + 1번의 kakao-sync ) / redirectUri : 팝업 종료 후 리다이렉트할 파일 경로
* 해당 API를 호출하여 받은 응답 값(loginUrl)으로 카카오 로그인 팝업을 출력합니다.
* 카카오 간편 가입 완료 후 카카오 로그인 팝업이 종료될 때 팝업 URL에 파라미터로 code 값을 전달받습니다.\
  이때 OpenID 로그인 url 조회하기 API 호출 시 파라미터 값으로 넣은 redirectUri에 해당하는 파일에 code 값을 가져옵니다.

***

> **▶ Openid Access Token 발급하기**
>
> GET /oauth/openid [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/get-oauth-openid)
>
> OpenId 회원의 AccessToken 발급하기 위한 API 입니다.

* 들어가야 하는 provider : ncp\_kakao-sync
* ②에서 발급받은 code 값을 이용하여 해당 API를 호출합니다.&#x20;
* 해당 API 호출 후 받은 응답 값 중
  * (1) accessToken을 로컬 스토리지에 저장합니다.
  * (2) ordinaryMemberResponse 값도 저장합니다. (이후에 사용합니다.)\
    -> ordinaryMemberResponse 값은 기존 일반 회원으로 가입되어 있던 경우를 체크하여 api로 내려주는 값입니다.
* 해당 값은 기존 회원 가입 일과 기존 회원 마스킹 된 이메일 주소를 가지고 있습니다.

{% code overflow="wrap" %}

```
"ordinaryMemberResponse": {
        "email": "fp***@kakao.com",
        "signUpDateTime": "2021-11-29 10:04:18"
    }
```

{% endcode %}

***

### **2)**  기존 가입 회원 카카오 계정 전환 팝업 화면

* 기존 일반 회원으로 가입되어 있는 경우 카카오싱크(간편 로그인) 회원으로 전환할 것인지, 카카오싱크 계정으로 신규 가입할 것인지 선택이 가능합니다.
  * 이에 따라 추가로 팝업 커스텀 처리를 통해 쇼핑몰에 노출이 필요합니다.
* 기존 일반 회원으로 가입되어 있던 상태에서 카카오싱크 회원으로 전환 시 회원 유형이 쇼핑몰 회원에서 오픈아이디 회원으로 변경됨에 따라 기존 계정으로 로그인이 불가합니다. (아이디/ 비밀번호 찾기 불가)
  * 팝업 구현 시 카카오 계정으로 전환 이후 기존 계정으로 로그인이 불가하다는 안내 문구 출력이 필요합니다.
* ordinaryMemberResponse 값을 노출 처리합니다.

<figure><img src="/files/iIKgHRiplpA0RBsYCstK" alt=""><figcaption></figcaption></figure>

1. **아이디/ 비밀번호 입력 (인풋)**
   * 간편 로그인 전환에 필요한 아이디와 비밀번호 인풋 창을 생성합니다.

***

2. **간편 로그인으로 전환하기 (버튼)**

> **▶ 기존 회원과 오픈 아이디 연동하기**
>
> POST /profile/synchronize [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/synchronize)
>
> 기존 회원과 오픈 아이디 회원을 연동합니다.

* 아이디와 비밀번호 인풋에 들어간 `value` 값, 기존의 accessToken을 사용하여 해당 api를 호출합니다.\
  &#x20; (아이디와 비밀번호는 기존 회원의 정보와 일치하는지 비교할 때 사용하기 때문에, 일치할 때만 성공적으로 호출됩니다.)
* 아이디/ 비밀번호 입력 후 유효성 검사 실패 시, 그에 따른 알럿 메세지가 출력되어야 합니다.
* 호출 성공 시 기존의 accessToken을 삭제 후, Response 값으로 받은 새로운 accessToken을 로컬 스토리지에 저장합니다.
* 기존 회원이 휴면 처리된 상태인 경우 간편 로그인으로 전환되지 않아 해당 api 호출 시 실패 처리됩니다.\
  호출 실패 후 발생하는 에러코드는 M0020이며, 해당 에러코드를 통해 "입력하신 아이디는 휴면상태의 계정입니다. 기존 회원으로 로그인 후 휴면상태를 해지해 주세요."와 같은 알럿 창을 출력시키거나 휴면회원 전환 페이지로 이동 후 휴면회원 해지 시 다시 카카오 계정 전환 팝업으로 이동합니다.&#x20;

***

3. **카카오 계정으로 신규 가입하기 (버튼)**

> **▶ 오픈 아이디 회원가입 처리하기**
>
> POST /profile/openid [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile-openid)
>
> 오픈 아이디를 사용한 회원 가입 처리입니다.

* 이전에 가지고 있던 accessToken을 활용하여 해당 api 호출이 정상적으로 된 경우 회원 상태가 `ACTIVE`로 변경되면 로그인 처리합니다.