> 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_member_guide.md).

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

{% 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)
    * 하나의 URI(host와 path)만 등록 가능하며, 변경 필요 시 NHN커머스에 요청 바랍니다. 
(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
* 고객사 회원시스템에 방화벽(ACL) 또는 IP 화이트리스트가 설정되어 있는 경우, 샵바이서버 발신 IP를 사전에 등록해야 정상적으로 인증 요청이 도달합니다.
  * 등록 대상 IP: 115.89.203.145
  * 고객사는 해당 IP를 방화벽/보안장비 또는 API 서버 ACL에 허용(inbound) 등록해야 합니다.
  * IP 미등록 시 샵바이서버의 인증 요청이 차단되어 타임아웃 또는 연결 거부(Connection Refused) 오류가 발생할 수 있습니다.
  * ACL 등록 후에는 실제 인증 요청 테스트를 통해 정상 통신 여부를 확인할 것을 권장합니다.

***

#### ▶ 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로 전달해 주세요.\
      \* 위 경우에는 샵바이에서 등급 평가를 '사용함'으로 설정 하더라도 해당 회원이 쇼핑몰에 로그인하는 시점에 외부 연동 회원 데이터로 동기화 되므로 유의바랍니다.