# \[엔터프라이즈] 외부 회원 연동 가이드

{% hint style="info" %} <mark style="color:red;">**일부 API는 2024년 11월 6일(수) 업데이트 되었습니다.**</mark> [**\[공지보기\]**](https://www.godo.co.kr/support/board/35/40/2496)
{% endhint %}

{% hint style="warning" %}
아래 가이드를 통해, 고객사에서 기존에 보유하고 있던 회원정보를 이용하여 샵바이 쇼핑몰에서 로그인 가능합니다. 쇼핑몰 회원 인증/ 휴면회원 해제/ 회원 탈퇴 연동을 진행해보세요.

※ 외부 회원 연동은 토큰 기반 연동 방식을 제공합니다.&#x20;

<mark style="color:blue;">**※ 외부 회원 연동 시 쇼핑몰회원(간편 로그인 포함) 가입은 불가합니다.**</mark>
{% endhint %}

{% hint style="info" %}
오로라 기본 스킨에서는 인증 관리를 쉽게 할 수 있는 유틸리티를 제공합니다. 자세한 내용은 [**인증관리 유틸리티 사용법(외부 회원 연동)**](https://nhnent.dooray.com/share/pages/YXtIoJnnTD2_0Mwbn70dwA) 가이드를 참고하세요.
{% endhint %}

## (연동방식) 토큰 기반 연동 <a href="#id-1-ed-86-a0-ed-81-b0-ea-b8-b0-eb-b0-98-ec-97-b0-eb-8f-99" id="id-1-ed-86-a0-ed-81-b0-ea-b8-b0-eb-b0-98-ec-97-b0-eb-8f-99"></a>

### 1. 기본 FLOW <a href="#ea-b8-b0-eb-b3-b8-flow" id="ea-b8-b0-eb-b3-b8-flow"></a>

<figure><img src="https://rlyfaazj0.toastcdn.net/SERVICE/20210812/01_%EC%88%98%EC%A0%95(2).png" alt=""><figcaption></figcaption></figure>



### 2. 쇼핑몰 사용자 인증 <a href="#ea-b8-b0-eb-b3-b8-flow" id="ea-b8-b0-eb-b3-b8-flow"></a>

```
▶ 요약
shopby API를 사용하기 위해서는 전용 accessToken이 필요합니다.
해당 토큰을 발행하기 위해서, 몰의 로그인 토큰을 검증하고 회원을 조회하는 API의 개발이 필요합니다.
API 개발 후, [NHN커머스> 고객센터> 1:1문의]를 통해 개발된 API를 NHN커머스에 등록요청 바랍니다. 

아래 2가지 정보를 전달주시길 바랍니다.
(1) 쇼핑몰 번호 
    * 쇼핑몰번호는 서비스어드민> 서비스관리> 쇼핑몰관리에서 확인 가능합니다. 
(2) check-token URI(로그인 연동을 위한 URI)
(3) authorizationType : (기본값은 타입 미포함)
```

▶ [외부아이디 로그인 토큰으로 샵바이 토큰 획득 API 바로가기](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/post-oauth-openid)

외부아이디(오픈아이디 포함) 로그인을 통한 샵바이 토큰 획득 API에 대한 안내 입니다.

<br>

### <mark style="color:blue;">고객사의 회원 시스템의 토큰으로 샵바이 토큰을 획득하기 위한 연동 API 스펙</mark>

#### ▶ 쇼핑몰 FE -> 샵바이 서버 요청&#x20;

<https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/post-oauth-openid> API 를 이용하여 고객사의 토큰을 이용해 샵바이 토큰을 발급받을 수 있습니다.

해당 API 요청 시 아래의 값은 필수값으로 전송해야 합니다.

* provider : ncpstore
* openAccessToken : 외부입점사에서 발급한 accessToken

***

#### ▶ 샵바이서버 -> 고객사 회원시스템 인증 요청&#x20;

고객사에서는 샵바이의 스팩에 맞는 request param과 response 에 맞는 API를 제공해야 합니다.

예시) GET [https://abc.com/id?token=](https://abc.com/id?token=myToken){token}<br>

요청의 형태는 위 URI 와 같으며  queryParam 으로 token 이라는 파라메터에 <mark style="color:blue;">**고객사 로그인 토큰 값**</mark>을 전달합니다. URI는 각 고객사에 맞게 수정 가능합니다.

* 로그인 토큰을 Header에 Authorization 필드로도 전달합니다. 아래 두 가지 형태 모두 지원합니다.&#x20;
  * 타입 포함 - Authorization : {type} {token} ex) Authorization : Bearer abc123
  * 타입 미포함 - Authorization : {token} ex) Authorization : abc123

***

#### ▶ Response

**(1) 유효한 토큰인 경우**

* 유효한 토큰이면 성공(200)으로 응답
* HTTP Status <mark style="color:blue;">200 OK</mark>

<table><thead><tr><th>항목</th><th width="104">타입</th><th width="99">필수여부</th><th width="124">제한</th><th width="110">Null인 경우</th><th>설명</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>O</td><td>최대 50자</td><td>Null 불가</td><td><p><mark style="color:red;">업체에서 관리하는 회원의 유일값</mark></p><p>(전화번호 등 변동가능한 값 사용이 어렵습니다)</p></td></tr><tr><td>name</td><td>String</td><td>X<br></td><td>최대 50자</td><td>기존 저장값 유지</td><td>사용자 이름</td></tr><tr><td>adultCertified</td><td>Boolean</td><td>X</td><td><br></td><td>기존 저장값 유지</td><td>성인 인증 여부</td></tr><tr><td>gradeNo</td><td>Number</td><td>X</td><td></td><td>기존 저장값 유지</td><td>회원 등급 (사전에 등록 필요)</td></tr><tr><td>groupNos</td><td>Array</td><td>X</td><td></td><td>기존 저장값 유지</td><td>회원 그룹 (사전에 등록 필요)</td></tr><tr><td>nickname</td><td>String</td><td>X<br></td><td>최대 30자</td><td>기존 저장값 유지</td><td>사용자 별명, 별칭</td></tr><tr><td>email</td><td>String</td><td>X<br></td><td>최대 50자</td><td>기존 저장값 유지</td><td>이메일</td></tr><tr><td>phone</td><td>String</td><td>X<br></td><td><p>숫자만</p><p>(- 제거 필수)</p></td><td>기존 저장값 유지</td><td>휴대전화번호</td></tr><tr><td>nation</td><td>String</td><td>X<br></td><td></td><td>기존 저장값 유지</td><td>KR, US, JP, CN / 기본값은 쇼핑몰 설정을 따름</td></tr><tr><td>privacyPolicyAgreed</td><td>Boolean</td><td>X<br></td><td></td><td>기존 저장값 유지</td><td>본인인증여부</td></tr><tr><td>pushPolicyAgreed</td><td>Boolean</td><td>X<br></td><td></td><td>기존 저장값 유지</td><td>앱푸시동의 여부 - 샵바이에서 사용하지 않음</td></tr><tr><td>smsPolicyAgreed</td><td>Boolean</td><td>X<br></td><td></td><td>기존 저장값 유지</td><td>광고성sms 수신동의 여부</td></tr><tr><td>emailPolicyAgreed</td><td>Boolean</td><td>X<br></td><td></td><td>기존 저장값 유지</td><td>광고성email 수신동의 여부<br></td></tr><tr><td>gender</td><td>String</td><td>X</td><td></td><td>기존 저장값 유지</td><td>F, M<br>/ 성별(F: 여성, M: 남성)</td></tr><tr><td>ci</td><td>String</td><td>X</td><td></td><td>기존 저장값 유지</td><td>ci</td></tr><tr><td>birthday</td><td>String</td><td>X</td><td>'yyyyMMdd' 형식</td><td>기존 저장값 유지</td><td>생년월일</td></tr><tr><td>businessName</td><td>String</td><td>X</td><td>최대 50자</td><td>기존 저장값 유지</td><td>사업자명</td></tr><tr><td>businessRegistrationNumber</td><td>String</td><td>X</td><td>10자<br>('-' 포함 12자)</td><td>기존 저장값 유지</td><td>사업자등록번호<br><br>예시)<br>* 하이픈(-) 미포함: 1234567890<br>* 하이픈(-) 포함: 123-45-67890</td></tr><tr><td>extraJson</td><td>String</td><td>X</td><td>JSON String</td><td>기존 저장값 유지</td><td>추가 정보 (입점사 회원 커스텀 정보)</td></tr><tr><td>zipCode</td><td>String</td><td>X</td><td>최대 50자</td><td>기존 값 유지</td><td>우편번호</td></tr><tr><td>streetAddress</td><td>String</td><td>X</td><td>최대 500자</td><td>기존 값 유지</td><td>도로명 주소</td></tr><tr><td>streetAddressDetail</td><td>String</td><td>X</td><td>최대 500자</td><td>기존 값 유지</td><td>도로명 주소 상세</td></tr><tr><td>landLotAddress</td><td>String</td><td>X</td><td>최대 500자</td><td>기존 값 유지</td><td>지번 주소</td></tr><tr><td>landLotAddressDetail</td><td>String</td><td>X</td><td>최대 500자</td><td>기존 값 유지</td><td>지번 상세 주소</td></tr><tr><td>city</td><td>String</td><td>X</td><td>최대 500자</td><td>기존 값 유지</td><td>시, 도</td></tr><tr><td>state</td><td>String</td><td>X</td><td>최대 500자</td><td>기존 값 유지</td><td>구, 군</td></tr></tbody></table>

{% hint style="success" %}
현재 샵바이에서는 **만 14세 미만 회원의 회원가입을 제한**하고 있으나, \
**외부회원 연동인 경우에 한하여 허용**하고 있습니다.&#x20;

외부회원연동은 고객사 회원의 시스템을 기반으로 샵바이에 연동하는 것이므로 \
**만 14세 미만 회원이 존재하는 경우,&#x20;**<mark style="color:red;">**법정대리인 동의 절차를 모두 완료**</mark>**하신 뒤 연동해 주세요.**&#x20;

해당 가이드 미숙지로 발생하는 이슈에 대한 책임은 고객사에 있으니 반드시 유의 부탁드립니다.
{% endhint %}

{% hint style="success" %}
외부회원연동의 경우, 샵바이 내 smsPolicyAgreed, emailPolicyAgreed 값이 저장/변경된 시점을 기준으로 \
동의/거부일시로 처리되어, 실제 회원이 동의/거부한 시점과 다를 수 있습니다.

따라서 정확한 동의일 관리 및 안내를 위해 **광고성 수신 동의여부에 대한 법적고지**는 \
**고객사 회원의 시스템에서 진행해주셔야 합니다.**
{% endhint %}

{% hint style="success" %}
샵바이 관리자에서 <mark style="color:red;">**회원등급과 회원그룹을 설정 후**</mark> NHN커머스 측으로 <mark style="color:red;">**요청**</mark> 시 groupNos 값을 전달해 드립니다.
{% endhint %}

{% hint style="success" %}
**extraJson** 항목에, 고객사에서 추가적으로 저장하고 싶은 회원정보를 JsonString형태로 샵바이에 전달가능합니다. 이렇게 전달된 extraJson정보는 회원정보 조회하기 [shop API](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile)와 [server API](https://server-docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile)에서 응답값 내 additionalInfo로 바이패스되어 전달됩니다.&#x20;
{% endhint %}

{% hint style="success" %}
**businessName**과 **businessRegistrationNumber** 2개 모두 값이 있어야 최초 등록 가능합니다.\
2개 항목 모두 ""(empty)로 보내면 기존 등록된 내용이 삭제됩니다.
{% endhint %}

<figure><img src="https://rlyfaazj0.toastcdn.net/20230126/154134.579838000/image.png" alt=""><figcaption></figcaption></figure>

***

#### **Example**

{% code overflow="wrap" %}

```
{
    "id" : "898010",
    "adultCertified" : false,
    "name" : "Jieun Lee",
    "nickname" : "아이유",
    "email" : "jieun@mail.com",
    "phone" : "01012348989",
    "nation" : "KR",
    "privacyPolicyAgreed" : true,
    "pushPolicyAgreed" : true,
    "smsPolicyAgreed" : false,
    "emailPolicyAgreed" : false,
    "gender" : "F",
    "ci" : "abcde",
    "birthday" : "19990101",
    "businessName" : "NHN커머스",
    "businessRegistrationNumber" : "1231212345",
    "extraJson" : "{\"job\":\"가수\",\"hobby\":[\"운동하기\",\"영화보기\"]}"
    "zipCode" : "08390"
    "city" : "서울특별시"
    "state" : "구로구"
    "streetAddress" : "디지털로26길 43"
    "streetAddressDetail" : "R동 6, 7층"
    "landLotAddress" : "구로동 212-8"
    "landLotAddressDetail" : "R동 6, 7층"
 }
```

{% endcode %}

고객(회원)이 설정한 서비스에 대한 마케팅 동의 여부 등을 위 API의 응답으로 보내주시면 쇼핑몰에 진입할 때마다

회원 정보를 응답 값으로 매번 변경합니다.

***

#### (2) 기타 고객사 API 측 오류인 경우

* 나머지 고객사 API 측 오류면 고객사에서 내려준 response 를 그대로 message 에 포함하여 오류(400)로 응답합니다.
* 샵바이 토큰 발행 api (<https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/post-oauth-openid> ) 의 응답으로 유효하지 않은 토큰일 경우에도 오류(400)로 응답합니다.&#x20;

***

### 3. 회원탈퇴 <a href="#ea-b8-b0-eb-b3-b8-flow" id="ea-b8-b0-eb-b3-b8-flow"></a>

▶ [외부회원 탈퇴 API 바로가기](https://server-docs.shopby.co.kr/?url.primaryName=member/#/Profile/delete-profile)

앱에서 회원탈퇴할 경우, server api의  회원 탈퇴 API (<https://server-docs.shopby.co.kr/?url.primaryName=member/#/Profile/delete-profile>) 호출을 반드시 해주세요.

※ 외부 회원 연동은 탈퇴 철회 불가하며, 탈퇴 시 즉시 탈퇴처리됩니다.

***

### 4. 휴면처리 <a href="#ea-b8-b0-eb-b3-b8-flow" id="ea-b8-b0-eb-b3-b8-flow"></a>

▶ [휴면처리 API 바로가기](https://server-docs.shopby.co.kr/?url.primaryName=member/#/Profile/put-profile-dormant)

앱에서 휴면처리될 경우, server api의  휴면처리 API (<https://server-docs.shopby.co.kr/?url.primaryName=member/#/Profile/put-profile-dormant>) 호출을 반드시 해주세요.

***

### 5. 회원 등급 평가 <a href="#ea-b8-b0-eb-b3-b8-flow" id="ea-b8-b0-eb-b3-b8-flow"></a>

1. 외부 회원 연동을 사용하시면서 동시에 샵바이에서 제공하는 회원 등급 평가를 사용하시고 싶으실 경우,\
   회원등급(gradeNo) 값을 null 로 보내면 기존에 저장된 값을 업데이트 하지 않고 그대로 유지하므로 샵바이에서 제공하는 회원등급을 사용하실 수 있습니다.
2. 외부 연동 회원 데이터로 동기화 하고 싶으실 경우,
   1. 샵바이 관리자 내 '회원 등급 관리' 메뉴에서 \[등급 평가 설정] 버튼을 클릭하시어 자동 등급 평가 사용을 '사용 안 함' 처리해주세요.
   2. 연동 데이터 전달 시에는 회원등급(gradeNo) 값을 해당 쇼핑몰의 groupNo로 전달해 주세요.\
      \* 위 경우에는 샵바이에서 등급 평가를 '사용함'으로 설정 하더라도 해당 회원이 쇼핑몰에 로그인하는 시점에 외부 연동 회원 데이터로 동기화 되므로 유의바랍니다.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://workspace-help.nhn-commerce.com/contents/recommended/prm_member_guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.