# 샵바이 스킨 설명서

본 문서는 샵바이 솔루션 정책과 업데이트에 따라서 별도 안내 없이 수정될 수 있습니다.

샵바이 기본 스킨은  javascript와 react를 통해 고객들의 최접선에 있는 쇼핑몰 프론트 화면을 자유롭게 커스텀할 수 있도록 NHN커머스에서 제작한 스킨입니다.

> **스킨(skin)이란?** \
> 쇼핑몰 고객들이 보는 쇼핑몰 프론트 화면 디자인 (템플릿, 레이아웃)을 뜻합니다.

{% hint style="success" %}
️쇼핑몰 신규 생성 시, 기본 스킨으로 NHN커머스에서 제작한 샘플 (스킨명:오로라) 개별형 스킨이 세팅됩니다. \
본 설명서는 쇼핑몰 운영 방식이 '스킨'인 몰을 기준으로 안내합니다. 

샵바이 기본 스킨은 javascript 기반으로 제작된 오로라 개별형 (PC+모바일) 스킨과 react기반으로 제작된 오로라 리액트 통합형 스킨으로 제작되었습니다. 

샵바이 엔터프라이즈의 헤드리스(headless) 운영 방식인 몰은 [API문서](https://docs.shopby.co.kr/)를 확인하여 스킨 개발 진행이 필요합니다. 
{% endhint %}

***

### 용어 설명

#### ■ 스킨 구분

#### 개별형

* PC스킨과 Mobile스킨의 소스 코드가 각각의 형태로 개발된 스킨을 말하며 아래와 같이 분류됩니다. 
  * 개별형 (PC+Mobile) : 하나의 프로젝트 내 PC스킨과 Mobile스킨의 소스코드가 모두 개발된 경우
  * 개별형 (PC) : PC스킨만 개발된 경우
  * 개별형 (Mobile) : Mobile스킨만 개발된 경우

#### 통합형

* PC스킨과 Mobile스킨의 소스코드가 하나의 형태로 개발된 스킨으로 반응형으로 개발된 스킨도 통합형 스킨으로 분류됩니다. 

#### ■ 저장 방법

#### GitLab

* 소스코드를 GitLab에 저장하여 소스코드가 저장된 GitLab 프로젝트와 쇼핑몰을 연결하는 방식입니다.

***

### 오로라(Aurora) 스킨과 오로라 리액트(Aurora React) 스킨의 차이는 무엇인가요? 

#### ■ 오로라(Aurora) 개별형 스킨

<figure><img src="/files/n4JS95xC95xC8so9AyuJ" alt=""><figcaption><p>오로라 개별형 (PC+모바일)</p></figcaption></figure>

* 쇼핑몰 신규 생성 시 기본으로 세팅되는 스킨입니다.
* shop by basic, pro, enterprise 모두 적용이 가능합니다.
* 오로라 (Aurora) 스킨은 PC스킨과 Mobile스킨의 소스코드가 각각의 형태로 개발된 스킨으로 개별형(PC+모바일)으로 분류됩니다.
* javascript 기반으로 제작되었습니다.
* 스킨 에디터를 통해 디자인 수정이 가능합니다. [ 에디터 가이드 바로가기](https://nhnent.dooray.com/share/pages/7ik2itl8T6ew2JGRZa7sEQ)

#### ■ 오로라 리액트(Aurora React) 통합형 스킨

<figure><img src="/files/DiYzno7YmJ8qLJExwVUD" alt=""><figcaption><p>오로라 리액트 통합형</p></figcaption></figure>

* shop by basic, pro, enterprise 모두 적용이 가능합니다.
* 오로라 리액트(Aurora React)스킨은 PC/Mobile 구분이 없는 통합형 스킨으로 모바일 퍼스트(Mobile frtst)스킨으로 제작되었습니다.
* react 기반으로 제작되었습니다.
* NHN 커머스에서 제공하는 @shopby 패키지를 활용하여 보다 손 쉬운 개발이 가능합니다.
* &#x20;[오로라 리액트 가이드 바로가기](https://nhnent.dooray.com/share/pages/WoOk8q6KT1K3MZcLSuyZsw)


# 개발 프로세스

{% hint style="info" %}
디자인 파트너 계정이 존재한 스킨 판매 에이전시의 경우 [GitLab스킨 판매 프로세스 가이드](<https://nhnent.dooray.com/share/pages/RwdJEHPDQtCV6688_odoxQ >)를 확인하시길 바랍니다.
{% endhint %}

shop by 라인업의 쇼핑몰 신규 생성 시, 기본 스킨으로 NHN커머스에서 제작한 샘플 스킨 (스킨명 : 오로라 개별형 (PC+모바일))이 세팅됩니다. \
해당 스킨 커스텀하여 "나만의 새로운 스킨"을 제작할 수 있도록 가이드 드립니다.

#### 아래 목차 순서대로 문서를 확인하는 것을 추천합니다.

* step 1) [등록](/aurora-guide/process/setting)
* step 2) [개발](/aurora-guide/process/development)&#x20;
  * [개발 환경 구성하기](/aurora-guide/process/development/setting)
  * [스킨 디렉토리 구조](/aurora-guide/process/development/directory)
* step 3) [설치](/aurora-guide/process/installation)

스킨을 개발하여 워크스페이스 셀러어드민에서 개발한 스킨을 쇼핑몰 관리자에 설치하여 사용할 수 있습니다.


# 등록

셀러 어드민 내 디자인 상품 등록에 대해 안내합니다.

{% hint style="info" %}
스킨 저장소(GitLab) 내 소스코드를 저장할 프로젝트를 발급받기 위해서는 셀러어드민에 상품을 등록해야 합니다.
{% endhint %}

#### ◼︎ GitLab 이란?&#x20;

공동 소스코드 작업을 위한 변경사항 및 버전 등을 로컬에서 추적하고 관리할 수 있는 소스코드 버전 관리 시스템입니다.\
디자인 스킨 소스코드를 GitLab 프로젝트에 저장해두고 디자인 스킨을 쇼핑몰에 설치하여 배포할 수 있습니다.

#### ◼︎ 한국어 설정 방법&#x20;

언어 설정 기능을 통해 GitLab을 한국어로 쉽게 이용할 수 있습니다.&#x20;

```
로그인 > 우측 상단 아이콘 > settings > preferences > localization > 한국어 > 저장
```

상품을 등록하여 스킨 소스코드를 저장할 프로젝트를 발급 받아 소스코드를 저장하고,\
이를 쇼핑몰 관리자에 설치할 수 있습니다.&#x20;

아래 프로세스에 따라 개발을 시작해 주시기 바랍니다.&#x20;

<div align="left"><figure><img src="/files/qx8M9su1FMsTeJXDYXgN" alt=""><figcaption></figcaption></figure></div>

***

### 등록 경로

```
워크스페이스 > 셀러어드민 > 상품 > 디자인
```

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

#### ① 개발 방식

스킨을 개발하기 전 먼저 특정 스킨을 기반으로 일부를 수정하여 개발할지 또는 처음부터 개발할지 개발 방식을 선택하는 항목입니다. \
선택된 값에 따라 스킨 저장소에 비어있는 프로젝트가 생성되거나 선택된 스킨 소스코드가 저장된 프로젝트가 생성됩니다. \
특정 스킨을 기반으로 개발하는 경우 스킨의 구분 (통합형, 개별형) / 빌드여부 / 빌드타입 선택에 제한이 있습니다.&#x20;

* 처음부터 개발하기&#x20;
  * 베이스 코드 없이 빈 프로젝트에서 개발을 시작할 수 있습니다.
* aurora react 스킨을 기반으로 개발하기 [오로라 리액트 스킨 개발 가이드 ](https://nhnent.dooray.com/share/pages/WoOk8q6KT1K3MZcLSuyZsw)
  * [aurora react](https://skins.shopby.co.kr/shopby/aurora-skin) 스킨 코드를 베이스로 프로젝트가 생성됩니다.
  * aurora react 스킨은 빌드가 필요하여, 빌드여부는 `Y`로 설정합니다.
  * 빌드타입은 [yam](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) 패키지 매니저로 설정하는 것을 권장합니다.&#x20;
* **aurora 스킨을 기반으로 개발하기**&#x20;
  * [aurora](https://skins.shopby.co.kr/shopby/aurora-vanilla) 스킨 코드를 베이스로 프로젝트가 생성됩니다.
  * aurora 스킨은 모든 페이지를 정적 파일로 제공하기 때문에 빌드를 하지 않으며, 빌드여부는 `N`로 설정합니다.&#x20;

{% hint style="info" %}
본 가이드는 aurora 오로라 개별형 스킨을 기준으로 작성되었습니다.&#x20;
{% endhint %}

#### ② 프로젝트명

스킨 저장소에 프로젝트가 생성될 때 사용되는 항목으로 입력한 프로젝트명으로 스킨 저장소에 프로젝트가 생성됩니다.\
생성된 프로젝트명은 수정할 수 없습니다.

#### ③ 상품명

셀러어드민에 노출되는 항목입니다.

#### ④ 구분

스킨 소스코드 저장 구분을 선택하는 항목입니다.\
위 (①)에서 설명한 내용과 같이 개발방식에 따라 구분 선택에 제한적 입니다.&#x20;

#### ⑤ 배너정보

스킨에서 사용하는 배너그룹을 정의한 메타정보와 배너 샘플 이미지가 포함된 정보를 등록하는 항목입니다.\
스킨에서는 어느 위치에서 어떠한 배너를 호출하겠다는 내용이 포함되어 있기 때문에 배너정보는 반드시 필요합니다.\
배너 정보 관련하여 자세한 내용은 [개발 환경 구성하기 문서](/aurora-guide/process/development/setting)를 참고하시길 바랍니다.&#x20;

다만 상품을 등록하는 시점에는 스킨 개발을 시작하는 단계일 수 있어 배너 정보는 상품 등록 후 개발이 완료된 이후 상품 수정 화면에서 등록하시면 됩니다.\
특정 스킨을 기반으로 개발하는 경우 각 스킨에서 사용된 메타정보와 샘플 이미지가 자동 등록되나, 상품 수정 화면에서 등록된 파일을 삭제 후 재등록이 가능합니다.

{% hint style="info" %}
등록된 상품이 설치된 쇼핑몰이 존재하는 경우 배너 정보 수정이 불가합니다.&#x20;
{% endhint %}

#### ⑥ 빌드여부

위 (①)에서 설명한 내용과 같이 개발방식에 따라 빌드여부 선택이 제한됩니다.

* 처음부터 개발하기
  * 프로젝트 개발 환경에 따라 빌드여부를 설정합니다.
  * 빌드가 필요한 경우 빌드 명령어는 `build` 로 고정합니다.
* aurora react 의 경우 빌드가 필요한 환경이기 때문에 빌드여부를 `Y`로 설정해야 합니다.
* **aurora 기본 스킨은 정적 파일을 제공하기 때문에 빌드하지 않습니다.**

#### ⑦ 빌드타입

위 (⑥)에서 빌드여부 Y로 선택한 경우에만 필요한 항목입니다. \
프로젝트를 빌드할 때 패키지를 매니저에 따라 빌드 명령어를 실행합니다.&#x20;

```
# yarn 을 선택한 경우
$ yarn build

# npm 을 선택한 경우
$ npm run build
```


# 개발

스킨 코드를 개발하여 스킨을 제작할 수 있습니다.

<div align="left"><figure><img src="/files/aofGsKYOH336y2Wm5MzN" alt=""><figcaption></figcaption></figure></div>

프로젝트가 저장된 위치는 [상품 > 디자인 목록](https://workspace.godo.co.kr/seller-admin/product/skin)에서 확인할 수 있습니다. \
저장 위치로 이동해 하기 가이드를 참고하여 개발을 진행하세요.

* [shop api 문서](https://docs.shopby.co.kr/)
* aurora 화면별 API 활용 가이드
  * 오로라 개별형 기반 페이지별 API 활용 가이드입니다.&#x20;
* [aurora 모듈 가이드](https://nhn-commerce-fe.github.io/shopby-ui-docs/module/index.html)
  * 오로라 개별형 스킨에서 사용가능한 모듈에 대한 가이드입니다.


# 개발 환경 구성하기

* [배너 정보 (asset) 파일 등록하기](#assets-1)
* [배너 정보 (asset) 파일이란?](#assets)
* [스킨 유형 (platformType)별 zip 파일 구조](#platformtype-zip)
* [로컬 개발 환경 구성하기](#undefined-3)

***

### 배너 정보(assets) 파일 등록하기

스킨에서 사용하는 배너그룹을 정의하는 메타정보와 배너에 사용되는 샘플 이미지가 포함된 정보입니다. \
스킨을 사용하는 쇼핑몰이 생성될 때 해당 정보로 배너그룹이 생성됩니다.

#### ◼︎ 등록 방법 <a href="#eb-93-b1-eb-a1-9d-eb-b0-a9-eb-b2-95" id="eb-93-b1-eb-a1-9d-eb-b0-a9-eb-b2-95"></a>

* [셀러어드민 > 상품 > 디자인](https://workspace.godo.co.kr/seller-admin/product/skin)에서 배너 정보 등록이 필요한 스킨의 `기본 정보` 클릭
* 디자인 정보 수정에서 배너정보 등록

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

#### **◼︎ zip 파일 구성 시 주의사항**

* 20MB 이내의 zip 파일 형태
* csv 파일 저장 시 utf-8 로 저장

배너 정보 등록 시 쇼핑몰 어드민 아래 경로에서 배너 이미지를 등록하거나 수정할 수 있습니다.

```
shop by pro: 디자인> 디자인설정> 스킨 배너관리
shop by premium: 전시관리> 스킨 배너관리
```

<figure><img src="https://github.com/nhn-commerce-fe/shopby-ui-docs/assets/131448949/cf6229b3-dc28-4447-b460-59a2492db5a6" alt=""><figcaption></figcaption></figure>

***

### 배너 정보 (assets) 파일이란?

* 개념&#x20;
  * 스킨에서 사용하는 배너그룹을 정의하는 메타정보, 배너에 사용되는 샘플 이미지가 포함된 정보입니다.&#x20;
* 필요한 이유
  * 아래서 설명드리는 배너정보(asset파일)은 20MB 이내의 zip파일 형태로 업로드가 필요합니다.
  * 이를 통해 해당 메타정보가 쇼핑몰 어드민(관리자)에 바로 노출되며, 이후 배너를 조회하는 API를 호출할 수 있는 개념입니다.
  * 따라서 스킨이 사용할 배너와 배너그룹에 대한 정확한 정보를 반드시 bannerGroup.csv, banner.csv에 입력해야 합니다.&#x20;

{% hint style="info" %}
단, csv파일 작성 후 저장 시 한글이 깨질 수 있으니 반드시 UTF-8로 저장해야하는 점을 확인부탁드립니다.

*(참고) cs파일 UTF-8저장 방법*\
*엑셀 파일 > 다른 이름으로 저장 > 팝업창 우측 하단 '도구(L)'메뉴 버튼 > '웹 옵션(W)' 선택 > 웹 옵션 창에서 '인코딩' 탭 진입하여 '문서를 다음 형식으로 저장(S)' 내 유니코드(UTF-8) 선택*
{% endhint %}

***

### 스킨 유형(platformType)별 zip파일 구조

앞선 문서에서 안내해 드린 대로 스킨은 적용되는 환경에 따라 아래와 같은 유형이 있습니다. \
각 유형별로 아래와 같은 zip 파일 구조를 갖춰야 합니다.&#x20;

{% hint style="info" %}
오로라 기본 스킨은 개별형(PC+모바일) 스킨이며, 본 스킨 개발 가이드는 개별형을 기준으로 안내합니다.
{% endhint %}

* 개별형(PC + MOBILE) : 하나의 GitLab 프로젝트 내 PC스킨과 Mobile스킨의 소스코드가 모두 개발된 경우
* 개별형(PC) : PC스킨만 개발된 경우
* 개별형(MOBILE) : Mobile스킨만 개발된 경우
* 통합형(COMBINE) : PC스킨과 Mobile스킨의 소스코드가 하나의 형태로 개발된 스킨

***

### ◼︎ asset 디렉토리 구조

스킨 유형별로 아래와 같이 assets을 구성하세요.

```
/assets
   ㄴ /img
       ㄴ /banner
           ㄴ 이미지파일1
           ㄴ 이미지파일2
   ㄴ banner.csv
   ㄴ bannerGroup.csv
```

***

### ◼︎ bannerGroup.csv

스킨에서 사용할 각 배너그룹을 정의하는 메타정보 파일입니다.

* #### **platformType**

bannerGruop.csv 의 platformType은 아래와 같이 작성해 주셔야 합니다.&#x20;

* 개별형(pc+mobile): <mark style="background-color:yellow;">pc/banner.csv</mark>, <mark style="background-color:yellow;">mobile/banner.csv</mark>
* 개별형(pc) : <mark style="background-color:yellow;">PC</mark>
* 개별형(mobile) : <mark style="background-color:yellow;">MOBILE\_WEB</mark>
* 통합형 스킨: <mark style="background-color:yellow;">RESPONSIVE</mark>

- #### bannerGroupType/ bannerGroupCode/bannerGroupName <a href="#undefined" id="undefined"></a>

[배너 영역 가이드](/aurora-guide/api-1/main/banner)를 참고하시길 바랍니다.

* (참고) \<span style="color:#121212;">bannerGroupCode\</span>: \
  쇼핑몰 스킨 내 배너의 위치와 bannerGroupCode 는 무관 (ex) BANNER03 을 BANNER04 보다 쇼핑몰 상단에 배치 가능
* (참고) \<span style="color:#121212;">bannerGroupName\</span>: \
  자유롭게 입력가능
* 예제코드 (오로라 리액트 통합형 기준)

#### <mark style="color:purple;">**✓ 예제코드**</mark>

```
,platformType,bannerGroupType,bannerGroupCode,bannerGroupName
,RESPONSIVE,LOGO,LOGO,로고 전용 - 상단로고
,RESPONSIVE,SLIDE,BNSLIDE,움직이는 배너 - 메인 상단 배너
,RESPONSIVE,NORMAL,BANNER01,일반 배너 - 메인 중간 배너 1
,RESPONSIVE,NORMAL,BANNER02,일반 배너 - 메인 중간 배너 2
,RESPONSIVE,NORMAL,BANNER03,일반 배너 - 메인 중간 배너 3
,RESPONSIVE,NORMAL,BANNER04,일반 배너 - 메인 중간 배너 4
,RESPONSIVE,NORMAL,BANNER05,일반 배너 - 메인 중간 배너 5
,RESPONSIVE,NORMAL,BNBOTTOM,일반 배너 - 메인 하단 배너
,RESPONSIVE,NORMAL,BNBGLEFT,일반 배너 - PC 배경 좌측 배너
,RESPONSIVE,NORMAL,BNDETAIL,일반 배너 - 상품상세 배너
```

***

### ◼︎ banner.csv <a href="#e2-93-92-banner.csv" id="e2-93-92-banner.csv"></a>

스킨에서 사용하는 최초의 initial sample data를 입력하는 파일입니다.\
initial sample data란, 개발된 스킨이 배포되었을 때 샘플로서 보여지는 배너(즉 배너 이미지) 정보를 의미합니다.

하나의 배너그룹 안에 여러 개의 배너가 추가될 수 있으므로,\
\<span style="color:#121212;">banner.csv\</span>는 입력행 수 제한이 없습니다.

* bannerGroupCode
  * 해당 배너가 포함될 배너그룹 코드
  * bannerGroup.csv파일 내 bannerGroupCode 정의 선행 필수
* bannerTitle: 배너명
* bannerImage
  * 배너에서 사용할 배너 이미지 파일명 (경로 포함)
  * 스킨 내 이미지가 존재해야함
  * bannerGroupType 이 SLIDE 인 경우, 행 추가를 통해 여러 개의 이미지 등록가능
* displayOrder
  * 동일한 배너그룹에 속한 배너들 간 노출 순서&#x20;
  * ex. 배너그룹 내 배너가 1개만 존재할 경우 default값은 *,1* 으로 입력

#### <mark style="color:purple;">**✓ 예제코드**</mark>

```
,bannerGroupCode,bannerTitle,bannerImage,displayOrder
,LOGO,로고 전용 - 상단로고,/assets/img/banner/header-logo.png,1
,BNSLIDE,움직이는 배너 - 메인 상단 배너,/assets/img/banner/main_slide_banner01.png,1
,BNSLIDE,움직이는 배너 - 메인 상단 배너,/assets/img/banner/main_slide_banner02.png,2
,BNSLIDE,움직이는 배너 - 메인 상단 배너,/assets/img/banner/main_slide_banner03.png,3
,BNSLIDE,움직이는 배너 - 메인 상단 배너,/assets/img/banner/main_slide_banner04.png,4
,BNSLIDE,움직이는 배너 - 메인 상단 배너,/assets/img/banner/main_slide_banner05.png,5
,BNSLIDE,움직이는 배너 - 메인 상단 배너,/assets/img/banner/main_slide_banner06.png,6
,BANNER01,일반 배너 - 메인 중간 배너 1,/assets/img/banner/main_banner01.png,1
,BANNER02,일반 배너 - 메인 중간 배너 2,/assets/img/banner/main_banner02.png,1
,BANNER03,일반 배너 - 메인 중간 배너 3,/assets/img/banner/main_banner03.png,1
,BANNER04,일반 배너 - 메인 중간 배너 4,/assets/img/banner/main_banner04.png,1
,BANNER05,일반 배너 - 메인 중간 배너 5,/assets/img/banner/main_banner05.png,1
,BNBOTTOM,일반 배너 - 메인 하단 배너,/assets/img/banner/main_bottom_banner.png,1
,BNBGLEFT,일반 배너 - PC 배경 좌측 배너,/assets/img/banner/pc_left_banner.png,1
,BNDETAIL,일반 배너 - 상품상세 배너,/assets/img/banner/productdetail_banner.png,1
```

***

### 로컬 개발 환경 구성하기&#x20;

기본 스킨을 코드 베이스로 개발하는 경우 참고하세요.

* aurora : <https://skins.shopby.co.kr/shopby/aurora-vanilla/-/blob/main/README.md>
* aurora react : <https://skins.shopby.co.kr/shopby/aurora-skin/-/blob/main/README.md>


# 스킨 디렉토리 구조

### 필수 항목

워크스페이스에서 제공하는 배포 프로세스를 이용하는 경우 디렉토리 구조 중 일부를 유지해야 정상적으로 서빙할 수 있습니다.&#x20;

* <mark style="background-color:yellow;">pc</mark>/<mark style="background-color:yellow;">mobile</mark> 소문자 등록
  * 디바이스 플랫폼 타입에 따라 <mark style="background-color:yellow;">pc</mark> 또는 <mark style="background-color:yellow;">mobile</mark> 하위에 존재하는 파일을 제공합니다.
* 메인페이지는 루트에 <mark style="background-color:yellow;">index.html</mark> (메인페이지)로 추가
  * <mark style="background-color:orange;">/</mark> 경로로 매핑되어 있는 파일명은 <mark style="background-color:yellow;">index.html</mark> 입니다.
  * 다른 파일명으로 추가 시 <mark style="background-color:yellow;">{쇼핑몰명}.shopby.co.kr</mark> 로 접근했을 때 흰 화면이 노출될 수 있습니다.&#x20;

```
📦 pc 혹은 mobile
└─ index.html
```

이 외에는 자유롭게 구성할 수 있습니다.&#x20;

***

### aurora 디렉토리 구조

aurora 스킨은 하기와 같은 디렉토리 구조를 갖습니다.&#x20;

```
📦 pc 혹은 mobile
├─ 🍱 assets
├─ callback
├─ core
├─ modals
├─ pages
├─ partials
├─ environment.json
├─ favicon.ico // 파비콘
├─ index.html // 메인페이지
├─ index.js // 메인페이지
├─ manifest.json // mobile 전용
└─ serviceWorker.js // mobile 전용
```

***

### assets

aurora 스킨에서 사용하는 이미지와 스타일 파일이 존재합니다.&#x20;

```
🍱 assets
├─ images
└─ styles
   ├─ pages
   ├─ custom-common.css
   ├─ main.css
   └─ shopby-skin-{mobile 혹은 pc}.css
```

* pages : 각 페이지별 스타일 파일
* main.css : 메인 페이지 스타일&#x20;
* shopby-skin-{pc 혹은 mobile}.css : 스킨에서 사용하는 공통 스타
  * 해당 파일은 읽기 전용 파일입니다.&#x20;
  * 임의 수정 시 레이아웃 및 공통으로 사용되는 스타일이 정상적으로 노출되지 않을 수 있습니다.&#x20;
* custom-common.css : 전체 페이지에 일괄 적용이 필요한 스타일을 정의해 사용할 수 있습니다.&#x20;

#### <mark style="color:purple;">**✓ 공통 스타일 로드 예시**</mark>&#x20;

```
<link rel="stylesheet" href="/assets/styles/shopby-skin-{pc 혹은 mobile}.css" />
<link rel="stylesheet" href="/assets/styles/custom-common.css" />
```

***

### callback

인증 혹은 결제 시 필요한 콜백 페이지를 정의합니다. 상세 내용은 페이지 별 개발 가이드를 참고해주세요.&#x20;

```
📦 callback
├─ auth-callback.html
├─ auth-callback.js
├─ kcp-callback.html
├─ kcp-callback.js
├─ my-pay-callback.html
└─ my-pay-callbakc.js
```

***

### core

스킨에서 필요한 코어 로직입니다. 상세 내용은 페이지 별 가이드를 참고해주세요.&#x20;

```
📦 core
├─ api-initialize-{pc 혹은 mobile}.js
├─ error.js
├─ external-service-config.js
├─ intro.js
├─ naver-marketing-config.js
└─ naver-pay.js
```

* api-initialize-{pc 혹은 mobile}.js : <mark style="background-color:yellow;">DOMContentLoaded</mark>시점에 플렛폼 타입에 따라 공통 데이터를 호출합니다.
  * pc : 'PC' 플랫폼 타입으로 호출
  * mobile : 'MOBILE\_WEB' 플랫폼 타입을 호출&#x20;
  * 공통 데이터&#x20;
    * 쇼핑몰 정보
      * [malls 몰 정보 조회하기 API 응답 값과 동일](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)
    * 약관 정보

      * 회사 소개, 이용약관, 개인정보 처리방침, 이용안내 4가지 항목을 기본으로 호출합니다.
      * 각 항목의 데이터는 [적용 중인 몰 약관 조회하기 API 응답 값과 동일](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms)합니다.

      ```
      const terms = [
          {MALL_INTRODUCTION : 적용 중인 몰 약관 조회하기 API 응답 값},
          {USE : 적용 중인 몰 약관 조회하기 API 응답 값},
          {PI_PROCESS : 적용 중인 몰 약관 조회하기 API 응답 값},
          {ACCESS_GUIDE : 적용 중인 몰 약관 조회하기 API 응답 값}
      ];
      ```
    * 게시판 설정 정보
      * [게시판 설정 조회하기 API 응답 값과 동일](https://docs.shopby.co.kr/?url.primaryName=manage/#/Board/get-board-config)합니다.
    * 결제 설정 정보
      * [주문 설정 값 가져오기 API 응답 값과 동일](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderConfiguration/get-order-configuration)
    * 배너 설정 정보
      * [사용 혹은 작업중 스킨 정보 및 배너 그룹 조회하기 API 응답 값과 동일](https://docs.shopby.co.kr/?url.primaryName=display/#/SkinBanner/get-skin-banners-groups-by-skin)
    * 회원정보(로그인 한 경우)
      * [회원정보 조회하기 API 응답 값과 동일](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile)
    * 플랫폼 타입 : PC 혹은 MOBILE\_WEB
* error.js
  * api 호출 및 스크립트 오류 발생 시 error.js 에서 공통으로 핸들링합니다.
  * [unhandledrejection](https://developer.mozilla.org/en-US/docs/Web/API/Window/unhandledrejection_event) 는 프로미스 오류 발생 시 호출되는 이벤트입니다.
  * [error](https://developer.mozilla.org/en-US/docs/Web/API/Window/error_event) 는 스크립트 오류 발생 시 호출되는 이벤트입니다.<br>

    ```
    window.addEventListener('unhandledrejection', handleRejection);
    window.addEventListener('error', handleError);
    ```

***

### modals

스킨에서 사용하는 레이어 모달이 정의되어 있습니다.

***

### pages

각 페이지가 정의된 디렉토리 입니다.\
상세 내용은 페이지별 개발 가이드를 참고해 주세요.&#x20;

***

### partials

페이지에서 부분적으로 삽입해야하는 부분을 제공합니다.\ <mark style="background-color:yellow;">partials</mark> 는 <mark style="background-color:yellow;">template</mark> 태그로 삽입해야 합니다.

#### <mark style="color:purple;">**✓ 예시**</mark>&#x20;

{% code overflow="wrap" %}

```
<!-- 메타정보 -->
<template shopby-partials="@partials/common-meta.html" shopby-partials-js="@partials/common-meta.js"></template>

<!-- 디자인팝업 -->
<template shopby-partials="@partials/design-popup.html" shopby-partials-js="@partials/design-popup.js"></template>

<!-- 공통 모달  (알럿, 컴펌 사용 시 필요)-->
<template shopby-partials="@partials/modal.html"></template>
```

{% endcode %}

***

### environment.json

서버에서 주입하는 파일이기 때문에 프로덕션에서는 디렉토리 내 존재할 필요가 없지만,\
로컬에서 서버를 구동하기 위해서는 필요한 파일입니다.&#x20;

```
{
   "clientId": "clientId",
   "profile": "real"
}
```

**clientId 세팅하기**

<mark style="background-color:yellow;">clientId</mark>는 각 쇼핑몰을 구분하는 값으로 shop API 호출 시 필수 request값입니다.\ <mark style="background-color:yellow;">{pc/mobile}/environment.json</mark> 에 부여받은 <mark style="background-color:yellow;">clientId</mark>를 기입합니다.

#### clientId **확인하기**

* shop by pro : <mark style="background-color:yellow;">쇼핑몰도메인/environment.json</mark> 에서 확인 가능\
  예) example.shopby.co.kr/environment.json
* shop by premium :
  * 서비스어드민 : <mark style="background-color:yellow;">서비스관리 > 쇼핑몰관리 > (쇼핑몰 선택) > 개발연동정보 > 클라이언트 아이디</mark>에서 확인 가능
* 쇼핑몰도메인/environment.json 에서 확인 가능\
  예) example.shopby.co.kr/environment.json


# 설치

스킨 저장소에 저장된 소스코드를 쇼핑몰 관리자에 설치할 수 있습니다.

<div align="left"><figure><img src="/files/lhLAVSv79l9koHyrtyZo" alt=""><figcaption></figcaption></figure></div>

### step 1. 쇼핑몰 관리자에 설치 <a href="#step1.-ec-87-bc-ed-95-91-eb-aa-b0-ea-b4-80-eb-a6-ac-ec-9e-90-ec-97-90-ec-84-a4-ec-b9-98" id="step1.-ec-87-bc-ed-95-91-eb-aa-b0-ea-b4-80-eb-a6-ac-ec-9e-90-ec-97-90-ec-84-a4-ec-b9-98"></a>

등록된 상품을 쇼핑몰 관리자에 설치하여 쇼핑몰에서 사용할 수 있습니다.\
쇼핑몰 관리자에서 사용 중인 스킨의 소스코드가 수정될 경우 쇼핑몰 프런트에도 수정된 내용이 즉시 반영됩니다.

#### 설치경로 <a href="#ec-84-a4-ec-b9-98-ea-b2-bd-eb-a1-9c" id="ec-84-a4-ec-b9-98-ea-b2-bd-eb-a1-9c"></a>

워크스페이스 > 셀러어드민 > 주문 > 디자인

**① 상품**\
셀러어드민에 등록된 스킨만 설치할 수 있습니다. 설치할 스킨이 노출되지 않는 경우 스킨 개발 프로세스를 참고하여 스킨 등록을 요청해 주시기 바랍니다.

**② 상품 유형**\
특정 쇼핑몰에 따라 선택한 스킨 상품 기반으로 추가 수정 작업이 필요한 경우 단순복사 + 디자인 수정을, 그렇지 않은 경우 단순복사로 선택해 주시기 바랍니다.

**③ 소스코드 제공 여부**\
소스코드 제공 여부에 따라 쇼핑몰 관리자에서 스킨을 복사할 수 있는 기능이 제공됩니다.\
제공 안 함: 복사 불가 / 제공함: 복사 가능

**④ 쇼핑몰 번호**\
쇼핑몰을 구분할 수 있는 고유 번호로 스킨을 설치할 쇼핑몰의 쇼핑몰 번호를 입력해 주셔야 합니다.\
\*쇼핑몰번호는 쇼핑몰 관리자 > 기본 정책 > 쇼핑몰 관리 화면에서 확인할 수 있습니다.

**⑤ 기본 도메인**\
쇼핑몰을 신청할 때 기본으로 발급되는 도메인으로 스킨을 설치할 쇼핑몰의 기본도메인을 입력해 주셔야 합니다.

{% hint style="info" %}
기본 도메인은 NHN커머스 마이페이지 > 쇼핑몰 관리 > 쇼핑몰 목록 화면에서 확인할 수 있습니다.
{% endhint %}

위 항목을 입력 후 등록하면 요청한 일시 기준으로 주문 데이터가 생성됩니다.\
상품 유형이 단순복사인 경우에는 자동으로 설치되지만, 단순복사+디자인 수정인 경우 수정 작업이 완료된 이후 설치에 필요한 정보를 입력해 주셔야 설치가 진행됩니다.\
생성된 주문 데이터의 처리상태를 통해 설치 성공여부를 확인할 수 있습니다. 설치에 실패한 경우 실패사유를 확인한 후 다시 시도해 주셔야 합니다.

### step 2. 스킨 설치 완료 <a href="#step2.-ec-8a-a4-ed-82-a8-ec-84-a4-ec-b9-98-ec-99-84-eb-a3-8c" id="step2.-ec-8a-a4-ed-82-a8-ec-84-a4-ec-b9-98-ec-99-84-eb-a3-8c"></a>

이후 "등록" 버튼 클릭 시, 설치를 요청한 일시 기준으로 주문 데이터가 생성됩니다.

(참고) 상품 유형이 "단순복사"인 경우에는 자동으로 설치되지만, "단순복사+디자인 수정"인 경우 수정 작업이 완료된 이후 설치에 필요한 정보를 입력해 주셔야 설치가 진행됩니다.\
(참고) 생성된 주문 데이터의 처리상태를 통해 설치 성공여부를 확인할 수 있습니다. 설치에 실패한 경우 실패사유를 확인한 후 다시 시도해 주셔야 합니다.

설치가 완료된 스킨은 쇼핑몰 어드민(관리자) 내 \[디자인> 디자인 관리> 디자인 스킨 리스트> 보유 스킨]에서 확인이 가능합니다.

### step 3. "사용 스킨"으로 변경 <a href="#step3.-22-ec-82-ac-ec-9a-a9-ec-8a-a4-ed-82-a8-22-ec-9c-bc-eb-a1-9c-eb-b3-80-ea-b2-bd" id="step3.-22-ec-82-ac-ec-9a-a9-ec-8a-a4-ed-82-a8-22-ec-9c-bc-eb-a1-9c-eb-b3-80-ea-b2-bd"></a>

실제로 해당 설치된 스킨은 "사용 스킨"이 아닌 "보유 스킨"으로 설치되었으므로\
해당 쇼핑몰 어드민(관리자)에서 쇼핑몰 운영자가 직접 사용스킨으로 변경처리 필요합니다.


# 기본 API 이해하기

샵바이 API의 기초 개념과 공통적으로 사용되는 주요 API를 소개합니다.

* [샵바이 API 호출 가이드](/aurora-guide/api/shopbyapi)
* [외부 스크립트 호출 가이드](/aurora-guide/api/script)


# 샵바이 API 호출 가이드

이 문서는 샵바이 API의 기초 정보와 호출 방법을 소개합니다.

* [샵바이 API 호출 및 연동 개념](#api)
* [샵바이 API 공통 파라미터(Parameters)](#api-parameters)
* [로그인 상태 구분](#undefined-2)
* [쇼핑몰 기본 정보 호출](#undefined-3)

***

### 샵바이 API 호출 및 연동 개념

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

샵바이 API는 RESTful한 아키텍쳐로서 표준 HTTP Request Method, 리소스를 예측할 수 있는 엔드포인트 URL, HTTP 코드 기반의 에러 메시지를 제공합니다. \
스킨은 샵바이 솔루션에서 제공하는 샵바이 API를 RESTful한 방식으로 호출하여 어드민과 연동합니다.&#x20;

#### 용어소개

#### **■  shop API**&#x20;

NHN커머스에서 제공하는 오픈 소스입니다. \
고객들이 접근하는 쇼핑몰 사이트 화면을 구성할 수 있습니다.&#x20;

#### ■ 스킨(skin)

쇼핑몰 고객들이 보는 쇼핑몰 프론트 화면 디자인 (템플릿, 레이아웃)을 뜻합니다.

#### ■ 어드민(admin)

쇼핑몰 운영자님이 사용하는 화면으로 상품, 주문, 회원 관리 등 쇼핑몰을 관리하는 화면입니다.

***

### 샵바이 API 공통 파라미터(Parameters)

모든 샵바이 API는 Request header 에 아래 3개의 파라미터(Parameters)를 필수 값(required)으로 넣어야 합니다. Request 파라미터는 API별로 상이하나, 아래 3가지 항목은 모든 API에서 공통적으로 요구됩니다.

* **Version**
  * API 버전 (샵바이는 1.0 버전으로 API를 제공하고 있으며, 버전이 다른 API의 경우 문서 제목의 버전을 참고 바랍니다.)
* **clientId**
  * 클라이언트 아이디로서, 쇼핑몰 사이트를 출력하기 위해 할당된 각 상점의 쇼핑몰 구분 값(프론트에서 API호출 시 해당하는 쇼핑몰을 판단할 수 있는 key값)
  * shop by pro : 도메인/environment.json 으로 확인 가능
    * 예) example.shopby.co.kr/environment.json
  * shop by premium
    * (방법1) 서비스어드민 > 서비스관리 > 쇼핑몰관리 > (쇼핑몰 선택) > 개발연동정보 > 클라이언트 아이디에서 확인 가능
    * (방법2) 스킨 사용할 경우 : 도메인/environment.json 으로 확인 가능
      * 예) example.shopby.co.kr/environment.json
* **platform**
  * 현재 실행 플랫폼으로서, 쇼핑몰 사이트를 출력하는 디바이스 기준 (PC, MOBILE\_WEB, AOS, IOS)

#### <mark style="color:purple;">**✓ 예시코드**</mark>

아래는 Request header 에 필수 값 3개를 입력하여 호출하는 예제 코드이며, 모든 샵바이 API 를 호출할 때 실행됩니다.&#x20;

```
1
2          const requestInit = {
3            method,
4            headers: {
5              platform: 'PC',
6              clientId: shopby.config.skin.clientId,
7              Version: '1.0',
8            }, 
9            body: isFormData ? requestBody : JSON.stringify(requestBody),
10          };
11
```

***

### 로그인 상태 구분

쇼핑몰에서는 회원(member)과 비회원(guest)을 판별하기 위해, 로그인 상태 여부를 구분하는 것이 중요합니다. 앞으로 소개 드릴 화면별 설명에서는, 고객이 로그인을 했는지(=회원) 또는 하지 않았는지(=비회원)에 따라 사용되는 API가 다를 수 있으므로, 로그인 상태 여부를 판단하는 로직에 대해 소개하겠습니다.

<div align="left"><figure><img src="/files/BZhNf4DH0D09OvcwcdNR" alt="" width="489"><figcaption></figcaption></figure></div>

샵바이에서는 OAuth2 기반의 로그인 방식을 사용합니다. 액세스 토큰(accesssToken)과 리프레시 토큰(refreshToken)을 이용하여 로그인 상태를 구분할 수 있으며, 액세스 토큰과 리프레시 토큰의 유효기간 및 샵바이 API의 에러 응답 값에 따라 로그인 상태가 결정됩니다.&#x20;

직접 shop API 호출 시 OAuth 2.0을 적용하는 방법은 [OAuth 2.0 적용 가이드](/aurora-guide/api/shopbyapi/oauth2.0)에서 확인하실 수 있습니다.&#x20;

<div align="left"><figure><img src="/files/OYxUhejTL5vz05NU3vHM" alt=""><figcaption></figcaption></figure></div>

OAuth2 방식이 적용되지 않은 고객들은 액세스 토큰(accessToken) 기반의 로그인 방식을 사용합니다.\
기본적으로 액세스 토큰의 존재 유무에 따라 로그인 상태를 구분할 수 있으며, 그 외 액세스 토큰 의 유효 기간 및 샵바이 API의 에러 응답 값에 따라 로그인 상태가 결정됩니다.&#x20;

엑세스 토큰 발급 API 등 보다 자세한 내용은 [로그인화면](/aurora-guide/api-1/sign-in) 문서를 확인하시길 바랍니다.&#x20;

***

### 쇼핑몰 기본 정보 호출

#### ■ API 호출 과정

* step 1 : CDN에서 몰 정보 조회하기
* step 2-1 : CDN에 몰 정보가 존재하는 경우, 해당 정보를 사용
* step 2-2 : CDN에 몰 정보가 없는 경우, <mark style="background-color:yellow;">GET/malls</mark> 호출

#### ■ CDN 호출 정보

* URI : clientId 와 전체 주소를 모두 인코딩을 해야 CDN에 저장된 정보에 올바르게 접근할 수 있습니다.

{% code overflow="wrap" fullWidth="false" %}

```
1
2            const uri = encodeURI('https://rlgkd0v7e.toastcdn.net/mall-configurations/${profile}/${encodeURIComponent(clientId)}/mallInfo.js')
3
```

{% endcode %}

* dataType: <mark style="background-color:yellow;">jsonp</mark>
* jsonpCallback: <mark style="background-color:yellow;">getMalls</mark> (임의 수정 불가)

#### <mark style="color:purple;">**✓ 예시코드**</mark>

{% code overflow="wrap" %}

```
1
2            const cdnUri = encodeURI('https://rlgkd0v7e.toastcdn.net/mall-configurations/real/${encodeURIComponent(상점의 clientId 를 입력하세요)}/mallInfo.js');
3
4            $.ajax({
5              url: cdnUri,
6              jsonpCallback: 'getMalls',
7              dataType: 'jsonp',
8              success: function (malls) }
9            // cdn 에 정보가 있는 경우 여기서 malls 정보를 처리하세요.
10            }, error: function () {
11            // cdn 에 없는 경우 기존에 사용하고 있었던 getMalls api 를 직접 호출하여 malls 정보를 받아 처리하세요. },
12            });
13
```

{% endcode %}

#### ■ GET/malls

쇼핑몰 기본 정보를 호출할 수 있는 `GET/malls`을 소개합니다. \
해당 API는 쇼핑몰 어느 화면에서든 공통적으로 필요한 기본 API입니다.

> [GET /malls](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)\
> ► 쇼핑몰 기본 정보 조회하기\
> (쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.)

해당 API는 쇼핑몰 명, 회원가입 시 설정 값, 푸터 영역에 명시하는 쇼핑몰 기본 정보, 네이버웹마스터 설정 값, 구글 에널리틱스 설정 값 등의 데이터를 포함합니다.

기본 스킨에서는 호출된 Responses의 리턴 값을 모두 사용하고 있으며, 각 리턴 값이 어느 화면에서 사용되었는지는 이후 진행될 문서에서 화면별로 다시 소개합니다.&#x20;


# OAuth 2.0 적용 가이드

샵바이 API 호출 시 OAuth 2.0 적용 방법을 안내합니다.

### 🤖 기능

OAuth 2.0은 accessToken과 refreshToken을 사용하여 인증 상태를 관리하게 됩니다.\
기본 스킨에서 OAuth 2.0은 다음과 같이 동작합니다.

<div align="left"><figure><img src="/files/VF0GKPo8hm3caqc17F22" alt="" width="489"><figcaption></figcaption></figure></div>

* 만료된 accessToken으로 shop API 요청을 보내는 경우, accessToken을 갱신하고 갱신된 accessToken으로 API를 호출하게 됩니다.
* accessToken과 refreshToken이 모두 만료된 경우, 토큰이 갱신되지 않으며, <mark style="background-color:yellow;">만료된 리프레시 토큰입니다.</mark> 라는 문구가 노출되고 로그인 페이지로 이동합니다.

기본 스킨에서 제공하는 것을 사용하지 않고 직접 shop API를 호출하는 경우, OAuth 2.0의 토큰 갱신/재요청 처리를 위해 별도로 처리가 필요합니다.

#### **🖇️ 관련 문서**

* 오로라(PC+모바일) 개별형 스킨 \
  [v.1.4.3 릴리즈노 노트 바로가기](https://nhnent.dooray.com/share/pages/mBkooLTRTNCCyxUNdS9_HA/3920961448422344871)
* 오로라 리액트 통합형 스킨 \
  [v.1.7.2 릴리즈 노트 바로가기](https://skins.shopby.co.kr/shopby/aurora-skin/-/releases/v1.7.2)\
  [v.1.7.3 릴리즈 노트 바로가기<br>](https://skins.shopby.co.kr/shopby/aurora-skin/-/releases/v1.7.3)
* shop API 문서\
  [OAuth 2.0 API 바로가기](https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2)

shop API를 직접 호출하여 사용하는 경우, OAuth 2.0 적용 방법에 관한 내용입니다. 오로라 스킨을 기준으로 OAuth 2.0을 위해 별도 처리가 필요한 부분 위주로 안내합니다.

오로라 리액트 스킨을 사용하시는 경우, shop API를 호출하실 때, fetchHttpRequest를 사용해 주시면 OAuth 2.0을 별도 처리 없이 적용하실 수 있습니다. refreshToken 만료 시 토큰 만료 alert가 노출되지 않는다면 try/catch로 catchError 처리가 필요할 수 있습니다.

### 📝 내용

shop API를 직접 호출하여 사용하는 경우, OAuth 2.0 적용 방법에 관한 내용입니다. 오로라 스킨을 기준으로 OAuth 2.0을 위해 별도 처리가 필요한 부분 위주로 안내합니다.

오로라 리액트 스킨을 사용하시는 경우, shop API를 호출하실 때, fetchHttpRequest를 사용해 주시면 OAuth 2.0을 별도 처리 없이 적용하실 수 있습니다. \
refreshToken 만료 시 토큰 만료 alert가 노출되지 않는다면 try/catch로 catchError 처리가 필요할 수 있습니다.

***

shopby의 API는 baseURL 값으로 shop API인지 구분합니다. shop API 요청 시 옵션으로 보내는 baseURL 값에 따라서 OAuth 2.0 적용을 위해 처리해야 하는 범위가 달라집니다.

### 1. baseURL이 shop API인 경우 <a href="#id-1.-baseurl-ec-9d-b4-shop-api-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="id-1.-baseurl-ec-9d-b4-shop-api-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

**제공범위**

* shop API 요청 시 <mark style="background-color:yellow;">Shop-By-Authorization</mark> 헤더를 보내지 않더라도, <mark style="background-color:yellow;">Shop-By-Authorization</mark> 헤더로 accessToken 값을 보내줍니다.
* 만료된 accessToken으로 API를 요청한 경우, accessToken이 갱신됩니다.

**추가 처리 필요 범위**

1. accessToken이 갱신된 이후, 재요청 처리가 필요합니다.
   * API의 응답이 401 에러로 발생할 때, 요청한 API를 동일하게 다시 호출해 주시면 갱신된 토큰으로 재요청됩니다.
2. 토큰 갱신 시도 시 accessToken/refreshToken이 모두 만료된 경우, 토큰 만료 alert가 노출되어야 합니다.
   * 만약 토큰 만료 alert가 노출되지 않는다면 try/catch에서 해당 에러에 대한 처리가 필요할 수 있습니다.

**유의 사항**

* accessToken 갱신의 경우, API가 초기화된 이후에 실행해야 에러 없이 동작하게 됩니다. 만약 <mark style="background-color:yellow;">Cannot read properties of null (reading 'auth')</mark>과 같은 에러가 발생하게 된다면 이는 API가 초기화되지 않은 시점에 실행된 것입니다.
* 해당 경우에는 아래 코드 예시와 같이 EventManager에서 'PAGE\_LOAD\_COMPLETED' 라는 이벤트에 등록하여 처리해 주시면 됩니다.

<mark style="color:purple;">**✓ 예시코드**</mark>

{% code overflow="wrap" fullWidth="false" %}

```
...
const fetchShopApiWithBaseURL = async () => {
  const fetchProfileApi = async () => {
    const host = 'https://shop-api.e-ncp.com';
    
    // baseURL이 shop API인 경우
    const res = await fetch(`${host}/profile`, {
      ...
      baseURL: host,
    });
    if (!res.ok) {
      throw await res.json();
    }

    return res;
  };
  try {
    await fetchProfileApi();
  } catch (error) {
    if (error.status === 401) {
      // API 재요청
      await fetchProfileApi();
    } else {
      throw error;
    }
  }
}; 
  
...

// API가 초기화되지 않은 시점에서 실행 시 에러가 발생할 수 있습니다. 에러가 발생한다면 아래와 같이 API 초기화 이후에 실행될 수 있도록 처리하실 수 있습니다.
ShopbySkin.EventManager.on('PAGE_LOAD_COMPLETED', () => {
  fetchShopApiWithBaseURL();
});
...
```

{% endcode %}

### 2. baseURL이 다른 값이거나 미포함 시 <a href="#id-2.-baseurl-ec-9d-b4-eb-8b-a4-eb-a5-b8-ea-b0-92-ec-9d-b4-ea-b1-b0-eb-82-98-eb-af-b8-ed-8f-ac-ed-95-a8" id="id-2.-baseurl-ec-9d-b4-eb-8b-a4-eb-a5-b8-ea-b0-92-ec-9d-b4-ea-b1-b0-eb-82-98-eb-af-b8-ed-8f-ac-ed-95-a8"></a>

**제공범위**

* 일반적인 API 호출과 동일하게 동작합니다.
  * <mark style="background-color:yellow;">Shop-By-Authorization</mark> 헤더에 accessToken 값이 자동으로 보내지지 않습니다.
  * 만료된 accessToken으로 API를 요청하더라도, accessToken 갱신이 되지 않습니다.

**추가 처리 필요 범위**

1. shop API 요청 시 <mark style="background-color:yellow;">Shop-By-Authorization</mark> 헤더에 accessToken을 보내줘야 합니다.
2. accessToken이 만료된 경우, accessToken 갱신이 필요합니다.
   * accessToken 갱신을 처리하실 때 해당 함수를 사용하여 처리해 주시면 됩니다.
     * <mark style="background-color:yellow;">ShopbySkin.utils.renewAccessToken()</mark>
3. accessToken이 갱신된 이후, 재요청 처리를 해줘야 합니다.
4. 토큰 갱신 시도 시 accessToken/refreshToken 이 모두 만료된 경우, 토큰 만료 alert가 노출되어야 합니다.
   * 만약 토큰 만료 alert가 노출되지 않는다면 try/catch에서 해당 에러에 대한 처리가 필요할 수 있습니다.

**유의사항**

* accessToken 갱신의 경우, API가 초기화된 이후에 실행해야 에러 없이 동작하게 됩니다. 만약 <mark style="background-color:yellow;">Cannot read properties of null (reading 'auth')</mark>과 같은 에러가 발생하게 된다면 이는 API가 초기화되지 않은 시점에 실행된 것입니다.
* 해당 경우에는 아래 코드 예시와 같이 EventManager에서 'PAGE\_LOAD\_COMPLETED' 라는 이벤트에 등록하여 처리해 주시면 됩니다.

<mark style="color:purple;">**✓ 예시코드**</mark>

{% code overflow="wrap" %}

```
...
const fetchShopApiWithOutBaseURL = async () => {
  const fetchProfileApi = async () => {
    const headers = {
      'Shop-By-Authorization': `Bearer ${accessToken}`,
      ...,
    };
    
    const host = 'https://shop-api.e-ncp.com';
    
    // baseURL이 없는 경우
    const res = await fetch(`${host}/profile`, {
      headers,
    });
    if (!res.ok) throw await res.json();

    return res;
  };
  try {
    await fetchProfileApi();
  } catch (error) {
    if (error.status === 401) {
      // 토큰 갱신 처리 - PUT /oauth2 토큰 갱신하기 shop api 호출
      await ShopbySkin.utils.renewAccessToken();
        
      // API 재요청 처리
      await fetchProfileApi();
    } else {
      throw error;
    }
  }
};

...

// API가 초기화되지 않은 시점에서 실행 시 에러가 발생할 수 있습니다. 에러가 발생한다면 아래와 같이 API 초기화 이후에 실행될 수 있도록 처리하실 수 있습니다.
ShopbySkin.EventManager.on('PAGE_LOAD_COMPLETED', () => {
  fetchShopApiWithOutBaseURL();
});
...
```

{% endcode %}


# 외부 스크립트 호출 가이드

어드민에서 설정한 외부 스크립트와 앱 개발사가 추가한 외부 스크립트를 쇼핑몰에 적용할 수 있도록 개발하는 방법을 안내합니다.

### 외부 스크립트 설정하기

외부 스크립트를 추가할 수 있는 방법은 두가지 입니다.

#### 1. 관리자 > 외부 스크립트 설정에서 추가하기 &#x20;

쇼핑몰에 적용할 스크립트를 설정할 수 있는 기능을 제공합니다.

```
샵바이 베이직/프로 : 설정 > 기본정책 > 외부서비스 설정
샵바이 프리미엄 : 서비스 관리 > 외부 서비스 설정
```

#### 2. 앱 개발사 > server api 로 추가하기&#x20;

쇼핑몰에서 앱 설치 시 등록된 스크립트가 실행되어야 합니다.&#x20;

***

### 쇼핑몰에 외부 스크립트 조회하기&#x20;

두가지 방법으로 등록된 외부 스크립트를 모두 조회해야 정상적으로 외부 스크립트가 실행됩니다.&#x20;

<mark style="background-color:yellow;">어드민 (관리자)</mark>에서 설정한 외부 스크립트를 호출하는 API 입니다.&#x20;

> [GET /page/scripts](https://docs.shopby.co.kr/?url.primaryName=manage/#/Page/search-external-script)\
> ► 외부 스크립트 조회하기\
> 쇼핑몰에서 사용 중인 외부 스크립트 리스트를 불러옵니다.

<mark style="background-color:yellow;">앱 개발사</mark>에서 직접 등록한 외부 스크립트를 호출하는 API 입니다.&#x20;

> [GET /external-scripts](https://docs.shopby.co.kr/?url.primaryName=workspace/#/ExternalScript/get-external-scripts)
>
> ► 외부 스크립트 조회하기\
> 쇼핑몰에서 사용중인 외부 스크립트 리스트를 불러옵니다.&#x20;

{% hint style="info" %}
6월 경, [GET /page/scripts](https://docs.shopby.co.kr/?url.primaryName=manage/#/Page/search-external-script) 가 1.1 버전으로 업그레이드됩니다.&#x20;

1.1 버전에서는 어드민 스크립트와 외부 스크립트로 등록된 모든 스크립트를 한 번에 조회할 수 있습니다.\
1.1 버전 업그레이드 시 기본 스킨에도 적용할 예정입니다.
{% endhint %}

상기 API를 호출하면, 스크립트 내용을 담은 객체들이 배열에 담긴 형태로 응답 값이 옵니다.\
해당 객체가 갖고 있는 속성들의 의미는 다음과 같습니다.&#x20;

* deviceType : 스크립트를 적용하고자 하는 디바이스 타입
* pageType : 스크립트를 적용하고자 하는 위치 (ENUM)
* pageTypeLabel : pageType을 한글로 해석한 값
* content : 스크립트 본문

<mark style="background-color:yellow;">deviceType</mark> 과 <mark style="background-color:yellow;">pageType</mark>을 참고하여, \
적절한 위치에서 content가 실행될 수 있도록 개발이 진행되어야합니다.\ <mark style="background-color:yellow;">deviceType</mark>으로 올 수 있는 값들은 'PC', 'Mobile' 두 가지이며,\ <mark style="background-color:yellow;">pageType</mark>으로 올 수 있는 값들은 다음과 같습니다.

<table><thead><tr><th width="280.3333333333333">ENUM 명</th><th width="256">적용 페이지</th><th>소스 위치</th></tr></thead><tbody><tr><td>COMMON_HEAD</td><td>모든 화면</td><td>header 태그 내부 끝</td></tr><tr><td>COMMON_FOOTER</td><td>모든 화면</td><td>body 태그 내부 끝</td></tr><tr><td>MAIN</td><td>메인 화면</td><td>body 태그 내부</td></tr><tr><td>DISPLAY_SECTION</td><td>메인분류 상품조회 화면</td><td>body 태그 내부</td></tr><tr><td>PRODUCT</td><td>상품 상세화면</td><td>body 태그 내부</td></tr><tr><td>PRODUCT_LIST</td><td>상품 리스트 화면</td><td>body 태그 내부</td></tr><tr><td>PRODUCT_SEARCH</td><td>상품 검색결과 화면</td><td>body 태그 내부</td></tr><tr><td>MEMBER_JOIN_COMPLETE</td><td>회원가입 완료 화면</td><td>body 태그 내부</td></tr><tr><td>CART</td><td>장바구니 화면</td><td>body 태그 내부</td></tr><tr><td>ORDER</td><td>주문서 작성 화면</td><td>body 태그 내부</td></tr><tr><td>ORDER_COMPLETE</td><td>주문 완료 화면</td><td>body 태그 내부</td></tr><tr><td>ORDER_DETAIL</td><td>마이페이지 내 주문 상세 화면</td><td>body 태그 내부</td></tr><tr><td>MY_PAGE</td><td>마이페이지</td><td>body 태그 내부</td></tr></tbody></table>

예를 들어 하기와 같은 응답값이 들어왔다고 가정하면,

```
1
2    scriptContents: [{
3      deviceType: 'PC',
4      pageType: 'CART',
5      pageTypeLabel: (생략),
6      content: '<script>console.log('샵바이 CART')</script>'
7    },
8    {
9      deviceType: 'Mobile',
10      pageType: 'COMMON_HEAD',
11      pageTypeLabel: (생략),
12      content: '<script>console.log('샵바이 COMMON_HEAD')</script>'
13    }, ]
14
```

1. PC 몰 - 장바구니 페이지의 window\.document.body 내부에 *'*<mark style="background-color:yellow;">\<script>console.log('샵바이 CART')\</script>'\</span></mark>소스가 들어갈 수 있게 해야 하며,
2. Mobile 몰 - 모든 페이지의 window\.document.head 내부 맨 끝에 *'*<mark style="background-color:yellow;">\<script>console.log('샵바이 COMMON\\\_HEAD')\</script>\</span></mark>*'* 소스가 들어갈 수 있게 해야 합니다.\
   단, 해당 소스를 넣기 전 **글로벌 변수**를 먼저 세팅해야 합니다.

***

### 외부 스크립트 실행 순서&#x20;

외부 스크립트는 공통 상단, 페이지별, 공통 하단으로 위치를 지정할 수 있습니다.\
각 위치에 삽입된 스크립트는 <mark style="background-color:yellow;">공통 상단 -> 페이지별 -> 공통 하단</mark> 순으로 실행되어야 합니다.&#x20;

***

### 글로벌 변수 세팅

외부 스크립트를 설정할 때 몰의 정보 (ex. 장바구니 데이터)를 이용한 스크립트도 사용할 수 있도록 쇼핑몰에 글로벌 변수들을 세팅해야 합니다.&#x20;

이 글로벌 변수들은 추후 외부 App용 스크립트에서도 사용될 수 있습니다.\
세팅해야 하는 변수는 [쇼핑몰 관리자 내 외부스크립트 변수 조회 가이드](https://admin-remote.shopby.co.kr/popup/variable-guide)에서 확인할 수 있습니다.&#x20;


# 화면별 API 활용 가이드

쇼핑몰 개발을 위해 각 화면별 가이드 문서를 확인해 주세요. !&#x20;

* 공통 영역
  * 공통 상단
  * 공통 하단
  * 디자인 팝업
  * 슬라이드 메뉴 (모바일 전용)
  * 최근 본 상품
* 메인 화면
  * 배너 영역
  * 상품진열 영역
  * 인스타그램 연동
* 회원가입
* 로그인
* 간편 로그인
* 휴대폰 본인인증
* 상품 리스트
* 상품 상세
  * 상품 기본정보
* 장바구니
* 주문서
* 마이페이지 > 쇼핑정보
  * 주문 목록
  * 주문 상세&#x20;
  * 좋아요
* 마이페이지 > 혜택관리
  * 쿠폰
  * 적립금
* 마이페이지 > 회원정보
  * 회원정보 수정
  * 배송지 관리
  * 회원탈퇴
* 마이페이지 > 나의 게시글

  * 1:1문의
  * 상품문의
  * 상품후기


# 공통 영역

쇼핑몰 내에서 화면이 바뀌어도, 계속 유지되는 요소를 공통 화면으로서 소개합니다

* #### [공통 상단](/aurora-guide/api-1/common/header)
  * 로고 배너
  * 장바구니 개수
  * 전체 카테고리 *<mark style="background-color:orange;">PC</mark>*<br>

* #### [공통 하단](/aurora-guide/api-1/common/footer)
  * 쇼핑몰 정보
  * 약관 (회사소개, 이용약관, 개인정보처리방침, 이용안내)
  * 게시판 *<mark style="background-color:orange;">PC</mark>*
  * 하단 바 *<mark style="background-color:green;">Mobile</mark>*<br>

* #### [디자인 팝업](/aurora-guide/api-1/common/design-popup)

* #### [슬라이드 메뉴 (모바일 전용)](/aurora-guide/api-1/common/slide-menu)
  * 로그인
  * 카테고리
  * 기획전
  * 게시판<br>

* #### [최근 본 상품](/aurora-guide/api-1/common/recent-product)


# 공통 상단

헤더 (Header, 쇼핑몰 공통 상단) 영역

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

상단 바 영역에서 API를 호출하여 화면을 구성해야 하는 요소는 아래 3가지 입니다.

* ⓐ 로고 배너
* ⓑ 장바구니 개수
* ⓒ 전체 카테고리 *<mark style="background-color:orange;">PC</mark>*
* ⓓ MY메뉴 > 1:1문의 버튼(PC)

#### ■ ⓐ 로고 배너

배너 영역 문서에서 소개하는 API 입니다.\
해당 배너 리스트 데이터에 쇼핑몰 로고(Logo)가 포함되어 있습니다.\
로고의 경우 화면이 바뀌어도 대부분의 스킨에서 고정된 자리에 위치해 있기 때문에, 사실상 모든 화면에서 지속적으로 사용되는 API 입니다.

* [배너영역 ](https://workspace-help.nhn-commerce.com/undefined-1/api-1/undefined-1/undefined)

#### ■ ⓑ 장바구니 개수

장바구니 기능은  쇼핑몰 회원 여부와 상관없이 제공합니다.\
단, 회원인 경우에만 API를 호출하여 비회원인 경우 API 호출이 아닌 localStorage에 자체적으로 저장합니다.

* 회원 (member)

> [**GET /cart**](https://docs.shopby.co.kr/?url.primaryName=order/#/Cart/get-cart)
>
> ► 장바구니 개수 조회하기 \
> 로그인 회원의 장바구니 개수를 조회합니다.&#x20;

* 비회원(guest)
  * 비회원의 경우에도 장바구니 버튼을 제공합니다. 단, API 호출이 아닌 localStorage 내 비회원 장바구니 데이터를 자체적으로 관리해야 합니다.

#### ■ ⓒ 전체 카테고리 *<mark style="background-color:orange;">PC</mark>*

> [**GET /categories**](https://docs.shopby.co.kr/?url.primaryName=display/#/Category/get-categories-by-keyword)
>
> ►전체 카테고리 조회하기\
> 쇼핑몰의 카테고리를 조회합니다.&#x20;

쇼핑몰 화면에서 카테고리란, 화면이 바뀌어도 대부분의 경우 화면에 상시 노출되는 요소입니다.

아래 2가지 형태의 카테고리 데이터를 제공합니다.

* flatCategories : 모든 카테고리를 하나의 배열에 쭉 나열한 형태
* multiLevelCategories : 계층을 가지는 카테고리 형태 (최대 5depth)

오로라 개별형 기본 스킨에서는 2depth까지 리스팅되어 출력되며,\
카테고리 상품 리스트에서는 5depth까지 표기됩니다.&#x20;

```
shop by basic/pro: 상품> 상품 분류관리> 전시 카테고리 관리
shop by premium: 전시관리 > 전시 카테고리 관리
```

#### ■ ⓓ MY메뉴 > 1:1문의 버튼(PC)

MY 버튼 hover 시 노출되는 메뉴중 1:1문의 메뉴는 어드민에서 사용설정을 통해 노출이 결정됩니다.


# 공통 하단

### 푸터 **(Footer, 쇼핑몰 하단) 영역**

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

* ⓐ 쇼핑몰 정보
* ⓑ 약관 (회사소개, 이용약관, 개인정보처리방침, 이용안내)
* ⓒ 게시판 *<mark style="background-color:orange;">PC</mark>*

쇼핑몰 하단 푸터 영역에 필수적으로 기재해야 할 법적 필수 항목은 다음과 같습니다. &#x20;

{% hint style="info" %}
법적 필수항목

* 상호 및 대표자 이름
* 사업장 주소 (소재지)
* 연락처 (대표번호, 이메일)
* 개인정보관리책임자
* 사업자등록번호
* 통신판매업신고번호
* 이용약관
* 개인정보취급방침
* 호스팅제공자 : 전자상거래법 규정에 따라 호스팅서비스 제공자 상호를 표시하도록 의무화되어 있습니다.
  * 호스팅제공자 : 엔에이치엔커머스(주)
  * Hosting by 엔에이치엔커머스(주)
* 에스크로 인증마크
  {% endhint %}

#### ■ ⓐ 쇼핑몰 정보

> [GET /malls](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)
>
> ► 몰 정보 조회하기\
> 쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.&#x20;

#### ■ ⓑ 약관 (회사소개, 이용약관, 개인정보처리방침, 이용안내)&#x20;

> [GET /terms](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms)
>
> ► 몰 약관 조회하기\
> 쇼핑몰에 적용 중인 몰 약관을 조회합니다.

```
shop by basic/pro: 설정 > 기본정책 > 약관/개인정보처리방침 관리
shop by premium: 서비스관리 > 약관/개인정보처리방침 관리
```

termsTypes 으로 각 약관 내용을 구분합니다.

* 쇼핑몰/회사소개 : MALL\_INTRODUSTION
* 이용약관 : USE
* 개인정보처리방침 : PI\_PROCESS
* 이용안내 : ACCESS\_GUIDE

해당 API는 푸터 영역 뿐만 아니라 회원가입, 회원탈퇴 및 주문서 구매 동의 화면에서도 활용됩니다.

#### ■ ⓒ 게시판 *<mark style="background-color:orange;">PC</mark>*

> [GET /boards/corigurations](https://docs.shopby.co.kr/?url.primaryName=manage/#/Board/get-board-config)
>
> ► 게시판 설정 조회하기\
> 전체 게시판의 설정 정보를 조회합니다.

* 일반 게시판 설정 : boardConfigs

푸터 영역의 일반 게시판 메뉴에서는 일반 게시판 사용 설정이 '사용함'인 게시판 리스트를 모두 노출합니다.

일반 게시판은 공지사항, FAQ, 자유게시판, 이벤트/혜택, 메모게시판을 의미합니다.\
쇼핑몰 어드민 아래 경로에서 관리할 수 있습니다.

```
shop by basic/pro: 게시판 > 게시판 관리 > 게시판 리스트
shop by premium: 운영관리 > 게시판 관리 
```

아래 3가지 게시판의 경우, 쇼핑몰 고객이 [마이페이지 > 나의 게시글](/aurora-guide/api-1/mypage-post) 에서 관리할 수 있습니다.&#x20;

* 1:1문의 설정 : inquiryConfig
* 상품문의 설정 : productInquiryConfig
* 상품후기 설정 : productReviewConfig

***

### 하단 바  *<mark style="background-color:green;">Mobile</mark>*

<div align="left"><figure><img src="/files/Hgj406YO990Fh1B9Yw4w" alt="" width="375"><figcaption></figcaption></figure></div>

하단 바 영역에는 홈 버튼, 검색 영역, 마이페이지, 최근 본 상품 버튼이 있습니다.\
해당 항목들은 API를 별도 호출하지 않는 부분으로서 프론트 화면 커스텀이 가능합니다.&#x20;


# 디자인 팝업

### 공통설정

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

공통설정으로 추가한 팝업은 [GET /display/popups 전체 팝업 목록 조회하기](https://docs.shopby.co.kr/?url.primaryName=display/#/Popup/get-popups)를 호출해 페이지 유형으로 조회해서 개발할 수 있습니다.

> 페이지 유형은 API 상세보기를 통해 확인하세요.

### 개별설정

<figure><img src="/files/WzuS58jaMXhIYZcN18Zg" alt=""><figcaption><p>특정 상품의 상품상세 페이지에서만 팝업을 노출하게하는 예시</p></figcaption></figure>

개별 설정을 통해 파라메터 조건에따라 팝업을 노출할 수 있습니다.\
개별설정으로 추가한 팝업은 [POST /design-popups 디자인 팝업 조회하기](https://docs.shopby.co.kr/?url.primaryName=display/#/Popup/get-design-popup)를 호출해서 개발할 수 있습니다.

아래 주소로 접근시에만 해당 팝업이 노출됩니다.

<div align="left"><figure><img src="/files/zha4GWIM9A26dGTEfHvt" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Nf3zjBhIZqPs1XBZrKmn" alt=""><figcaption></figcaption></figure></div>

### 추가기능

기본 스킨에서 제공하는 `오늘 하루 보이지 않음`기능은 `localStorage`사용하고 있습니다.


# 슬라이드 메뉴 (모바일 전용)

### 슬라이드 메뉴 영역 *<mark style="background-color:green;">Mobile</mark>*

<div align="left"><figure><img src="/files/MwsFNgu7kINfimbv2fhE" alt="" width="563"><figcaption></figcaption></figure></div>

* ⓐ 로그인
* ⓑ 카테고리
* ⓒ 게시판

#### ■ ⓐ 로그인

[로그인 가이드 문서](/aurora-guide/api-1/sign-in)를 확인하시기 바랍니다.

#### ■ ⓑ 카테고리

> [**GET /categories**](https://docs.shopby.co.kr/?url.primaryName=display/#/Category/get-categories-by-keyword)
>
> ►전체 카테고리 조회하기\
> 쇼핑몰의 카테고리를 조회합니다.&#x20;

쇼핑몰 화면에서 카테고리란, 화면이 바뀌어도 대부분의 경우 화면에 상시 노출되는 요소입니다.

아래 2가지 형태의 카테고리 데이터를 제공합니다.

* flatCategories : 모든 카테고리를 하나의 배열에 쭉 나열한 형태
* multiLevelCategories : 계층을 가지는 카테고리 형태 (최대 5depth)

오로라 개별형 기본 스킨에서는 3depth까지 리스팅되어 출력되며,\
카테고리 상품 리스트에서는 5depth까지 표기됩니다.&#x20;

```
shop by basic/pro: 상품> 상품 분류관리> 전시 카테고리 관리
shop by premium: 전시관리 > 전시 카테고리 관리
```

#### ■ ⓒ 게시판

> [GET /boards/corigurations](https://docs.shopby.co.kr/?url.primaryName=manage/#/Board/get-board-config)
>
> ► 게시판 설정 조회하기\
> 전체 게시판의 설정 정보를 조회합니다.

* 일반 게시판 설정 : boardConfigs

일반 게시판 사용 설정이 '사용함'인 게시판 리스트를 모두 노출합니다.

일반 게시판은 공지사항, FAQ, 자유게시판, 이벤트/혜택, 메모게시판을 의미합니다.\
쇼핑몰 어드민 아래 경로에서 관리할 수 있습니다.

```
shop by basic/pro: 게시판 > 게시판 관리 > 게시판 리스트
shop by premium: 운영관리 > 게시판 관리 
```

아래 3가지 게시판의 경우, 쇼핑몰 고객이 [마이페이지 > 나의 게시글](/aurora-guide/api-1/mypage-post) 에서 관리할 수 있습니다.&#x20;

* 1:1문의 설정 : inquiryConfig
* 상품문의 설정 : productInquiryConfig
* 상품후기 설정 : productReviewConfig

1:1문의 설정, 상품문의 설정, 상품후기 설정은 쇼핑몰 어드민 아래 경로에서 관리할 수 있습니다.

| 고정 게시판                        | shopby basic/pro       | shopby premium              |
| ----------------------------- | ---------------------- | --------------------------- |
| 1:1문의 설정(inquiryConfig)       | 게시판 > 1:1문의 > 1:1문의 설정 | 운영관리 > 1:1 문의 관리 > 1:1문의 설정 |
| 상품문의 설정(productInquiryConfig) | 게시판 > 상품문의 > 상품문의 설정   | 상품관리 > 상품문의 관리 > 상품문의 설정    |
| 상품후기 설정(productReviewConfig)  |                        | 상품관리 > 상품평 관리 > 상품후기 설정     |


# 최근 본 상품

### 최근 본 상품

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

기본 스킨에서 '최근 본 상품'은 화면이 전환되어도 공통 화면으로서 유지되는 영역입니다.\
회원인 경우와 비회원인 경우, 각각 호출해야 하는 API가 상이합니다.

* 비회원(guest)

> [GET /guest/recent-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Profile/get-guest-recent-products)
>
> ►비회원 최근 본 상품 조회하기\
> 로그인 하지 않은 고객이 최근 본 상품을 조회합니다. &#x20;

localStorage에 저장한 상품 번호 리스트 mallproductNos를 통해 최근 본 상품을 조회합니다.

* 회원(member)

> [GET /profile/recent-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Profile/get-profile-recent-products)
>
> ► 최근 본 상품 조회하기\
> 로그인 이후에만 호출 가능(accessToken)합니다.&#x20;

해당 API는 PC 마이페이지 메인 화면에서도 활용됩니다.&#x20;


# 메인 화면

메인 화면 레이아웃을 소개합니다.

기본 스킨에서 메인화면의 레이아웃은 아래 4가지 영역으로 구성되어 있습니다.

* <mark style="color:green;">🅐</mark> [공통 영역](/aurora-guide/api-1/common) : 쇼핑몰 내에서 화면이 바뀌어도 계속 유지되는 요소를 의미합니다.&#x20;
* <mark style="color:purple;">🅑</mark> [배너 영역](/aurora-guide/api-1/main/banner) : 쇼핑몰에서 로고 혹은 프로모션 이벤트를 노출하기 위한 공간이자 이미지 입니다.&#x20;
* <mark style="color:yellow;">🅒</mark> [상품진열 영역](/aurora-guide/api-1/main/display-product) : 메인 페이지 내에서 특별한 목적에 따라 상품 리스트를 노출하기 위한 공간입니다.&#x20;
* <mark style="color:blue;">🅓</mark> [인스타그램 연동](/aurora-guide/api-1/main/instagram) : 인스타그램 아이디를 연동하여 SNS 게시물을 노출할 수 있습니다.&#x20;

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


# 배너 영역

쇼핑몰 메인페이지 화면 내 '배너(Banner)' 영역에 대한 정책과 기능, 사용할 수 있는 API를 소개합니다.

* [용어 소개](#undefined)
* [배너 그룹(Banner Group)](#banner-group-1)

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

***

### 용어 소개

#### ◼︎ 배너(Banner)

* 쇼핑몰에서 로고 혹은 프로모션 이벤트를 노출하기 위한 공간이자 이미지입니다.

쇼핑몰 어드민 아래 경로에서 관리할 수 있습니다.

```
shop by pro: 디자인> 디자인설정> 스킨 배너관리
shop by premium: 전시관리> 스킨 배너관리
```

#### ◼︎ 배너 그룹(Banner Group)

* 각각의 배너를 유형별로 분류한 개념입니다.
* 모든 배너는 배너그룹으로 그룹핑하여 사용해야 하며, 하나의 배너그룹 안에 여러 개의 배너가 추가될 수 있습니다.

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

***

### 배너 그룹(Banner Group)

배너 그룹은 각각의 배너를 유형별로 분류한 개념입니다.\
아래 예시는 오로라 개별형(PC+모바일) 기본 스킨을 기준으로한 분류입니다.&#x20;

아래 소개 드릴 배너 그룹의 각 위치를 자유롭게 변경하여 스킨을 제작할 수 있습니다.&#x20;

{% hint style="info" %}
단, 오로라 개별형 기본 스킨의 경우, 프론트 소스 직접 수정 및 위치 변경이 불가합니다.

만약 수정이 필요한 경우 \[디자인 > 디자인 관리 > 디자인 스킨리스트]에서 기본 스킨을 '복사' 후, \
\[에디터]] 기능을 이용하여 소스 수정이 가능합니다.&#x20;
{% endhint %}

### 배너 그룹 분류

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

#### ◼︎ bannerGroupCode (배너그룹코드)

각 배너그룹은 고유의 배너그룹코드(bannerGroupCode)를 통해 구분됩니다.\
위 도표에 기재된 고정된 12가지 배너그룹코드만 사용 가능합니다.&#x20;

#### ◼︎ bannerGroupName (배너그룹명)

오로라 개별형 기본 스킨에서는 12개의 배너그룹이 배너그룹명(bannerGroupName)을 \
상단로고, 메인 상단배너, 메인 중간배너 1\~5, 메인 중간좌측배너, 메인 하단배너, 스크롤 좌측 배너, 스크롤 우측 배너, 상품 상세 배너로 사용하고 있습니다. \
해당 배너그룹명은 스킨 제작 시 [bannerGroup.csv](https://workspace-help.nhn-commerce.com/undefined-1/undefined/undefined-1/undefined#bannergroup.csv)에 자유롭게 입력할 수 있습니다.&#x20;

#### ◼︎ bannerGroupType (배너그룹타입)

배너그룹은 배너그룹 노출 유형에 따라 3가지 배너그룹타입(bannerGroupType)으로 분류됩니다.\
(LOGO, SLIDE, NORMAL로 제공)

LOGO 배너그룹은 LOGO(로고 배너)로 타입이 고정되어 있으며,\
나머지 배너그룹은 SLIDE(움직이는 배너) 혹은 NORMAL(일반 배너)로 타입을 설정 가능합니다.&#x20;

* **LOGO** : 메인 상단에 노출되는 로고 유형
* **SLIDE** : 슬라이드 효과가 추가된 배너 유형 (멀티 배너)
* **NORMAL** : 배너 이미지를 노출해주는 기본 배너 유형 (단일 배너)

#### ◼︎ platformType (디바이스 유형)

{% hint style="info" %}
단, 오로라 개별형 스킨은 platformType이 **PC** or **MOBILE\_WEB** 으로 구분됩니다.&#x20;
{% endhint %}

> [GET /skin-banners/groups-by-skin](https://docs.shopby.co.kr/?url.primaryName=display/#/SkinBanner/get-skin-banners-groups-by-skin)
>
> ►사용중인 스킨 정보 및 배너 그룹 조회하기\
> 쇼핑몰에서 사용중인 스킨정보 및 배너그룹 정보를 조회합니다.&#x20;

해당 API에서 리턴값으로 조회한 groupCode 정보를 바탕으로,\
아래 소개드릴 GET /skin-banners API에서 배너 정보를 조회하여 고객들이 보는 쇼핑몰 화면에 배너를 노출합니다.

* **groupCode** : 앞서 설명드린 배너그룹코드(bannerGroupCode)입니다. 참고로 bannerGruops.csv 파일에서는 bannerGroupCode로 정의하며, API 스키마에서는 groupCode로 정의하고 있습니다.
* **isLiveSkin(사용스킨)** : 현재 쇼핑몰에 적용되어 있는 스킨을 의미합니다. \
  사용중이지 않은 그 외 스킨은 '보유 스킨'이 됩니다.&#x20;

> [GET /skin-banners](https://docs.shopby.co.kr/?url.primaryName=display/#/SkinBanner/get-skin-banners)
>
> ► 플랫폼 별 전체 스킨 배너 조회하기\
> 쇼핑몰의 모든 배너 정보를 조회합니다.&#x20;

groupCode(=즉 bannerGroupCode)에 연동되어 있는 쇼핑몰의 배너 정보를 조회합니다.\
(요청한 배너그룹 코드에 매칭되는 배너 정보만 조회합니다.)

만약 gruopCode로 전체 배너 리스트 정보를 조회하기 위해서는 GET /groups-by-skin API에서 리턴 값으로 내려주는 groupCode를 모두 요청해야만 전체 배너 리스트 정보를 조회할 수 있습니다. \
해당 API를 통해 고객들이 보는 쇼핑몰 화면에 배너를 노출합니다.&#x20;

배너 정보는 쇼핑몰 어드민 아래 경로에서 관리할 수 있습니다.

```
shop by pro: 디자인> 디자인설정> 스킨 배너관리
shop by premium: 전시관리> 스킨 배너관리
```

해당 배너 리스트 데이터에 쇼핑몰 로고(LOGO)가 포함되어 있습니다. \
로고의 경우 화면이 바뀌어도 대부분의 스킨에서 고정된 자리에 위치해 있기 때문에 사실상 모든 화면에서 지속적으로 사용되는 API입니다.&#x20;

> [GET /skin-banners/{bannerId}](https://docs.shopby.co.kr/?url.primaryName=display/#/SkinBanner/get-skin-banners-by-banner-id)
>
> ► 스킨의 배너 ID를 통해 배너리스트 조회하기\
> 스킨 배너 ID로 배너 정보를 조회합니다.&#x20;

쇼핑몰에 등록된 모든 스킨에서 배너 ID로 배너 정보를 조회할 수 있습니다.&#x20;

쇼핑몰 생성 시 오로라 개별형 기본 스킨에서는 배너 ID가 자동으로 입력되며, ID는 수정해서 사용하실 수 있습니다.\
'쇼핑몰 공용 배너'를 등록하면 스킨에 구애받지 않고 해당 쇼핑몰에 등록된 모든 스킨에서 배너 ID기준으로 사용하실 수 있습니다.&#x20;


# 상품진열 영역

쇼핑몰 메인페이지 화면 내 '상품진열' 영역에 대한 정책과 기능, 사용할 수 있는 API를 소개합니다.

* ['상품진열' 개념](#undefined)
* [좋아요 버튼 구현](#like-products)
* [장바구니 버튼 구현 (옵션 선택 팝업)](#cart)

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

***

### 상품진열 영역

상품진열 영역이란, 메인 페이지 내에서 특별한 목적에 따라 상품 리스트를 노출하기 위한 공간입니다. \
최초 쇼핑몰 생성 시, 세팅되는 상품 진열명은 '신규상품, 인기상품, MD추천, HOT, EVENT'로 구성됩니다.

오로라 개별형 기본 스킨 메인 화면에는 플랫폼(PC, 모바일) 별로 각 5개의 상품진열이 설정되어 있습니다. \
상품진열은 플랫폼별(PC, 모바일)로 설정이 가능하며, 스킨에 접속한 디바이스 구분에 따라 설정한 상품진열을 조회하여 노출합니다.

#### 어드민(관리자)에서의 상품진열 영역관리 <a href="#undefined" id="undefined"></a>

설정된 상품진열의 사용여부, 전시하고자 하는 상품 리스트 등 관련 설정은 아래 어드민 경로에서 관리할 수 있습니다.

```
shop by pro : 디자인 > 디자인 설정 > 상품 진열 관리
shop by premium: 전시관리 > 상품 진열 관리
```

#### 쇼핑몰 노출 위치에 따른 5개의 진열 ID <a href="#ec-87-bc-ed-95-91-eb-aa-b0-eb-85-b8-ec-b6-9c-ec-9c-84-ec-b9-98-ec-97-90-eb-94-b0-eb-a5-b8-5-ea-b0-9c" id="ec-87-bc-ed-95-91-eb-aa-b0-eb-85-b8-ec-b6-9c-ec-9c-84-ec-b9-98-ec-97-90-eb-94-b0-eb-a5-b8-5-ea-b0-9c"></a>

기본 스킨에서는 설정된 상품진열을 `진열ID(sectionId)`로 조회하여 노출하고 있습니다.

기본으로 세팅되는 상품진열의 진열ID는 아래와 같습니다.\
정해진 아래 진열ID를 소스 내 하드코딩하여 각 섹션의 위치를 구분할 수 있습니다.

* **PC** : SCPC0001, SCPC0002, SCPC0003, SCPC0004, SCPC0005
* **Mobile**: SCMO0001, SCMO0002, SCMO0003, SCMO0004, SCMO0005

> [GET / display/sections/{sectionNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductSection/get-section-v1-1)
>
> ► 진열번호 기준으로 상품진열 조회하기 \
> 상품 진열 번호(sectionNo)을 기준으로 상품 진열을 조회하는 API입니다.

**진열번호(sectionNo)**: 상품진열 등록 시 부여되는 유일값으로 모든 상품진열에 존재하는 값입니다.

> [GET /display/sections/ids/{sectionId}](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductSection/get-sections-by-section-id)
>
> ▶ 진열ID 기준으로 상품진열 조회하기\
> 상품 진열ID(sectionId)을 기준으로 상품 진열을 조회하는 API입니다.

**진열ID(sectionId)**: 진열번호 외에 다른 기준으로 호출이 필요할 경우 사용할 수 있는 값입니다.\
어드민에서 쇼핑몰 별 중복체크를 지원하므로, 다른 쇼핑몰에서 사용하는 값으로 상품진열 ID를 사용하실 수 있습니다.

#### '추가'로 상품진열 등록하기 <a href="#ec-b6-94-ea-b0-80-eb-a1-9c-ec-83-81-ed-92-88-ec-a7-84-ec-97-b4-eb-93-b1-eb-a1-9d-ed-95-98-ea-b8-b0" id="ec-b6-94-ea-b0-80-eb-a1-9c-ec-83-81-ed-92-88-ec-a7-84-ec-97-b4-eb-93-b1-eb-a1-9d-ed-95-98-ea-b8-b0"></a>

쇼핑몰 생성 시, 오로라 개별형 기본 스킨에는 기본으로 세팅되는 PC 5개, 모바일 5개의 상품진열코드만 반영이 되어 있습니다.

기본스킨에서 제공하는 상품진열 외에 추가로 노출하고자 할 경우,\
어드민에서 상품 진열을 등록한 후 노출하고자 하는 상품진열의 번호 또는 ID로 조회하여 노출할 수 있습니다.

진열번호, 진열ID 모두 진열 별로 API를 호출하여 상품 리스트를 가져오기 때문에, 상품진열 개수 별로 각각 API호출을 진행하셔야 합니다.\
즉, 기본 스킨에서는 상품진열 5개 SCPC0001 \~ SCPC0005를 모두 사용하기 때문에, 총 5번의 해당 API 호출이 발생합니다

***

### '좋아요' 와 '장바구니' 기능 <a href="#f0-9f-85-90-ec-a2-8b-ec-95-84-ec-9a-94-ec-99-80-f0-9f-85-91-ec-9e-a5-eb-b0-94-ea-b5-ac-eb-8b-88-ea-b" id="f0-9f-85-90-ec-a2-8b-ec-95-84-ec-9a-94-ec-99-80-f0-9f-85-91-ec-9e-a5-eb-b0-94-ea-b5-ac-eb-8b-88-ea-b"></a>

상품진열 내 전시된 상품에 대해 제공되는 '좋아요' 및 '장바구니' 기능을 소개합니다.

{% hint style="info" %}
어드민내에서 상품을 전시하는 방식(=디스플레이 유형)에 따라 '좋아요' 및 '장바구니' 기능 제공 여부가 다릅니다.
{% endhint %}

#### 디스플레이 유형 (PC/Mobile) <a href="#eb-94-94-ec-8a-a4-ed-94-8c-eb-a0-88-ec-9d-b4-ec-9c-a0-ed-98-95-pc-mobile" id="eb-94-94-ec-8a-a4-ed-94-8c-eb-a0-88-ec-9d-b4-ec-9c-a0-ed-98-95-pc-mobile"></a>

상품진열의 '디스플레이 유형'은 어드민에서 설정 가능합니다.

```
- shop by pro: 디자인> 디자인 설정> 상품 진열관리 
- shop by premium: 전시관리> 상품 진열관리
```

각 디스플레이 유형에 따라 가로 또는 세로 상품노출 개수는 고정되어 있으며,\
고정되지 않은 방향의 상품 노출 개수만 어드민에서 설정 가능합니다.

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

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

***

### 좋아요(like-products) 버튼 구현

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

좋아요 기능은 일종의 위시리스트 개념으로, 해당 상품에 대한 단순 좋아요(like-products)를 표시할 수 있습니다.\
따라서 주문서 페이지와 바로 연결하여 결제가 이루어지는 장바구니(cart)와 사용 목적이 구분됩니다.

좋아요 기능은 쇼핑몰 회원(member)의 경우에만 사용 가능하므로, 버튼 클릭 시 로그인 여부를 확인해야 합니다.

* 비회원(guest)
  * 비회원의 경우 좋아요 기능을 지원하지 않습니다.
  * 좋아요 버튼 클릭 시 로그인 여부를 확인하여, 미로그인(비회원)시 서비스이용불가 안내창 노출 후 로그인 페이지로 현재창 이동해야 합니다.
* 회원(member)
  * 로그인한 상태에서 좋아요 버튼 클릭 시, 아래 POST /profile/like-products를 호출합니다.
  * 해당 API로 좋아요가 적용된 상품은 [마이페이지\_쇼핑정보](https://workspace-help.nhn-commerce.com/undefined-1/api-1/greater-than/undefined-3) 내 '좋아요' 리스트에 추가됩니다.

> [POST /profile/like-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Profile/post-profile-like-products)
>
> ▶ 회원이 상품을 좋아한다고 추가/삭제하기\
> 회원이 좋아요한 상품을 목록에 추가하거나 삭제합니다

***

### 장바구니(cart) 버튼 구현

선택한 상품을 옵션 단위로 장바구니에 추가하는 기능입니다. \
상품진열 디스플레이 유형 중 'PC-리스트형', 'PC-장바구니형'인 경우에만 '장바구니' 버튼이 제공됩니다.

<figure><img src="/files/VTwbDj6lE4926F07mqX2" alt=""><figcaption><p>PC-리스트형</p></figcaption></figure>

<figure><img src="/files/qKoUM64SpMeHuSPzQgtZ" alt=""><figcaption><p>PC-장바구니형</p></figcaption></figure>

#### Ⓐ 장바구니 버튼

Ⓑ 상품 옵션 선택 레이어 팝업을 노출하기 위한 버튼입니다. \
단, 성인 인증 상품일 경우 회원/비회원 여부를 확인하여 필요 시 로그인 화면으로 이동시켜야 합니다. \
로그인 이후에는 성인 인증 여부를 확인하는 컨펌창이 필요합니다.

#### Ⓑ 상품 옵션 선택 레이어 팝업

<div align="left"><figure><img src="/files/D4J3vWu82dZFspm2KWpt" alt="" width="375"><figcaption></figcaption></figure></div>

오로라 개별형 기본 스킨에서는 장바구니 버튼 버튼 클릭 시, 상품 옵션을 선택할 수 있는 레이어 팝업이 출력됩니다.\
상품 옵션 구현 방법은 [상품 상세화면](/aurora-guide/api-1/product-detail)의 '옵션' 항목과 동일하니, 해당 문서를 참고하시길 바랍니다.

참고로, Ⓑ상품 옵션을 선택할 수 있는 레이어 팝업이 출력되는 점을 제외하고\
아래 안내 드릴 메인 페이지 내 Ⓒ '장바구니 담기 버튼' 호출 로직은 상품 상세화면 내 '장바구니 버튼' 호출 로직과 동일합니다

<div align="left"><figure><img src="/files/7fivwwoVHwHhZ9RiSMTC" alt="" width="375"><figcaption></figcaption></figure></div>

**추가상품**

선택한 상품에 설정된 추가상품이 존재할 시, 본 상품의 옵션 정보 하단에 추가상품의 상품 선택/옵션 선택 영역이 출력됩니다.

> [GET /products/{productNo}/extra-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-extra-products)
>
> ► 추가상품 조회하기\
> 상품번호에 대한 추가상품을 조회할 수 있습니다.

[`추가상품 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-extra-products)는 **추가상품의 옵션 정보**를 함께 반환하여,  별도의 [`옵션 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product%20Option/get-product-options)를 호출할 필요가 없습니다.

다만, [`추가상품 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-extra-products)에서 제공하는 옵션 정보는 기존 [`옵션 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product%20Option/get-product-options)의 필드 구성 및 데이터 구조와 **상이한 부분**이 있습니다.\
만약 일반 상품 옵션과 동일하게 처리해야 하는 경우, 필드명 및 데이터 구조가 **기존과** **호환되도록 변환 처리**가 필요할 수 있습니다.

자세한 필드 구성 및 응답 구조는 **API 문서**를 참고하시기 바랍니다.

#### Ⓒ 장바구니 담기 버튼&#x20;

장바구니 버튼 기능은 쇼핑몰 회원 여부와 상관없이 제공합니다.\
단, 회원인 경우에만 API를 호출하며 비회원인 경우 API 호출이 아닌 localStorage에 자체적으로 저장합니다.

* 회원(member)
  * 로그인한 상태에서 장바구니 담기 버튼 클릭 시, 아래 POST /cart를 호출하여 선택한 상품의 옵션이 장바구니에 추가됩니다.&#x20;

> [POST /cart](https://docs.shopby.co.kr/?url.primaryName=order/#/Cart/post-cart)
>
> ▶ 장바구니 등록하기\
> 로그인 회원의 상품 구매 수량과 옵션을 장바구니에 등록합니다.

* 비회원(guest)
  * 비회원인 경우에도 장바구니 담기 버튼을 제공합니다.
  * 단, API 호출이 아닌 localStorage 내 비회원 장바구니 데이터를 자체적으로 관리해야 합니다.
  * localStorage에 비회원 장바구니 데이터 저장 시, POST /cart의 request body와 동일한 데이터 형식으로 저장해야 합니다. 이후 상품 상세화면 혹은 장바구니 화면에서 주문서 호출 시 request 형식을 통일하기 위한 목적입니다.

#### Ⓓ 바로구매 버튼

바로구매 버튼 클릭 시 우선 로그인 여부를 확인하여, 만약 미로그인(비회원)일 경우 비회원 주문을 진행합니다.\
로그인한 회원일 경우 아래 POST /order-sheets API로 주문서를 생성한 뒤 [주문서 화면](/aurora-guide/api-1/order-sheet-form)으로 이동합니다.&#x20;

> [POST /order-sheets](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/post-order-sheet)
>
> ► 주문서 작성하기\
> 선태한 상품의 옵션에 대한 주문서를 생성합니다.&#x20;

주문서를 생성하는 API로 주문서 화면으로 이동하기 전 단계에서 호출해야 합니다.\
해당 API에서 응답 값으로 획득한 주문서 번호 orderSheetNo 를 [주문서 화면](/aurora-guide/api-1/order-sheet-form)으로 전달합니다. \
비회원 주문인 경우 accessToken을 null로 보냅니다.


# 인스타그램 연동

쇼핑몰 메인 페이지 화면 내 '인스타그램 연동' 영역에 대한 정책과 기능, 사용할 수 있는 API를 소개합니다.

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

아래 어드민 경로에서 인스타그램 연동이 가능합니다.&#x20;

```
shop by pro : 설정 > 기본정책 > 외부서비스 설정 > 인스타그램 연동
shop by premium : 서비스관리 > 외부서비스 설정 > 인스타그램 연동
```

쇼핑몰 대표 인스타그램 계정을 생성 후 인스타그램을 연동하면 쇼핑몰에 노출시킬 수 있습니다.\
인스타그램 게시물은 최대 12개로 노출되며, 1시간 마다 자동 갱신됩니다.\
인스타그램 위젯은 PC(6x2) / 모바일(3x4)로 노출됩니다.

> [**GET /mall**](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)
>
> ► 쇼핑몰 기본 정보 조회\
> 쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.

위 API 스키마에서는 instagramUsed 로 정의하고 있습니다.&#x20;


# 회원가입

일반 회원가입 및 간편 회원가입 기능을 지원하는 회원가입 화면입니다.

<div align="left"><figure><img src="/files/FrMq517PZe8pHYQploYl" alt="" width="375"><figcaption></figcaption></figure></div>

일반 회원가입 / 간편 회원가입 중 하나를 선택합니다.&#x20;

* 일반 회원가입
  * 아래 문서에서 상세 프로세스를 화면 별로 안내해 드립니다.
* 간편 회원가입
  * [간편 로그인](/aurora-guide/api-1/open-id) 문서 내용을 참고하시길 바랍니다. &#x20;

***

### 일반 회원가입 화면

<div align="left"><figure><img src="/files/l8UodNbBdjXP2yb06PN9" alt="" width="375"><figcaption></figcaption></figure></div>

* 🅐[ 회원정보 입력 영역](#a)
* 🅑[ 약관동의 영역](#b)
* 🅒[ 회원가입 완료](#c)
* 🅓 [회원가입 승인대기](#undefined-10)

***

### 🅐 회원정보 입력 영역

회원가입 항목은 아래 어드민에서 설정이 가능합니다.&#x20;

```
shop by basic/pro : 회원 > 회원관리 > 회원가입 항목 관리
shop by premium : 회원관리 > 회원가입 항목 관리
```

#### ■  회원가입 시 입력 항목

* 아이디
* 비밀번호
* 비밀번호 확인
* 이름
* 닉네임
* 이메일 주소
* 휴대폰 번호
* 전화번호
* 주소
* 생년월일
* 성별

{% hint style="info" %}
단, 회원가입 항목은 어드민 '회원가입 항목 관리'에서 '사용함'으로 설정된 항목만 노출됩니다.&#x20;
{% endhint %}

#### ■ 입력 정보 중복 여부 확인

회원정보 입력 항목 중 아이디, 이메일, 닉네임의 경우 중복 여부를 확인해야 합니다.

오로라 개별형 기본 스킨에서는 해당 쇼핑몰 내 중복된 회원정보가 없을 경우 *'ex) 사용 가능한 아이디 입니다.'* 라는 안내 메시지를 노출하며, 중복된 회원정보가 존재하는 경우 *'ex) 이미 사용중인 아이디 입니다.  다른 아이디를 입력해 주세요.'* 라는 안내 메세지를 노출합니다.&#x20;

> [GET /profile/id/exist](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile-ci-exists)
>
> ► CI 중복 확인하기\
> 해당 쇼핑몰에 이미 해당 아이디로 가입한 회원이 존재하는지 확인합니다.&#x20;

> [GET /profile/email/exist](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile-email-exist)
>
> ► 이메일 중복 여부 체크하기\
> 해당 쇼핑몰에 이미 해당 이메일로 가입한 회원이 존재하는지 확인합니다.&#x20;

> [GET /profile/nickname/exist](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile-nickname-exist)
>
> ► 닉네임 중복 여부 체크하기\
> 해당 쇼핑몰에 이미 해당 닉네임으로 가입한 회원이 존재하는지 확인합니다.&#x20;

#### ■ 인증번호 노출 여부

이메일 인증 버튼, SMS 인증 버튼 또는 휴대폰 본인인증 버튼의 경우 [샵바이 API 호출 가이드](/aurora-guide/api/shopbyapi) 문서에서 소개한\ <mark style="background-color:yellow;">GET /malls</mark> 를 통해 어드민의 이메일/SMS/휴대폰 인증 사용함 여부를 확인하여 인증버튼 노출 여부를 결정합니다.&#x20;

아래 어드민에서 설정할 수 있습니다.&#x20;

```
shop by basic/pro : 설정 > 기본정책 > 쇼핑몰관리 > 회원 인증 설정
shop by premium : 서비스관리 > 쇼핑몰관리 > 회원 인증 설정
```

<div><figure><img src="/files/WnHVZdhJi5mtEKkDdYYE" alt=""><figcaption><p>이메일인증</p></figcaption></figure> <figure><img src="/files/33K1ryzYeQnCJYlhoRuy" alt=""><figcaption><p>SMS인증</p></figcaption></figure> <figure><img src="/files/yvXwzUvo6XFAd4TMrIyo" alt=""><figcaption><p>휴대폰인증</p></figcaption></figure></div>

* 인증 종류 설정&#x20;
  * 이메일인증 선택 시 : 이메일 인증 버튼 노출
  * SMS인증 선택 시 : SMS 인증 버튼 노출
  * 휴대폰인증 선택 시 : 휴대폰 본인인증 버튼 노출

> [GET /malls](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)\
> ► 쇼핑몰 기본 정보 조회하기\
> 쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.

해당 API는 쇼핑몰 어느 화면에서든 공통적으로 필요한 기본 API 입니다.

#### ■ 인증번호 발송 및 확인

이메일, SMS, 휴대폰 인증 모두 아래 API가 동일하게 적용됩니다.&#x20;

> [POST /authentications](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/SendAuthenticationNumber)
>
> ► 인증번호 발송하기\
> 인증번호를 발송 합니다.&#x20;

회원의 연락처 또는 입력한 연락처로 인증번호를 발송합니다.\
해당 API는 회원가입 화면 뿐만 아니라, 아이디/비밀번호 찾기 및 회원정보 수정 등의 화면에서도 사용됩니다. \
Request body 내 <mark style="background-color:yellow;">type</mark>에서 SMS인증의 경우 SMS, 이메일 인증의 경우 EMAIL을 입력합니다.

* SMS 인증 : 5분
* 이메일 인증 : 10분

> [GET /authentications](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/get-authentications)
>
> ► 인증번호 확인하기\
> 입력 받은 인증번호를 확인합니다.&#x20;

사용자로부터 입력 받은 인증 번호의 유효성을 체크하며, 실패 시 에러코드 메시지를 전달합니다.

#### ■ 우편번호 찾기

우편번호 찾기 버튼 클릭 시, 우편번호 찾기 레이어 팝업이 출력됩니다.

<div align="left"><figure><img src="/files/M7t6cos7UbPEogtcJEIz" alt="" width="375"><figcaption></figcaption></figure></div>

> [GET /addresses/search](https://docs.shopby.co.kr/?url.primaryName=manage/#/Address/search-addresses)
>
> ► 주소 조회하기\
> 검색 키워드로 주소 정보를 조회합니다.&#x20;

***

### 🅑 약관동의 영역

<div align="left"><figure><img src="/files/xPlHeGeBHhoaZ9qOTgSY" alt="" width="375"><figcaption></figcaption></figure></div>

#### ■ 약관 데이터 호출

어드민 아래 경로에서 설정할 수 있습니다.&#x20;

```
shop by basic/pro : 설정 > 기본정책 > 약관/개인정보처리방침
shop by premium : 서비스관리 > 약관/개인정보처리방침
```

> [GET /terms](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms)
>
> ► 적용 중인 몰 약관 조회하기\
> 해당 쇼핑몰에 적용 중인 약관을 조회합니다.

해당 API는 회원가입 화면 뿐만 아니라, 주문서 구매 동의 화면 / 회원탈퇴 화면 / 쇼핑몰 푸터 영역에서도 활용됩니다.&#x20;

* 조회할 약관 타입 리스트
  * \[필수] 이용약관 USE
  * \[필수] 전자금융 거래 이용 약관 E\_COMMERCE
  * \[필수] 개인정보 수집 및 이용동의 PI\_COLLECTION\_AND\_USE\_REQUIRED
  * \[필수] 만 14세 이상 가입 동의 PI\_14\_AGE
  * \[선택] 개인정보 수집 및 이용동의 PI\_COLLECTION\_AND\_USE\_OPTIONAL
  * \[선택] 개인정보 처리/위탁에 대한 동의 PI\_PROCESS\_CONSIGNMENT
  * \[선택] 개인정보 제 3자 제공에 대한 동의 PI\_THIRD\_PARTY\_PROVISION
  * \[선택] 마케팅 목적의 개인정보 수집/이용 동의 MARKETING\_INFO\_USAGE
  * \[선택] 광고성 수신 동의 MARKETING\_RECEIVE

`약관/개인정보처리방침`에서 `추가 동의 항목`을 추가할 수 있습니다.\
추가된 동의항목은 [POST /terms/custom 추가 약관 조회하기](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/post-search-used-terms) API를 통해 확인할 수 있습니다.

***

### 🅒 회원가입 완료&#x20;

<div align="left"><figure><img src="/files/K4piVeCbSjPCrbaz2nbS" alt="" width="375"><figcaption></figcaption></figure></div>

POST /profile 을 통해 회원가입이 진행됩니다.&#x20;

> [POST /profile](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile)
>
> ► 프로필 생성하기\
> 회원 프로필이 등록됩니다.&#x20;

***

### 🅓 회원가입 승인대기

회원가입 승인 사용 설정을 '승인 후 가입'으로 설정한 경우 사용자가 회원가입 완료 시,\
회원가입 승인대기 화면이 출력됩니다.&#x20;

어드민 아래 경로에서 설정하실 수 있습니다.&#x20;

```
shop by basic/pro : 설정 > 기본정책 > 쇼핑몰 관리 > 쇼핑몰 수정 > 회원 설정 - 회원가입 승인 사용설정
shop by premium : 서비스관리 > 쇼핑몰 관리 > 쇼핑몰 수정 > 회원 설정 - 회원가입 승인 사용설정
```

<div align="left"><figure><img src="/files/e01dX0tVO26avaiNyg6l" alt="" width="375"><figcaption></figcaption></figure></div>


# 로그인

쇼핑몰 로그인 화면 및 로그인 시나리오에 대해 소개합니다.

<div align="left"><figure><img src="/files/qxkxZpsxD2iYRrDOXdgS" alt="" width="375"><figcaption></figcaption></figure></div>

* 🅐 일반회원 로그인
  * ⓐ accessToken 발급
  * ⓑ 휴면회원 로직
  * ⓒ 비밀번호 유효기간 초과 로직
* 🅑 아이디 찾기
* 🅒 비밀번호 찾기
* 🅓 회원가입
* 🅔 비회원 주문조회
* 🅕 간편 로그인&#x20;

***

### 🅐 일반회원 로그인

회원가입 시 생성한 회원 정보 (아이디 / 비밀번호)를 입력하는 화면입니다.

<div align="left"><figure><img src="/files/eHOUfhd2K8HOgO7YDBlx" alt="" width="375"><figcaption></figcaption></figure></div>

#### ■ 로그인 프로세스

<div align="left"><figure><img src="/files/e5QLARxrRqmANU80OnG6" alt="" width="489"><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="/files/h3loqfYPTeAWoqzix08i" alt="" width="511"><figcaption></figcaption></figure></div>

두 가지 회원유형인 🅐일반 로그인 회원과 🅑간편 로그인 회원은 각각 로그인 로직이 상이하나,\
공통적으로 accessToken/refreshToken을 획득 해야 합니다.

#### ◼︎ ⓐ AccessToken / RefreshToken 발급

> [POST /oauth2](https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2/post-oauth2-token)
>
> ► 엑세스 토큰/리프레시 토큰 발급하기\
> 엑세스 토큰 (accessToken) / 리프레시 토큰 (refreshToken) 을 발급합니다.

샵바이에서는 OAuth2 기반의 로그인 방식을 사용합니다. \
OAuth2가 적용되지 않은 경우, 액세스 토큰(accessToken) 기반의 로그인 방식을 사용합니다.

#### ◼︎ ⓐ AccessToken 발급

> [POST /oauth/token](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/post-oauth-token-1-success)
>
> ► 엑세스 토큰 발급하기\
> 엑세스 토큰 (accessToken)을 발급합니다.&#x20;

사용자가 입력한 아이디와 비밀번호로 해당 API를 호출하여 유효한 회원일 경우 accessToken/refreshToken을 획득합니다.

회원 액세스 토큰의 기본 유효시간은 30분, 리프레시 토큰의 기본 유효기간은 1일이며, 자동 로그인을 위해 keepLogin을 true로 요청하면 유효기간이 90일인 리프레시 토큰이 생성됩니다. 리프레시 토큰이 유효한 동안 액세스 토큰이 만료된 경우, 토큰을 갱신해야 합니다. 회원은 비밀번호 유효기간 90일이 지나면 비밀번호를 변경해야 합니다.

아래 API를 통해 토큰을 갱신할 수 있으며, 토큰 갱신과 관련된 자세한 내용은 [OAuth 2.0 적용 가이드](/aurora-guide/api/shopbyapi/oauth2.0)에서 확인하실 수 있습니다.

> [PUT /oauth2](https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2/put-oauth2-token)
>
> ► 엑세스 토큰 갱신하기\
> 엑세스 토큰 (accessToken)을 갱신합니다.&#x20;

액세스 토큰 기반의 로그인 방식을 사용하는 경우, 회원 액세스 토큰의 기본 유효기간은 30분이며, 자동 로그인을 위해 keepLogin을 true로 요청하면 유효기간이 90일인 토큰이 생성됩니다. 해당 방식은 토큰 갱신 작업을 진행하지 않습니다. 회원은 비밀번호 유효기간 90일이 지나면 비밀번호를 변경해야 합니다.

#### ◼︎ ⓑ 휴면 회원 로직

{% hint style="info" %}
2023년 9월 15일 개인정보보호법 개정에 따라 '개인정보 유효기간제'가 폐지되어,

쇼핑몰 운영방침에 따라 자율적으로 휴면회원 배치 사용 여부를 설정할 수 있습니다.&#x20;
{% endhint %}

아래 어드민 경로에서 휴면회원 사용 여부를 설정할 수 있습니다.

```
shop by basic/pro : 설정 > 기본정책 > 쇼핑몰관리 > 쇼핑몰 수정 > 휴면회원 사용여부 설정
shop by premium : 서비스관리 > 쇼핑몰 관리 > 쇼핑몰 수정 > 휴면회원 사용여부 설정
```

1. 직전 단계에서 Oauth2 기반 로그인 방식인 경우 **POST /oauth2** 혹은 **POST /oauth2/openid** 호출\
   액세스 토큰 기반의 로그인 방식인 경우 **POST /oauth/token** 혹은 **POST /oauth/openid** 호출
2. 해당 API 응답 값에서 <mark style="background-color:yellow;">dormantMemberResponse</mark>가 null이 아닌 경우\
   휴면회원 해제 여부 컨펌창 노출
3. 휴면회원 해제 API 호출

<div><figure><img src="/files/Oquq1as0XWKx9vxervFC" alt=""><figcaption></figcaption></figure> <figure><img src="/files/Gpeo9mX3VxD6aEzFSyi8" alt=""><figcaption></figcaption></figure></div>

#### ■ 휴면 회원 판단

accessToken 을 획득했지만, 현재 사용자가 '휴면 회원'인 경우에는 휴면 회원 로직을 실행합니다.\
(일반회원 및 간편로그인 회원)

아래 POST /oauth2, POST /oauth2/openid, POST /oauth/token 혹은 POST /oauth/openid 응답 값 중 '휴면 회원 정보 dormantMemberResponse' 가 null이 아닌 경우 휴면회원으로 간주합니다.

> [POST /oauth2](https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2/post-oauth2-token)\
> ► 엑세스 토큰 / 리프레시 토큰 발급하기 \
> 액세스 토큰 (accessToken) / 리프레시 토큰 (refreshToken) 을 발급합니다.

> [POST /oauth/token](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/post-oauth-token-1-success)
>
> ► 엑세스 토큰 발급하기\
> 엑세스 토큰 (accessToken)을 발급합니다.&#x20;

사용자가 입력한 아이디와 비밀번호로 해당 API를 호출하여 유효한 회원일 경우 accessToken을 획득합니다.

> [POST /oauth2/openid](https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2/post-oauth2-openid-token)
>
> ► OpenId AccessToken/RefreshToken 발급하기\
> OpenId 회원의 액세스 토큰 (accessToken) / 리프레시 토큰 (refreshToken)을 발급합니다.

> [POST /oauth/openid](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/post-oauth-openid)
>
> ► OpenId AccessToken 발급하기\
> OpenId 회원의 액세스 토큰 (accessToken)을 발급합니다.

#### Open ID 회원이란?&#x20;

카카오, 네이버와 등과 같은 외부 IdP(Identity Provider, 즉 아이디 제공자)를 이용하여 로그인하는 회원을 뜻합니다.\
사용자가 입력한 아이디와 비밀번호로 해당 API를 호출하여, 유효한 회원일 경우 accessToken 을 획득합니다.

#### ■ 휴면 회원 해제

휴면 해제 진행 시 아래 API를 호출하여 휴면해제 처리합니다. \
휴면 해제 성공 시 로그인 상태로 간주합니다. &#x20;

> [PUT /profile/dormancy](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/put-profile-dormancy)
>
> ► 휴면 해제하기\
> 회원의 휴면 상태를 해제합니다.&#x20;

### ⓒ 비밀번호 90일 초과 로직

<div align="left"><figure><img src="/files/yxhW9TtbGS49QskrfWoe" alt="" width="375"><figcaption></figcaption></figure></div>

비밀번호 유효기간 90일 초과 시 비밀번호를 변경하는 페이지를 노출합니다.\
비밀번호 변경 일시 및 '다음에 변경' 최종 처리 일시가 현재 시점 기준 90일을 초과한 경우, \
비밀번호 변경안내 페이지로 이동합니다.&#x20;

{% hint style="info" %}
단, '일반 로그인 회원'의 경우에만 비밀번호 유효기간 로직이 실행되며,

쇼핑몰 비밀번호가 없는 '간편 로그인 회원'의 경우 비밀번호 변경 안내 대상이 아닙니다.&#x20;
{% endhint %}

> [POST /oauth2](https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2/post-oauth2-token)\
> ► 엑세스 토큰 / 리프레시 토큰 발급하기 \
> 액세스 토큰 (accessToken) / 리프레시 토큰 (refreshToken) 을 발급합니다.

> [POST /oauth/token](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/post-oauth-token-1-success)
>
> ► accessToken 발급하기\
> 엑세스 토큰 (accessToken)을 발급합니다.

* 응답 값 중 '비밀번호 변경 일로부터 경과일 수 <mark style="background-color:yellow;">daysFromLastPasswordChange</mark>' 가 \
  90일 이상인 경우 비밀번호 변경 안내 대상입니다.&#x20;

> [POST /profile/check-password](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile-check-password)
>
> ► 비밀번호 확인하기\
> 입력된 비밀번호를 확인합니다.

* '비밀번호 변경' 클릭 시 해당 API를 호출하여 , 현재 비밀번호가 일치하는지 확인합니다.

> [PUT /profile/password](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/put-profile-password-1-1)
>
> ► 비밀번호 변경하기\
> 비밀번호를 변경합니다.

* '비밀번호 변경' 버튼 클릭 시입력한 새 비밀번호 <mark style="background-color:yellow;">newPassword</mark>로 비밀번호를 변경합니다.\
  기본 스킨에서는 비밀번호 변경에 성공 시, 로그아웃 처리 후 로그인 화면으로 이동합니다. \
  즉 새로 accessToken을 발급 받아야 합니다.
* 만약 '다음에 변경' 버튼 클릭 시 <mark style="background-color:yellow;">willChangeNextTime</mark> 값을 통해 <mark style="background-color:yellow;">daysFromLastPasswordChange</mark>가 현재 날짜로 업데이트 됩니다. 비밀번호 변경은 권장 사항으로서, '다음에 변경' 클릭 시 전 단계에서 획득한 accessToken을 이상 없이 사용할 수 있으며 로그인 상태로 간주됩니다.
* 만약 회원이 '비밀번호 변경' 혹은 '다음에 변경' 버튼을 클릭하지 않은 채, 다른 방법 (타 버튼 클릭, URI 직접 입력 등)을 통해 다른 화면으로 이동했다 하더라도 계속 로그인 상태로 간주합니다.\
  단, 이 경우 <mark style="background-color:yellow;">daysFromLastPasswordChange</mark>값이 90일 이상으로 유지되므로, 나중에 다시 로그인 시도 시 해당 비밀번호 변경 안내 화면이 다시 노출됩니다.

***

### 🅑 아이디 찾기

'아이디 찾기' 버튼 클릭 시 아이디 찾기 화면으로 이동합니다.

<div><figure><img src="/files/esN0yJJV0NaIWJCM9ZYV" alt=""><figcaption></figcaption></figure> <figure><img src="/files/y2k2vUzbWqCmNYoVdnl3" alt=""><figcaption></figcaption></figure></div>

> [POST /profile/find-id](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile-find-id)
>
> ► 아이디 찾기\
> 회원가입 시 입력한 정보로 아이디를 검색합니다.&#x20;

회원가입 시 입력한 이름/이메일/휴대폰 번호 정보를 통해 아이디를 검색 합니다.&#x20;

* 이메일 : 회원가입 시 입력한 이메일 정보로 동일 데이터 존재 여부 조회
* 휴대폰번호 : 회원가입 시 입력한 휴대폰 번호로 데이터 존재 여부 조회

이후 입력한 정보와 일치하는 회원정보가 있을 경우 아이디 안내 화면을 노출합니다.&#x20;

{% hint style="info" %}
아이디 안내 화면에서 아이디는 마스킹 처리하여 표기합니다.&#x20;
{% endhint %}

<div align="left"><figure><img src="/files/v6i9CqgyTa3bpYmNB6SM" alt="" width="375"><figcaption></figcaption></figure></div>

* 이메일 형식 아이디 : 아이디 중 앞 2자리를 제외한 나머지는 마스킹 처리
* 이메일 형식이 아닌 아이디 : 끝 3자리 마스킹 처리&#x20;

기본 스킨에서는 아이디가 여러개인 경우 개행 처리하며, 조회한 아이디가 휴면회원일 경우 (휴면) 텍스트를 노출합니다.&#x20;

#### ◼︎ 휴대폰 본인인증

회원인증 설정을 '휴대폰인증' 으로 설정한 경우, '휴대폰 본인인증' 탭 항목이 추가로 노출됩니다.&#x20;

<div align="left"><figure><img src="/files/HMuQvxEGO8jTYtOeyxkW" alt="" width="375"><figcaption></figcaption></figure></div>

'휴대폰 본인인증' 탭 선택 시 [휴대폰 본인인증 화면](/aurora-guide/api-1/sms-authentication)을 실행한 후, \
POST /profile/find-id 를 호출하여 아이디를 찾을 수 있습니다. \
NHN KCP 휴대폰 본인인증 절차를 완료한 경우, 아이디 안내 화면에서 아이디 마스킹 처리를 하지 않고 안내합니다.&#x20;

***

### 🅒 비밀번호 찾기

'비밀번호 찾기' 버튼 클릭 시 비밀번호 찾기 화면으로 이동합니다.\
비밀번호 찾기 화면은 <mark style="background-color:purple;">아이디 입력 → 본인인증 → 비밀번호 변경 → 변경완료</mark> 4단계 화면으로 진행됩니다.&#x20;

#### ◼︎ 아이디 입력&#x20;

<div align="left"><figure><img src="/files/JwnNTuosDTxsWVHexKlU" alt="" width="375"><figcaption></figcaption></figure></div>

> [GET /profile/password/search-account](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile-password-search-account)
>
> ► 비밀번호 찾기를 위한 계정 조회하기\
> 비밀번호 찾기를 위한 계정 정보를 조회합니다.&#x20;

사용자가 입력한 회원 아이디를 바탕으로 '회원번호 memberNo' 를 획득합니다.&#x20;

#### ◼︎ 본인인증

비밀번호 찾기를 위한 본인인증 수단은 총 3개를 제공합니다.

<div><figure><img src="/files/4FTH04zF1gtETgFPJEvs" alt=""><figcaption></figcaption></figure> <figure><img src="/files/IN0CRK19jkZsrdTKfZEn" alt=""><figcaption></figcaption></figure> <figure><img src="/files/VrThhGaHrqWMExEUw7np" alt=""><figcaption></figcaption></figure></div>

* 이메일 인증 : 등록된 이메일로 찾기
* 휴대폰번호 인증 : 등록된 휴대폰 번호로 찾기
* [휴대폰 본인인증 ](/aurora-guide/api-1/sms-authentication)
  * NHN KCP 외부 인증모듈을 호출하여 휴대폰 본인인증을 진행합니다.&#x20;
  * 회원인증 설정을 '휴대폰인증' 으로 설정한 경우, '휴대폰 본인인증' 탭 항목이 추가로 노출됩니다.

> [POST /authentications](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/SendAuthenticationNumber)
>
> ► 인증번호 발송하기\
> 회원의 연락처로 인증번호를 발송합니다.&#x20;

GET /profile/password/search-account 에서 전달받은 '회원번호 memberNo'를 바탕으로 \
등록된 이메일 또는 휴대폰 번호로 인증번호를 발송합니다.

<div align="left"><figure><img src="/files/xwO2VXa1XFtnzXIkiMhz" alt="" width="375"><figcaption></figcaption></figure></div>

> [GET /authentications](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/get-authentications)
>
> ► 인증번호 확인하기\
> 전달받은 인증번호를 확인합니다.&#x20;

Usage 값으로 FIND\_PASSWORD 를 입력합니다.&#x20;

#### ◼︎ 비밀번호 변경

본인인증 성공 시, 신규 비밀번호를 입력할 수 있습니다.&#x20;

<div align="left"><figure><img src="/files/nmYQQMNaVwrj33fV9qMX" alt="" width="375"><figcaption></figcaption></figure></div>

> [POST /profile/change-password-after-cert](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile-change-password-after-cert)
>
> ► 비밀번호 변경하기\
> 회원인증 후 비밀번호를 변경합니다.&#x20;

기존에 사용 중이던 비밀번호와 동일한 비밀번호로 변경할 수 없습니다.&#x20;

#### ◼︎ 변경완료

<div align="left"><figure><img src="/files/FHrPjVyPw9Qrt961xnYn" alt="" width="375"><figcaption></figcaption></figure></div>

만약 해당 회원이 휴면회원인 경우, 비밀번호 변경 성공 후 아래 API를 호출하여 휴면해제 처리합니다.&#x20;

> [PUT /profile/dormancy](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/put-profile-dormancy)
>
> ► 휴면 해제하기\
> 회원의 휴면상태를 해제합니다.&#x20;

***

### 🅓 회원가입

회원가입 페이지로 연결되는 회원가입 버튼을 노출합니다.\
상세 내용은 [회원가입 화면](/aurora-guide/api-1/sign-up-form) 문서를 참고하시길 바랍니다.&#x20;

<div align="left"><figure><img src="/files/XFc6wOm1QcL2BfnnjUYw" alt="" width="375"><figcaption></figcaption></figure></div>

***

### 🅔 비회원 주문조회

비회원 주문조회는 비회원이 구매한 주문 건에 대한 주문정보를 확인할 수 있도록 비회원 정보를 입력하는 영역입니다.\
비회원으로 주문한 주문번호와 주문 시 작성한 주문번호 비밀번호를 입력하여 확인할 수 있습니다.&#x20;

<div align="left"><figure><img src="/files/7KSQfcWBqAcFqhXIOaq1" alt="" width="375"><figcaption></figcaption></figure></div>

입력한 주문번호 / 주문번호 비밀번호와 일치하는 비회원 주문정보가 없는 경우, 아래 화면과 같은 alert 을 출력합니다.&#x20;

<div align="left"><figure><img src="/files/dfPcV7fP9jYdgkTmueCy" alt="" width="375"><figcaption></figcaption></figure></div>

> [POST /guest/orders/{orderNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/GuestOrder/get-guest-orders-order-no)
>
> ► 비회원 주문 상세 조회하기\
> 비회원 주문의 상세 정보를 조회합니다.&#x20;

입력받은 주문번호와 주문번호 비밀번호로 해당 API를 호출하여 비회원 주문정보를 조회합니다.\
조회 성공 시, 주문번호 <mark style="background-color:yellow;">orderNo</mark> 기준으로 비회원 주문 상세 정보 화면을 노출합니다.&#x20;

***

### 🅕 간편 로그인

일반 회원 로그인 영역 하단에 간편 로그인 기능을 제공합니다. \
현재 제공하는 간편 로그인은 페이코, 네이버, 카카오, 페이스북 총 4개 입니다.&#x20;

<div align="left"><figure><img src="/files/pRFYd04XV47WjKXuMOdy" alt="" width="375"><figcaption></figcaption></figure></div>

아래 어드민 경로에서 설정이 가능합니다. \
각 어드민별 페이지에서 연동 설정한 외부 IdP(Identity Provider, 즉 아이디 제공자)를 노출합니다.

```
shop by basic/pro : 설정 > 기본정책 > 외부서비스 설정
shop by premium : 서비스관리 > 쇼핑몰 관리
```

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

> [GET /malls](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)\
> ► 몰 정보 조회하기\
> 쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.&#x20;

어드민에 연동 설정이 되어있는 간편 로그인 인증업체 (외부 IdP)정보를 조회합니다.\
연동되어 있지 않은 인증업체의 로그인 버튼은 노출되지 않습니다.

해당 API 응답 값 중 <mark style="background-color:yellow;">openIdJoinConfig</mark> 내  <mark style="background-color:yellow;">providers</mark> 값을 통해 확인 가능합니다.

각 간편 로그인 버튼 클릭 이후의 상세 로직은 [간편 로그인 화면](/aurora-guide/api-1/open-id) 문서를 확인하시길 바랍니다.&#x20;


# 간편 로그인

간편 로그인 기능 및 간편 로그인 회원가입에 대해 소개합니다.

* 🅐 간편 로그인 연동 프로세스
* 🅑 간편 로그인 회원가입
* 🅒 카카오 싱크&#x20;

<div align="left"><figure><img src="/files/5zNbwxGKaODKKYhjcSwm" alt="" width="563"><figcaption></figcaption></figure></div>

간편 로그인 연동 로직에 대해 소개합니다.\
OAuth 프로토콜 중 간편회원 로그인 기능을 통해 accessToken을 획득하는 방식입니다.

기본 스킨에서 간편 로그인을 구현한 연동 시나리오는 위 다이어그램과 같습니다.\
이를 아래 문서에서 각 프로세스 별 상세 설명합니다.&#x20;

***

### 🅐 간편 로그인 연동 프로세스

### ⓐ 간편 회원 로그인 버튼&#x20;

<div align="left"><figure><img src="/files/pRFYd04XV47WjKXuMOdy" alt="" width="375"><figcaption></figcaption></figure></div>

회원가입 페이지, 로그인 페이지 등에서 노출되는 간편 로그인 기능입니다.\
현재 제공하는 간편 로그인은 페이코, 네이버, 카카오, 페이스북 총 4개 입니다.&#x20;

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

어드민에서 각 간편 로그인 제공사 개발자 센터에서 발급 받은 Client ID와 Client Secret 키를 입력합니다.&#x20;

```
shop by basic/pro : 설정 > 기본정책 > 외부서비스 설정
shop by premium : 서비스관리 > 쇼핑몰 관리
```

어드민에서 연동 설정된 제공사에 한해, 회원가입 페이지 및 로그인 페이지에서 간편 로그인 기능이 제공됩니다.

> [GET /malls](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)\
> ► 몰 정보 조회하기\
> 쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.&#x20;

어드민에 연동 설정이 되어 있는 간편 로그인 제공사 정보를 조회합니다. \
연동되어 있지 않은 간편 로그인 제공사의 로그인 버튼은 노출되지 않습니다.

해당 API 응답 값 중 <mark style="background-color:yellow;">openIdJoinConfig</mark> 내  <mark style="background-color:yellow;">providers</mark> 값을 통해 확인 가능합니다.

### ⓑ 간편 로그인 연동 URI 획득

간편 로그인 제공사(provider)이 각각 다르므로, \
provider 별 일부 화면을 노출하기 위해서는 먼저 아래 API를 호출하여 간편 로그인 연동 URI를 조회합니다.&#x20;

> [GET /oauth/login-url](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/get-oauth-login-url)
>
> ► Openid 로그인 URI 조회하기\
> OpenID 로그 URI를 조회합니다.&#x20;

해당 API 호출 시 3개의 파라미터가 필요하며 각 파라미터에 대한 설명은 아래와 같습니다.

* **provider**
  * 간편 로그인 제공사
  * 각 제공사 id 앞에 'ncp\_' 를 추가 (ex. ncp\_payco, ncp\_naver, ncp\_kakao, ncp\_facebook)
* **state**&#x20;
  * CSRF 공격 방지용 토큰
  * client 에서 생성한 숫자, 영문 대소문자로 이루어진 6자리의 random string
* **redirectUri**
  * 인증 성공 후 이동할 쇼핑몰의 리다이렉트 URI (인코딩 필수)
  * 형식 : {location.origin}/callback/auth-callback.html
    * 참고) 모바일 도메인에 /m 을 추가해서 사용하는 경우 \
      {location.origin}/m/callback/auth-callback.html

### ⓒ 간편 로그인 제공사 (Provider) 화면 노출

획득한 간편 로그인 연동 URI를 통해 각 간편 로그인 제공사 화면을 노출합니다.

<div><figure><img src="/files/KCYoz8M6vHNib3DW0B1V" alt=""><figcaption></figcaption></figure> <figure><img src="/files/rcxGSmm4iNuboUsLlAJQ" alt=""><figcaption></figcaption></figure> <figure><img src="/files/a0AskYUx34y3XZL4uUSY" alt=""><figcaption></figcaption></figure> <figure><img src="/files/hV2J0js3cgfBkxf4XfZS" alt=""><figcaption></figcaption></figure></div>

### ⓓ 쇼핑몰 redirectURI로 이동

간편 로그인 제공사 화면에서 인증에 성공 후, code 값과 함께 쇼핑몰 redirecURI로 이동합니다.\
이를 통해 프론트 화면에도 각 간편 로그인 제공사에서의 인증 성공 여부를 전달합니다.&#x20;

#### <mark style="color:purple;">✓ 예시 코드</mark>

```
https://{쇼핑몰 도메인}/callback/auth-callback?code=XXXXXXXXXX
```

### ⓔ accessToken 획득

쇼핑몰 redirectURI에서 아래 API를 호출하여 accessToken과 refrehshToken을 획득합니다.

> [POST /oauth2/openid](https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2/post-oauth2-openid-token)
>
> ► OpenId AccessToken/RefreshToken 발급하기\
> OpenId 회원의 액세스 토큰 (accessToken) / 리프레시 토큰 (refreshToken)을 발급합니다.

액세스 기반의 로그인 방식을 사용하는 경우 아래 API를 호출하여 accessToken을 획득합니다.

> [POST /oauth/openid](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/post-oauth-openid)
>
> ► OpenId AccessToken 발급하기\
> OpenId 엑세스 토큰(accessToken)을 발급합니다.

### ⓕ 회원가입 여부 확인

해당 간편 로그인 계정이 현재 쇼핑몰에 가입한 상태인지 아닌지 여부를 확인합니다.

> [GET /profile](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile)
>
> ► 회원정보 조회하기\
> 회원정보를 조회합니다.&#x20;

응답 값 중 memberStatus 값이 WAITING 인 경우 쇼핑몰 미가입 상태로 판단합니다.

* **간편 로그인 회원인 경우**\
  해당 간편 로그인 계정으로 로그인합니다.
* **간편 로그인 회원이 아닌 경우 (미가입 상태)**\
  아래 문서에서 소개 드릴, 간편 로그인 회원가입 로직을 진행합니다.

***

### 🅑 간편 로그인 회원가입

간편 로그인 회원가입에 대해 소개합니다.\
간편 로그인을 통해 신규 가입을 하는 회원의 경우, 아래 화면을 통해 회원가입을 진행합니다.

<div align="left"><figure><img src="/files/aFQMAdkyzZdt7adncExk" alt="" width="375"><figcaption></figcaption></figure></div>

### ⓐ 간편로그인 회원가입 팝업

이전 단계에서 이미 호출한 GET /profile 응답 값을 활용하여 memberName, email, id, 휴대폰번호, 성별, 생일 등을 화면에 노출합니다.

### ⓑ 약관 데이터 호출

약관 내용은 아래 어드민 경로에서 설정할 수 있습니다.&#x20;

```
shop by basic/pro : 설정 > 기본정책 > 약관/개인정보처리방침
shop by premium : 서비스관리 > 약관/개인정보처리방침
```

> [GET /terms](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms)
>
> ► 적용 중인 몰 약관 조회하기\
> 해당 쇼핑몰에 적용 중인 약관을 조회합니다.

> [POST /terms/custom](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/post-search-used-terms)
>
> `약관/개인정보처리방침`에서 `추가 동의 항목`을 추가할 수 있습니다.\
> 추가된 동의항목은 [POST /terms/custom 추가 약관 조회하기](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/post-search-used-terms) API를 통해 확인할 수 있습니다.&#x20;

► 적용 중인 몰 약관 조회하기\
해당 쇼핑몰에 적용 중인 약관을 조회합니다.

아래 약관 데이터를 불러와서 약관 사용 여부가 <mark style="background-color:yellow;">true</mark> 인 항목들에 한하여 화면에 노출합니다.&#x20;

* \[필수] 이용약관 USE
* \[필수] 개인정보 수집 및 이용동의 PI\_COLLECTION\_AND\_USE\_REQUIRED
* \[필수] 만 14세 이상 가입 동의 PI\_14\_AGE
* \[선택] 개인정보 수집 및 이용동의 PI\_COLLECTION\_AND\_USE\_OPTIONAL
* \[선택] 개인정보 처리/위탁에 대한 동의 PI\_PROCESS\_CONSIGNMENT
* \[선택] 개인정보 제 3자 제공에 대한 동의 PI\_THIRD\_PARTY\_PROVISION

### ⓒ 회원가입

해당 버튼 클릭 시 아래 API를 호출하여 간편 로그인 회원가입을 완료합니다.

> [POST /profile/openid](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile-openid)
>
> ► 오픈 아이디 회원가입 처리하기\
> OpenID 회원 프로필이 등록됩니다.&#x20;

***

### 🅒 카카오 싱크

#### ◼︎ 카카오 싱크 세팅 방법

* [shop by basic/pro 카카오 싱크 신청 가이드](https://workspace.nhn-commerce.com/support/recommendedContents/189897)
* [shop by premium 카카오 싱크 신청 가이드](https://workspace.nhn-commerce.com/support/recommendedContents/186321)


# 휴대폰 본인인증

회원 본인인증 방법을 '휴대폰인증'으로 설정한 경우 노출되는 NHN KCP 휴대폰 인증 모듈에 대해 소개합니다.

회원 본인인증 방법은 이메일 인증 / SMS 인증 / 휴대폰 인증 3가지 인증 방법을 제공합니다.\
아래 어드민 경로에서 설정할 수 있습니다.&#x20;

```
shop by basic/pro : 설정 > 기본정책 > 쇼핑몰 관리 > 쇼핑몰 수정 > 회원 인증 설정
shop by premium : 서비스관리 > 쇼핑몰 관리 > 쇼핑몰 수정 > 회원 인증 설정
```

회원 본인 인증의 경우, 아래와 같은 화면에서 활용됩니다.

* 아이디 및 비밀번호 찾기 시&#x20;
* 성인 인증 필요 시 (성인인증 사용 상품 구매 및 성인인증 인트로페이지)
* 회원 휴면해제 시
* 마이페이지 회원정보 수정 시
* 쇼핑몰 회원가입 시&#x20;

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

***

### 🅐 휴대폰 본인인증 버튼

회원 본인인증 방법을 '휴대폰인증'으로 설정한 경우, 화면 내 '휴대폰 본인인증' 버튼이 노출됩니다.&#x20;

> [GET /malls](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)
>
> ► 몰 정보 조회하기\
> 쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회합니다.

[샵바이 API 호출 가이드](/aurora-guide/api/shopbyapi) 문서에서 소개한 GET /malls 내 <mark style="background-color:yellow;">mallJoinConfig</mark> 값을 통해\
어드민의 휴대폰 인증 사용함 여부를 확인합니다.

***

### 🅑 NHN KCP 인증모듈 로직

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

### ⓐ 휴대폰 본인인증 버튼 클릭

휴대폰 본인인증 버튼이 노출된 쇼핑몰 화면에서 버튼 클릭 시,\
/callback/kcp-callback 을 통해 URI key 값 여부를 확인합니다.

### ⓑ HTML form 획득

KCP 인증 모듈 팝업을 출력하기 위해서 GET /kcp/id-verification 을 통해 HTML form을 요청해야 합니다.\
해당 API를 통해 HTML form 생성 시, 화면 내 'NHN KCP 인증 팝업 (외부모듈)'이 노출됩니다.

> [GET /kcp/id-verification/form](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-form)
>
> ▶ KCP 본인인증 요청하기\
> 본인 인증을 위한 form을 생성합니다

### ⓒ Key 파라미터 획득

'NHN KCP 인증팝업(외부 모듈)'을 통해 사용자가 인증에 성공하면, callback 주소로 본인인증 키 `key` 가 전달됩니다.

#### <mark style="color:purple;">**✓ 예시 코드**</mark>

```
https://{쇼핑몰 도메인}/callback/kcp-callback.html?key=XXXXXXXXXX
```

### ⓓ 본인인증 결과 조회

해당 key 를 파라미터 값으로 본인인증 인증 성공 및 실패 여부를 판단한 뒤, 화면에 성공 및 실패 결과를 전달합니다.\
성공 시 다음 화면으로 리다이렉트 되며 팝업이 종료됩니다.

> [GET /kcp/id-verification/response](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-response)
>
> ▶ KCP 본인인증 결과 조회하기\
> NHN KCP 본인인증 결과를 확인합니다

### ⓔ 본인인증 결과 획득 <a href="#e2-93-94-eb-b3-b8-ec-9d-b8-ec-9d-b8-ec-a6-9d-ea-b2-b0-ea-b3-bc-ed-9a-8d-eb-93-9d" id="e2-93-94-eb-b3-b8-ec-9d-b8-ec-9d-b8-ec-a6-9d-ea-b2-b0-ea-b3-bc-ed-9a-8d-eb-93-9d"></a>

성공 시 다음 화면으로 리다이렉트 되며 팝업이 종료됩니다.

#### **㉠ 회원가입 진행 중 이루어진 본인인증이었을 경우**

만약 '[회원가입 화면](/aurora-guide/api-1/sign-up-form)'에서 휴대폰 본인 인증을 진행한 경우였다면,\
본인인증 성공 시 해당 API 응답 값 중, CI 값을 회원가입 화면으로 전달하여 CI 중복 확인을 추가적으로 진행해야 하며\
phone 핸드폰 번호 값을 회원정보 입력화면에 자동 출력합니다.

#### **㉡ 성인 인증 여부 갱신**

NHN KCP 본인인증 결과 조회 이후 로그인 여부를 판단하여\
만약 해당 회원이 로그인 상태였을 경우(accessToken을 가지고 있었을 경우), 성인인증 여부를 갱신해야 합니다.

> [POST /kcp/age-verification](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/post-kcp-age-verification)
>
> ▶ 회원 성인인증 하기\
> 회원 성인인증 여부를 갱신합니다

이전 단계에서 획득한 key 파라미터로 사용합니다.

한 번 성인인증을 완료한 회원은 인증을 완료한 시점부터 1년간 인증 기록이 유지됩니다.\
기간 내 다시 본인인증에 성공할 경우 성인인증 일시가 갱신됩니다.

### ⓕ 팝업 차단 여부 체크 <a href="#e2-93-94-eb-b3-b8-ec-9d-b8-ec-9d-b8-ec-a6-9d-ea-b2-b0-ea-b3-bc-ed-9a-8d-eb-93-9d" id="e2-93-94-eb-b3-b8-ec-9d-b8-ec-9d-b8-ec-a6-9d-ea-b2-b0-ea-b3-bc-ed-9a-8d-eb-93-9d"></a>

사용자의 브라우저 환경에서 팝업 차단 설정이 활성화되어 있는 경우, 인증 모듈이 정상적으로 동작하지 않을 수 있습니다.\
이 경우, 팝업 차단 여부를 확인하고 사용자에게 팝업 허용 안내 메시지를 제공하여 정상적인 인증 절차를 진행할 수 있도록 해야 합니다.

브라우저에서는 특정 사이트에 대한 팝업 허용 설정 상태를 직접적으로 확인할 수 있는 방법은 제공하지 않습니다. 다만, `window.open()` 함수를 통해 팝업 호출 시, 팝업이 정상적으로 열렸는지 여부를 아래와 같은 방식으로 확인할 수 있습니다.

**예시 코드**

```javascript
const popup = window.open('https://example.com', '_blank');
if (!popup || popup.closed || typeof popup.closed === 'undefined') {
  alert('팝업이 차단되어 인증을 진행할 수 없습니다. 브라우저의 팝업 허용 설정을 확인해주세요.');
}
```

KCP 인증 모듈은 HTML form 태그를 이용해 팝업 창을 호출하는 방식을 사용하므로, 이를 응용하여 팝업 차단 여부를 확인할 수 있습니다. 일반적인 `window.open()` 호출 외에도, form을 통한 팝업 호출 시 반환되는 팝업 객체를 활용하여 팝업이 정상적으로 열렸는지 여부를 체크할 수 있습니다.

**예시 코드**

```javascript
const response = await fetch("/kcp/id-verification/form");  // 인증모듈 form 요청(예시)
const source = await response.text();

const parser = new DOMParser();
const doc = parser.parseFromString(source, "text/html"); //DOM Document로 변환

const formElement = doc.querySelector("form#form_auth");  // 응답받은 form 데이터의 name 값 참조
document.body.appendChild(formElement);

const popup = window.open("", formElement.target);  // 응답받은 form 데이터의 target 값 참조
formElement.submit();

if (!popup || popup.closed || typeof popup.closed === 'undefined') {
  alert('팝업이 차단되어 인증을 진행할 수 없습니다. 브라우저의 팝업 허용 설정을 확인해주세요.');
}
```


# 상품 리스트

쇼핑몰에서 판매하는 상품의 리스트를 전시하는 화면입니다.

* 🅐 [전시 카테고리](#undefined)
* 🅑 [상품 리스트 조회 영역](#undefined-1)
* 🅒 [좋아요 버튼](#undefined-2)

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

***

### 🅐 전시 카테고리 <a href="#display-category" id="display-category"></a>

쇼핑몰 어드민에 매핑된 상품 카테고리를 출력하는 영역입니다.\
상위 depth의 카테고리의 경우 해당 카테고리 하위 카테고리에 매핑된 전체 상품을 출력합니다.&#x20;

아래 어드민 경로에서 설정하실 수 있습니다.&#x20;

```
shop by basic/pro : 상품 > 상품 분류 관리 > 전시 카테고리 관리
shop by premium : 전시관리 > 전시 카테고리 관리
```

> [GET /categories](https://docs.shopby.co.kr/?url.primaryName=display/#/Category/get-categories-by-keyword)
>
> ► 전시 카테고리 조회\
> 쇼핑몰의 모든 카테고리 정보를 조회합니다.

쇼핑몰 화면에서 카테고리란, 화면이 바뀌어도 대부분의 경우 화면에 상시 노출되는 요소입니다.

아래 2가지 형태의 카테고리 데이터를 제공합니다.&#x20;

* flatCategories : 모든 카테고리를 하나의 배열에 쭉 나열한 형태
* multiLevelCategories : 계층을 가지는 카테고리 형태 (최대 5depth)

기본 스킨에서는 <mark style="background-color:yellow;">multiLevelCategories</mark>를 사용하고 있습니다.\
따라서 카테고리는 아래와 같이 계층 구조로 구성되며, 최대 5depth까지 어드민에서 카테고리를 추가할 수 있습니다.

***

### 🅑 상품 리스트 조회 영역 <a href="#product-list-search" id="product-list-search"></a>

아래 GET /products/search 호출을 통해 리턴 값으로 받은 상품 리스트를 노출하는 영역입니다.&#x20;

> [GET /products/search ](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-search)
>
> ► 상품 검색하기 \
> 다양한 검색 옵션에 맞는 상품 리스트를 조회합니다.
>
> 선택 값인 파라미터(Parameters)에 어떤 값을 입력하느냐에 따라 \
> 카테고리, 정렬, 검색 등 다양한 조건의 상품 리스트를 가져올 수 있습니다.

> [GET /categories/{categoryNo}/display-setting](https://docs.shopby.co.kr/?url.primaryName=display/#/Category/get-category-display-setting)
>
> ► 전시카테고리 진열 설정 조회
>
> 전시카테고리번호(categoryNo)에 해당하는 전시카테고리의 진열 설정을 조회합니다.\
> API 응답으로 전달된 진열 방식을 기준으로 화면의 정렬 여부와 상품 조회 API의 정렬 조건(`order.by`)을 결정합니다.

{% hint style="info" %}
기본 스킨에서는 전시카테고리의 진열 방식이 **'자동 진열'** 인 경우에만 정렬 조건 선택 영역이 노출되며,\
**'수동 진열'** 인 경우에는 노출되지 않습니다.
{% endhint %}

#### <mark style="background-color:violet;">**㉠ 정렬 조건 order.by**</mark>

#### 1. 자동 정렬 <a href="#id-1-ec-9e-90-eb-8f-99-ec-a0-95-eb-a0-ac" id="id-1-ec-9e-90-eb-8f-99-ec-a0-95-eb-a0-ac"></a>

운영자가 별도로 노출 순서를 설정하지 않은 경우 기본으로 적용되는 정렬 방식입니다.\
아래 정렬 조건은 `order.by` 의 자동 정렬 조건이며, 운영자가 원하는 정렬 조건을 호출하여 \
상품 리스트를 노출할 수 있습니다.

* &#x20;자동 정렬 조건&#x20;
  * ✅판매량순 (POPULAR) : 주문 건 수 기준
  * ✅낮은/높은 가격순 (DISCOUNTED\_PRICE) : 할인 적용가 기준
  * ✅상품 후기순 (REVIEW) : 상품 후기 갯수 기준
  * ✅신상품순 (RECENT\_PRODUCT) : 상품 등록일 기준
  * 판매일자(SALE\_YMD), 판매종료일자(SALE\_END\_YMD : 판매시작/종료일 기준
  * 좋아요순 (LIKE\_CNT) : 좋아요 갯수 기준
  * 유효일자순 (EXPIRATION\_DATE) : 상품 유효일자 기준
  * 인기순(POPULAR) : 판매가 및 인기도 기준 [점수 산정 기준 보기 >](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-search)

✅ 표시된 항목은 개별형 스킨에 기본으로 출력되는 정렬조건

#### 2. 수동 정렬 <a href="#id-2-ec-88-98-eb-8f-99-ec-a0-95-eb-a0-ac" id="id-2-ec-88-98-eb-8f-99-ec-a0-95-eb-a0-ac"></a>

운영자가 어드민에서 직접 설정한 상품 노출 순서를 그대로 프론트에 반영하는 정렬 방식입니다.\
`order.by` 파라미터의 `DISPLAY_CATEGORY_ORDER` 값을 호출하면,\
서비스어드민의 **전시관리 > 전시카테고리 진열 관리** 메뉴에서 설정한 상품 순서(상단 고정 포함)대로\
상품 리스트가 출력됩니다.<br>

**📌 TIP**\
**어드민에서의 상품 노출 순서 조정**

전시카테고리 진열 관리(수동 진열)에서 운영자는 카테고리별 상품 노출 순서를 직접 조정할 수 있습니다.

* **순서 변경** : 상품을 체크한 뒤 `최상단 / 위로 / 아래로 / 최하단` 버튼 또는 `N번째로 이동` 입력으로 노출 순서를 조정합니다.
* **상단 고정** : 특정 상품을 카테고리 최상단에 고정 노출할 수 있습니다.\
  &#x20;                (상단 고정 → 일반 진열 순서 순으로 노출)

#### <mark style="background-color:violet;">㉡ 카테고리  categoryNos</mark>

전달된 전시카테고리 번호를 기준으로 해당 전시카테고리 내의 상품을 검색합니다.<br>

#### <mark style="background-color:violet;">㉢ 키워드 검색 filter.keywords</mark>

키워드 검색창(search engine)에 입력하여 검색 시, 기본 스킨에서는 '{검색어} 검색결과 N개' 라고 안내문구가 출력되며, 검색된 결과가 없는 경우 '검색 결과가 없습니다.' 라고 상품 리스트 출력 영역에 안내 문구가 노출됩니다.&#x20;

***

### 🅒 좋아요 버튼 <a href="#like-button" id="like-button"></a>

상품 리스트 화면에서 기본 스킨의 상품 리스트 조회 영역은 [메인 상품진열 영역](/aurora-guide/api-1/main/display-product#eb-94-94-ec-8a-a4-ed-94-8c-eb-a0-88-ec-9d-b4-ec-9c-a0-ed-98-95-pc-mobile)의 디스플레이 유형 중 '갤러리형'으로 제공됩니다.  \
따라서 좋아요 버튼이 제공되며, 장바구니 버튼은 제공되지 않습니다.&#x20;

좋아요 기능은 쇼핑몰 회원(member)의 경우에만 사용 가능하므로, 버튼 클릭 시 로그인 여부를 확인해야 합니다.

* 비회원(guest)
  * 비회원의 경우 좋아요 기능을 지원하지 않습니다.
  * 좋아요 버튼 클릭 시 로그인 여부를 확인하여, 미로그인(비회원)시 서비스이용불가 안내창 노출 후 로그인 페이지로 현재창 이동해야 합니다.
* 회원(member)
  * 로그인한 상태에서 좋아요 버튼 클릭 시, 아래 POST /profile/like-products를 호출합니다.
  * 해당 API로 좋아요가 적용된 상품은 [마이페이지\_쇼핑정보](https://workspace-help.nhn-commerce.com/undefined-1/api-1/greater-than/undefined-3) 내 '좋아요' 리스트에 추가됩니다.

> [POST /profile/like-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Profile/post-profile-like-products)
>
> ▶ 회원이 상품을 좋아한다고 추가/삭제하기\
> 회원이 좋아요한 상품을 목록에 추가하거나 삭제합니다


# 상품 상세

특정 상품의 상세 정보를 확인할 수 있는 상품 상세화면 문서입니다.

* [상품 기본 정보 ](/aurora-guide/api-1/product-detail/product-summary)
* [상품 상세 배너 (모바일 전용)](/aurora-guide/api-1/product-detail/banner)
* [상품 상세정보 (탭)](/aurora-guide/api-1/product-detail/product-detail)
* [배송/반품/교환 안내 (탭)](/aurora-guide/api-1/product-detail/shipping_claim)
* [상품후기 (탭)](/aurora-guide/api-1/product-detail/product-review)
* [상품문의 (탭)](/aurora-guide/api-1/product-detail/inquiry)
* [관련상품](/aurora-guide/api-1/product-detail/relatedproducts)

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


# 상품 기본 정보

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

* 🅐 [상품 기본정보](#undefined)
* 🅑 [옵션 정보](#undefined-1)
* 🅒 [쿠폰 다운받기](#undefined-3)
* 🅓 [좋아요 버튼](#undefined-4)
* 🅔 [장바구니 버튼](#undefined-5)
* 🅕 [구매하기 버튼](#undefined-6)

***

### 🅐 상품 기본 정보

> [GET /products/{productNo}](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-product)
>
> ► 상품 상세 조회하기\
> 해당 상품번호 {productNo}에 대한 상세 정보를 조회합니다.&#x20;

해당 상품 정보에 대한 상품 이미지 URL, 상품 기본정보, 상세 정보, 배송/반품/교환, 후기, 문의, 관련상품 등의 정보를 조회할 수 있습니다.&#x20;

엔드 포인트 URL에 따라 본 화면을 구성하는 여러가지 데이터를 불러오며, 영역별로 API를 소개합니다.&#x20;

***

### 🅑 옵션 정보

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

쇼핑몰에서 판매할 상품을 등록할 때, '상품 (예시 : 오로라 수딩 세럼)' 에 대한 '옵션 (예시 : 30ml, 50ml, 100ml)'을 설정할 수 있습니다.&#x20;

아래 어드민 경로에서 2가지 형태의 옵션 기능을 제공합니다.&#x20;

{% code overflow="wrap" %}

```
shop by basic/pro : 상품 > 상품 관리 > 상품 등록 > 일반 상품 > 판매정보 > 옵션 사용 여부 '사용함'
shop by premium : 상품관리 > 상품등록 > 일반 상품 > 판매정보 > 옵션 사용 여부 '사용함'
```

{% endcode %}

### ◼︎ 옵션 유형

#### ⓐ 선택형 옵션 (조합형)

쇼핑몰 고객이 선택하는 형태의 옵션입니다.\
shop by 에서는 여러 옵션을 조합하는 '선택형(조합형) 옵션' 형태를 제공하고 있습니다.&#x20;

노출 방식에 따라 '분리형'과 '일체형' 2가지 유형으로 구분됩니다.

* 분리형 옵션 multiLevelOptions : 각 옵션 별로 계층(단계)를 구분하여 셀렉트 박스를 제공합니다.
* 일체형 옵션 flatOptions : 쇼핑몰 고객이 선택할 수 있는 옵션을 모두 리스트업 하여 셀렉트 박스를 제공합니다.

<div><figure><img src="/files/iBDWirCS9zgQHFblVwU4" alt=""><figcaption><p>분리형 옵션</p></figcaption></figure> <figure><img src="/files/yWCpWNmD1g5JJrQg2W1Y" alt=""><figcaption><p>일체형 옵션</p></figcaption></figure></div>

#### ⓑ 텍스트 옵션

쇼핑몰 고객이 직접 옵션값을 입력하는 형태입니다.\
어드민에서 '매칭타입'에 따라 상품별 / 옵션별로 텍스트 옵션을 노출할 수 있습니다.

* 상품별 : 쇼핑몰 고객이 상품 당 1개의 텍스트 옵션만 입력할 수 있습니다.
* 옵션별 : 각 옵션별로 개별 텍스트 옵션을 입력할 수 있습니다.
* 수량별 : 설정한 수량만큼 텍스트 옵션을 입력할 수 있습니다.

<div><figure><img src="/files/yHaeU69OrEuqf7pMdrft" alt=""><figcaption><p>상품별</p></figcaption></figure> <figure><img src="/files/jjySycdFZIj5vhin3r7V" alt=""><figcaption><p>옵션별</p></figcaption></figure> <figure><img src="/files/rUURNMg5EMgVXja8IdL6" alt=""><figcaption><p>수량별</p></figcaption></figure></div>

### ◼︎ 옵션 조회 API

{% hint style="info" %}
상품을 구매하는 기준은 '상품 단위'가 아니라 '옵션 단위' 입니다.&#x20;
{% endhint %}

상품의 옵션 단위로 주문이 진행되므로 옵션이 없는 상품은 없습니다.\
어드민에서 옵션 없는 상품으로 등록한 경우, 내부적으로는 자동으로 하나의 옵션이 생성됩니다.&#x20;

따라서 쇼핑몰 고객이 실제로 상품을 구매하기 위해서는\
본 화면에서 GET /products/{productNo}와 함께 아래 옵션 조회 API를 반드시 호출해야 합니다.

> [GET /products/{productNo}/options](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-product-options)
>
> ► 상품 옵션 조회하기 \
> 해당 상품번호(productNo)에 대한 옵션 정보를 조회합니다.

#### **◼︎ TYPE**

* 선택형 옵션 및 텍스트 옵션을 선택할 수 있습니다.&#x20;
* 만약 어드민에서 옵션 사용 여부를 '사용 안 함'으로 설정한 경우 응답 값이 Default로 내려옵니다.

#### **◼︎ flatOptions**

* 일체형 옵션 (각 옵션들의 조합으로 생성되는 모든 옵션을 쭉 나열한 데이터)&#x20;
* selectType에서 flat 선택 시 flatLevelOptions 값을 활용

<div align="left"><figure><img src="/files/Q15Y9QrI0aFxD7dvHZD3" alt=""><figcaption></figcaption></figure></div>

#### **◼︎ multuLevelOptions**

* 분리형 옵션 (계층 구조로 구성된 옵션 데이터)
* selectType 에서 multi 선택 시 multiLevelOptions 값을 활용

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

#### ◼︎ input

* inputLabel 텍스트 옵션 내 입력 문구를 의미합니다.
* ex) 최근에 생산된 상품으로 보내주세요.

***

### 🅒 쿠폰 다운받기

쇼핑몰 고객이 현재 다운로드 받을 수 있는 쿠폰 리스트와 쿠폰을 다운받을 수 있는 팝업을 노출합니다.\
상품 기본 정보에서 \[쿠폰받기] 버튼 클릭 시 쿠폰 다운로드 팝업을 출력합니다.

<figure><img src="/files/8GPgagSZoi3SMUQzUygi" alt=""><figcaption></figcaption></figure>

> [GET /coupons/products/issuable/coupons](https://docs.shopby.co.kr/?url.primaryName=promotion/#/Coupon/get-issuable-coupons-by-product-nos)
>
> ► 상품번호 리스트별 발급 가능한 쿠폰 조회하기
>
> 본 상품과 추가상품에서 발급 가능한 모든 쿠폰을 조회합니다.

쿠폰 다운받기 팝업에서, \[쿠폰받기] / \[쿠폰 한번에 받기] 버튼 클릭 시 로그인 여부를 체크 후 쿠폰을 다운로드 합니다.

\[쿠폰받기] 버튼 클릭 시 개별로 쿠폰을 다운로드합니다.

> [POST /coupons/{couponNo}/download](https://docs.shopby.co.kr/?url.primaryName=promotion/#/Coupon/post-download-coupons)
>
> ► 쿠폰 발급하기
>
> 선택한 쿠폰번호에 해당하는 다운로드 쿠폰을 발급 받습니다.

\[쿠폰 한번에 받기] 버튼 클릭 시 상품번호 리스트 별로 발급 가능한 모든 쿠폰을 다운로드 합니다.

> [POST /coupons/products/download](https://docs.shopby.co.kr/?url.primaryName=promotion/#/Coupon/post-download-coupons-bulk-by-product-nos)
>
> ► 상품번호 리스트별 발급 가능한 쿠폰을 다운로드 하기\
> 본 상품과 추가상품에서 다운로드 받을 수 있는 모든 쿠폰을 발급합니다.

상품번호(productNo) 리스트로 해당 상품에서 다운받을 수 있는 모든 쿠폰을 발급합니다. 추가상품이 설정된 경우, 본 상품과 추가상품의 상품번호 리스트를 활용합니다.

아래 어드민 경로의 설정에 따라 정보가 노출됩니다.

```
shop by basic/pro : 프로모션 > 혜택관리 > 쿠폰 관리
shop by premium : 프로모션관리 > 할인쿠폰 관리
```

#### ⓐ 출력되는 쿠폰

* 발급 유형 : 다운로드 발급
* 발급 상태 : 발급중
* 해당 상품이 대상 상품인 쿠폰
* 즉시 할인가를 기준으로 할인되는 금액이 높은 순으로 쿠폰을 정렬
* 할인 금액이 동일하다면 주문 쿠폰이 상품 쿠폰보다 상단에 출력
* 할인되는 금액 및 혜택 구분이 모두 동일하다면 쿠폰 등록일 기준 최신순으로 출력

#### ⓑ 혜택

* 정률로 설정 시 % 출력, 정액으로 설정 시 금액 출력
* 쿠폰 유형 (주문적용 쿠폰 → 주문 할인 / 상품적용 쿠폰 → 상품 할인)
* 최대 할인금액 (할인 금액을 정률로 설정한 경우에만 노출)
* 최소 기준금액 (최소 금액을 설정하는 경우 노출)

#### ⓒ 다운로드 버튼

* 발급 시 (회원 별 발급 수량 제한이 있을 경우) '발급 완료' 표기
* 발급 불가 쿠폰의 경우 안내 문구 출력\
  (발급 대상 회원 등급일 경우 / 발급 불가한 시간, 요일인 경우 / 쿠폰의 일별 총 발급 수량 소진 시)

***

### 🅓 좋아요 버튼

해당 상품을 좋아요 상품 리스트에 추가/삭제 할 수 있습니다. \
좋아요 기능은 쇼핑몰 회원(member)의 경우에만 사용 가능하므로, 버튼 클릭 시 로그인 여부를 확인해야 합니다.

* 비회원(guest)
  * 비회원의 경우 좋아요 기능을 지원하지 않습니다.
  * 좋아요 버튼 클릭 시 로그인 여부를 확인하여, 미로그인(비회원)시 서비스이용불가 안내창 노출 후 로그인 페이지로 현재창 이동해야 합니다.
* 회원(member)
  * 로그인한 상태에서 좋아요 버튼 클릭 시, 아래 POST /profile/like-products를 호출합니다.
  * 해당 API로 좋아요가 적용된 상품은 [마이페이지\_쇼핑정보](https://nhnent.dooray.com/share/pages/WoOk8q6KT1K3MZcLSuyZsw/3519672284532356682) 내 '좋아요' 리스트에 추가됩니다.

> [POST /profile/like-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Profile/post-profile-like-products)
>
> ▶ 회원이 상품을 좋아한다고 추가/삭제하기\
> 회원이 좋아요한 상품을 목록에 추가하거나 삭제합니다

***

### 🅔 장바구니 버튼&#x20;

선택한 상품을 옵션 단위로 장바구니에 추가하는 기능입니다.\
장바구니(cart) 버튼 클릭 시, 상품 옵션 선택 여부를 확인 후 [장바구니 화면](/aurora-guide/api-1/cart)으로 이동합니다.&#x20;

<div align="left"><figure><img src="/files/2CqIJoelsg2DZ2gL8BBj" alt="" width="563"><figcaption></figcaption></figure></div>

장바구니 버튼 기능은 쇼핑몰 회원 여부와 상관없이 제공합니다.\
단, 회원인 경우에만 API를 호출하며 비회원인 경우 API 호출이 아닌 localStorage에 자체적으로 저장합니다.

* 회원(member)
  * 로그인한 상태에서 장바구니 담기 버튼 클릭 시, 아래 POST /cart를 호출하여 선택한 상품의 옵션이 장바구니에 추가됩니다.&#x20;

> [POST /cart](https://docs.shopby.co.kr/?url.primaryName=order/#/Cart/post-cart)
>
> ▶ 장바구니 등록하기\
> 로그인 회원의 상품 구매 수량과 옵션을 장바구니에 등록합니다.

* 비회원(guest)
  * 비회원인 경우에도 장바구니 담기 버튼을 제공합니다.
  * 단, API 호출이 아닌 localStorage 내 비회원 장바구니 데이터를 자체적으로 관리해야 합니다.
  * localStorage에 비회원 장바구니 데이터 저장 시, POST /cart의 request body와 동일한 데이터 형식으로 저장해야 합니다. 이후 상품 상세화면 혹은 장바구니 화면에서 주문서 호출 시 request 형식을 통일하기 위한 목적입니다.

***

### 🅕 구매하기 버튼&#x20;

<div align="left"><figure><img src="/files/EEFZjNZ4a6ACMJFxO9qn" alt="" width="563"><figcaption></figcaption></figure></div>

버튼 클릭 시 우선 로그인 여부를 확인한 뒤 POST /order-sheets API로 주문서를 생성합니다.\
만약 미로그인(비회원)일 경우에는 해당 API로 비회원 주문을 진행합니다.&#x20;

> [POST /order-sheets](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/post-order-sheet)
>
> ► 주문서 생성 요청\
> 선택한 상품의 옵션에 대한 주문서를 생성합니다.

주문서를 생성하는 API로 주문서 화면으로 이동하기 전 단계에서 호출해야 합니다.\
해당 API에서 응답 값으로 획득한 주문서 번호 orderSheetNo를 [주문서 화면](/aurora-guide/api-1/order-sheet-form)으로 전달합니다. \
비회원 주문인 경우 accessToken을 null로 보냅니다.&#x20;


# 상품 상세 배너 (모바일 전용)

<div align="left"><figure><img src="/files/rkZanhCRjGjKQC2RWeJ1" alt="" width="375"><figcaption></figcaption></figure></div>

> [GET /skin-banners](https://docs.shopby.co.kr/?url.primaryName=display/#/SkinBanner/get-skin-banners)
>
> ► 전체 배너 조회하기\
> 쇼핑몰의 모든 배너 정보를 조회합니다.

앞서 메인 화면 > 배너 영역 문서에서 소개한 API 입니다.\
해당 배너 리스트 데이터에 상품 상세에 표기되는 배너 정보가 포함되어 있습니다.

아래 어드민 경로에서 모바일 스킨의 '상품 상세 배너'에서 설정한 정보를 불러올 수 있습니다.&#x20;

```
shop by basic/pro : 디자인 > 디자인 설정 > 스킨 배너 관리
shop by premium : 전시관리 > 스킨 배너 관리
```

메인 페이지 외에 상품 상세에서도 배너 정보를 불러와 사용할 수 있습니다.&#x20;


# 상품 상세정보 (탭)

상품 상세 정보 영역에 대해 소개합니다.

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

아래 어드민 경로에서 항목들에 대한 에디터(editor)기능을 제공하고 있습니다.\
에디터 기능을 통해 쇼핑몰 관리자는 상품 상세 정보 영역에 노출할 내용을 작성할 수 있습니다.&#x20;

```
shop by basic/pro : 상품 > 상품 관리 > 상품 등록 
shop by premium : 상품관리 > 상품등록
```

<div align="left"><figure><img src="/files/sDvtYOJtnx7XokgpenJX" alt="" width="563"><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="/files/YCmtbC8OvvbZCze9OJoO" alt=""><figcaption></figcaption></figure></div>

* 상품 상세
  * 상품 상세 (상단)
  * 상품 상세&#x20;
    * ⓐ 등록된 옵션 이미지 사용
  * 상품 상세 (하단)
* 기본 정보
  * 원산지
  * 제조일자
  * 유효일자
* 상품정보제공고시
* 인증정보

> [GET /productNo](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-product)
>
> ► 상품 상세 조회\
> 해당 상품번호(productNo)에 대한 상세 정보를 조회합니다.

[상품 기본정보](https://workspace-help.nhn-commerce.com/undefined-1/api-1/undefined-7/undefined) 문서에서 소개했던 API 입니다. \
해당 상품번호에 대한 상품 기본정보, 상세 정보, 배송/반품/교환, 후기, 문의, 관련상품 등의 정보를 조회할 수 있습니다.&#x20;

어드민에 작성한 데이터를 그대로 쇼핑몰 고객들이 보는 화면에 노출합니다.\
해당 정보들은 GET /products/{productNo} 리턴 값에 포함되어 있으며, 에디터로 작성한 내용은 html 코드 형태로 제공하므로 곧바로 상품 페이지 html 에 추가할 수 있습니다.

* contentFooter : 상품 상세 하단
* content : 상품 상세
* contentHeader : 상품 상세 상단

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

#### ⓐ 등록된 옵션 이미지 사용&#x20;

상품 상세정보 영역에서 '등록된 옵션 이미지 사용' 기능에 대해 소개합니다.

어드민에서 '상품 상세 사용' 토글 대신 '등록된 옵션 이미지 사용' 항목을 선택할 수 있습니다. \
등록된 옵션 이미지 사용 선택 시, 옵션 이미지가 등록되어 있는 옵션의 이미지 등록 여부 및 사용 여부에 따라\
\[판매정보 > 옵션 > 옵션 수정] 에서 등록해 두었던 옵션의 첫 번째 옵션 값과 이미지가 노출됩니다.&#x20;

<div align="left"><figure><img src="/files/RS9hfgTOECDkrzhVU0lI" alt="" width="563"><figcaption></figcaption></figure></div>

> [GET /products/{productNo}/options/{optionNo}/images](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-option-images)
>
> ► 옵션의 이미지 정보 조회하기 \
> 해당 상품번호(productNo)에 대한 옵션 이미지 목록 정보를 조회합니다.


# 배송/반품/교환 안내 (탭)

상품 배송/반품/교환 안내 영역에 대해 소개합니다.

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

아래 어드민 경로에서 항목들에 대한 에디터(editor)기능을 제공하고 있습니다.\
에디터 기능을 통해 쇼핑몰 관리자는 상품 배송/반품/교환 영역에 노출할 내용을 작성할 수 있습니다.&#x20;

```
shop by basic/pro : 상품 > 상품 관리 > 상품 등록 
shop by premium : 상품관리 > 상품등록
```

<div align="left"><figure><img src="/files/qcsoSr9eBKVMD1EM2A51" alt="" width="563"><figcaption></figcaption></figure></div>

* 배송/반품/교환 안내
  * 배송안내
  * AS안내
  * 교환안내
  * 환불안내&#x20;

> [GET /productNo](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-product)
>
> ► 상품 상세 조회\
> 해당 상품번호(productNo)에 대한 상세 정보를 조회합니다.

[상품 기본정보](https://workspace-help.nhn-commerce.com/undefined-1/api-1/undefined-7/undefined) 문서에서 소개했던 API 입니다. \
해당 상품번호에 대한 상품 기본정보, 상세 정보, 배송/반품/교환, 후기, 문의, 관련상품 등의 정보를 조회할 수 있습니다.&#x20;

어드민에 작성한 데이터를 그대로 쇼핑몰 고객들이 보는 화면에 노출합니다.\
해당 정보들은 GET /products/{productNo} 리턴 값에 포함되어 있으며, 에디터로 작성한 내용은 html 코드 형태로 제공하므로 곧바로 상품 페이지 html 에 추가할 수 있습니다.


# 상품후기 (탭)

상품 상세 > 상품후기(탭) 영역을 소개합니다.

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

> [GET/ products/{productNo}/product-reviews](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-product-product-reviews)
>
> ► 상품평 목록 조회하기\
> 해당 상품번호에 작성된 상품평을 조회합니다.&#x20;

해당 상품번호(productNo) 기준으로 작성된 상품평 목록을 조회하며, 아래의 항목으로 리스트를 구성합니다.

* 상품 정보 (상품 이미지 / 상품명 / 옵션명)
* 별점
* 작성자/작성일
* 후기 정보 (후기 내용 / 후기 이미지)

***

<figure><img src="/files/3YVAO8lZ98U0jCJHoUFk" alt=""><figcaption></figcaption></figure>

* 🅐 [상품후기 등록](#undefined)
* 🅑 [상품후기 수정](#undefined-1)
* 🅒 [상품후기 상세조회](#undefined-2)
* 🅓 [상품후기 삭제](#undefined-3)

***

### 🅐 상품후기 등록

작성 가능한 상품후기 목록은 구매한 상품의 옵션 기준으로 출력됩니다.\
로그인한 회원의 상품이 배송완료되어, 상품평을 작성할 수 있는 상태일 경우 \[상품후기 등록] 버튼을 노출합니다.&#x20;

\[상품후기 등록] 버튼 클릭 시 상품후기 등록 팝업이 출력됩니다.

<div align="left"><figure><img src="/files/irdFa3HBw96Tx0QGL9bP" alt="" width="563"><figcaption></figcaption></figure></div>

> [GET /products/{productNo}/product-reviews](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/post-product-reviews)
>
> ► 상품평 등록하기\
> 해당 상품번호에 대한 상품평을 등록합니다.

해당 상품번호(productNo) 기준으로 상품평을 등록할 수 있습니다. \
상품후기 등록 팝업에서 아래 항목을 제공합니다.

* 주문상품 선택
  * 나의 게시글 > 상품후기에서 게시글 등록이 가능한 주문상품(옵션 기준)을 선택해야 합니다.&#x20;
* 평점&#x20;
  * 0점, 1점, 2점, 3점, 4점, 5점 / 최대 5점까지 선택 가능합니다.
* 내용
  * 최대 1,000자 까지 입력 가능합니다.
* 첨부파일&#x20;
  * 첨부파일은 최대 10개까지 등록 가능하며, 1개당 용량은 5MB로 제한됩니다.
  * 단, 어드민 상품후기 게시판 설정에서 첨부파일 '사용 안 함'으로 설정 시 첨부파일 기능은 제공되지 않습니다.

***

### 🅑 상품후기 수정

> [PUT /products/{productNo}/product-reviews/{reviewNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/put-product-review)
>
> ► 상품평 수정하기\
> 작성자 본인의 상품후기를 수정합니다.&#x20;

해당 상품번호(productNo)에 대한 작성자 본인의 상품후기를 수정합니다.

상품후기는 작성자 본인만 수정 가능 합니다.\
수정이 가능한 범위는 주문상품, 평점, 내용, 첨부파일 입니다.&#x20;

***

### 🅒 상품후기 상세조회

* [GET /products/{productNo}/product-reviews/{reviewNo} 상품평 가져오기](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-products-product-reviews) API 로 수정할 상품후기 정보를 조회해 수정 폼에 노출합니다.

***

### 🅓 상품후기 삭제

> [DELETE /products/{productNo}/product-reviews/{reviewNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/delete-product-review)
>
> ► 상품평 삭제하기\
> 해당 상품번호에 대한 작성자 본인의 상품후기를 삭제합니다.&#x20;

해당 상품번호(productNo)에 대한 작성자 본인의 상품후기를 삭제합니다.


# 상품문의 (탭)

상품 상세 > 상품문의(탭) 영역을 소개합니다.

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

상품문의는 회원만 작성 가능하며, 비회원 작성이 불가합니다.\
비밀글 쓰기 기능이 '사용함'인 경우 상품문의 등록 팝업에서 비밀글 여부를 설정할 수 있는 기능을 제공해야 합니다.&#x20;

아래 어드민 경로에서 설정이 가능합니다.

```
shop by basic/pro : 게시판 > 게시판 관리 > 상품문의 > 상품문의 설정 (탭)
shop by premium : 상품관리 > 상품문의 관리 > 상품문의 설정 (탭)
```

> [GET /products/{productNo}/inquiries](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/get-product-inquiries)
>
> ► 상품문의 목록 조회하기\
> 해당 상품번호에 대한 상품 문의 목록을 조회합니다.

해당 상품번호(productNo)에 대한 상품문의 목록을 조회합니다.\
답변이 완료되지 않은 문의 글에 대해서만 수정 및 삭제가 가능합니다.&#x20;

***

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

* 🅐 [상품문의 등록](#undefined)
* 🅑 [상품문의 수정](#undefined-1)
* 🅒 [상품문의 상세조회](#undefined-2)
* 🅓 [상품후기 삭제](#undefined-3)

***

### 🅐 상품문의 등록

기본 스킨의 경우 상품 상세 > 상품문의 (탭)에서 \[상품문의 등록] 버튼을 제공하고 있어, \
해당 버튼을 통해 상품문의 게시글 등록이 가능합니다.

\[상품문의 등록] 버튼 클릭 시 상품문의 등록 팝업이 출력되며, 회원에게만 제공됩니다.&#x20;

<div align="left"><figure><img src="/files/0Scn9dxsTb7LQRW3t6Wm" alt="" width="563"><figcaption></figcaption></figure></div>

> [POST /products/{productNo}/inquiries ](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/post-product-inquiries)
>
> ► 상품문의 등록하기 \
> 해당 상품번호에 대한 상품문의를 등록합니다.

해당 상품번호(productNo) 기준으로 상품문의를 등록할 수 있습니다. \
상품문의 등록 팝업에서 아래 항목을 제공합니다.

* 문의유형
  * 문의유형은 어드민에서 등록한 문의유형을 select-box로 제공합니다.
* 상품
  * 문의할 상품이 porductNo 기준으로 고정되어 있습니다.
* 내용
  * 최대 1,000자까지 입력 가능합니다.
* 비밀글 설정
  * 어드민에서 비밀 글쓰기를 '사용함'으로 설정하는 경우 등록 시 비밀글 여부를 선택할 수 있습니다.
  * 어드민에서 비밀 글쓰기를 '사용 안 함'으로 설정하는 경우 등록 시 비밀글 여부 항목은 제공되지 않아야 합니다.

***

### 🅑 상품문의 수정

> [PUT /inquiries/{inquiryNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/put-product-inquiry)
>
> ► 상품문의 수정하기\
> 해당 문의번호 inquiryNo에 대한 상품문의를 수정합니다.

상품문의 '제목' 클릭 시, 작성자 본인만 상품문의를 수정할 수 있습니다.\
제목 / 내용 / 문의 유형만 수정이 가능하며, 답변이 완료된 문의는 수정할 수 없습니다.&#x20;

***

### 🅒 상품문의 상세조회

[GET /products/{productNo}/inquiries/{inquiryNo} 상품문의 조회하기](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/get-product-inquiry) API 를 호출 해 상품문의 수정 폼에 상세 정보를 노출할 수 있습니다.

***

### 🅓 상품문의 삭제

> [DELETE /products/inquiries/{inquiryNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/delete-product-inquiry)
>
> ► 상품문의 삭제하기
>
> 작성자의 상품문의를 삭제합니다.

상품문의 '제목' 클릭 시, 작성자 본인만 상품문의를 삭제할 수 있습니다.\
답변이 완료되지 않은 문의 건에 대해서만 삭제가 가능합니다.

상품문의 상세 조회 시 inquirystatus (답변상태) 값이 답변완료인 경우, \
\[삭제] 버튼을 미노출하며 삭제기능을 제공하지 않습니다.&#x20;


# 관련상품

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

어드민에서 설정한 관련상품 목록을 상품 상세페이지 최하단에 노출합니다.

아래 어드민 경로에서 관련상품을 설정할 수 있습니다.

```
shop by basic/pro : 상품 > 상품관리 > 상품 등록/수정 > 기본정보 - 관련상품 설정
shop by premium : 상품관리 > 상품 등록/수정 > 기본정보 - 관련상품 설정
```

> [GET /products/{productNo}/related-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-related-products)
>
> ► 관련상품 정보 조회하기 \
> 관련상품 정보를 조회할 수 있습니다.&#x20;

디스플레이 유형은 스와이프형으로 세로 1줄로 설정한 관련상품이 스와이프를 통해 확인이 가능합니다.

{% hint style="info" %}
관련상품을 '사용안 함' 설정 시 영역이 미노출됩니다.&#x20;
{% endhint %}


# 추가상품

* 🅐 [추가상품 설정](#undefined)
* 🅑 [추가상품 전용](#undefined-1)

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

***

#### **🅐 추가상품 설정**

어드민에서 설정한 추가상품 목록을 본 상품의 상세 페이지에 노출합니다.

<img src="https://nhnent.dooray.com/wikis/4116818104642965673/files/4190116949668991762" alt="" width="937">

ⓐ **상품 선택**

추가상품에 설정된 옵션이 없을 경우, 상품 선택 여부를 결정할 수 있는 영역이 노출됩니다.

ⓑ **옵션 선택**

추가상품에 설정된 옵션이 있을 경우, 옵션 선택 여부를 결정할 수 있는 영역이 노출됩니다.

아래 어드민 경로에서 추가상품을 설정할 수 있습니다.

```
shop by basic/pro : 상품 > 상품관리 > 상품 등록/수정 > 판매정보 - 추가상품 설정
shop by premium : 상품관리 > 상품 등록/수정 > 판매정보 - 추가상품 설정
```

> [GET/products/{productNo}/extra-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-extra-products)
>
> ► 추가상품 조회하기\
> 상품번호에 대한 추가상품을 조회할 수 있습니다.

선택된 추가상품의 노출 순서는 어드민에 저장된 순서가 반영되며, 최초에는 상품 등록일 기준 오름차순으로 정렬됩니다.

{% hint style="info" %}
선택한 상품에 저장된 노출 설정에 따라, 최종적으로 쇼핑몰 표시 여부가 결정됩니다.
{% endhint %}

{% hint style="danger" %}
기본스킨에서는 노출 가능한 상품이더라도, <mark style="background-color:red;">본 상품과 같이 결제 가능한 수단이 없다면 추가상품이 미노출</mark>됩니다.

API에서는 결제 수단에 따른 추가상품의 노출여부를 필터링하지 않으며, 결제 수단 정보만 전달합니다.
{% endhint %}

따라서 기본스킨에서는 [`상품 상세 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-product)의 `baseInfo.paymentMeans` 와 [`추가상품 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-extra-products)의 `extraProducts[].paymentMeans` 를 비교하여 일치하는 결제 수단이 1개 이상 없을 경우, 해당 본 상품에 설정된 추가상품을 노출하지 않도록 처리합니다.

{% hint style="info" %}
추가상품의 옵션을 조회할 때는 본 상품과 다르게 [`옵션 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product%20Option/get-product-options)를 활용하지 않고[`추가상품 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product%20Option/get-product-options)에서 제공하는 `extraProducts[].optionInfo` 를 활용합니다.
{% endhint %}

다만, [`추가상품 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-extra-products)에서 제공하는 옵션 정보는 기존 [`옵션 조회하기 API`](https://docs.shopby.co.kr/?url.primaryName=product/#/Product%20Option/get-product-options)의 필드 구성 및 데이터 구조와 **상이한 부분**이 있습니다.  만약 일반 상품 상세 옵션과 동일한 로직으로 처리해야 하는 경우, 필드명 및 데이터 구조가 기존과 **호환되도록 변환 처리**가 필요할 수 있습니다.

자세한 필드 구성 및 응답 구조는 **API 문서**를 참고하시기 바랍니다.

***

#### **🅑 추가상품 전용**

어드민에서 설정한 추가상품을 추가상품 전용으로만 사용합니다.

아래 어드민 경로에서 추가상품 전용여부를 설정할 수 있습니다.

```
shop by basic/pro : 상품 > 상품관리 > 상품 등록/수정 > 판매정보 - 추가상품 전용
shop by premium : 상품관리 > 상품 등록/수정 > 판매정보 - 추가상품 전용
```

\[추가상품 전용 : 사용함]으로 설정된 상품은 본 상품과 함께 구매만 가능합니다.

{% hint style="danger" %} <mark style="background-color:red;">쇼핑몰에서 검색 시 노출이 제한</mark>되며, 상품의 상세 페이지 진입 시 '접근 불가' 알럿을 출력합니다.
{% endhint %}


# 장바구니

장바구니 화면을 소개합니다

* 🅐 [장바구니 리스트](#undefined) (장바구니 리스트 및 금액, 옵션 변경, 삭제)
* 🅑 [금액 정보](#undefined-4) (상품 선택에 따른 금액계산)
* 🅒 [주문 버튼](#undefined-5)

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

***

### 🅐 장바구니 리스트

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

### ㉠ 장바구니 목록 조회

장바구니 목록 정보를 조회하여, 해당 금액을 합산해 화면에 노출합니다.\
장바구니에 담긴 상품의 정보는 장바구니에 추가된 시점이 아닌 현재 시점 기준으로 출력됩니다.

로그인 여부에 따라 회원과 비회원 장바구니 목록을 조회하는 API가 상이하나, \
응답 값 (Responses)형식은 동일합니다.&#x20;

#### ◼︎ **장바구니 리스트 내 추가상품이 포함된 화면**

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

#### ◼︎ 회원 (member)

> [GET /cart](https://docs.shopby.co.kr/?url.primaryName=order/#/Cart/get-cart)
>
> ► 장바구니 목록 조회하기\
> 로그인 회원의 장바구니 목록을 조회합니다.&#x20;

회원의 장바구니 목록 내 상품 정보와 합배송 상품의 합산 금액 정보를 조회합니다.&#x20;

* <mark style="background-color:yellow;">deliveryGroups</mark>
  * 실제 구매 가능한 장바구니 목록입니다.
  * 장바구니 관련 아래 소개 드릴 API에서 파라미터로 자주 활용되는 cartNo (장바구니 번호)의 경우, \
    스키마 내 orderProductOptions에서 상품 옵션 별로 확인 가능합니다.
  * 동일 배송지별 합배송을 하기 위해서, 배송지 그룹 deliveryGroups > 주문 상품 orderProducts > 주문 상품 옵션 orderProductOptions 기준으로 매핑되어 3depth 배열로 응답 값이 나열됩니다.&#x20;
  * '옵션'과 '텍스트 옵션'이 모두 동일한 상품일 경우, orderProductOptions 에서 optionNo와 optionInputs값을 비교하여 '중복 상품' 이라는 안내 라벨을 화면에 노출합니다.&#x20;
  * 추가상품 여부의 경우, orderProductOptions에서 isExtraProduct로 확인 가능합니다.
    * 추가상품은 상품명 앞에 \[추가] 라벨을 표시하고, 상품명 상단에 본상품명인 baseProductName을 노출합니다.
    * 단, 장바구니 내에서 본상품과 추가상품의 연관관계가 사라질 경우 위 추가상품 정보를 노출하지 않습니다.
  * 추가상품 전용 여부의 경우, orderProducts에서 extraProductOnly로 확인 가능합니다.
* <mark style="background-color:yellow;">price</mark>
  * 장바구니 가격 정보입니다.
  * 실제 구매 가능한 장바구니 리스트 deliveryGroups 를 모두 합산한 가격을 노출합니다.\
    (총 합계금액 = 총 상품금액 - 총 할인금애 + 총 배송비)
  * 배송비&#x20;
    * 만약 합배송이라서 동일한 배송비가 묶여서 적용되는 경우 열을 병합하여 배송비를 표기합니다.
    * 묶음 기준은 어드민의 배송비 템플릿 '묶음 배송 불가' 상품입니다.&#x20;
  * 예상 적립금
    * accumulationAmtWhenBuyConfirm 을 호출하여 노출할 수 있으며, \
      '(판매가 - 즉시할인금액 ± 옵션가)x수량' 으로 계산됩니다.&#x20;
    * 단, 어드민에서 '구매 적립금 기준 금액'에 따라 선택되지 않은 금액은 계산 시 제외됩니다.&#x20;
* <mark style="background-color:yellow;">invalidProducts</mark>
  * 장바구니에 추가한 상품 중, 구매 불가능한 장바구니 리스트입니다.
  * 구매 불가능 상품 invalidProducts > 주문 상품 옵션 orderProductOptions 기준으로 매핑(mapping)되어 2depth 배열로 응답 데이터가 나타납니다.
  * invalidProducts인 경우 '구매 제한 상품' 처리하여 화면에 노출하며 합산 가격에서는 해당 가격을 제외합니다.&#x20;
  * 추가상품 관련 필드를 deliveryGroups와 동일하게 확인 가능합니다.
    * 추가상품은 deliveryGroups와 동일하게 \[추가] 라벨과 함께 본상품명을 노출합니다.
  * 추가상품 전용 여부의 경우, extraProductOnly로 확인 가능합니다.

#### ◼︎ 비회원 (guest)

> [POST /guest/cart](https://docs.shopby.co.kr/?url.primaryName=order/#/GuestOrder/post-guest-cart)
>
> ► 비회원 장바구니 목록 조회하기\
> 로그인 하지 않은 비회원의 장바구니 목록을 조회합니다.

로그인 하지 않은 비회원의 장바구니 금액 및 합배송 상품을 계산하여 장바구니 목록을 조회합니다.

{% hint style="info" %}
비회원의 경우, 장바구니 데이터를 샵바이 DB 서버에 따로 저장하지 않고, localStorage에 저장하므로

아래 문서의 ㉡ 장바구니 옵션/수량 변경, ㉢ 장바구니 삭제, 🅑 금액 정보에 대한 API가 별도로 존재하지 않고

모두 해당 POST/ guest/cart를 호출하여 조회/수정/계산 합니다.&#x20;
{% endhint %}

{% hint style="info" %}
비회원 장바구니의 경우, 같은 상품이더라도 엮인 본상품 번호가 다른 추가상품인 경우, 행을 별도로 노출합니다.
{% endhint %}

### ㉡ 장바구니 옵션/수량 변경&#x20;

장바구니 화면 내에서 상품의 옵션 및 수량 변경이 가능합니다.

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

상품 이미지 하단에 \[옵션/수량 변경] 버튼이 출력되며, 클릭 시 옵션 별로 옵션 및 수량 정보를 수정할 수 있습니다.\
구매 불가 상품의 경우 해당 버튼이 노출되지 않습니다.&#x20;

{% hint style="info" %}
상품을 구매하는 기준은 '상품 단위'가 아닌 '옵션 단위' 입니다.
{% endhint %}

#### ◼︎ Step 1. \[옵션/수량 변경] 버튼 클릭&#x20;

[상품 상세화면](/aurora-guide/api-1/product-detail/product-summary)에서 소개한 GET /products/{productNo}/options 을 호출하여 \
해당 상품의 모든 옵션 정보를 불러와 select-box 구현합니다.&#x20;

> [GET /product/{productNo}/options](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-product-options)
>
> ► 상품 옵션 조회하기\
> 해당 상품번호(productNo)에 대한 옵션 정보를 조회합니다.

{% hint style="info" %}
장바구니에서 상품의 '옵션을 변경' 한다는 것은 기존 항목을 삭제하고 새로운 항목을 추가하는 프로세스 입니다. 따라서, (step 2-1) 옵션 변경이 포함된 경우와 (step 2-2) 옵션을 변경하지 않고 수량만 변경하는 경우에 각각 호출하는 API가 상이합니다.&#x20;
{% endhint %}

#### ◼︎ Step 2-1. 옵션 변경 및 옵션과 수량을 함께 변경하는 경우

'변경 완료' 버튼 클릭 시 아래 2가지 API를 호출하여 DELETE /cart 로 기존 장바구니 옵션을 삭제하고, \
POST /cart 로 새로운 장바구니 옵션을 등록합니다.

> [DELETE /cart](https://docs.shopby.co.kr/?url.primaryName=order/#/Cart/delete-cart)
>
> ► 장바구니 삭제하기\
> 로그인 회원의 장바구니를 삭제합니다.

> [POST /cart](https://docs.shopby.co.kr/?url.primaryName=order/#/Cart/post-cart)
>
> ► 장바구니 등록하기\
> 로그인 회원의 장바구니 구매 수량과 옵션을 등록합니다.&#x20;

Request Body <mark style="background-color:yellow;">OptionInputs</mark> 을 통해 텍스트 옵션도 수정 가능합니다.&#x20;

추가상품 전용 상품의 경우, 단독으로 옵션을 등록할 수 없어 해당 상품의 옵션만 변경하는 게 불가능합니다. 따라서 회원 장바구니에서 추가상품 전용 상품의 옵션 변경 시, 다음 상품들을 함께 삭제 후 재등록해야 합니다.

* 변경할 추가상품 전용 상품(옵션 변경 대상 상품)
* 해당 추가상품 전용 상품과 엮인 본상품
* 해당 추가상품 전용 상품과 엮인 본상품과 연관관계를 갖는 추가상품 전용이 아닌 상품들(옵션 변경 대상 상품과 동일한 baseProductNo를 갖는 extraProductOnly가 false인 상품들)
  * 해당 상품을 포함하지 않을 시, 옵션 변경 대상 상품과 동일한 본상품을 갖는 추가상품 전용이 아닌 상품들은 본상품과의 연관관계를 잃게 됩니다.

#### ◼︎ Step 2-2. 옵션을 변경하지 않고, 장바구니 수량만 변경하는 경우

> [PUT /cart](https://docs.shopby.co.kr/?url.primaryName=order/#/Cart/put-cart)\
> ► 장바구니 수정하기\
> 로그인 회원의 장바구니 구매 수량을 수정합니다.

#### ◼︎ Step 3. 이후 단계

㉠ 장바구니 리스트를 다시 호출하여 화면에 노출합니다.&#x20;

### ㉢ 장바구니 삭제

장바구니 리스트에서 특정 상품만 선택하여 삭제할 수 있습니다.

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

> [DELETE /cart](https://docs.shopby.co.kr/?url.primaryName=order/#/Cart/delete-cart)
>
> ► 장바구니 삭제하기\
> 로그인 회원의 장바구니를 삭제합니다.

***

### 🅑 금액 정보

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

장바구니 리스트에서 체크박스에 '체크 된 항목이 변경될 때마다' 실시간으로 금액 정보를 계산합니다.

{% hint style="info" %}
주문 금액을 계산하는 로직은 아래 GET /cart/calculate 단일 API만 사용하시길 바랍니다.
{% endhint %}

> [GET /cart/calculate](https://docs.shopby.co.kr/?url.primaryName=order/#/Cart/get-cart-calculate)
>
> ► 장바구니에서 선택된 상품금액 계산하기\
> 장바구니에서 선택된 상품(cartNo) 금액을 게산합니다.

선택된 상품의 가격정보를 포함하여 예상 적립금도 함께 계산하여 노출됩니다.\
cartNo은 GET /cart API 내 상품 옵션 별로 orderProductOptions 에서 확인 가능합니다.&#x20;

***

### 🅒 주문 버튼

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

* **PC**
  * 상품 체크 박스 선택 후 \[선택 상품 주문] 버튼 클릭 시 선택한 상품 옵션에 대한 주문서를 생성합니다.
  * \[전체 상품 주문] 버튼 클릭 시, 장바구니 리스트 전체 상품 옵션에 대한 주문서를 생성합니다.
* **모바일**&#x20;
  * 상품 체크박스 선택 후 \[주문하기] 버튼 클릭 시, 선택한 상품 옵션에 대한 주문서를 생성합니다.&#x20;

> [POST /order-sheets](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/post-order-sheet)
>
> ► 주문서 생성 요청하기\
> 선택한 상품의 옵션에 대한 주문서를 생성합니다.

주문서를 생성하는 API로 주문서 화면으로 이동하기 전 단계에서 호출해야 합니다.\
해당 API에서 응답 값으로 획득한 주문서 번호 orderSheetsNo 를 주문서 화면으로 전달합니다.&#x20;

비회원 주문인 경우 accessToken을 null로 보냅니다.&#x20;


# 주문서

주문서 화면을 소개합니다.

* (intro) 주문서 화면 진입 로직
* 🅐 주문상품 정보
* 🅑 주문자 정보
* 🅒 배송지 정보
* 🅓 혜택 적용
* 🅔 사은품정보
* 🅕 결제수단 선택
* 🅖 결제 정보
* 🅗 약관 동의
* 🅘 결제 편의 모듈 javascript (결제하기 버튼)

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

***

### 주문서 화면 진입 로직

<div align="left"><figure><img src="/files/4x33wg4vzzVkrnrUljkg" alt=""><figcaption></figcaption></figure></div>

앞서 소개한 문서인 [상품 상세화면](/aurora-guide/api-1/product-detail), [장바구니 화면](/aurora-guide/api-1/cart) 에서 POST /order-sheets 주문서 생성 요청 API를 통해 획득한 orderSheetNo(주문서 번호)에 해당하는 주문 상품 상세 정보를 통해 '주문서 화면'을 구현합니다.

{% hint style="info" %}
단, 미로그인 상태인 경우 로그인 화면을 먼저 노출한 뒤,

로그인 실행 또는 \[비회원 주문하기] 버튼을 통해 주문서 화면에 진입합니다.&#x20;
{% endhint %}

주문서 화면에서는 회원과 비회원에 따른 화면에 대해 각각 설명합니다.&#x20;

#### ◼︎ 로그인 화면 내 \[비회원 주문하기] 버튼

<div align="left"><figure><img src="/files/tzxFj9YUHYR2t4qcWSjm" alt="" width="375"><figcaption></figcaption></figure></div>

***

### 🅐 주문상품 정보

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

주문한 상품 목록과 기본 금액 정보를 노출하는 영역입니다.\
앞서 소개드린 [장바구니 화면](/aurora-guide/api-1/cart)과 동일한 화면 구성입니다.&#x20;

POST /order-sheets를 통해 '주문서가 생성된 시점'에 확정된 금액만 노출됩니다.

{% hint style="info" %}
단, 배송지 변경 / 쿠폰 / 적립금 사용에 따른 최종 결제금액은 🅖 결제정보 영역에 실시간으로 반영됩니다.
{% endhint %}

> [GET /order-sheets/{orderSheetNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet)
>
> ► 주문서 가져오기\
> 주문서 상세 정보를 조회합니다.&#x20;

앞서 POST /order-sheets 주문서 생성 요청 API를 통해 획득한 orderSheetsNo(주문서 번호)에 해당하는 주문 상품 상세 정보를 호출합니다.

앞으로 본 주문서의 각 화면 영역을 구현하기 위해, 해당 API가 🅑 주문자 정보, 🅒 배송지 정보에서도 사용되며  각 항목에서 다시 소개해 드립니다.

주문 상품의 가격 정보는 <mark style="background-color:yellow;">deliveryGroups</mark> 내 각 옵션들이 포함한 금액 정보 (구매 금액, 할인 금액, 배송비)를 합산하여 화면에 노출합니다.\
단, 비회원 주문인 경우 accessToken을 비워둡니다.(null)

#### ◼︎ **주문상품 정보 내 추가상품이 포함된 화면**

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

본 상품과 같이 주문된 추가상품의 상품정보에는 상품명 앞에 \[추가] 라벨을, 상품명 상단에 본 상품명을 노출합니다.\
추가상품 여부는 deliveryGroups\[].orderProducts\[].orderProductOptions\[] 내 isExtraProduct, 추가상품의 본 상품명은 baseProductName로 노출합니다.

***

### 🅑 주문자 정보

주문자 정보를 노출 및 입력하는 영역으로 회원 / 비회원에 따라 다른 화면이 노출됩니다.

#### ◼︎ 회원(member)

<figure><img src="/files/3LX1JsFwmeUB8Qm5SvOa" alt=""><figcaption></figcaption></figure>

앞서 소개한 GET /order-sheets/{orderSheetsNo} 응답 값 중 <mark style="background-color:yellow;">orderContact</mark> 값을 통해 회원 정보를 자동으로 출력할 수 있으며, 해당 화면에서 주문자가 직접 수정 가능합니다.

{% hint style="info" %}
회원이 보유하지 않은 정보는 공란으로 표시되며, 주문자가 직접 입력해야 합니다.

간편 로그인 회원의 경우 '회원명, 휴대폰 번호, 이메일' 정보가 orderContact에 없을 수 있습니다.&#x20;
{% endhint %}

#### ◼︎ 비회원(guest)

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

비회원 주문인 경우 ordererContact가 null 입니다.\
따라서 주문자 정보 입력란이 모두 비어있으며, 주문자가 직접 입력할 수 있습니다.

비회원 주문 조회 시 사용할 '주문 비밀번호'를 입력할 수 있는 화면 영역이 추가되어야 합니다.&#x20;

***

### 🅒 배송지 정보

주문자의 배송지 정보를 노출 및 입력하는 화면 영역으로 회원 / 비회원에 따라 다른 화면이 노출됩니다.

{% hint style="info" %}
단, 배송지 변경에 따른 배송비 금액 변동이 있을 수 있습니다.

실시간으로 변동되는 최종 결제 금액은 🅖 결제정보 영역을 참고해주시길 바랍니다.&#x20;
{% endhint %}

#### ◼︎ 회원(member)

<figure><img src="/files/5URkjCQHTg6w0Ag4rnWX" alt=""><figcaption></figcaption></figure>

앞서 소개한 GET /order-sheets/{orderSheetsNo}응답 값 중 <mark style="background-color:yellow;">orderSheetAddress</mark> 값을 통해 배송지 정보를 자동으로 출력할 수 있으며, 해당 화면에서 주문자가 직접 수정 가능합니다.

배송지 확인 항목은 주문자가 기본 배송지, 최근 배송지, 신규 배송지 중 선택할 수 있습니다.

* 기본 배송지 : mainAddress 값을 통해 디폴트로 자동 출력되는 항목입니다.
* 최근 배송지 : recentAddress 값을 통해 회원의 주문 내역 중 가장 마지막에 주문 완료된 배송지 정보를 출력합니다.&#x20;
* 신규 배송지 : 공란이 출력되며 주문자 직접 입력이 가능한 항목입니다.&#x20;

#### ◼︎ 배송지 주소 회원정보 반영

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

배송지 주소 입력 후 '회원정보 반영' 체크 박스 클릭 후 주문 완료 시, \
해당 배송 정보의 주소가 회원의 주소 정보에 업데이트 되며, 업데이트 시 회원정보 수정 log에 반영됩니다.

이후 🅖 결제하기 영역에서 소개 드릴 POST /payments /reserve 결제하기 API에서 Request Body의 updateMember 을 true 로 보내면 회원정보의 주소가 입력된 배송지 정보로 업데이트 됩니다.

#### ◼︎ 배송지 관리

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

회원(member) 노출되는 기능입니다.\
주문서 화면에서 \[배송지 관리] 버튼 클릭 시 아래와 같이 '배송지 관리' 팝업이 출력되며,\
해당 회원이 가지고 있는 모든 배송지 정보를 조회 및 선택/수정/추가/삭제 할 수 있습니다.&#x20;

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

#### ㉠ 배송지 목록 출력

> [GET /profile/shipping-addresses](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/get-profile-shipping-addresses)
>
> ► 배송지 목록 가져오기\
> 배송지 상세 정보를 조회합니다.

<mark style="background-color:yellow;">bookedAddresse</mark>s는 '배송지 관리'에서 관리되는 배송지 목록을 내려주고 있습니다.

#### ㉡ \[배송지 추가] 버튼&#x20;

> [POST /profile/shipping-addresses](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/post-profile-shipping-addresses)
>
> ► 배송지 등록하기\
> 배송지 정보를 추가합니다.&#x20;

addressType 배송지 유형은 크게 2가지입니다.

* <mark style="background-color:yellow;">book</mark>
  * 저장된 배송지를 의미합니다.
  * 개수 제한 없이 등록이 가능합니다.
  * '배송지 관리' 내 등록 추가된 주소
  * 🅖 결제하기 영역에서 소개될 POST /payments/reserve 결제하기 API에서 Request Body의 saveAddressBook을 true로 보낼 경우 저장되는 주소
* <mark style="background-color:yellow;">RECENT</mark>
  * 최근 배송지를 의미합니다.
  * 주문 완료 시 자동 저장됩니다.
  * 해당 API에서는 최대 10개까지 최근 배송지를 내려줄 수 있으나, 기본 스킨에서는 최근 배송지를 1개만 사용하고 있습니다.&#x20;
* <mark style="background-color:yellow;">RECURRING\_PAY</mark>
  * 정기결제 배송주소로서, shop by premium에서 사용되는 항목입니다.&#x20;

#### ㉢ \[수정] 버튼

\[배송지 추가] 버튼 클릭 시 노출되는 팝업과 동일하나, 공란이 아닌 선택한 배송지 정보가 등록된 상태로 노출됩니다.

> [PUT /profile/shipping-addresses/{addressNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/put-profile-shipping-addresses-address-no)
>
> ► 배송지 수정하기\
> 선택한 배송지 번호 기준으로 배송지의 상세 정보를 수정합니다.&#x20;

#### ㉣ \[삭제] 버튼&#x20;

> [DELETE /profile/shipping-addresses/{addressNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/delete-profile-shipping-addresses-address-no)
>
> ► 배송지 삭제하기\
> 선택한 배송지 번호 기준으로 배송지의 정보를 삭제합니다.&#x20;

#### ◼︎ 비회원(guest)

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

비회원 주문인 경우, 앞서 소개한 GET /order-sheets/{orderSheetsNo}응답 값 중 orderSheetAddress값이 null이므로 주문자가 배송지 정보를 직접 입력해야합니다.

#### ◼︎ \[우편번호 찾기] 버튼&#x20;

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

\[우편번호 찾기] 버튼 클릭 시, 우편번호 찾기 레이어가 출력됩니다.

> [GET /adresses/search](https://docs.shopby.co.kr/?url.primaryName=manage/#/Address/search-addresses)\
> ► 주소 조회하기\
> 검색된 키워드로 주소 정보를 조회합니다.

#### ◼︎ 개인통관고유부호

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

상품의 해외배송 여부에 '해외배송 상품' 체크 표시된 상품인 경우, '개인통관고유부호' 입력 항목이 추가로 노출됩니다. \
\[개인통관고유부호 발급] 버튼 클릭 시, [관세청 개인통관고유부호 발급](https://unipass.customs.go.kr/csp/persIndex.do) 사이트가 출력됩니다.&#x20;

{% hint style="info" %}
'개인통관고유부호'는 회원 / 비회원 동일하게 적용됩니다.
{% endhint %}

***

### 🅓 혜택 적용

&#x20;회원의 경우에만 '쿠폰 사용' 및 '적립금 사용' 항목이 노출되며, 비회원의 경우 노출되지 않습니다.

#### ◼︎ 회원(member)

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

#### ◼︎ 비회원(guest)&#x20;

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

비회원 주문하기 시, 혜택 적용 영역에서 \[회원 로그인] 클릭 시 로그인 화면으로 이동합니다.&#x20;

#### ◼︎ 쿠폰 적용하기 팝업

회원(member)에게만 노출되는 기능입니다.

> [GET /order-sheets/{orderSheetNo}/coupons](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheets-order-sheet-no-coupons)
>
> ► 적용 가능한 쿠폰정보 조회하기\
> 해당 주문서에 적용 가능한 모든 쿠폰 (상품쿠폰, 주문쿠폰)을 조회합니다.

주문서 화면에서 \[쿠폰 사용] 버튼 클릭 시, 해당 API를 통해 쿠폰 적용하기 팝업이 발생합니다.\
회원이 이미 발급 받아 보유한 쿠폰 중, 해당 주문서에 적용 가능한 모든 쿠폰 (상품쿠폰, 주문쿠폰)을 노출합니다.

제공하는 쿠폰의 유형에는 '상품 쿠폰'과 '주문 쿠폰 (장바구니쿠폰)' 2가지 종류가 있습니다.\
각각 개별 상품 혹은 주문 단위 (장바구니)로 적용이 가능합니다.

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

* **상품 쿠폰**
  * 상품 단위의 쿠폰으로, 하나의 상품에는 하나의 상품 쿠폰만 적용할 수 있습니다.
  * 하나의 상품에 특정 쿠폰(couponNo기준)을 적용했을 경우, 다른 상품에는 해당 쿠폰을 적용할 수 없으며 '사용 불가' 안내 메시지가 출력됩니다.
  * 만약 회원이 동일한 상품 쿠폰을 여러 장 발급 받았을 경우, 각 쿠폰은 couponNo기준으로 별개의 쿠폰이므로 하나의 상품에만 적용 가능합니다.
  * '쿠폰 미사용' 옵션이 가장 상단에 출력되며, 이후 할인 금액이 높은 순 > 등록일 기준 최신 순으로 정렬됩니다.
* **주문 쿠폰 (장바구니 쿠폰)**
  * 주문서에 적용할 수 있는 쿠폰으로, 주문서 당 하나의 주문 쿠폰만 적용이 가능합니다.
  * 배송비를 제외한 주문금액에 적용되는 쿠폰입니다.

***

### **🅔 사은품 정보**&#x20;

사은품을 선택할 수 있는 영역입니다.
\
최종 결제금액을 기준으로 지급조건을 충족한 사은품이 있는 경우에만 '사은품 정보' 영역이 노출됩니다.

아래 어드민 경로에서 사은품 기본 설정 및 지급조건을 관리할 수 있습니다.

```
shop by enterprise : 프로모션관리> 사은품 관리
```

#### **◼︎ 받을 수 있는 사은품 목록**

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

> [GET /order-sheets/{orderSheetNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet)
>
> ► 주문서 가져오기\
> 주문서 상세 정보를 조회합니다.

응답 값 중 `freeGiftInfos`를 통해 지급 가능한 사은품 정보를 화면에 노출합니다.

{% hint style="info" %}
어드민 설정의 '사은품 중복지급 허용' 여부에 따라 API에서 조회되는 사은품 정보가 달라질 수 있습니다.

* '허용 안 함'인 경우 : 가장 최근에 등록된 1개의 지급조건만 주문서에 노출됩니다.
  * 단, 주문에 주문금액 기준 지급조건과 상품금액 기준 지급조건이 모두 적용된 경우, 주문금액 기준 지급조건이 우선 적용됩니다.
* '허용함'인 경우 : 지급조건을 만족한 사은품이 모두 노출됩니다.
  * 동일한 사은품 조건이 중복 응답될 수 있으며 이 경우 동일한 사은품 지급조건 번호를 가집니다.\
    따라서, 조건별 유효성 검증이나 사은품 선택 처리를 위해 사은품 지급조건 번호 외에 고유한 식별자를 별도로 생성하여 관리해야 합니다.
    {% endhint %}

사은품은 100% 할인으로 설정되어 시스템 상 0원으로 처리되지만, 프론트 화면에서는 가격 정보가 노출되지 않습니다.

> [POST /order-sheets/{orderSheetNo}/calculate](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/post-order-sheets-order-sheet-no-calculate)
>
> ► 쿠폰 및 배송지 정보가 적용된 금액 조회하기\
> 쿠폰 및 적립금 정보가 적용된 금액/사은품 정보를 계산합니다.

쿠폰·적립금 등 혜택 정보가 변경될 경우, 지급 가능한 사은품 조건이 달라질 수 있습니다.\
따라서 쿠폰 또는 적립금 사용 후에는 해당 API를 호출하여 변경된 혜택 정보가 반영된 `freeGiftInfos`값을 다시 조회한 뒤, 해당 정보를 기준으로 사은품 정보를 화면에 노출합니다.

사은품 지급 금액 기준은 다음과 같습니다.

* 상품금액 기준 : 상품별로 금액조건을 체크하여 사은품을 지급합니다.
  * 기준금액 : 판매가 – 즉시할인금액 ± 옵션가 - 추가할인금액 - 상품쿠폰 할인금액
* 주문금액 기준 : 주문당 금액조건을 체크하여 사은품을 지급합니다.
  * 총 주문금액의 합 기준금액 : ∑(판매가 – 즉시할인금액 ± 옵션가 - 추가할인금액 - 상품쿠폰 할인금액) - 주문쿠폰 할인금액
  * 지급 대상 금액의 합 기준금액 : ∑(판매가 – 즉시할인금액 ± 옵션가 - 추가할인금액 - 상품쿠폰 할인금액)

#### **◼︎ 사은품 지급옵션 수량**

사은품 지급옵션 수량(`freeGiftInfos[].freeGiftOptionCountType`)은 두 가지 타입으로 구분됩니다.

* **`ALL`: 전체 지급**
  * 최대 지급 가능한 개수를 화면에 표시하지 않습니다.
  * 사은품을 선택하는 체크박스와 `선택 안 함` 항목을 화면에 표시하지 않습니다.
  * [결제하기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve) 호출 시, 선택한 사은품 목록을 전달하지 않으면 사은품이 전체 지급됩니다.
* **`SELECT`: 선택 개수 설정**
  * 최대 지급 가능한 개수를 화면에 표시합니다.
  * 사은품을 선택하는 체크박스와 `선택 안 함` 항목을 화면에 표시합니다.
  * 각 사은품 지급 조건마다 `freeGiftInfos[].freeGiftOptionCount` 을 초과하여 사은품을 선택하는 경우, 얼럿을 노출합니다.
  * [결제하기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve) 호출 시, 선택한 사은품 목록을 전달하지 않으면 사은품이 지급되지 않습니다.

***

### 🅕 결제수단 선택

결제 수단을 선택할 수 있는 영역입니다.&#x20;

{% hint style="info" %}
단, 적립금 전액 결제 또는 결제정보에서 '최종 결제 금액'이 0원인 경우, 해당 영역이 노출되지 않습니다.&#x20;
{% endhint %}

아래 어드민 경로에서 결제수단 사용 설정에 따라 노출 항목이 달라집니다.

```
shop by pro: 설정 > 기본정책 > 쇼핑몰 관리 에서 결제
shop by enterprise : 현재 어드민기능을 제공예정중입니다. 
(별도 결제수단 추가 필요 시, NHN 커머스1:1문의를 통해 요청바랍니다)
```

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

> [GET /order-sheets/{orderSheetNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet)
>
> ► 주문서 가져오기\
> 주문서 상세 정보를 조회합니다.

응답 값 중 availablePayTypes의 payType를 통해 위와 같이 어드민에서 설정한 결제 수단 화면을 노출합니다.\
비회원 주문인 경우 accessToken을 비워둡니다. (null)\
이후 '🅘  결제하기 버튼' 클릭 시, 선택된 각 결제 수단에 따라 해당 결제 모듈이 팝업 형태로 노출됩니다.

단, '무통장 입금'의 경우 별도의 결제 모듈을 사용하지 않으므로' \
입금자명 / 계좌번호를 추가로 입력 받아 🅘 결제하기 API 호출 시 전달해야 합니다.\
계좌 정보의 경우' 응답 값 중 <mark style="background-color:yellow;">tradeBankAccountInfos</mark>을 참고하실 수 있습니다.

***

### 🅖 결제정보

🅐 주문상품 정보 영역에서 노출되었던 금액 정보에서, 🅓 혜택 적용 정보를 실시간으로 반영한 최종 결제금액 화면입니다.

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

최종 금액을 계산하는 로직은 GET /order-sheets/{orderSheetNo}/calculate 단일 API만 사용하시기 바랍니다.

> [POST /order-sheets/{orderSheetNo}/calculate](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/post-order-sheets-order-sheet-no-calculate)
>
> ► 쿠폰 및 배송지 정보가 적용된 금액 조회하기\
> 쿠폰 및 적립금 정보가 적용된 금액을 계산합니다.

🅓 혜택 적용 영역에서 쿠폰 사용 및 적립금 사용 금액이 변경될 때마다 해당 API를 호출하여, \
'최종 결제금액' 정보를 실시간으로 화면에 노출합니다.&#x20;

비회원 주문인 경우 accessToken을 비워둡니다. (null)

* accumulationUseAmt 적립금 정보
* couponRequest 쿠폰 정보

***

### 🅗 약관 동의

결제하기 전 필요한 약관 동의에 대한 영역입니다.\
회원 / 비회원에 따라 다른 화면이 노출됩니다.&#x20;

기본 스킨에서는 기본적으로 '구매 진행 동의' 약관이 필수로 노출되며, \
로그인 여부에 따라 그 외 약관이 추가로 노출됩니다.

아래 어드민 경로에서 약관 내용을 관리하실 수 있습니다.&#x20;

```
shop by pro: 설정> 기본 정책> 약관/개인정보 처리방침 관리
shop by enterprise : 서비스관리> 약관/개인정보 처리방침 관리 
```

> [GET /rerms](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms)
>
> ► 몰 약관 조회하기\
> 해당 쇼핑몰에 적용 중인 약관을 조회합니다.

해당 API는 주문서 구매 동의 화면 뿐 아니라, 회원가입, 회원탈퇴 및 쇼핑몰 푸터 영역에서도 활용됩니다.

#### ◼︎ 회원(member)

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

* \[필수] 구매 진행 동의 약관&#x20;
  * 구매 진행동의 기본 문구가 노출됩니다. (구매하실 상품의 결제 정보를 확인하였으며, 구매 진행에 동의합니다.)
* \[필수] 개인정보 수집/이용 <mark style="background-color:yellow;">PI\_COLLECTION\_AND\_USE\_REQUIRED</mark>
* \[필수] 개인정보 판매자 제공 <mark style="background-color:yellow;">PI\_SELLER\_PROVISION</mark> (파트너사상품 포함 시)
* \[필수] 개인정보 국외이전 동의 <mark style="background-color:yellow;">TRANSFER\_AGREE</mark> (해외배송상품 포함 시)
* \[필수] 통관정보 수집/이용 <mark style="background-color:yellow;">CLEARANCE\_INFO\_COLLECTION\_AND\_USE</mark> (해외배송상품 포함 시)
* \[필수] 주류구매 개인정보 제공 동의 <mark style="background-color:yellow;">PI\_LIQUOR\_PURCHASE\_PROVISION</mark> (주류카테고리 상품 포함 시)

#### ◼︎ 비회원(guest)

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

* \[필수] 구매 진행 동의 약관&#x20;
  * 구매 진행동의 기본 문구가 노출됩니다. (구매하실 상품의 결제 정보를 확인하였으며, 구매 진행에 동의합니다.)
* \[필수] 이용약관 <mark style="background-color:yellow;">USE</mark>
* \[필수] 개인정보 수집/이용 <mark style="background-color:yellow;">PI\_COLLECTION\_AND\_USE\_REQUIRED</mark>
* \[필수] 개인정보 판매자 제공 <mark style="background-color:yellow;">PI\_SELLER\_PROVISION</mark> (파트너사상품 포함 시)
* \[필수] 개인정보 국외이전 동의 <mark style="background-color:yellow;">TRANSFER\_AGREE</mark> (해외배송상품 포함 시)
* \[필수] 통관정보 수집/이용 <mark style="background-color:yellow;">CLEARANCE\_INFO\_COLLECTION\_AND\_USE</mark> (해외배송상품 포함 시)

***

### 🅘 결제 편의 모듈 javascript (결제하기 버튼)

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

실제 결제 API 를 호출하는 화면입니다.\
'결제하기'버튼 클릭 시, 🅕 결제 수단 선택에 따라 결제가 진행됩니다.

* PG 결제수단 선택 시 각 PG사 결제 모듈이 레이어 팝업으로 출력됩니다.
* 무통장 입금 / 0원 결제 / 전액 적립금 결제인 경우, 버튼 클릭 시 주문 완료 처리됩니다.

#### ◼︎ 결제 편의 모듈

결제하기 버튼 클릭 시, 결제에 필요한 데이터 유효성 체크 후 실제 결제를 위한 샵바이 API를 호출합니다.

샵바이 서버에서는 Client에서 결제 API 를 호출할 수 있는 간단한 javascript 코드를 제공하고 있습니다.\
[자세한 내용은 결제 모듈(NCPPay) 가이드를 참고해주세요.](https://workspace-help.nhn-commerce.com/contents/recommended/ncp_pay)

#### ◼︎ 결제하기 API

reservation에 필요한 request 값은 아래 API 데이터 양식을 참고하시길 바랍니다.

> [POST /payments/reserve](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve)
>
> ► 결제하기\
> 주문 된 결제를 진행합니다.

Request Body 내 payType 결제수단과 PgTypes외부 PG사에 대해 안내드립니다.\
해당 값 들은 GET /order-sheets/{orderSheetNo} 주문서 조회하기 API에서, \
해당 쇼핑몰/상품이 설정한 결제수단에 따라 availablePayTypes 사용가능한 결제정보 응답 값으로 내려줍니다.

쇼핑몰에서 다양한 PG사와 계약해서 결제수단을 제공할 수 있기 때문에, payType을 기준으로 pgTypes를 내려주고 있으니 프론트에서 구현 시 내려온 pgTypes에 따라 결제모듈을 제공할 수 있습니다.

#### ◼︎ 결제 결과

`결제 모듈(NCPPay)`에 설정한 confirmUrl로 성공 또는 실패 결과를 리턴합니다.\
이후 결제 성공 여부에 따라 '주문완료' 또는 '주문 실패' 화면을 출력합니다.


# 마이페이지 > 쇼핑정보

마이페이지 '쇼핑정보'에 대해 페이지 구현하는 방식을 소개합니다.

* 🅐 [주문목록/배송조회](/aurora-guide/api-1/mypage-shopping/order-list) ([클레임 신청](/aurora-guide/api-1/mypage-shopping/order-list#undefined-8))
* 🅑 [취소/반품/교환 내역](/aurora-guide/api-1/mypage-shopping/claim-list)
* [주문 상세](/aurora-guide/api-1/mypage-shopping/order-detail)
* 🅒 [좋아요](/aurora-guide/api-1/mypage-shopping/like-product-list)

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


# 주문목록/배송조회

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

기본 스킨에서 주문목록/배송조회 페이지는 아래와 같은 항목으로 구성되어 있습니다.

* 주문일자(주문번호) : 주문이 발생한 일자 (YYYY.MM.DD) 와 주문번호가 노출되며, 해당 주문 클릭시 주문 상세 페이지로 이동 가능합니다.
* 상품 정보 : 동일 주문 번호 내 상품 옵션 기준으로 상품의 썸네일, 상품명, 구매한 옵션 (선택형 옵션, 텍스트형 옵션)이 출력됩니다.&#x20;
* 수량 : 주문 상품 구매 수량을 출력합니다.
* 상품금액 : 상품 결제 금액이 출력됩니다.
* 진행상태 : 주문 상품 기준으로 조회 시점의 주문상태와 클레임 상태가 출력됩니다.
* 접수 : 주문 상품의 '진행상태'에 따른 클레임 신청 버튼이 출력됩니다.&#x20;

#### ◼︎ 주문목록/배송조회 내 추가상품이 포함된 화면

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

* 추가상품 정보 : 동일 주문 번호 내 상품 옵션 기준으로 상품 정보와 추가상품 구분 표시(\[추가] 라벨, 엮인 본 상품명)이 출력됩니다.

비회원의 경우 비회원 인증 후(주문번호 및 주문비밀번호 입력) 주문 목록 접근 시 주문 상세 페이지로 이동됩니다.\
비회원 주문상세 페이지에 대해서는 아래 비회원 주문상세에서 확인 하실 수 있습니다.

기본 스킨의 경우 아래 API 를 통해 아래와 같이 주문 목록 화면을 제공하고 있습니다.

> [GET /profile/orders](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/get-profile-orders)
>
> ► 주문 리스트 조회하기\
> 회원 기준으로 일정 기간동안 생성한 주문 리스트를 조회합니다.&#x20;

회원이 일정 기간 (시작일\~종료일) 에 생성한 주문리스트를 조회하는 것으로 accessToken(회원 엑세스 토큰)을 기준으로 호출하여 주문리스트 데이터를 응답 받을 수 있습니다.\
주문 리스트 조회 API의 경우 시작일\~종료일을 지정하여 주문리스트를 호출하거나, 주문상태를 지정하여 주문리스트를 호출 할 수도 있습니다.

* 기본 스킨의 경우 당일로 부터 이전 7일 까지의 주문리스트를 Default로 제공합니다.\
  주문번호 내 상품 옵션기준으로 상품정보가 노출되므로, 1개의 주문번호에 주문한 다수 개의 상품 정보가 출력될 수 있습니다.
* 오로라 개별형 기본 스킨에는 한 페이지 당 20개의 주문번호를 노출합니다

***

### 🅐 상품 정보

주문리스트 조회 API GET/ profile/orders에서는 상품 정보를 주문번호 <mark style="background-color:yellow;">itms</mark> > 옵션주문번호<mark style="background-color:yellow;">orderOptions</mark> 기준으로 2Depth 배열로 데이터 제공하며, 기본 스킨에서는 위의 2Depth 데이터인 <mark style="background-color:yellow;">orderOptions</mark> 값을 옵션 단위의 1Depth 배열로 구성하여 화면을 출력하고 있습니다.

***

### 🅑 진행상태

진행상태 영역에서는 해당 주문 건의 주문상태 및 클레임 상태를 출력합니다.

* 주문 상태 : 입금대기 , 결제완료, 상품준비중, 배송준비중, 배송중, 배송완료, 구매확정
* 클레임 상태 : 취소신청, 취소대기, 취소완료, 교환신청, 교환처리, 교환완료, 반품신청, 반품처리, 반품완료

주문 상태, 클레임 상태의 출력은 주문리스트 조회 API 의 응답값 중  <mark style="background-color:yellow;">clameStatusType</mark> (클레임 상태 정보), <mark style="background-color:yellow;">orderStatusTypeLabel</mark> (주문 상태 정보),  <mark style="background-color:yellow;">nextAction</mark> (다음에 할 수 있는 작업)등을 사용하여 진행상태 텍스트와 버튼을 제공할 수 있습니다.

<mark style="background-color:yellow;">clameStatusType</mark> (클레임 상태 정보)의 응답 여부에 따라 진행상태 값을 출력합니다.

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

#### ◼︎ ⓐ 주문 상태

클레임 정보가 없는 경우 주문 상태 정보를 출력 합니다.\
즉, <mark style="background-color:yellow;">clameStatusType = null</mark> 일 때, <mark style="background-color:yellow;">orderStatusTypeLabel</mark> 값을 주문 상태 정보로 출력할 수 있습니다.

#### ◼︎ ⓑ 클레임 상태

클레임 정보가 있는 경우 클레임 상태 정보를 출력 합니다.\
즉, <mark style="background-color:yellow;">clameStatusType</mark> 값이 null이 아닐 때, claimStatusType , claimNo, claimStatusTypeLabel 값을 사용하여 진행상태를 출력합니다.

#### ◼︎ ⓒ 다음에 할 수 있는 버튼 (nextAcitons)

다음에 할 수 있는 작업 값을 통해 진행 상태 값에 따른 구매자 액션 버튼을 제공합니다.\
예를 들어, 진행상태가 배송완료 상태 인 경우 '배송완료'에서 구매자가 할 수 있는 액션인 <mark style="color:orange;">배송조회, 구매확정, 후기작성</mark>*<mark style="color:orange;">,</mark>* <mark style="color:orange;"></mark><mark style="color:orange;">교환신청</mark>*<mark style="color:orange;">,</mark>* <mark style="color:orange;"></mark><mark style="color:orange;">반품신청</mark>에 대한 버튼을 제공합니다.

<mark style="background-color:yellow;">nextActions</mark> 의 응답 값으로 회신 되는 값에 맞는 버튼을 노출하여 구매자에게 쇼핑몰 기능을 제공할 수 있습니다.\ <mark style="background-color:yellow;">nextActions</mark> 의 값으로는 진행상태 정보에 따라 아래의 표의 액션을 할 수 있습니다.

* 주문번호 <mark style="background-color:yellow;">items</mark> 기준

입금대기와 결제완료 상태에서만 주문단위 action이 가능합니다.

<table><thead><tr><th width="230">주문상태/클레임상태</th><th width="323">nextAction</th><th>제공 필요 버튼</th></tr></thead><tbody><tr><td>DEPOSIT_WAIT 입금대기</td><td>CANCEL_ALL 주문번호 내 전체상품 취소<br>CHANGE_ADDRESS 배송지변경</td><td>취소신청<br>배송지변경</td></tr><tr><td>PAY_DONE 결제완료</td><td>CANCEL_ALL 주문번호 내 전체상품 취소<br>CHANGE_ADDRESS 배송지변경</td><td>취소신청<br>배송지변경</td></tr></tbody></table>

* 옵션주문번호 <mark style="background-color:yellow;">orderOptions</mark> 기준

<table><thead><tr><th width="317">주문상태/클레임상태</th><th width="262">nextAction</th><th>제공 필요 버튼</th></tr></thead><tbody><tr><td>DEPOSIT_WAIT 입금대기</td><td>CANCEL (옵션별) 취소</td><td>취소신청</td></tr><tr><td>PAY_DONE 결제완료</td><td>EXCHANGE 교환<br>CANCEL 취소</td><td>교환신청<br>취소신청</td></tr><tr><td>PRODUCT_PREPARE 상품준비중</td><td>EXCHANGE 교환<br>CANCEL 취소</td><td>교환신청<br>취소신청</td></tr><tr><td>DELIVERY_PREPARE 배송준비중</td><td>EXCHANGE 교환<br>CANCEL 취소</td><td>교환신청<br>취소신청</td></tr><tr><td>DELIVERY_ING 배송중</td><td>DELIVERY_DONE 수취확인<br>VIEW_DELIVERY 배송조회<br>RETURN 반품<br>EXCHANGE 교환<br>CONFIRM_ORDER 구매확정<br>WRITE_REVIEW 후기작성<mark style="color:red;">(추가상품 전용인 경우 제공X)</mark></td><td>배송조회<br>반품신청<br>교환신청<br>구매확정<br>후기작성<mark style="color:red;">(추가상품 전용인 경우 제공X)</mark></td></tr><tr><td>DELIVERY_DONE 배송완료</td><td>VIEW_DELIVERY 배송조회<br>CONFIRM_ORDER 구매확정<br>RETURN 반품<br>EXCHANGE 교환<br>WRITE_REVIEW 후기작성<mark style="color:red;">(추가상품 전용인 경우 제공X)</mark></td><td>배송조회<br>구매확정<br>교환신청<br>반품신청<br>후기작성<mark style="color:red;">(추가상품 전용인 경우 제공X)</mark></td></tr><tr><td>BUY_CONFIRM 구매확정</td><td>WRITE_REVIEW 후기작성<mark style="color:red;">(추가상품 전용인 경우 제공X)</mark></td><td>후기작성<mark style="color:red;">(추가상품 전용인 경우 제공X)</mark></td></tr><tr><td>CANCEL_REQUEST 취소신청(승인대기)</td><td>VIEW_CLAIM 클레임조회<br>WITHDRAW_CANCEL 취소신청 취소</td><td>취소신청(=진행상태 조회버튼)<br>취소신청철회</td></tr><tr><td>CANCEL_PROC_REQUEST_REFUND 취소처리(환불보류)<br>CANCEL_PROC_WAITING_REFUND 취소처리(환불대기)</td><td>-</td><td>취소처리중(=진행상태 조회 버튼)</td></tr><tr><td>CANCEL_DONE 취소완료 (환불완료)<br>CANCEL_NO_REFUND 취소완료(환불없음)</td><td>VIEW_CLAIM 클레임조회</td><td>취소완료(=진행상태 조회 버튼)</td></tr><tr><td>EXCHANGE_REQUEST 교환신청(승인대기)</td><td>VIEW_CLAIM 클레임조회<br>WITHDRAW_EXCHANGE교환신청 취소</td><td>교환신청(=진행상태 조회 버튼)<br>교환신청철회</td></tr><tr><td>EXCHANGE_REJECT_REQUEST 교환처리(철회대기)</td><td>VIEW_CLAIM 클레임조회</td><td>교환신청(=진행상태 조회 버튼)</td></tr><tr><td>EXCHANGE_PROC_BEFORE_RECEIVE 교환처리(수거진행)<br>EXCHANGE_PROC_REQUEST_PAY 교환처리(결제대기)<br>EXCHANGE_PROC_REQUEST_REFUND 교환처리(환불보류)<br>EXCHANGE_PROC_WAITING 교환처리(처리대기)<br>EXCHANGE_PROC_WAITING_PAY 교환처리(입금처리대기)<br>EXCHANGE_PROC_WAITING_REFUND 교환처리(환불대기)</td><td>-</td><td>교환처리중(=진행상태 조회 버튼)</td></tr><tr><td>EXCHANGE_DONE 교환완료 (차액없음)<br>EXCHANGE_DONE_PAY_DONE 교환완료 (결제완료)<br>EXCHANGE_DONE_REFUND_DONE 교환완료(환불완료)</td><td>VIEW_CLAIM 클레임조회</td><td>교환완료(=진행상태 조회 버튼)</td></tr><tr><td>RETURN_REQUEST 반품신청(승인대기)</td><td>VIEW_CLAIM 클레임조회<br>WITHDRAW_RETURN 반품신청 취소</td><td>반품신청(=진행상태 조회 버튼)<br>반품신청철회</td></tr><tr><td>RETURN_REJECT_REQUEST 반품신청 (철회대기)</td><td>VIEW_CLAIM 클레임조회</td><td>반품신청(=진행상태 조회 버튼)</td></tr><tr><td>RETURN_PROC_BEFORE_RECEIVE 반품처리(수거진행)<br>RETURN_PROC_REQUEST_REFUND 반품처리(환불보류)<br>RETURN_PROC_WAITING_REFUND 반품처리(환불대기)<br>RETURN_REFUND_AMT_ADJUST_REQUESTED 반품처리(조정요청)</td><td>-</td><td>반품처리중(=진행상태 조회 버튼)</td></tr><tr><td>RETURN_DONE 반품완료(환불완료)<br>RETURN_NO_REFUND 반품완료(환불없음)</td><td>VIEW_CLAIM 클레임조회</td><td>반품완료(=진행상태 조회 버튼)</td></tr></tbody></table>

#### **◼︎ \[배송조회] 버튼**

* 배송조회 팝업을 출력합니다.
* 배송조회 팝업은 <mark style="background-color:yellow;">nextActions</mark> 의 URL 를 참고하여 출력합니다.

#### **◼︎ \[구매확정] 버튼**

* 구매확정 버튼 클릭 시 아래 구매확정 API를 호출 하여 구매확정 처리를 합니다.
* 에스크로 결제 건의 경우, 배송완료 시 PG사에서 발송한 이메일을 통해 구매확정 처리가 가능하므로 구매확정 버튼을 제공하지 않습니다.

> [PUT /profile/order-options/{orderOptionNo}/confirm](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/put-profile-order-options-order-option-no-confirm)
>
> ▶ 상품 주문 구매 확정하기\
> 상품 주문을 구매확정 처리합니다

#### **◼︎ \[후기작성] 버튼**

* 후기(상품평) 작성 버튼 클릭 시 후기를 작성할 수 있는 페이지를 제공합니다.
* 기본 스킨에서는 후기작성 페이지를 레이어팝업으로 제공하고 있습니다.&#x20;
* 페이지 형식은 스킨 개발 시 자유롭게 처리 가능합니다.

> [POST /products/{productNo}/product-reviews](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/post-product-reviews)
>
> ▶ 상품평 등록하기\
> 상품평을 등록합니다

주문 옵션 번호와 옵션 번호 기준으로 상품평을 작성할 수 있으며, 상품평 평점, 상품평 내용, 첨부파일을 등록할 수 있습니다. API 호출 시 상품번호와 회원 엑세 스토큰을 통해 작성할 상품을 지정하여 상품평을 등록 받을 수 있습니다.\
등록된 후기는 각 상품의 상품 상세 페이지 및 [마이페이지 > 나의 게시글](/aurora-guide/api-1/mypage-post)의 상품 후기메뉴에서 확인 가능합니다.

{% hint style="info" %}
&#x20;네이버페이 주문의 구매확정 이후 후기 작성이 가능합니다.\
\* 구매확정 이전 상태에서 후기 작성 요청 시 에러 메시지 회신됩니다.&#x20;

에스크로 주문건은 구매확정 이후 후기 작성이 가능합니다.\
\* 구매확정 이전 상태에서 후기작성 요청 시 에러 메시지가 회신됩니다.
{% endhint %}

{% hint style="danger" %}
\[추가상품 전용 : 사용함]인 상품은 후기 작성이 불가능합니다.\
\* 위 API를 통해 기능을 구현하여도, 후기 작성 버튼 자체가 노출되지 않습니다.
{% endhint %}

#### **◼︎ \[클레임 상태] 정보 버튼**

* 클레임 상태 정보는 주문번호 내 진행 중이거나 완료된 클레임이 있는 경우 클레임 신청 내역을 확인할 수 있는 페이지 입니다.
* 기본 스킨 기준으로 클레임 상태 정보는 레이어 팝업으로 제공되고 있습니다.

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

> [GET /profile/claims/{claimNo}/result](https://docs.shopby.co.kr/?url.primaryName=claim/#/Member/get-profile-claims-no-result)
>
> ▶ 회원 클레임 상세보기(클레임 번호)\
> 클레임 번호로 해당 회원의 클레임 신청 내역의 세부 정보를 확인합니다

> [GET /guest/claims/{claimNo}/result](https://docs.shopby.co.kr/?url.primaryName=claim/#/Guest/get-guest-claims-no-result)
>
> ▶ 클레임 상세보기 (클레임 번호)\
> 클레임 번호로 비회원의 클레임 신청 내역의 세부 정보를 확인합니다

클레임 상세 보기는 회원/비회원 여부에 따라 호출하는 API 가 다릅니다.\
회원의 경우 회원 클레임 상세 보기  API를 통해, 비회원의 경우 비회원 클레임 상세보기 API 를 통해 호출바랍니다.

***

### 🅒 접수

<figure><img src="/files/6YQ78uLmmxbKUF4HUJDW" alt=""><figcaption></figcaption></figure>

주문 목록 내 접수 항목은 주문상태에 따라 구매자가 신청 가능한 클레임 단계 (취소, 반품, 교환, 신청철회 등) 버튼이 출력됩니다.\
주문상태에 따른 클레임 신청 버튼은 [GET /profile/orders](https://docs.shopby.co.kr/?urls.primaryName=order#/%5BProfile%5D%20%3E%20MyOrder/%EC%A3%BC%EB%AC%B8%20%EB%A6%AC%EC%8A%A4%ED%8A%B8%20%EC%A1%B0%ED%9A%8C) 내 <mark style="background-color:yellow;">nextActions</mark> 의 값이 아래의 값을 가질 때 각 값에 따른 버튼을 노출해주시면 됩니다.

| nextAction         | 다음 단계 액션명         | 버튼              |
| ------------------ | ----------------- | --------------- |
| CANCEL             | 취소신청              | \[취소신청] 버튼이미지   |
| CANCEL\_ALL        | 주문번호 내 전체 상품 취소신청 | \[취소신청] 버튼이미지   |
| WITHDRAW\_CANCEL   | 취소신청 철회           | \[취소신청철회] 버튼이미지 |
| EXCHANGE           | 교환신청              | \[교환신청] 버튼이미지   |
| WITHDRAW\_EXCHANGE | 교환신청 철회           | \[교환신청철회] 버튼이미지 |
| RETURN             | 반품신청              | \[반품신청] 버튼이미지   |
| WITHDRAW\_RETURN   | 반품신청 철회           | \[반품신청철회] 버튼이미지 |

#### ◼︎ \[클레임 버튼] 구현 방법 <a href="#ed-81-b4-eb-a0-88-ec-9e-84-eb-b2-84-ed-8a-bc-ea-b5-ac-ed-98-84-eb-b0-a9-eb-b2-95" id="ed-81-b4-eb-a0-88-ec-9e-84-eb-b2-84-ed-8a-bc-ea-b5-ac-ed-98-84-eb-b0-a9-eb-b2-95"></a>

클레임 신청 버튼인 <mark style="color:orange;">취소신청 , 교환신청, 반품신청</mark> 버튼 클릭 시 클레임 신청 화면으로 이동합니다.\ <mark style="background-color:yellow;">orderOptionNo</mark>, <mark style="background-color:yellow;">claimType</mark>의 값에 따라 클레임 신청 API를 호출하며, 클레임 신청 시 회원/비회원에 따라 제공되는 API가 다릅니다.

* 회원 : [\[GET\]회원 클레임 신청 정보 조회 API](https://docs.shopby.co.kr/?urls.primaryName=claim#/Member/get-profile-order-options-no-claims)
* 비회원 : [\[GET\] 클레임 신청 정보 조회 API](https://docs.shopby.co.kr/?urls.primaryName=claim#/Guest/get-guest-order-options-no-claims)

클레임 신청 화면은 아래 페이지에서 더 자세히 확인해주세요.

#### ◼︎ 에스크로 클레임 신청 주의사항 <a href="#ec-97-90-ec-8a-a4-ed-81-ac-eb-a1-9c-ed-81-b4-eb-a0-88-ec-9e-84-ec-8b-a0-ec-b2-a-d-ec-a3-bc-ec-9d-98" id="ec-97-90-ec-8a-a4-ed-81-ac-eb-a1-9c-ed-81-b4-eb-a0-88-ec-9e-84-ec-8b-a0-ec-b2-a-d-ec-a3-bc-ec-9d-98"></a>

{% hint style="info" %}
&#x20;에스크로 결제 주문은 주문번호에 포함된 상품의 전체 취소만 가능하며, 부분 취소, 전체 교환, 부분 교환, 전체 반품, 부분 반품 신청은 불가하도록 작업해야 합니다.

\* 부분 취소, 전체 교환, 부분 교환, 전체 반품, 부분 반품 요청 시 오류 메시지를 응답하고 있습니다.
{% endhint %}

#### ◼︎ 네이버 페이 주문건 처리 방법 <a href="#eb-84-a4-ec-9d-b4-eb-b2-84-ed-8e-98-ec-9d-b4-ec-a3-bc-eb-ac-b8-ea-b1-b4-ec-b2-98-eb-a6-ac-eb-b0-a9-e" id="eb-84-a4-ec-9d-b4-eb-b2-84-ed-8e-98-ec-9d-b4-ec-a3-bc-eb-ac-b8-ea-b1-b4-ec-b2-98-eb-a6-ac-eb-b0-a9-e"></a>

네이버페이 주문건의 경우 취소/교환/반품 신청 모두 네이버페이 판매자센터에서 처리해야 합니다.

***

### 클레임 신청 (취소/반품/교환)

주문에 대한 취소/반품/교환을 신청할 수 있는 페이지를 제공합니다. 취소/반품/교환 신청 페이지는 회원 및 비회원 에 따라 API가 각각 제공되며, 아래의 API를 통해 신청 페이지를 생성하여 제공할 수 있습니다.

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

> [GET /profile/order-options/{orderOptionNo}/claims](https://docs.shopby.co.kr/?url.primaryName=claim/#/Member/get-profile-order-options-no-claims)
>
> ▶ 회원 클레임 신청을 위한 정보 조회하기\
> 회원이 구매한 주문 중 주문상품옵션 기준으로 클레임(취소/반품/교환)을 신청할 수 있도록 정보를 조회합니다

> [GET /guest/order-options/{orderOptionNo}/claims](https://docs.shopby.co.kr/?url.primaryName=claim/#/Guest/get-guest-order-options-no-claims)
>
> ▶ 클레임 신청을 위한 정보 조회하기\
> 비회원이 구매한 주문 중 클레임(취소/반품/교환)을 신청할 수 있도록 정보 조회합니다

#### ◼︎ 클레임 (취소/반품/교환) 신청 가능 주문상품 리스트

주문 내 주문상품옵션 기준으로 취소/반품/교환하려는 상품과 수량을 선택할 수 있습니다.\
클레임(취소/반품/교환)은 주문상품옵션 기준으로 하기 때문에 API 호출 시 <mark style="background-color:yellow;">orderOptionNo</mark> 기준으로 주문상품 리스트를 가져옵니다.

{% hint style="info" %}
&#x20;취소/반품의 경우 동일 주문번호 내 클레임 신청 1회에 다수의 주문상품옵션을 선택하여 복수 신청이 가능합니다.\
교환의 경우에는 클레임 1회 신청 시 동일 주문번호 내 클레임 복수 신청이 불가하니 교환 기능 제공 시 주문상품옵션 별로 각각 교환 신청이 가능하도록 기능 제공해야 합니다.

\* 네이버페이 주문의 경우 네이버페이 정책 상 각 주문상품옵션 별로 클레임 신청해야 합니다.
{% endhint %}

클레임 신청 시 복수 신청이 가능한 주문상품옵션번호의 경우 <mark style="background-color:yellow;">claimableOptions</mark> 값으로 주문상품옵션 정보를 확인할 수 있습니다.\
복수 신청이 불가한 주문상품의 경우 <mark style="background-color:yellow;">claimableOptions</mark>값은 전송되지 않습니다.

본 상품과 같이 주문된 추가상품의 상품 정보는 상품명 앞에 \[추가] 라벨을, 상품명 상단에 본 상품명을 노출합니다.\
추가상품 여부는 originalOption 내 isExtraProduct, 추가상품의 본 상품명은 baseProductName로 노출합니다.

#### ◼︎ 클레임 (취소/반품/교환) 사유

취소/반품/교환 신청 하는 사유를 입력할 수 있는 영역입니다. 입력한 귀책 사유에 따라 반품 배송비 등이 구매자 혹은 판매자에게 부과 됩니다.

클레임 사유로는 '귀책 대상' , '귀책사유', '상세사유', '첨부파일'을 입력할 수 있습니다.

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

* 귀책 대상\
  \- 귀책 대상은 구매자 BUYER, 판매자 SELLER 2가지 항목만 있습니다. \
  \- 결제완료 이후 주문건에 대해서는 모두 입력 항목 제공됩니다. (입금 대기 미제공)\
  \- 에스크로 주문 건의 경우 입력 항목 제공하지 않습니다.
* 귀책 사유\
  \- select-box로 제공하며, claimReasonTypes 스키마 ENUM으로 클레임 사유 출력합니다.\
  \- 귀책 사유의 경우에도 귀책 대상과 동일하게 결제 완료 주문건에 대해 입력 항목 제공(입금 대기 미제공)하며,

  에스크로 주문건의 경우 노출하지 않습니다.&#x20;
* 상세 사유\
  \- input 으로 입력 항목 제공합니다. \
  \- 모든 클레임 상태에서 사유에 대해 자유 입력 가능합니다.&#x20;
* 첨부파일\
  \- 클레임 신청을 증명할 수 있는 첨부파일 업로드 할 수 있습니다. \
  \- 배송중이거나 배송완료의 주문상태에서만 기능 제공됩니다.

#### ◼︎ 클레임 정보 (계좌정보)

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

무통장 및 가상계좌 입금을 통해 주문한 경우, 환불 금액을 받을 계좌 정보를 입력할 수 있습니다.\
'취소', '반품' 신청페이지에서만 해당 영역을 제공합니다.\
환불 계좌 정보 내 은행은 select-box로 제공하며 선택 값은 <mark style="background-color:yellow;">availableBanks</mark>의 값을 사용하여 노출합니다.

#### ◼︎ 반품 수거 정보

<figure><img src="/files/3YYN0TfSUUpBEBOLwo0a" alt=""><figcaption></figcaption></figure>

배송 이후 (주문상태값 : 배송중, 배송완료) '교환', '반품' 을 신청하는 경우에 주문 상품의 수거에 대한 정보를 입력할 수 있는 영역입니다.\
반품 수거 방법으로는 <mark style="color:orange;">판매자 수거요청</mark> 과 <mark style="color:orange;">구매자 직접 반품</mark> 2가지 항목을 제공하며, 선택한 수거 방법에 따라 입력 항목은 다르게 제공합니다.

* 판매자 수거 요청
  * 교환, 반품 신청 시 배송된 상품을 판매자가 택배사에 연락하여 수거 하는 방식입니다.
  * 반품 수거 방법, 반품자명, 수거지 주소, 휴대폰 번호, 전화번호, 수거시 참고사항을 입력할 수 있습니다.
  * <mark style="background-color:yellow;">returnAddress</mark> 의 값을 입력 화면에 출력합니다.
    * \[배송지 목록에서 선택] 버튼 클릭 시 [배송지 관리 팝업](/aurora-guide/api-1/order-sheet-form#undefined-6)을 노출합니다.&#x20;
* 구매자 직접 반품
  * 교환, 반품 시 배송된 상품을 구매자가 알아서 택배사를 통해 쇼핑몰에 상품을 배송합니다.
  * 반품 수거 방법 , 반품 접수 정보를 입력 할 수 있습니다.
  * 반품 접수 정보 내 택배사 선택은 select-box로 제공되며, 택배사 값은 <mark style="background-color:yellow;">deliveryCompanyTypeWithLabels</mark> 값을 통해 제공합니다.

#### ◼︎ 교환 출고 정보

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

교환되어 재발송 되는 상품의 배송지 정보를 입력할 수 있습니다.\
교환 신청 페이지에서만 입력 항목을 제공하며, 입력 항목에 기본 데이터로 <mark style="background-color:yellow;">exchangeAddress</mark>의 값을 출력합니다.

쇼핑몰 회원 계정에 저장된 배송지 정보를 활용하기 위해서는 [배송지 관리 팝업](/aurora-guide/api-1/order-sheet-form#undefined-6)을 노출하여 기능을 제공합니다.

해외구매대행 상품으로 <mark style="background-color:yellow;">exchangeAddress.customsIdNumber</mark> 값이 존재하는 경우 개인통관고유부호를 입력할 수 있는 input 을 제공합니다.

#### ◼︎ 클레임 (취소/반품/교환) 신청 버튼

<div align="left"><figure><img src="/files/vKzbxUNHFZDs2ZvMyBjR" alt="" width="563"><figcaption></figcaption></figure></div>

신청 버튼 클릭 시, 실제 클레임 신청 페이지에서 입력한 내용을 확인 (유효성 체크) 하고, 각 클레임 타입(주문취소/교환/반품)에 맞는 API를 호출 하여 클레임을 신청합니다.

주문 취소에 대한 API 호출 경로는 아래와 같습니다.\
주문 취소는 부분 취소 요청 가능하며 1개의 클레임 신청 시 복수신청 가능하므로 회원/비회원에 따라 아래의 API 경로를 통해 요청하시면 됩니다.

> [POST /profile/claims/cancle](https://docs.shopby.co.kr/?url.primaryName=claim/#/Member/post-profile-claims-cancel)
>
> ▶ 회원 주문취소 신청하기\
> 회원의 주문을 취소 신청합니다.

> [POST /guest/claims/cancle](https://docs.shopby.co.kr/?url.primaryName=claim/#/Guest/post-guest-claims-cancel)
>
> ▶ 비회원 주문취소 신청하기\
> 비회원의 주문을 취소 신청합니다.

에스크로 주문건의 경우 회원/비회원 여부에 따라 별도 API를 통해 취소 신청이 가능합니다.\
에스크로 주문건은 전체 취소만 지원하므로, 아래의 API 를 통해 취소 신청을 해야 합니다.

> [POST /profile/orders/{orderNo}/claims/cancle](https://docs.shopby.co.kr/?url.primaryName=claim/#/Member/post-profile-orders-order-no-claims-cancel)
>
> ▶ 회원 주문취소 신청하기\
> 회원의  에스크로 주문을 취소 신청합니다.

> [POST /guest/order/{orderNo}/claims/cancle](https://docs.shopby.co.kr/?url.primaryName=claim/#/Guest/post-guest-orders-order-no-claims-cancel)
>
> ▶ 비회원 주문취소 신청하기\
> 비회원의 에스크로 주문을 취소 신청합니다.

반품 요청 또한 1회 클레임 신청 시 복수 주문상품 옵션에 대해 반품 신청할 수 있으므로 회원/비회원 여부에 따라 아래의 API를 통해 신청해주시면 됩니다.

> [POST /profile/claims/return](https://docs.shopby.co.kr/?url.primaryName=claim/#/Member/post-profile-claims-return)
>
> ▶ 회원 반품 신청하기\
> 회원의 주문을 반품 신청합니다.

> [POST /guest/claims/return](https://docs.shopby.co.kr/?url.primaryName=claim/#/Guest/post-guest-claims-return)
>
> ▶ 비회원 반품 신청하기\
> 비회원의 주문을 반품 신청합니다

교환 신청은 회원만 가능하며, 비회원은 교환 신청이 불가합니다.\
교환 신청은 1회 클레임 신청 시 1개의 주문상품옵션번호만 신청 가능합니다.

> [POST /profile/order-options/{orderOptionNo}/claims/exchange](https://docs.shopby.co.kr/?url.primaryName=claim/#/Member/post-profile-order-options-no-claims-exchange)
>
> ▶ 회원 교환 신청하기\
> 회원의 주문에 대한 교환을 신청합니다


# 취소/반품/교환 내역

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

취소/반품/교환 내역 리스트는 주문/배송 조회와 동일한 API를 사용하여 리스트 화면을 제공합니다.\ <mark style="background-color:yellow;">orderRequestType</mark>의 값으로 클레임에 해당하는 주문상태값을 지정하여 호출하여 클레임 리스트만 구매자에게 제공할 수 있습니다.

* 클레임 주문 상태
  * 취소신청\[승인대기] <mark style="background-color:yellow;">CANCEL\_PROCESSING</mark>
  * 취소처리중&#x20;
  * 취소완료 <mark style="background-color:yellow;">CANCEL\_DONE</mark>
  * 교환신청\[승인대기] <mark style="background-color:yellow;">EXCHANGE\_PROCESSING</mark>
  * 교환처리중
  * 교환완료 <mark style="background-color:yellow;">EXCHANGE\_DONE</mark>
  * 반품신청\[승인대기 ] <mark style="background-color:yellow;">RETURN\_PROCESSING</mark>
  * 반품처리중
  * 반품완료 <mark style="background-color:yellow;">RETURN\_DONE</mark>


# 주문 상세

기본 스킨에서는 회원의 경우 '마이페이지 > 주문목록/배송조회' 리스트에서 '주문번호'를 클릭한 경우 **주문 상세 페이지**로 이동하며, 비회원의 경우 로그인 페이지에서 비회원 주문 조회 (주문번호 , 주문 비밀번호 입력) 유효성 검증 후 입력한 주문번호의 주문 상세 페이지로 바로 이동됩니다.

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

주문 상세 페이지에서는 🅐 주문/배송 상세, 🅑 주문자 정보, 🅒 배송지 정보, 🅓 결제 정보, 🅔 환불정보, 🅕 추가 결제 정보, 🅖 반품 수거 정보, 🅗 교환 출고 정보 8개의 정보가 제공됩니다.\
각 영역 별 상세 내용은 아래 내용을 참고해주세요.

> [GET /profile/orders/{orderNo} ](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/get-profile-orders-order-no)
>
> ▶ 회원 주문 상세조회하기\
> 주문번호 기준으로 주문 상세 페이지의 데이터를 조회합니다.

> [GET /guest/orders/{orderNo} ](https://docs.shopby.co.kr/?url.primaryName=order/#/GuestOrder/get-guest-orders-order-no)
>
> ▶ 비회원 주문 상세 조회하기\
> 비회원 주문조회 시 주문 상세 페이지의 데이터를 확인할 수 있습니다.

***

### 🅐 주문 배송/상세

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

주문/배송 상세 영역은 주문목록/배송조회와 동일한 데이터가 제공됩니다.\
기본 스킨에서는 동일한 화면으로 제공되고 있습니다.

다만, 주문번호를 클릭 시에는 주문 상세에서는 별도의 액션은 제공하지 않습니다.\
접수나 진행 상태 영역은 주문목록/배송조회 리스트와 동일하게 *nextAction* 값에 따른 버튼 및 기능을 동일하게 제공하면 됩니다.

자세한 구현 방식은 위의 '[주문목록/배송조회](/aurora-guide/api-1/mypage-shopping/order-list)'리스트 내용을 참고해주세요.

***

### 🅑 주문자 정보

<figure><img src="/files/2s7bUrO10ikiMYQbFW3b" alt=""><figcaption></figcaption></figure>

주문자 정보는 주문서 작성 시 입력한 주문자의 정보를 노출합니다.\
주문자 정보로는 '주문자명', '이메일 주소', '휴대폰 번호', '전화번호', '주문메모' 정보가 있습니다.\
주문자 정보는 orderer (주문자정보), ordermemo(주문메모) 값을 통해 데이터를 확인 할 수 있습니다.

***

### 🅒 배송지 정보

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

배송지 정보는 shippingAddress(배송지 정보), deliveryMemo(배송메모) 를 활용하여 화면을 노출합니다.\
배송지 정보는 어드민 내에서도 주문 생성 이후 수정이 가능하며, 입금 대기\~ 배송준비중 상태에서도 구매자가 직접 배송지 변경이 가능합니다. 다만, 현재 오로라 기본 스킨에서는 제공하고 있지 않는 기능으로 하기 API를 활용해주시기 바랍니다.

> [PUT /profile/orders/{orderNo}/deliveries](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/put-profile-orders-order-no-deliveries)
>
> ► 회원 배송정보 수정하기\
> 회원이 구매한 주문 내 배송정보를 일괄 수정합니다.&#x20;

> [PUT /guest/orders/{orderNo}/deliveries](https://docs.shopby.co.kr/?url.primaryName=order/#/GuestOrder/put-guest-orders-order-no-deliveries)
>
> ► 비회원 배송정보 수정하기\
> 비회원 주문번호에 속한 배송정보를 일괄 수정합니다.

기본 스킨의 경우, 배송지 정보 수정은 주문목록/배송조회 리스트의 진행상태 항목에서도 동일하게 기능 제공합니다.

***

### 🅓 결제 정보

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

주문 시에 결제한 결제 수단이나 상품결제 금액, 할인혜택, 적립금 정보에 대해 출력합니다.\
주문 상세 정보의  firstOrderAmount(최초 주문 금액 정보), payInfo(결제 정보), accumulationAmtWhenBuyConfirm(구매확정 시 적립예정 적립금), payTypeLabel(결제수단) 데이터를 사용합니다.&#x20;

* 할인 및 적립금 사용은 주문서 작성 시 선택한 쿠폰(즉시 할인, 상품쿠폰할인, 주문쿠폰할인)에 따릅니다.&#x20;
  * 적립금의 경우도 주문서 작성 시 입력한 적립금 사용 금액에 따릅니다
  * 네이버페이 주문의 경우 즉시할인만 적용이 가능하므로, 쿠폰 할인은 모두 0원으로 출력됩니다.&#x20;
* 입금 정보는 주문시 선택한 결제 수단이 '무통장 입금'인 경우 어드민 버전에 따라 설정한 계좌 정보가 출력됩니다.
  * &#x20;shop by pro : \[기본정책 >쇼핑몰 관리]
  * shop by premium : \[서비스 관리 > 쇼핑몰 관리]
* 적립 정보는 주문에 포함된 상품이 구매확정된 이후 적립이 될 예정금액에 대해 표시 합니다.
  * 네이버페이 주문건도 적립정보는 동일하게 적용됩니다.

***

### 🅔 환불정보

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

취소/반품/교환이 발생한 주문의 경우, 주문상세 페이지 내 환불정보 영역이 추가됩니다.

환불 정보 영역의 경우 환불에 대한 주문 정보들을 노출 하며, 환불상품/ 환불 상품금액/ 환불배송비/ 환불차감 금액/ 환불 적립금/ 환불금액/ 환불 수단에 대한 정보를 구매자에게 제공합니다.

취소/교환/반품으로 인한 환불 정보는 GET /profile/orders/{orderNo}의 <mark style="background-color:yellow;">refundInfos</mark> 값으로 확인 가능합니다.\
취소/교환/반품으로 인해 추가 결제 금액이 발생하는 경우, 해당 API의 <mark style="background-color:yellow;">additionalPayInfos</mark> 값을 활용하여 제공합니다.

***

### 🅕 추가 결제 정보 (교환 시)

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

{% hint style="info" %}
해당 정보는 클레임이 존재할 경우에만 항목이 노출됩니다.
{% endhint %}

***

### 🅖 반품 수거 정보 (출고 후 교환 / 반품 시)

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

{% hint style="info" %}
해당 정보는 클레임이 존재할 경우에만 항목이 노출됩니다.
{% endhint %}

***

### 🅗 교환 출고 정보 (출고 후 교환 시)

<figure><img src="/files/6ej3b7R3usgXlCVgPCSg" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
해당 정보는 클레임이 존재할 경우에만 항목이 노출됩니다.
{% endhint %}


# 좋아요

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

상품 섹션 또는 상품리스트, 상품 상세에서 '좋아요'한 상품의 목록을 확인 할 수 있는 페이지 입니다.\
로그인한 회원에게만 좋아요 기능을 제공하고 있으므로 좋아요한 상품 리스트는 회원인 경우에만 확인 가능합니다.\
좋아요 리스트에서는 '선택', '상품 정보', '상품 금액', '할인/적립', '합계금액', '상품 문의', '삭제'를 제공합니다.

> [GET /profile/like-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Profile/get-profile-like-products)
>
> ▶ 회원이 좋아하는 상품목록 조회하기\
> 회원이 좋아요한 상품 목록을 조회합니다

좋아요 상품 리스트에서 좋아요한 상품을 삭제할 수 있습니다.

> [POST /profile/like-products](https://docs.shopby.co.kr/?url.primaryName=product/#/Profile/post-profile-like-products)
>
> ▶ 회원이 상품을 좋아한다고 추가/삭제하기\
> 회원이 좋아요한 상품을 목록에 추가하거나 삭제합니다

좋아요 상품으로 추가된 이력이 없는 경우 좋아요 목록에 추가되며, \
좋아요한 상품으로 기 등록되어 있는 경우 삭제 처리 됩니다.


# 마이페이지 > 혜택관리

회원이 쇼핑몰에서 제공하는 쿠폰, 적립금 등 제공 받은 혜택을 확인할 수 있습니다.

* 🅐 [쿠폰](/aurora-guide/api-1/mypage-benefit/coupon-list)
* 🅑 [적립금](/aurora-guide/api-1/mypage-benefit/accumulation-list)

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


# 쿠폰

기본 스킨에서 쿠폰은 '사용가능 쿠폰', '사용불가 쿠폰'으로 나눠서 쿠폰 리스트를 제공합니다.

* 사용 가능 쿠폰
  * 발급 받은 쿠폰 중 사용기간이 남아 있는 쿠폰

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

* 사용 불가 쿠폰
  * 발급 받은 쿠폰 중 사용이 불가한 쿠폰 (기간 만료 및 사용 완료)

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

#### ◼︎ 쿠폰 리스트

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

> [GET /coupons](https://docs.shopby.co.kr/?url.primaryName=promotion/#/Coupon/get-my-coupons)
>
> ▶ 내 쿠폰 가져오기\
> 회원의 사용가능 쿠폰과 사용불가 쿠폰을 구분하여 조회합니다.

API 호출 시 요청 파라미터 <mark style="background-color:yellow;">usable</mark> 의 값에 따라 사용 가능 쿠폰 혹은 사용 불가 쿠폰 정보를 조회 할 수 있습니다.

<mark style="background-color:yellow;">usable=true</mark> 인 경우에는 조회 시점 기준으로 사용 가능한 쿠폰의 정보를 확인 가능하며,\ <mark style="background-color:yellow;">usable=false</mark>인 경우에는 조회 시점 기준으로 사용 불가한 쿠폰의 정보를 확인할 수 있습니다.

기본 스킨의 경우 사용가능 쿠폰 리스트에서는 '만료일'을 출력하고, 사용불가 쿠폰리스트에서는 '사용일' 또는 '만료일'을 출력합니다.\
각 날짜 출력 구분은 아래의 내용으로 처리 하시면 됩니다.

{% code overflow="wrap" %}

```
사용가능 쿠폰리스트의 만료일은 used 가 true일때, useEndYmdt 값을 만료일로 출력 
사용불가 쿠폰리스트의 만료일은 used가 true일때, useEndYmdt 값을 만료일로 출력 
사용불가 쿠폰리스트의 만료일은 used가 false일때, expireYmdt 값을 만료일로 출력
```

{% endcode %}

#### ◼︎ 쿠폰 등록 하기

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

기본 스킨에서는 쿠폰 등록 버튼을 통해 쿠폰코드를 입력하여 쿠폰을 추가할 수 있는 기능을 제공합니다.\
쿠폰 등록 가능한 쿠폰 발급은 에서 발급 유형을 '코드발급'으로 등록한 쿠폰을 추가 할 수 있습니다.

아래 어드민 경로에서 쿠폰 등록이 가능합니다.

```
shop by basic/pro : 프로모션 > 쿠폰 관리
shop by premium : 프로모션 관리 > 할인쿠폰 관리 
```

쿠폰 코드는 쇼핑몰 운영자가 쿠폰 등록 시 입력한 프로모션 코드를 입력하면 쿠폰 추가가 가능합니다.

```
▶ 코드 쿠폰 발급하기
등록된 프로모션 코드를 입력하여 회원에게 쿠폰을 발급합니다.
```

> [POST /coupons/register-code/{promotionCode}](https://docs.shopby.co.kr/?url.primaryName=promotion/#/Coupon/post-register-code-download)
>
> ► 코드 쿠폰 발급하기\
> 등록된 프로모션 코드를 입력하여 회원에게 쿠폰을 발급합니다.


# 적립금

회원이 보유한 적립금 리스트를 제공합니다.&#x20;

기본 스킨에서는 1개의 적립금 리스트에서 '지급된 적립금'과 '차감된 적립금'이 각 행으로 제공되고 있습니다.\
지급/차감이 실행된 일시와 지급/차감 사유가 노출되는 내용 영역, 지급/차감 금액, 적립금의 유효기간(있는 경우)이 출력됩니다.

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

> [GET /profile/accumulations](https://docs.shopby.co.kr/?url.primaryName=manage/#/Accumulation/search-accumulation-histories)
>
> ▶ 적립금 이력 조회하기\
> 회원의 적립금 내역을 모두 조회합니다.

response 스키마 내 <mark style="background-color:yellow;">accumulationStatusGroupType</mark> 의 값에 따라 지급/차감 여부를 구분 할 수 있으며, \
적립 사유는 <mark style="background-color:yellow;">accumulationReserveReason</mark> 코드를 통해 확인 할 수 있습니다.

유효기간은 <mark style="background-color:yellow;">registerYmdt</mark>\~ <mark style="background-color:yellow;">expireYmdt</mark> 의 값에 따라 출력하시면 됩니다.

api 명세서상 `expireYmdt`(만료일)이 9999년 일때 `제한없음`으로 표기됩니다.

회원의 적립금 요약 내용(사용 가능한 총 적립금, 만료된 총 적립금)을 조회 하기 위해서는 아래의 API를 통해 확인 가능합니다.

> [GET /profile/accumulations/summary](https://docs.shopby.co.kr/?url.primaryName=manage/#/Accumulation/search-accumulations-summary)
>
> ▶ 적립금 요약 조회하기\
> 등록된 프로모션 코드를 입력하여 회원에게 쿠폰을 발급합니다.


# 마이페이지 > 회원정보

쇼핑몰 회원의 정보를 확인, 수정, 관리할 수 있는 메뉴로 아래의 3가지 메뉴를 제공하고 있습니다.

* 🅐 [회원정보 수정](/aurora-guide/api-1/mypage-member/modify-member)
* 🅑 [회원탈퇴](/aurora-guide/api-1/mypage-member/withdrawal)
* 🅒 [배송지 관리](/aurora-guide/api-1/mypage-member/shipping-list)

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


# 회원정보 수정

{% hint style="info" %}
회원정보 수정 및 탈퇴의 경우, 회원인증 과정을 거친 후 화면 접근이 가능합니다.&#x20;
{% endhint %}

### 회원 인증

회원 정보 수정 / 회원 탈퇴 시, 회원 본인임을 확인하기 위한 인증 과정입니다.\
회원 인증 방식은 '일반회원', '간편 로그인 회원'에 따라 인증 방식 및 제공 API가 다르므로 아래의 프로세스로 처리됩니다.

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

> [GET /profile](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile)
>
> ▶ 회원정보 조회하기\
> 회원의 정보를 조회합니다.

위의 API를 통해 회원 정보를 가져와서 일반 회원/간편로그인 회원 여부를 판단한 뒤, 회원 구분에 따라 인증을 처리 합니다.

* ㉠ 일반 회원 인증: 회원 비밀번호 입력을 통한 인증
* ㉡ 간편 로그인 회원 인증 : [간편 로그인](/aurora-guide/api-1/open-id) 연동 로직 수행

#### ◼︎ ㉠ 일반 회원 인증

<div align="left"><figure><img src="/files/DIzPedeGx6tXH3WuLRQy" alt="" width="375"><figcaption></figcaption></figure></div>

> [POST /profile/check-password](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile-check-password-failed)
>
> ▶ 비밀번호 확인하기\
> 회원의 비밀번호를 확인합니다.

비밀번호 입력 후 비밀번호 확인하기 API를 호출하여 인증을 진행합니다.\
비밀번호가 맞는 경우 회원 정보 수정 페이지 및 회원 탈퇴 페이지로 진입하며,\
비밀번호가 틀린 경우는 회원 정보 수정 페이지 및 회원 탈퇴 페이지로 접근이 불가합니다.

#### ◼︎ ㉡ 간편 로그인 회원 인증

회원 가입 시 진행한 [간편 로그인](/aurora-guide/api-1/open-id) 인증과정과 동일하게 처리 됩니다.

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

***

### 회원정보 수정

회원 가입 시 회원 정보 입력 화면과 동일하게 제공되며, 회원 정보에 등록된 값을 그대로 노출합니다. \
쇼핑몰 회원 가입 시에 동의 받는 약관에 대해 관리할 수 있도록 하단에 약관과 동의 항목을 제공합니다.

<figure><img src="/files/8feSo994j7Tpb8ZLt7g4" alt=""><figcaption></figcaption></figure>

#### ◼︎ 회원정보 조회

> [GET /profile](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/get-profile)
>
> ▶ 마스킹 해제된 회원정보 조회하기\
> 비밀번호 인증으로 마스킹이 해제된 회원 정보를 조회합니다.

해당하는 회원의 정보를 조회 하여 회원 수정 페이지에 출력합니다.\
이름은 수정이 불가하며, 수정이 가능한 항목에 대해서는 input 내 DB저장값이 노출되도록 제공하고 있습니다.

쇼핑몰 어드민에서 ㉠휴대폰인증/ ㉡이메일 인증/ ㉢SMS인증 총 3가지 인증방식 중 1가지를 선택하실 수 있습니다.

#### **㉠ 휴대폰 인증 (본인인증)**

기본 스킨에서는 '재인증' 버튼을 통해 본인인증 기능을 제공하고 있습니다.\
단, 본인인증 절차를 거치지 않고도 회원정보는 수정 가능하며, **이름 / 휴대폰번호** 수정 희망 시에만 재인증 버튼을 통해 수정이 가능합니다.

해당 쇼핑몰 어드민(관리자)에서 회원인증 '사용중'이고 인증수단이 '휴대폰본인인증'인 경우, 휴대폰 번호는 직접 수정이 불가하며 본인인증을 통해서만 수정이 가능합니다.

휴대폰 '재인증'버튼을 제공하며 클릭 시 KCP 본인인증 팝업을 출력하여 본인인증 로직을 진행합니다.\
휴대폰 본인인증 성공 시 휴대폰 번호화 이름 정보가 갱신됩니다.

> [POST /profile/rename](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile-rename)
>
> ▶ 본인인증 후 개인정보 갱신하기\
> 본인인증 후 개인정보를 갱신합니다

#### **㉡ 이메일 인증**

기본 스킨에서는 '재인증' 버튼을 통해 이메일 인증 기능을 제공하고 있습니다. \
단, 이메일 인증 절차를 거치지 않고도 회원정보는 수정 가능하며, 이메일 주소 수정 희망 시에만 재인증 버튼을 통해 수정이 가능합니다.

쇼핑몰이 회원인증 '사용중'이고 인증수단이 '이메일인증'인 경우, 이메일 주소는 이메일인증 이후에만 수정이 가능합니다. 이메일 주소 '재인증' 버튼을 제공하며 클릭 시 이메일 인증 로직을 진행합니다.

{% hint style="info" %}
기본스킨에서 이메일은 중복확인이 필수로 적용됩니다.
{% endhint %}

> [POST /authentications](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/SendAuthenticationNumber)
>
> ▶ 인증번호 발송하기\
> 인증번호를 발송합니다.

발송된 인증번호 확인은 아래의 API 를 참고해 주세요.

> [GET /authentications](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/get-authentications)
>
> ▶ 인증번호 확인하기\
> 입력 받은 인증번호를 확인합니다.

#### **㉢ SMS 인증**

기본 스킨에서는 '재인증' 버튼을 통해 SMS 인증 기능을 제공하고 있습니다.\
단, SMS 인증 절차를 거치지 않고도 회원정보는 수정 가능하며, **핸드폰 번호** 수정 희망 시에만 재인증 버튼을 통해 수정이 가능합니다.

쇼핑몰이 회원인증 '사용중'이고 인증수단이 'SMS인증'인 경우, 핸대폰 번호는 SMS 인증 이후에만 수정이 가능합니다.\
휴대폰 번호 '재인증'버튼을 제공하며 클릭 시 SMS 인증 로직을 진행합니다.

> [POST /authentications](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/SendAuthenticationNumber)
>
> ▶ 인증번호 발송하기\
> 인증번호를 발송합니다.

발송된 인증번호 확인은 아래의 API 를 참고하여 주세요.

> [GET /authentications](https://docs.shopby.co.kr/?url.primaryName=auth/#/Authentication/get-authentications)
>
> ▶ 인증번호 확인하기\
> 입력  받은 인증번호를 확인합니다.

#### 이메일/SMS 수신 동의, 거부 일시

기본 스킨에서는 이메일 SMS 수신 동의 여부에 대해 안내 하고 있습니다.\
동의 여부에 대해서는 회원정보 조회 하기 API 의 응답 값을 통해 확인 가능합니다.

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

#### ◼︎ 약관동의

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

> [GET /terms](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms)
>
> ▶ 적용 중인 몰 약관 조회하기\
> 해당 쇼핑몰의 약관을 조회합니다.

> [POST /terms/custom](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/post-search-used-terms)
>
> `약관/개인정보처리방침`에서 `추가 동의 항목`을 추가할 수 있습니다.\
> 추가된 동의항목은 [POST /terms/custom 추가 약관 조회하기](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/post-search-used-terms) API를 통해 확인할 수 있습니다.&#x20;

#### ◼︎ 회원정보 수정 버튼

<div align="left"><figure><img src="/files/AYgSPrMV8G8SZL9NfwLj" alt="" width="375"><figcaption></figcaption></figure></div>

> [PUT /profile](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/put-profile-v-1-1)
>
> ▶ 회원정보 수정하기\
> 회원 정보를 수정합니다.

회원 정보 수정 페이지에서 항목을 입력 하고 저장 처리 시 회원 정보 수정하기 API 를 호출하여 수정한 내용을 회원 DB에 반영합니다.\
수정 처리 시 응답 되는 값에 따라 ALERT 혹은 회원 정보 수정 완료를 진행합니다.


# 회원탈퇴

{% hint style="info" %}
회원정보 수정 및 탈퇴의 경우, 회원인증 과정을 거친 후 화면 접근이 가능합니다.&#x20;

회원인증 과정은 [회원정보 수정 화면](/aurora-guide/api-1/mypage-member/modify-member)을 참고하시길 바랍니다.&#x20;
{% endhint %}

기본 스킨에서는 탈퇴 페이지 내 탈퇴 사유 입력과 탈퇴 동의 체크박스를 제공합니다.

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

회원 탈퇴 페이지 내 회원 탈퇴에 대한 약관을 명시 하고자 하는 경우 아래의 API를 통해 약관 정보를 조회할 수 있습니다.

> [GET /terms](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms)
>
> ▶ 적용 중인 몰 약관 조회하기\
> 해당 쇼핑몰의 약관을 조회합니다.

탈퇴 안내에 대한 약관을 확인하기 위해서는 <mark style="background-color:yellow;">termsTypes=WITHDRAWAL\_GUIDE</mark> 로 요청하시면 탈퇴 안내 약관을 응답 받을 수 있습니다.\
탈퇴 사유와 탈퇴 안내에 대해 동의 시 탈퇴가 가능하며, 탈퇴 처리는 회원 탈퇴 하기 API를 호출하시면 됩니다.

> [DELETE /profile](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/delete-profile)
>
> ▶ 회원 탈퇴하기\
> 회원 탈퇴 처리합니다.


# 배송지 관리

회원 기준으로 배송지를 관리할 수 있는 페이지 입니다.

배송지를 등록하거나 수정, 삭제 할 수 있으며, 배송지는 개수 제한 없이 등록 가능합니다.\
배송지 등록 혹은 수정 시에 '기본 배송지'를 설정할 수 있으며 기본 배송지는 1개만 설정 가능합니다.\
기본 배송지로 등록된 배송지는 주문 페이지 내 배송지데이터로 출력됩니다.

#### ◼︎ 배송지 목록

등록된 배송지 목록 조회는 아래의 API를 통해 확인 가능합니다.

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

> [GET /profile/shipping-addresses](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/get-profile-booked-shipping-addresses)
>
> ▶ 배송지 목록 조회하기\
> 배송지 관리에 등록된 배송지 목록을 조회합니다.

기본 배송지는 삭제가 불가합니다.\
기본배송지로 설정된 주소 삭제를 원하는 경우 기본 배송지 설정을 해제하고 삭제해야 합니다.\
배송지 목록 가져오기를 통해 응답된 값 중 저장된 배송지값을 배송지 관리 목록에 출력할 수 있습니다.

#### ◼︎ 배송지 등록

> [POST /profile/shipping-addresses](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/post-profile-shipping-addresses)
>
> ▶ 배송지 등록하기\
> 배송지 관리에 배송지를 등록합니다.

배송지 목록에 배송지를 추가 하는 기능을 제공할 수 있습니다.\
추가 시 <mark style="background-color:yellow;">defaultYn=Y</mark> 로 호출 하는 경우 기본 배송지로 설정됩니다.

기존에 기본 배송지가 설정되어 있는 경우 다른 배송지를 기본배송지로 설정하는 경우 기본 배송지가 변경됩니다.\
개인고유통관부호 입력이 필요한 주소의 경우 <mark style="background-color:yellow;">request body</mark> 값으로 <mark style="background-color:yellow;">customsIdNumber</mark> 값을 추가하여 배송지 등록이 가능합니다.

<figure><img src="/files/7vHcYZn1OFG1gclKn1uH" alt=""><figcaption></figcaption></figure>

\[배송지 등록] 버튼을 통해 출력한 '배송지 등록' 팝업 내 \[우편번호 찾기] 버튼 클릭 시,\
우편번호 찾기를 통한 주소 검색 기능을 제공합니다.

> [GET /addresses/search](https://docs.shopby.co.kr/?url.primaryName=manage/#/Address/search-addresses)
>
> ▶ 주소 조회하기\
> 키워드 검색을 통한 주소정보를 검색합니다.

#### ◼︎ 배송지 수정

등록한 배송지를 수정하고자 하는 경우 아래의 API를 통해 수정 가능합니다.\
배송지 수정 하기를 위해서는 선택한 배송지 정보를 먼저 조회 후 나의 배송지 관리 팝업에서 등록된 정보로 배송지를 먼처 출력하여 제공합니다.

> [GET /profile/shipping-addresses/{addressNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/get-profile-shipping-addresses-address-no)
>
> ▶ 배송지 가져오기\
> 선택한 배송지의 세부 정보를 조회합니다.

등록된 정보를 기준으로 구매자가 수정을 완료 한 경우 PUT/ profile/shipping-addresses/{addressNo} 를 통해 배송지 정보를 수정합니다.

> [PUT /profile/shipping-addresses/{addressNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/put-profile-shipping-addresses-address-no)
>
> ▶ 배송지 수정하기\
> 선택한 배송지 정보를 수정합니다.

배송지 수정하기 API는 나의 배송지 관리 팝업 내 저장 버튼 클릭 시 호출하여 입력 값을 저장합니다.

#### ◼︎ 배송지 삭제

배송지 관리 목록 내 \[삭제] 버튼 클릭 시 선택한 배송지를 삭제 처리 합니다.

> [DELETE /profile/shipping-addresses/{addressNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/delete-profile-shipping-addresses-address-no)
>
> ▶ 배송지 삭제하기\
> 선택한 배송지 정보를 삭제합니다.

기본 배송지로 설정된 배송지는 삭제할 수 없습니다.\
기본 배송지 삭제 시도 시 응답 되는 에러 메시지를 참고 하여 안내해주시면 됩니다.


# 마이페이지 > 나의 게시글

나의 게시글 메뉴에서는 쇼핑몰 내 회원이 작성한 게시글 목록을 제공합니다.

* 🅐 [1:1문의](/aurora-guide/api-1/mypage-post/inquiry) : 쇼핑몰에 대한 문의를 등록한 것이며, 1:1문의는 등록자와 운영자만 확인할 수 있습니다.
* 🅑 [상품문의](/aurora-guide/api-1/mypage-post/product-inquiry)  : 상품에 대한 문의를 등록한 것이며, 공개여부에 따라 상품 상세에도 노출되어 다른 쇼핑몰 이용자도 확인 가능합니다.
* 🅒 [상품후기](/aurora-guide/api-1/mypage-post/product-review) : 구매한 상품의 후기를 작성할 수 있습니다. 작성한 후기는 상품 상세의 후기 탭에 노출됩니다.

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


# 1:1 문의

1:1문의는 어드민 아래 경로에서 설정이 가능합니다.&#x20;

```
shop by basic/pro : 게시판 > 게시판 관리 > 1:1문의 > 1:1문의 설정(탭)
shop by premium : 운영관리 > 1:1문의 관리 > 1:1문의 설정(탭)
```

1:1 문의는 회원에게만 제공되며, 비회원에게는 제공하지 않습니다. \
게시글은 비밀글로 모두 저장되어 등록자 자신과 운영자(어드민에서 게시글 확인)만 게시글 확인이 가능합니다.

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

#### ◼︎ 1:1 문의 목록 조회

> [GET /inquiries](https://docs.shopby.co.kr/?url.primaryName=manage/#/Inquiry/search-inquiries)
>
> ▶ 일대일 문의 내역 조회하기\
> 일대일 문의글 목록을 전체 검색합니다.

조회 시 해당 회원의 1:1 문의만 조회해야 하므로 요청 시 accessToken 값에 해당 회원의 accessToken 값을 추가하여 조회 하셔야 합니다.\
기본 스킨에서는 게시글 번호, 문의유형, 문의 제목, 문의일, 답변 상태 값을 노출하여 제공합니다.

> [GET /inquiries/{inquiriesNo}](https://docs.shopby.co.kr/?url.primaryName=manage/#/Inquiry/get-inquiry)
>
> ▶ 일대일 문의 상세 조회하기\
> 문의 번호 기준으로 일대일 문의 상세 내용을 조회합니다.

답변이 완료 되지 않은 문의 글에 대해서만 수정 및 삭제가 가능합니다.\
수정/삭제 API는 하단 내용에서 확인하실 수 있습니다.

<mark style="color:purple;">**\[답변대기 1:1문의]**</mark>

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

<mark style="color:purple;">**\[답변완료 1:1문의]**</mark>

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

#### ◼︎ 1:1 문의 등록

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

1:1 문의 목록에서 제공하는 \[1:1문의 등록] 버튼을 통해 게시글 등록이 가능합니다.\
\[1:1 문의 등록] 버튼 클릭 시 1:1 문의 내용을 입력할 수 있는 페이지를 제작하여 회원에게 제공합니다.\
기본 스킨에서는 아래의 항목을 제공합니다.

* 문의유형 : 문의유형은 어드민에서 등록한 문의 유형을 select-box로 제공합니다.
* 제목 : 제목은 최대 50자 까지 입력 가능합니다.
* 내용 : 내용은 최대 1000자 까지 입력 가능합니다.
* 첨부파일 : 첨부파일은 최대 10개 등록 가능하며, 1개 파일 당 용량은 5MB로 제한됩니다.
* 답변등록 알림 (SMS/이메일 수신) : 어드민의 자동 SMS설정, 자동 메일 설정 여부에 따라 답글 등록 시 1:1문의 등록자에게 답변 완료에 대해 안내 됩니다.&#x20;

> [POST /inquiries](https://docs.shopby.co.kr/?url.primaryName=manage/#/Inquiry/add-inquiry)
>
> ▶ 1:1 문의 등록하기\
> 1:1 문의를 등록합니다.

1:1 문의 등록 페이지 내 내용을 입력한 후에는 1:1 문의 등록 페이지에서 문의 등록을 위해 저장 버튼을 클릭합니다.\
저장 버튼 클릭 시 1:1 문의 등록 API를 호출하여 게시글을 등록합니다.<br>

#### ◼︎ 1:1문의 수정

> [PUT /inquiries/{inquiryNo}](https://docs.shopby.co.kr/?url.primaryName=manage/#/Inquiry/modify-inquiry)
>
> ▶ 1:1 문의 변경하기\
> 특정 1:1문의를 수정합니다.

1:1 문의 수정은 1:1문의 상세 페이지에서 기능 제공하며, 1:1 문의 수정하기를 위해서는 아래의 프로세스로 진행됩니다.\
inquiryStatus (답변상태) 값이 답변완료인 경우 수정 버튼을 미노출하여 답변완료인 경우 수정 기능을 제공하지 않습니다.

* 1:1 문의 상세 조회하기 API를 통해 수정하려는 1:1문의 내용을 조회 한 후 1:1문의 등록 팝업 내 등록한 문의 내용을 출력
* 출력 된 내용을 기반으로 쇼핑몰 회원이 1:1문의를 수정하여 등록
* 1:1문의 수정하기 API를 통해 수정 요청

#### ◼︎ 1:1문의 삭제 <a href="#undefined" id="undefined"></a>

> [DELETE /inquiries/{inquiryNo}](https://docs.shopby.co.kr/?url.primaryName=manage/#/Inquiry/remove-inquiry)
>
> ▶ 1:1 문의 삭제하기\
> 특정 1:1문의를 삭제합니다.

1:1 문의 삭제는 1:1문의 상세 페이지에서 기능 제공하며, 답변이 완료 되지 않은 문의건에 대해서만 삭제 가능합니다.\
1:1 문의 상세 조회 시 <mark style="background-color:yellow;">inquiryStatus (답변상태)</mark> 값이 답변완료인 경우 삭제 버튼을 미노출 하여 답변완료인 경우 삭제 기능을 제공하지 않습니다.\
답변이 완료되지 않은 1:1 문의의 경우 삭제 버튼 클릭 시 1:1문의 삭제하기 API를 호출하여 특정 1:1 문의를 삭제 합니다.


# 상품문의

상품문의는 어드민 아래 경로에서 설정이 가능합니다.&#x20;

```
shop by basic/pro : 게시판 > 게시판 관리 > 상품문의 > 상품문의 설정(탭)
shop by premium : 상품관리 > 상품문의 관리 > 상품문의 설정(탭)
```

상품문의는 회원만 작성 가능하며, 비회원은 작성이 불가 합니다.\
비밀글 설정은 어드민 설정에 따르며, 비밀글 쓰기 기능이 사용함인 경우 상품문의 등록 페이지에서 비밀글 여부를 설정할 수 있는 기능을 제공해야 합니다.

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

#### ◼︎ 상품 문의 목록 조회 <a href="#undefined" id="undefined"></a>

상품 문의 메뉴 접근 시 상품 문의 목록을 조회합니다.

> [GET /profile/product-inquiries](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/get-profile-product-inquiries)
>
> ▶ 내 상품문의 목록 조회하기\
> 회원의 상품 문의글 목록을 조회합니다.

특정회원의 상품 문의만 조회해야 하므로 요청시 accessToken 값에 해당 회원의 엑세스 토큰값을 추가하여 조회 하셔야 합니다.\
기본 스킨에서는 게시글 번호, 문의유형, 문의 정보(제목, 비밀글 등), 문의일, 답변 상태 값을 노출하여 제공합니다.

> [GET /products/{productNo}/inquiries/{inquiryNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/get-product-inquiry)
>
> ▶ 상품문의 조회하기\
> 상품번호로 상품 문의를 조회합니다.

상품 문의 조회하기 API를 통해 상품 문의 상세 페이지를 구성합니다.\
1:1 문의와 마찬가지로 답변이 완료 되지 않은 문의 글에 대해서만 수정 및 삭제가 가능합니다.\
수정/삭제 API는 하단 내용에서 확인하실 수 있습니다.

#### ◼︎ 상품문의 등록

<figure><img src="/files/9OEMuosgGd5tSn7bdyD1" alt=""><figcaption></figcaption></figure>

기본 스킨의 경우 상품문의 리스트에서 상품문의하기 버튼을 제공하고 있어 해당 버튼을 통해 게시글 등록이 가능합니다.\
상품 문의하기 버튼 클릭 시 상품 문의를 등록할 수 있는 페이지를 제작하여 회원에게 제공합니다.\
기본 스킨에서는 아래의 항목을 제공합니다.

* 문의유형: 문의유형은 어드민에서 등록한 문의 유형을 select-box로 제공합니다.
* 제목: 제목은 최대 50자 까지 입력 가능합니다.
* 내용: 내용은 최대 1000자 까지 입력 가능합니다.
* 비밀글 설정
  * 어드민에서 비밀글 쓰기를 사용함으로 설정하는 경우 등록시 비밀글 여부를 선택할 수 있도록 기능이 제공됩니다.
  * 어드민에서 비밀글 쓰기를 사용안함으로 설정하는 경우 등록시 비밀글 여부선택 항목은 제공되지 않아야 합니다.

상품 항목에서는 상품을 선택할 수 있는 페이지를 제공합니다.

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

> [GET /products/search](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-search)
>
> ► 상품 검색하기\
> 상품을 조회합니다.&#x20;

기본 스킨에서는 상품 선택 팝업 내 상품 검색 시 '카테고리', '검색어' 를 통해 조회할 수 있도록 제공하고 있습니다.

> [POST /products/{productNo}/inquiries](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/post-product-inquiries)
>
> ▶ 상품문의 등록하기 \
> 상품문의를 등록합니다.

상품 선택 및 상품문의 내용을 입력한 후에는 상품 문의 등록 페이지에서 문의 등록을 위해 저장 버튼을 클릭합니다.\
저장 버튼 클릭 시 상품 문의 등록 API를 호출하여 상품문의를 등록합니다.

#### ◼︎ 상품문의 수정 <a href="#undefined" id="undefined"></a>

상품문의 수정을 위해서는 아래의 단계로 진행됩니다.

1. 특정 상품문의 조회
2. 조회한 상품문의를 상품 문의 수정페이지 내 출력
3. 상품문의 수정
4. 상품 문의 수정 API 호출

먼저 앞서 언급한 상품문의 조회하기 API 를 통해 특정 상품문의 내용을 조회합니다.\
이후, 회원이 상품문의 등록페이지를 통해 수정한 내용을 아래의 API 를 호출하여 등록합니다.

> [PUT /products/inquiries/{inquiriesNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/put-product-inquiry)
>
> ▶ 상품문의 수정하기\
> 상품문의를 수정합니다.

상품 문의는 작성자 본인만 수정 가능하여 회원 엑세스 토큰 accessToken 은 요청 시 필수로 입력해야 합니다.\
수정이 가능한 범위는 문의유형, 제목, 내용, 비밀글 여부 에 대해서만 수정이 가능합니다.

#### ◼︎ 상품문의 삭제

> [DELETE /products/inquiries/{inquiryNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/ProductInquiry/delete-product-inquiry)
>
> ▶ 상품문의 삭제하기\
> 특정 상품문의를 삭제합니다.

상품 문의 삭제는 상품문의 상세 페이지에서 기능 제공하며, 답변이 완료 되지 않은 문의건에 대해서만 삭제 가능합니다.상품문의 상세 조회 시 <mark style="background-color:yellow;">inquiryStatus (답변상태)</mark> 값이 답변완료인 경우 삭제 버튼을 미노출 하여 답변 완료인 경우 삭제 기능을 제공하지 않습니다.

답변이 완료되지 않은 상품 문의의 경우 삭제 버튼 클릭 시 상품문의 삭제하기 API를 호출하여 특정 상품 문의를 삭제 합니다.


# 상품후기

상품후기는 어드민 아래 경로에서 설정이 가능합니다.&#x20;

```
shop by basic/pro : 게시판 > 게시판 관리 > 상품후기> 상품후기 설정(탭)
shop by premium : 상품관리 > 상품평 관리 > 상품문의 설정(탭)
```

상품후기는 회원만 작성 가능하며, 비회원은 작성이 불가 합니다.\
비밀 글쓰기는 제공되지 않으며, 상품 후기는 답글 기능도 제공되지 않습니다.\
첨부파일 기능은 어드민 설정에 따릅니다.

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

#### ◼︎ 상품후기 관리 <a href="#undefined" id="undefined"></a>

상품 후기 메뉴 접근 시 상품 후기 목록을 조회합니다.

> [GET /category/product-reviews](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-category-product-reviews)
>
> ▶ 카테고리 상품평 목록 조회하기\
> 카테고리 별 상품평 목록을 조회합니다.

기본 스킨의 경우 게시판은 카드형으로 제공하고 있으며, 아래의 항목으로 리스트를 구성합니다.

* 상품 정보 (상품 썸네일 / 상품명 / 옵션명)
* 별점
* 작성일
* 후기정보 (후기 내용 / 첨부파일 여부)
* 작성 가능 후기 버튼

후기 작성하기 버튼의 경우 클릭 시 후기 작성 페이지로 이동하며, 작성 가능한 후기 개수에 대해 카운트 하여 출력합니다.

> [GET /profile/order-options/product-reviewable](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-product-reviewable)
>
> ▶ 내 상품평 작성 가능 목록 조회하기\
> 회원이 작성 가능한 후기 목록을 조회합니다.

작성 가능한 상품 후기 목록은 구매한 상품의 옵션 기준으로 출력됩니다.\
버튼 클릭 시 상품 후기 등록 팝업이 출력됩니다.&#x20;

상품 후기 목록에서 상품 썸네일 하단 영역을 클릭하면 상품 후기 상세 페이지로 이동합니다.\
상품 후기 상세 페이지는 아래 API 를 통해 조회 가능합니다.

> [GET /products/{productNo}/product-reviews/{reviewNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-products-product-reviews)
>
> ▶ 상품평 가져오기\
> 상품평을 조회합니다.

상품 후기 조회 시 해당 회원이 등록한 상품 후기를 조회해야 하기 때문에 회원 엑세스 토큰 accessToken 값을 포함하여 요청합니다.\
회원 본인이 작성한 상품 후기에 대해서 '수정' 및 '삭제' 기능을 제공합니다.\
수정/ 삭제에 관한 내용은 아래에서 참고 부탁드립니다.

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

#### ◼︎ 상품후기 등록 <a href="#undefined" id="undefined"></a>

<figure><img src="/files/5WqPCwoDr36tStkHEpYn" alt=""><figcaption></figcaption></figure>

기본 스킨에서는 상품후기 등록 팝업에서 아래의 항목을 제공합니다.

* 주문 상품 선택 : 게시글 등록 시 상품후기 등록 가능한 주문상품(옵션 기준)을 선택해야 합니다.
* 평점 : 1점 \~5점까지 설정 가능합니다.
* 내용 : 최대 1000자 입력 가능합니다.
* 첨부파일 : 첨부파일은 이미지파일 최대 10개까지 등록 가능하며, 1개당 용량은 5MB로 제한됩니다.

\[상품 선택] 버튼 클릭 시 주문상품을 선택할 수 있는 팝업이 출력됩니다.

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

> [GET /profile/order-options/product-reviewable](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-profile-product-reviews)
>
> ► 작성 가능한 상품후기 목록 조회\
> 회원이 작성 가능한 후기 목록을 조회합니다.

작성가능한 상품후기 목록 조회하기 API로 응답 받은 구매정보를 통해 상품 후기 등록가능한 구매상품을 출력합니다.

구매상품 선택 페이지에서 선택한 구매상품을 상품 후기 등록 페이지 내 주문상품 영역에 출력합니다.&#x20;

> [POST /products/{productNo}/product-reviews](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/post-product-reviews)
>
> ▶ 상품평 등록하기\
> 상품평을 등록합니다.

#### ◼︎ 상품후기 수정 <a href="#undefined" id="undefined"></a>

상품후기 수정을 위해서는 아래의 단계로 진행됩니다.

1. 특정 상품 후기 조회
2. 조회한 상품 후기를 상품 후기 수정페이지 내 출력
3. 상품 후기 수정
4. 상품 후기 수정 API 호출

먼저 앞서 상품 후기 상세 페이지 구성 시 언급한 상품 후기 조회하기 API (하이퍼링크를 통한 앵커 처리) 를 통해 특정 상품 후기 내용을 조회합니다.\
이후, 회원이 상품 후기 등록페이지를 통해 수정한 내용을 아래의 API 를 호출하여 등록합니다.

> [PUT /products/{productNo}/product-reviews/{reviewNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/put-product-review)
>
> ▶ 상품후기 수정하기\
> 상품 후기를 수정합니다.

상품 후기는 작성자 본인만 수정 가능하여 회원 엑세스 토큰 accessToken 은 요청 시 필수로 입력해야 합니다.\
수정이 가능한 범위는 주문상품, 평점, 내용, 첨부파일 에 대해 수정이 가능합니다.

#### ◼︎ 상품후기 삭제

> [DELETE /products//{productNo}/product-reviews/{reviewNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/delete-product-review)
>
> ▶ 상품후기 삭제하기
>
> 특정 상품후기를 삭제합니다.

상품 후기 삭제는 상품후기 상세 페이지에서 기능 제공합니다.\
상품 후기는 작성자만 삭제 가능하여 요청 시 회원 엑세스 토큰accessToken을 필수값으로 전송해야 합니다.


# 상품후기 게시판

상품후기 게시판에 대해 소개합니다.

상품 상세 페이지에서 상품후기(탭)영역의 \[전체 상품후기 보기] 버튼 클릭 시 상품후기 게시판으로 이동됩니다.&#x20;

상품후기는 어드민 아래 경로에서 설정이 가능합니다.&#x20;

```
shop by basic/pro : 게시판 > 게시판 관리 > 상품후기> 상품후기 설정(탭)
shop by premium : 상품관리 > 상품평 관리 > 상품문의 설정(탭)
```

#### ◼︎ 상품후기 게시판

상품후기 게시판에서는 3개의 탭으로 구분하여 상품후기 목록 조회가 가능합니다.

* 전체 상품후기 : 쇼핑몰에 등록된 모든 상품후기를 조회합니다.&#x20;
* 포토 상품후기 : 쇼핑몰에 등록된 상품후기 중 포토가 포함된 상품후기만 조회합니다.
* 상품기준 상품후기 : 쇼핑몰에 등록된 상품후기를 상품기준으로 조회합니다.&#x20;

<figure><img src="/files/bdq7kCFTpdPKHK193urF" alt=""><figcaption><p>PC</p></figcaption></figure>

<figure><img src="/files/dqnBB9knkKZAhMcB8xaE" alt=""><figcaption><p>MO</p></figcaption></figure>

> [GET /reviews/boards](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-products-reviews-by-board)
>
> ► 상품평 게시판 목록 조회하기\
> 상품평 게시판 목록을 조회합니다 (전체 상품후기/포토 상품후기)

> [GET /reviews/boards/reviewde-products](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-reviews-by-products)
>
> ► 상품 기준 상품평 게시판 목록 조회하기\
> 상품 기준 상품평 게시판 목록을 조회합니다. (상품기준 상품후기)

#### ◼︎ 상품후기 등록/수정

{% hint style="info" %}
상품후기 등록/수정은 마이페이지 > 나의 게시글 > [상품후기 화면](/aurora-guide/api-1/mypage-post/product-review)에서 참고하시길 바랍니다.&#x20;
{% endhint %}

#### ◼︎ 상품후기 상세 팝업

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

상품후기 내용 클릭 시 상품후기 상세 팝업에 출력됩니다.\
상품 후기 상세 페이지는 아래 API 를 통해 조회 가능합니다.

> [GET /products/{productNo}/product-reviews/{reviewNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-products-product-reviews)
>
> ▶ 상품평 가져오기\
> 상품평을 조회합니다.

상품평에 작성된 댓글을 조회할 수 있습니다.&#x20;

> [GET /products/{productNo}/product-reviews/{reviewNo}/comments](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/get-products-product-reviews-comments)
>
> ► 상품평의 댓글 목록 조회하기\
> 상품평에 작성된 댓글을 조회합니다.&#x20;

상품평을 추천/추천 취소 할 수 있습니다.

> [GET /products/{productNo}/product-reviews/{reviewNo}/recommend](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/post-product-reviews-recommend)
>
> ► 상품평 추천하기\
> 상품평을 추천할 수 있습니다.

> [DELETE /products/{productNo}/product-reviews/{reviewNo}/recommend](https://docs.shopby.co.kr/?url.primaryName=display/#/Review/delete-product-reviews-recommend)
>
> ► 상품평 추천 취소하기\
> 추천한 상품평의 추천을 취소할 수 있습니다.


# 일반 게시판

일반 게시판에 대해 소개합니다.

기본 스킨에서는 5개의 일반 게시판을 제공합니다. (공지사항, FAQ, 자유 게시판, 이벤트/혜택, 메모 게시판)

일반 게시판은 어드민 아래 경로에서 설정이 가능합니다.&#x20;

```
shop by basic/pro : 게시판 > 게시판 관리 > 게시판 리스트
shop by premium : 운영관리 > 게시판 관리
```

#### ◼︎ 일반 게시판 목록

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

일반 게시판 접근 시 해당 게시판의 게시글 리스트를 조회합니다.

> [GET /boards/{boardNo}/articles](https://docs.shopby.co.kr/?url.primaryName=manage/#/Board/search-posts)
>
> ► 게시글 리스트 조회하기\
> 특정 게시판 (게시판 번호 기준)의 게시글 리스트를 조회합니다.&#x20;

기본 스킨의 경우 일반 게시판은 리스트형으로 제공되며, 아래 항목으로 리스트를 구성합니다.

* 번호, 제목(첨부파일 여부), 조회수, 작성자, 작성일

#### ◼︎ 게시글 등록

\[글쓰기] 버튼은 게시판 설정에 따라 노출/미노출됩니다. \
회원 / 비회원에 따라 다른 화면이 노출됩니다.

#### 회원 (member)

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

> [POST /boards/{boardNo}/articles](https://docs.shopby.co.kr/?url.primaryName=manage/#/Board/add-post)
>
> ► 게시글 작성하기\
> 게시글을 작성할 수 있습니다.&#x20;

회원이 게시글 등록 시 작성자명은 회원 정보를 자동으로 출력하며, 수정이 불가합니다. \
비밀글 설정 여부, 첨부파일 가능여부는 게시판 설정에서 설정이 가능합니다.

#### 비회원 (guest)

비회원 게시글 등록인 경우 입력란이 모두 비어있으며 작성자가 직접 입력할 수 있습니다.\
비회원 게시글 등록 시 '작성 비밀번호' 입력할 수 있는 영역이 추가되어야 합니다.\
비회원 게시글 등록 시에는 '비회원 글작성 이용동의' 약관 체크가 추가되어야 합니다.&#x20;

<figure><img src="/files/5OlCHD114hJpLtDqjPt5" alt=""><figcaption></figcaption></figure>

#### ◼︎ 게시글 상세

게시글 제목 클릭 시 게시글 상세 페이지로 이동합니다.&#x20;

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

> [GET /boards/{boardNo}/articles/{articleNo}](https://docs.shopby.co.kr/?url.primaryName=manage/#/Board/get-post)
>
> ► 게시글 상세 조회하기\
> 특정 게시글 (게시글 번호 기준)을 상세 조회할 수 있습니다.&#x20;

> [GET /boards/{boardNo}/articles/{articleNo}/replies](https://docs.shopby.co.kr/?url.primaryName=manage/#/Board/reply-posts)
>
> ► 게시글 답글 리스트 조회하기 \
> 게시글의 답글 리스트를 조회할 수 있습니다.&#x20;

게시글 답글은 어드민 설정에서 사용여부에 따라 노출됩니다.&#x20;

{% hint style="info" %}
비회원 게시글의 경우, 해당 게시글의 작성 비밀번호를 입력해야 합니다.&#x20;
{% endhint %}

#### ◼︎ 게시글 수정/삭제

게시글 수정/삭제는 작성자 본인만 가능하여 회원 엑세스 토큰 accessToken 은 요청 시 필수로 입력해야 합니다.

> [PUT /boards/{boardNo}/articles/{articleNo}](https://docs.shopby.co.kr/?url.primaryName=manage/#/Board/modify-post)
>
> ► 게시글 수정하기\
> 게시글을 수정할 수 있습니다.&#x20;

> [DELETE /boards/{boardNo}/articles/{articleNo}](https://docs.shopby.co.kr/?url.primaryName=manage/#/Board/remove-post)
>
> ► 게시글 삭제하기\
> 게시글을 삭제할 수 있습니다.

{% hint style="info" %}
비회원 게시글의 경우, 해당 게시글의 작성 비밀번호를 입력해야 합니다.&#x20;
{% endhint %}


# 기획전

쇼핑몰 상단에서 \[기획전] 버튼 클릭 시 기획전 목록 페이지로 이동합니다.

기획전은 아래 어드민 경로에서 등록/관리가 가능합니다. &#x20;

```
shop by basic/pro : 프로모션 > 기획전 관리
shop by premium : 전시관리 > 기획전 관리
```

#### ◼︎ 기획전 목록

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

등록된 기획전 목록을 조회할 수 있습니다. \
기획전은 최신순 / 마감순 정렬 버튼을 통해 순서대로 나열되며, \
기획전은 진행 중인 기간에 따라, 진행중 / 종료 라벨으로 구분됩니다.&#x20;

> [GET /display/events](https://docs.shopby.co.kr/?url.primaryName=display/#/Event/get-event-by-keyword-type)
>
> ► 기획전 조회하기\
> 기획전을 조회할 수 있습니다.&#x20;

#### ◼︎ 기획전 상세

기획전 목록에서 기획전을 클릭하면 기획전 상세 페이지로 이동합니다.\
종료된 기획전은 상세 페이지로 이동이 불가합니다.&#x20;

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

**기획전 상세 정보 조회**

> [GET /display/events/{eventKey}](https://docs.shopby.co.kr/?url.primaryName=display/#/Event/get-event-v2)
>
> [GET /display/events/ids/{eventId}](https://docs.shopby.co.kr/?url.primaryName=display/#/Event/get-event-by-id-v2)
>
> ► 기획전 상세 조회하기 v2.0\
> 기획전 상세 정보를 조회할 수 있습니다.

* eventKey: 기획전 번호, 기획전 ID로 모두 조회 가능
* eventId: 기획전 ID로만 조회 가능

기획전 상세에서는 아래 항목을 제공합니다.

* `top`: 기획전 상세 이미지를 화면에 노출합니다.
  * 상세 이미지 미 등록 시 출력되지 않습니다.
* `coupon`: 쿠폰 정보를 화면에 노출합니다.
  * \[쿠폰받기] 버튼 클릭 시 해당 기획전에 설정된 쿠폰을 다운받을 수 있습니다.
* `section`: 기획전에 설정된 상품 진열 정보가 조회됩니다.
  * 상품 진열 내 상품 리스트는 제공되지 않습니다.

**기획전 상품진열 상품 조회**

상품진열의 상품 리스트는 [기획전 상품진열 상품 조회하기 API](https://docs.shopby.co.kr/?url.primaryName=display/#/Event/get-event-section-products)를 통해 조회합니다.<br>

> [GET /display/events/{eventNo}/sections/{sectionNo}](https://docs.shopby.co.kr/?url.primaryName=display/#/Event/get-event-section-products)
>
> ► 기획전 상품진열 상품 조회하기\
> 기획전 상품진열에 있는 상품 리스트를 조회할 수 있습니다.

기획전 상세에서 응답된 기획전 번호(`eventNo`)와 상품진열 번호(`section[].sectionNo`)로

원하는 상품 진열의 상품 리스트를 조회할 수 있습니다.

`products` 값을 활용하여 화면에 상품을 노출할 수 있습니다.

**미리보기**

진행 중이 아닌 기획전은 기획전 정보가 조회되지 않습니다.

다만, 진행 중이 아닌 기획전 상세 내용을 미리보기 하고 싶다면 다음 API 호출 시 `preview` 값을 전달하여 미리보기가 가능합니다.

* [기획전 상세 조회하기 v2.0](https://docs.shopby.co.kr/?url.primaryName=display/#/Event/get-event-v2)
* [기획전 상품진열 상품 조회하기](https://docs.shopby.co.kr/?url.primaryName=display/#/Event/get-event-section-products)

자세한 내용은 API 문서에서 참고하실 수 있습니다.


# KCP 휴대폰 본인인증 연동 (iOS/AOS)

KCP 휴대폰 본인인증 모듈을 모바일앱 (iOS/AOS)에 연동 시 참고하실 수 있습니다.

휴대폰 본인인증 모듈은 iOS/AOS 어플리케이션 내 webview를 이용하여 연동합니다.

* [iOS 매뉴얼](#ios)
* [AOS 매뉴얼](#aos)

{% hint style="info" %}
휴대폰 본인인증 모듈에 대한 가이드는 [휴대폰 본인인증](/aurora-guide/api-1/sms-authentication) 문서를 참고하시길 바랍니다.&#x20;
{% endhint %}

***

### iOS 매뉴얼

#### 🅐 Xcode 설정 (iOS PASS 앱 관련 스키마 등록) <a href="#f0-9f-85-90-xcode-ec-84-a4-ec-a0-95-ios-pass-ec-95-b1-ea-b4-80-eb-a0-a8-ec-8a-a4-ed-82-a4-eb-a7-88-e" id="f0-9f-85-90-xcode-ec-84-a4-ec-a0-95-ios-pass-ec-95-b1-ea-b4-80-eb-a0-a8-ec-8a-a4-ed-82-a4-eb-a7-88-e"></a>

통신사의 PASS 앱(간편본인확인 앱)이 업데이트됨에 따라 iOS에서 가맹점 앱 서비스를 제공하는 경우, iOS9부터 보안을 강화하는 목적으로 앱을 호출할 때 앱 스키마를 등록해주어야 합니다.

| 통신사 | 앱 스키마              |
| --- | ------------------ |
| SKT | tauthlink          |
| KT  | ktauthexternalcall |
| LG  | upluscorporation   |

\
**ⓐ Info.plist 파일에 LSApplicationQueriesSchemes 배열을 정의하여 앱 스키마를 등록합니다.**

* ㉠ Information Property List에 LSApplicationQueriesSchemes를 <mark style="background-color:yellow;">Array</mark> 타입으로 추가합니다.
* ㉡ LSApplicationQueriesSchemes 하위 리스트에 String 타입으로 <mark style="background-color:yellow;">Item</mark>을 추가합니다.
* ㉢ `Item` 마다 앱 스키마를 입력합니다.

<div align="left"><figure><img src="/files/AHJIaNxcwOnXZv3AfmiI" alt=""><figcaption></figcaption></figure></div>

**ⓑ KCP 휴대폰 본인인증 완료 후 key값을 넘겨받기 위해 스키마를 등록합니다.**

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

#### 🅑 HTML form 획득 <a href="#f0-9f-85-91html-form-ed-9a-8d-eb-93-9d" id="f0-9f-85-91html-form-ed-9a-8d-eb-93-9d"></a>

KCP 휴대폰 본인인증 모듈 팝업을 출력하기 위해서 GET /kcp/id-verification을 통해 KCP로 제출할 HTML form을 요청해야 합니다.

> [GET /kcp/id-verification/form](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-form)
>
> ▶ KCP 본인인증 요청하기\
> 본인 인증을 위한 form을 생성합니다.

{% hint style="info" %}
&#x20;위 API가 아닌 임의로 form을 작성할 경우, NHN커머스 샵바이 측으로 callback을 받을 수 없습니다.

반드시 위 API 응답값으로 받은 form을 사용하시길 바랍니다.
{% endhint %}

* 응답값은 text/html 형식의 html form 양식입니다.
* returnURI는 <mark style="background-color:yellow;">scheme://</mark> 형식으로 작성합니다. (예 shopbyexample://form 🅐 - ⓑ 이미지 참고)
* 해당 API 호출시 <mark style="background-color:yellow;">request header</mark>내 <mark style="background-color:yellow;">platform</mark> 정보에 반드시 iOS를 입력하셔야 PASS 앱을 위한 아래의 추가변수가 form양식에 넘어옵니다.

<mark style="color:purple;">**✓ 예시코드**</mark>

```
<input type="hidden" name="kcp_cert_pass_use" value="Y"/>
```

#### 🅒 구현하기 <a href="#f0-9f-85-92-ea-b5-ac-ed-98-84-ed-95-98-ea-b8-b0" id="f0-9f-85-92-ea-b5-ac-ed-98-84-ed-95-98-ea-b8-b0"></a>

**ⓐ WKWebview 구성**

KCP 휴대폰본인인증 모듈은 웹으로 지원되기 때문에 WKWebview로 구성해야 합니다.

{% code overflow="wrap" %}

```
wkWebView.navigationDelegate = self
wkWebView.uiDelegate = self
wkWebView.configuration.preferences.javaScriptCanOpenWindowsAutomatically = true
```

{% endcode %}

**ⓑ webview - LoadData**

GET /kcp/id-verification호출로 전달받은 form을 webview에 로드합니다.

{% code overflow="wrap" %}

```
var htmlString = """
<html><title>KCPCert</title>
<body>\(formData)</body>  // formData 는 html form 양식입니다.
</html>
"""wkWebView.loadHTMLString(htmlString, baseURL: Bundle.main.bundleURL)
```

{% endcode %}

**ⓒ form.submit()**

webview의 <mark style="background-color:yellow;">evaluateJavaScript</mark>을 이용하여 form을 submit합니다.\
form이 submit되면 webview에서 새 창으로 KCP 휴대폰 본인인증 페이지가 노출됩니다.

{% hint style="info" %}
휴대폰 본인인증 화면은 WKWebview에서 새 창으로 열릴 수 있도록 구성해 주셔야 합니다. (ⓒ참고)

`evaluateJavaScript`는 html 폼 양식이 완전히 로드된 후( `webview didFinish`시점) 호출해 주시면 됩니다.
{% endhint %}

{% code overflow="wrap" %}

```
let injectJavaScript: String = """
// form id : form_auth
document.getElementById("form_auth").submit();
"""
var jsStr = injectJavaScript.trimmingCharacters(in: .whitespaces)
jsStr = jsStr.trimmingCharacters(in: .whitespacesAndNewlines)
jsStr = jsStr.trimmingCharacters(in: .newlines)
wkWebView.evaluateJavaScript(jsStr, completionHandler: nil)
```

{% endcode %}

**ⓓ WKWebview 구현**

WKWebview를 새 창으로 구현합니다.

아래 구현방식은 KCP 휴대폰 본인인증 연동을 위한 샘플이며, 개발 시 참고용으로 사용하시길 바랍니다.

{% code overflow="wrap" %}

```
func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration, for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
    let createWebView = WKWebView(frame: self.wkWebView.frame, configuration: configuration)
    createWebView.navigationDelegate = self
    createWebView.uiDelegate = self
    self.view.addSubview(createWebView)
    return createWebView
}
```

{% endcode %}

**ⓔ Key 파라미터 획득**

<mark style="background-color:yellow;">returnURI</mark>로 전달받은 <mark style="background-color:yellow;">URI</mark>를 parsing하여 <mark style="background-color:yellow;">key</mark>값을 추출합니다.\
WKWebview Delegate (WKNavigationDelegate)

{% code overflow="wrap" %}

```
public func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, preferences: WKWebpagePreferences, decisionHandler: @escaping (WKNavigationActionPolicy, WKWebpagePreferences) -> Void) {
    var policy = WKNavigationActionPolicy.allow
    if let requestURL = navigationAction.request.url {
        if requestURL.scheme == "shopbyexample"  {
                        if let host = requestURL.host, host == "form" {
                            if let _ = requestURL.query as String? {
                                if let urlComponent = URLComponents(url: requestURL, resolvingAgainstBaseURL: true) {
                                    let queryItems = urlComponent.queryItems
                                    if let key = queryItems?.first(where: { $0.name == "key" })?.value {
                                        print("key : \(key)")
                                    }
                                }
                            }
                            policy = .allow
                            decisionHandler(policy, preferences)
                            return
                        }
                    }
                    UIApplication.shared.open(requestURL, options: [:], completionHandler: nil)
                    policy = .cancel
    }
    decisionHandler(policy, preferences)
}
```

{% endcode %}

#### 🅓 본인인증 결과 조회 <a href="#f0-9f-85-93-eb-b3-b8-ec-9d-b8-ec-9d-b8-ec-a6-9d-ea-b2-b0-ea-b3-bc-ec-a1-b0-ed-9a-8c" id="f0-9f-85-93-eb-b3-b8-ec-9d-b8-ec-9d-b8-ec-a6-9d-ea-b2-b0-ea-b3-bc-ec-a1-b0-ed-9a-8c"></a>

해당 <mark style="background-color:yellow;">key</mark>로 본인인증 인증 성공 및 실패 여부를 판단한 뒤, 화면에 성공 및 실패 결과를 전달합니다.

> [GET /kcp/id-verification/response](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-response)
>
> ▶ KCP 본인인증 결과 조회하기\
> NHN KCP 본인인증 결과를 확인합니다.

#### 🅔 샘플코드(참고) <a href="#f0-9f-85-94-ec-83-98-ed-94-8c-ec-bd-94-eb-93-9c-ec-b0-b8-ea-b3-a0" id="f0-9f-85-94-ec-83-98-ed-94-8c-ec-bd-94-eb-93-9c-ec-b0-b8-ea-b3-a0"></a>

[KCPCertViewController.swift](https://nhnent.dooray.com/share/tree/WoOk8q6KT1K3MZcLSuyZsw/pages/3615381963904646601/files/3615931128094936280) 참고

***

### AOS 매뉴얼

#### 🅐 webview 세팅 <a href="#f0-9f-85-90-webview-ec-84-b8-ed-8c-85" id="f0-9f-85-90-webview-ec-84-b8-ed-8c-85"></a>

KCP 본인인증을 모바일로 사용하기 위해 webview를 세팅합니다.

{% code overflow="wrap" %}

```
binding.webView.apply {
    settings.apply {
        javaScriptEnabled = true
        javaScriptCanOpenWindowsAutomatically = true
        supportMultipleWindows()
    }
}
```

{% endcode %}

#### 🅑 HTML form 획득 <a href="#f0-9f-85-91-html-form-ed-9a-8d-eb-93-9d" id="f0-9f-85-91-html-form-ed-9a-8d-eb-93-9d"></a>

KCP 휴대폰 본인인증 모듈 팝업을 출력하기 위해서 GET /kcp/id-verification을 통해 KCP로 제출할 HTML form을 요청해야 합니다.

> [GET /kcp/id-verification/form](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-form)
>
> ▶ KCP 본인인증 요청하기\
> 본인 인증을 위한 form을 생성합니다.

{% hint style="info" %}
위 API가 아닌 임의로 form을 작성할 경우, NHN커머스 샵바이 측으로 callback을 받을 수 없습니다.

반드시 위 API 응답값으로 받은 form을 사용하시길 바랍니다.
{% endhint %}

* 응답값은 text/html 형식의 html form 양식입니다.
* returnURI는 <mark style="background-color:yellow;">scheme://</mark> 형식으로 작성합니다. (예 shopbyexample://form.html)

**ⓐ webview - LoadData**

GET /kcp/id-verification을 호출하여 전달받은 form을 webview에 로드합니다.

{% code overflow="wrap" %}

```
loadDataWithBaseURL(baseUrl, apiResponseData, "text/html", "UTF-8", "")
```

{% endcode %}

**ⓑ form.submit()**

webview의 <mark style="background-color:yellow;">evaluateJavaScript</mark>을 이용하여 form을 submit합니다.\
form이 submit되면 webview에서 KCP 휴대폰 본인인증 페이지로 리다이렉트 됩니다.

{% code overflow="wrap" %}

```
binding.webView.evaluateJavascript("document.form_auth.submit()") {}
```

{% endcode %}

<mark style="background-color:yellow;">evaluateJavaScript</mark>는 html 폼 양식이 완전히 로드된 후 <mark style="background-color:yellow;">WebViewClient</mark>를 이용하여 호출할 수 있습니다.

{% code overflow="wrap" %}

```
binding.webView.apply {
    webViewClient = object : WebViewClient() {
        override fun onPageFinished(view: WebView?, url: String?) {
            super.onPageFinished(view, url)
            if (url?.startsWith(baseUrl) == true) {
                binding.webView.evaluateJavascript("document.form_auth.submit()") {}
            }

        }
    }
}
```

{% endcode %}

**ⓒ Key 파라미터 획득**

본인인증이 정상적으로 끝났다면, <mark style="background-color:yellow;">returnURI</mark>로 <mark style="background-color:yellow;">key</mark>값을 전달 받습니다.

```
{YOUR_RETURN_URL}?key=XXXXXXXXXX
```

<mark style="background-color:yellow;">WebViewClient</mark>의 <mark style="background-color:yellow;">shouldOverrideUrlLoading</mark>을 통해 <mark style="background-color:yellow;">key</mark>값을 추출할 수 있습니다.

{% code overflow="wrap" %}

```
binding.webView.apply {
    webViewClient = object : WebViewClient() {
        override fun shouldOverrideUrlLoading(
            view: WebView?,
            request: WebResourceRequest?
        ): Boolean {
            if (request?.url.toString().startsWith(returnUrl)) {
                val uri = Uri.parse(request?.url.toString())
                val isContainsKey = uri.queryParameterNames.contains("key") // 파라미터에 key가 포함되어있는지 확인
                if (isContainsKey) println("key = ${uri.getQueryParameter("key")}") // key 추출

                //TODO:  key 추출 이후 과정을 이 곳에서 진행하시면 됩니다.
                return isContainsKey
            }
            return super.shouldOverrideUrlLoading(view, request)
        }
    }
}
```

{% endcode %}

#### 🅓 본인인증 결과 조회 <a href="#f0-9f-85-93-eb-b3-b8-ec-9d-b8-ec-9d-b8-ec-a6-9d-ea-b2-b0-ea-b3-bc-ec-a1-b0-ed-9a-8c" id="f0-9f-85-93-eb-b3-b8-ec-9d-b8-ec-9d-b8-ec-a6-9d-ea-b2-b0-ea-b3-bc-ec-a1-b0-ed-9a-8c"></a>

해당 <mark style="background-color:yellow;">key</mark>로 본인인증 인증 성공 및 실패 여부를 판단한 뒤, 화면에 성공 및 실패 결과를 전달합니다.

> [GET /kcp/id-verification/response](https://docs.shopby.co.kr/?url.primaryName=auth/#/KCPCertification/get-kcp-id-verification-response)
>
> ▶ KCP 본인인증 결과 조회하기\
> NHN KCP 본인인증 결과를 확인합니다.

#### 🅔 샘플코드(참고) <a href="#f0-9f-85-94-ec-83-98-ed-94-8c-ec-bd-94-eb-93-9c-ec-b0-b8-ea-b3-a0" id="f0-9f-85-94-ec-83-98-ed-94-8c-ec-bd-94-eb-93-9c-ec-b0-b8-ea-b3-a0"></a>

[MainActivity.kt](https://nhnent.dooray.com/share/tree/WoOk8q6KT1K3MZcLSuyZsw/pages/3615381963904646601/files/3615929480452935780) 참고


# \[샵바이] 웹훅(webhook) 가이드

샵바이에서 제공되는 다양한 웹훅 가이드를 안내 드립니다.

## 목차

* [#undefined-1](#undefined-1 "mention")
* [#webhook](#webhook "mention")
* [#undefined-2](#undefined-2 "mention")
* [#undefined-3](#undefined-3 "mention")
  * [#id-1](#id-1 "mention")
  * [#id-2](#id-2 "mention")
  * [#id-3](#id-3 "mention")
  * [#id-4](#id-4 "mention")
  * [#id-5](#id-5 "mention")
  * [#id-6](#id-6 "mention")
  * [#id-7](#id-7 "mention")

***

## 이해하기

* 웹훅(Webhook)이란 서버에서 특정 이벤트 발생했을 때 다른 서비스나 응용프로그램으로 알림을 보내는 기능입니다.
* 이를 사용하면 특정 이벤트가 발생했을 때 지정한 callback URL로 관련 이벤트 정보를 수신할 수 있습니다.
* 주기적으로 데이터를 조회하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어서 webhook은 리소스나 통신 측면에서 효율적입니다.
* 어떠한 이벤트가 발생했을 때 정보를 수신할 수 있는지는 제공 이벤트 항목 내용을 참고해 주시기 바랍니다.

{% hint style="warning" %}
웹훅 이벤트는 앱이 설치된 쇼핑몰에서 발생하는 이벤트 정보를 수신할 수 있으며,\
장애가 발생하여 발생한 이벤트에 대해 웹훅(Webhook)을 수신하지 못하는 경우 웹훅이 재 전송되지 않습니다.\
단, 수신하지 못한 웹훅은 [실패한 웹훅 조회하기 API](https://server-docs.shopby.co.kr/?url.primaryName=workspace/#/Webhook/get-webhooks-failed)로 조회할 수 있습니다.
{% endhint %}

***

## 웹훅(Webhook) 설정 방법

워크스페이스>셀러어드민에서 앱 등록/수정 시 개발 정보 탭에서 설정할 수 있습니다.\
지원 가능한 method : POST / PUT

1. 워크스페이스에 로그인하여 셀러어드민>상품>앱>\[T]개발 정보 화면에 접속합니다.
2. 사용할 웹훅(Webhook) 이벤트를 사용함으로 설정합니다.
3. method 및 이벤트 발생 시 웹훅(Webhook)을 수신할 URL을 설정합니다.
4. 설정된 내용을 \[저장] 합니다.

웹훅 설정 이후 앱이 쇼핑몰에 설치되어야 이벤트 정보를 수신할 수 있습니다.

{% hint style="success" %}
웹훅(Webhook)을 설정할 때는 관련된 server API의 권한이 있는 이벤트 항목만 사용할 수 있으며,

보유한 server API 권한을 삭제할 때는 관련 이벤트 항목의 웹훅(Webhook) 설정도 '사용 안 함'으로 설정해 주셔야 합니다.
{% endhint %}

{% hint style="warning" %}
판매앱의 정보를 변경하는 경우 심사 요청 후 심사가 승인되어야 변경된 정보가 반영됩니다.
{% endhint %}

***

## 제공 이벤트 항목

<table><thead><tr><th width="216">관련 server API</th><th>이벤트 유형</th><th>이벤트명</th></tr></thead><tbody><tr><td>-</td><td>CHANGE_APP_STATUS</td><td>앱 설치/삭제</td></tr><tr><td>전시 (=display)</td><td>PRODUCT_INQUIRY_ADDED</td><td>상품문의 등록</td></tr><tr><td>전시 (=display)</td><td>PRODUCT_INQUIRY_DELETED</td><td>상품문의 삭제</td></tr><tr><td>전시 (=display)</td><td>PRODUCT_REVIEW_ADDED</td><td>상품후기 등록</td></tr><tr><td>전시 (=display)</td><td>PRODUCT_REVIEW_DELETED</td><td>상품후기 삭제</td></tr><tr><td>운영 (=manage)</td><td>ACCUMULATION_ADDED</td><td>적립금 지급</td></tr><tr><td>운영 (=manage)</td><td>ACCUMULATION_SUBTRACTED</td><td>적립금 차감</td></tr><tr><td>운영 (=manage)</td><td>ACCUMULATION_SUBTRACT_ROLLBACK</td><td>적립금 차감 취소</td></tr><tr><td>운영 (=manage)</td><td>INQUIRY_ADDED</td><td>1:1문의 등록</td></tr><tr><td>운영 (=manage)</td><td>INQUIRY_MODIFIED</td><td>1:1문의 수정</td></tr><tr><td>운영 (=manage)</td><td>INQUIRY_DELETED</td><td>1:1문의 삭제</td></tr><tr><td>회원 (=member)</td><td>MEMBER_CREATED</td><td>회원가입</td></tr><tr><td>회원 (=member)</td><td>MEMBER_INFO_CHANGED</td><td>회원정보변경</td></tr><tr><td>회원 (=member)</td><td>MEMBER_GRADE_CHANGED</td><td>회원등급변경</td></tr><tr><td>회원 (=member)</td><td>MEMBER_GROUP_CHANGED</td><td>회원그룹변경</td></tr><tr><td>회원 (=member)</td><td>MEMBER_DORMANT</td><td>휴면회원 전환</td></tr><tr><td>회원 (=member)</td><td>MEMBER_RELEASED</td><td>휴면회원 해제</td></tr><tr><td>회원 (=member)</td><td>MEMBER_WITHDRAW</td><td>회원 탈퇴</td></tr><tr><td>주문 (=order)</td><td>CREATE_ORDER</td><td>주문 생성</td></tr><tr><td>주문 (=order)</td><td>CHANGE_ORDER_STATUS</td><td>주문 상태 변경</td></tr><tr><td>주문 (=order)</td><td>UPDATE_RECEIVER</td><td>수령자 정보 변경</td></tr><tr><td>주문 (=order)</td><td>ADD_TASK_MESSAGE</td><td>업무메시지 등록</td></tr><tr><td>주문 (=order)</td><td>UPDATE_TASK_MESSAGE</td><td>업무메시지 수정</td></tr><tr><td>주문 (=order)</td><td>DELETE_TASK_MESSAGE</td><td>업무메시지 삭제</td></tr><tr><td>상품 (=product)</td><td>PRODUCT_UPDATED</td><td>상품 등록/수정/삭제</td></tr></tbody></table>

***

## 이벤트별 샘플 데이터와 코드 정의

### 1. 앱 관련

<table><thead><tr><th>이벤트 유형</th><th>이벤트명</th><th data-hidden></th></tr></thead><tbody><tr><td>CHANGE_APP_STATUS</td><td>앱 설치/삭제</td><td></td></tr></tbody></table>

```java
// 샘플 데이터 및 파라미터 정의
{
    "eventType": "CHANGE_APP_STATUS", // 이벤트명
    "currentStatus": "ACTIVE", // 앱상태
    "appNo": 12345, // 앱일련번호
    "mallNo": 12345, // 쇼핑몰번호
    "appInstalledNo": 12345, // 앱설치번호
}
```

***

### 2. 전시 관련

| 이벤트 유형                    | 이벤트명    |
| ------------------------- | ------- |
| PRODUCT\_INQUIRY\_ADDED   | 상품문의 등록 |
| PRODUCT\_INQUIRY\_DELETED | 상품문의 삭제 |

```java
// 샘플 데이터 및 파라미터 정의
{
    "eventType": "PRODUCT_INQUIRY_ADDED", //이벤트명
    "mallNo": 12345, //쇼핑몰번호
    "inquiryNo" : 12345 //상품문의번호
}
```

| 이벤트 유형                   | 이벤트명    |
| ------------------------ | ------- |
| PRODUCT\_REVIEW\_ADDED   | 상품후기 등록 |
| PRODUCT\_REVIEW\_DELETED | 상품후기 삭제 |

<pre class="language-java"><code class="lang-java">// 샘플 데이터 및 파라미터 정의
<strong>{
</strong>"eventType": "PRODUCT_REVIEW_ADDED", //이벤트명
"mallNo": 12345, //쇼핑몰번호
"reviewNo" : 12345 //쇼핑몰에서 등록된 상품후기의 상품리뷰번호
"reviewNos": [12345, 12346] //server API로 등록된 상품후기의 상품리뷰번호
}
</code></pre>

***

### 3. 운영 관련

#### <mark style="color:red;">**\[적립금]**</mark>

| 이벤트 유형                           | 이벤트명      |
| -------------------------------- | --------- |
| ACCUMULATION\_ADDED              | 적립금 지급    |
| ACCUMULATION\_SUBTRACTED         | 적립금 차감    |
| ACCUMULATION\_SUBTRACT\_ROLLBACK | 적립금 차감 취소 |

```java
// 샘플 데이터 및 파라미터 정의
{
    "eventType": "ACCUMULATION_ADDED", //이벤트명
    "mallNo": 12345, //쇼핑몰번호
    "memberNo": 135375046, //회원번호
    "amount": 1000, //적립 또는 차감금액
    "accumulationReserveReason": "ADD_MANUAL", // 적립 또는 차감 사유
    "reasonDetail": "테스트 지급", // 상세
    "orderNo": null, //주문번호
    "orderOptionNo": "0", //주문옵션번호
    "registerAdminNo": 4099, //운영자번호
    "reviewNo": null //상품후기번호
}
```

***

#### <mark style="color:red;">**\[1:1문의]**</mark>

```java
 // 샘플 데이터 및 파라미터 정의
{
        "eventType": "INQUIRY_ADDED", //이벤트명
        "mallNo": 12345, //쇼핑몰번호
        "memberNo": 12345, //회원번호
        "inquiryNo": 12345, //1:1문의 일련번호
        "inquiryTypeNo": 12345, //1:1문의 유형번호
        "orderNo": null, // 주문에 대한 문의인 경우 주문번호
        "productNo": null, //주문된 상품번호
        "answerSmsSendYn": true, //1:1문의 답변 등록 시 SMS수신여부
        "inquiryTitle": "타이틀", //1:1문의 제목
        "memberId": "12345@nhn-commerce.com"//회원이메일
}
```

### 4. 회원 관련

| 이벤트 유형                 | 이벤트명    |
| ---------------------- | ------- |
| MEMBER\_CREATED        | 회원가입    |
| MEMBER\_INFO\_CHANGED  | 회원정보변경  |
| MEMBER\_GRADE\_CHANGED | 회원등급변경  |
| MEMBER\_GROUP\_CHANGED | 회원그룹변경  |
| MEMBER\_DORMANT        | 휴면회원 전환 |
| MEMBER\_RELEASED       | 휴면회원 해제 |
| MEMBER\_WITHDRAW       | 회원탈퇴    |

```java
// 샘플 데이터 및 파라미터 정의
{
    "eventType": "MEMBER_CREATED", //이벤트명
    "mallNo": 12345, //쇼핑몰 번호
    "memberNo": 12345, //회원번호
    "memberId": "chulsu", //회원아이디(외부연동 ID로 가입 시 null)
    "memberName": "홍길동", //회원이름
    "email": "gildong@nhn-commerce.com", //회원이메일
    "providerType": "KAKAO", //외부연동 ID로 가입 시 외부연동 값 노출(KAKAO, PAYCO 등)
    "gradeNo": 12345, //등급번호(회원의 등급이 변경된 경우 변경된 등급의 등급번호)
    "groupNos": [1, 2, 3], // 그룹번호 리스트(회원의 그룹이 추가/삭제된 경우, 반영이 된 모든 그룹번호 목록)
    "nickName": "angel1004", //닉네임
    "representativeMemberNo": 12345, //대표몰 회원번호(브랜드 로그인 사용하지 않는 경우 null)
    "recommenderId": "younghee" // 추천인 아이디(없으면 null)
}
```

***

### 5. 주문 관련

#### <mark style="color:red;">\[주문 생성]</mark>

| 이벤트 유형        | 이벤트명  |
| ------------- | ----- |
| CREATE\_ORDER | 주문 생성 |

{% code overflow="wrap" %}

```java
// 샘플 데이터 및 파라미터 정의
{
    "eventType": "CREATE_ORDER", //이벤트명
    "order": {
        "orderNo": "2021100201234567890", // 주문번호
        "mallNo": 30973, // 몰번호
        "serviceNo": 30388, // 서비스 번호
        "memberNo": 8411244, // 회원번호
        "memberYn": "Y", // 회원여부
        "ordererName": "홍길동", // 주문자명
        "ordererContact1": "010-1234-1234", // 주문자 핸드폰 번호
        "ordererContact2": "010-1234-1234", // 주문자 전화 번호
        "ordererEmail": "honggildong@naver.com", // 주문자 이메일
        "payType": "CREDIT_CARD", // PG타입(페이코/KCP 등)
        "pgType": "KCP", // 결제타입(페이코/신용카드 등)
        "platformType": "MOBILE_WEB", // 플렛폼 타입 (PC/MOBILE_WEB 등)
        "lastPayAmt": 185000.00, // 최종결제금액
        "lastSubPayAmt": 0.00, // 최종 적립금 결제금액
        "lastStandardAmt": 329000.00, // 최종상품금액(할인제외)
        "lastDeliveryAmt": 0.00, // 최종배송금액
        "lastRemoteDeliveryAmt": 0.00, // 최종지역별추가배송금액
        "lastImmediateDiscountAmt": 144000.00, // 최종즉시할인금액
        "lastAdditionalDiscountAmt": 0.00, // 최종추가할인금액
        "lastCartCouponDiscountAmt": 0.00, // 최종주문쿠폰할인금액
        "lastProductCouponDiscountAmt": 0.00, // 최종상품쿠폰할인금액
        "lastTaxFreeAmt": 0.00, // 최종비과세금액
        "lastTaxableAmt": 168181.00, // 최종과세금액
        "lastVatAmt": 16819.00, // 최종부과세액
        "firstSalesTaxAmt": 0.00, // 최초부과세액
        "lastSalesTaxAmt": 0.00, // 최종부과세액
        "firstCustomsDutyAmt": 0.00, // 최초관부가세
        "lastCustomsDutyAmt": 0.00, // 최종관부가세
        "registerYmdt": "2021-10-25 13:53:18", // 등록일
        "trackingKey": "trackingKey", // 쇼핑채널링-추적키
        "cartCouponIssueNo": 12, // 장바구니쿠폰 발급 번호
        "channelType": null // 유입 경로
        "orderProducts": [
            {
                "orderProductNo": 50000000, // 주문상품번호
                "mallProductNo": 100000000, // 상품번호
                "productName": "상품명",
                "productManagementCd": "", // 상품관리 코드
                "hsCode": "",
                "eanCode": null,
                "partnerNo": 50000, // 파트너 번호
                "lastProductCouponDiscountAmt": 0.00, // 상품 쿠폰 할인액
                "productCouponIssueNo": 13, // 사용한 상품 쿠폰 번호
                "orderProductOptions": [
                    {
                        "orderProductOptionNo": 5062925, // 주문상품옵션번호
                        "orderNo": "2021100201234567890", // 주문번호
                        "memberNo": 100000, // 회원번호
                        "userInputs": [ // 구매자 입력형 옵션
                            {
                              "inputLabel": "색깔", // 구매자 작성형 옵션 이름
                              "inputValue":"검정색", //구매자 입력형 옵션 값
                            }
                        ],
                        "serviceNo": 30000, // 서비스 번호
                        "mallNo": 1000, // 몰번호
                        "mallProductNo": 10000000, // 상품번호
                        "productName": "상품명",
                        "mallOptionNo": 6000000, // 상품옵션번호
                        "mallAdditionalProductNo": 0, // 추가 상품 번호
                        "optionUseYn": "Y", // 옵션 사용 여부
                        "optionName": "옵션명",
                        "optionValue": "옵션값",
                        "imageUrl": "//rlyfaazj0.toastcdn.net/...", // 상품 이미지 url
                        "orderCnt": 1, // 주문건수
                        "originalOrderCnt": 1, // 최초 주문 수량
                        "salePrice": 329000.00, // 판매 가격
                        "immediateDiscountAmt": 144000.00, // 즉시 할인 가격
                        "addPrice": 0.00, // 추가 금액
                        "additionalDiscountAmt": 0.00, // 추가 할인 금액
                        "partnerChargeAmt": 0.00, // 파트너 부담액
                        "adjustedAmt": 185000.00, // 조정된 상품 금액
                        "orderStatusType": "PAY_DONE", // 주문옵션상태
                        "displayBrandNo": 111111, // 브랜드 번호
                        "claimStatusType": null, // 클레임 상태
                        "orderYmdt": "2021-10-25 13:53:18", // 주문일시
                        "payYmdt": "2021-10-25 13:54:38", // 결제일시
                        "orderAcceptYmdt": null, // 주문접수일시
                        "releaseReadyYmdt": null, // 배송준비일시
                        "releaseYmdt": null, // 배송일시
                        "deliveryCompleteYmdt": null, // 배송완료일시
                        "buyConfirmYmdt": null, // 구매확정일시
                        "registerYmdt": "2021-10-25 13:53:18", // 주문옵션 생성일시
                        "trackingKey": "platform=MO&rid=851184319&aid=641_1_3_1025&mid=TMS", // 주문추적키 (쇼핑몰에서 생성되어 주문번호를 특정하는 구분값)
                        "deliveryNo": 400000, // 배송번호
                        "deliveryInternationalYn": false, // 해외배송여부
                        "commissionRate" : 0, //수수료율
                        "optionManagementCd": "", // 옵션 관리 코드
                        "deliveryTemplateNo": 50000, // 배송 템플릿 번호
                        "deliveryCompanyType": "CJ", // 배송 업체
                        "invoiceNo": null, // 송장번호
                        "receiverName": "홍길동", // 받는 사람 이름
                        "receiverContact1": "010-1234-5678", //수령자 휴대폰번호
                        "receiverContact2": "", //수령자 전화번호
                        "zipCd": "12345", //배송지 우편번호
                        "receiverAddress": "", // 주소
                        "receiverDetailAddress": "", // 상세 주소
                        "receiverJibunAddress": "", //지번 주소
                        "usesShippingInfoLaterInput": false, // 나중배송지 입력 여부
                        "shippingInfoLaterInputContact": null, // 나중배송지 입력 전화 번호
                        "encryptedShippingNo": null, // 나중배송지 입력 시 사용하는 암호화된 배송번호
                        "shippingEmptyAutoCancelYmdt" : "2023-10-25 13:54:38", // 배송지 미입력 시 자동 주문취소 일시
                        "customsIdNumber": '', // 개인통관고유부호
                        "extraManagementCd": "", // 옵션의 추가관리코드 (상품 등록/수정에서 설정 가능)
                    }
                ]
            }
        ]
    },
    "pay": {
        "pgType": "KCP", // PG 타입
        "payType": "CREDIT_CARD", // 결제 유형
        "payYmdt": "2021-10-25 13:54:38", // 결제일시
        "payStatusType": "DONE", // 결제상태
        "payInfo": {
            "payType": "CREDIT_CARD", // 결제 유형
            "cardInfo": {
                "cardCompany": "SHINHAN", // 카드사
                "cardCode": "CCLG", // PG 카드사 코드(PG별로 다름)
                "cardName": "신한카드", // 카드사명
                "approveYmdt": "2021-10-25 13:54:38", // 결제승인시간
                "cardNo": "*****", // 카드번호
                "cardApprovalNumber": "****", // 결제승인번호
                "noInterest": true, // 무이자여부
                "installmentPeriod": 5, // 할부기간
                "cardAmt": 185000 // 신용카드 결제금액
            },
            "bankInfo": {
                "bank" : "KDB", // 은행
                "bankCode": "", // PG 은행코드 (PG별로 다름)
                "bankName": "", // 은행명
                "account": "", // 계좌번호
                "bankAmt": 1000, // 입금해야할 금액
                "depositAmt": 1000, // 실제 입금금액
                "depositYmdt": "2021-10-25 13:54:38", // 입금일시
                "remitterName": "", // 입금자명
                "depositorName": "", // 예금주명
                "paymentExpirationYmdt": "2021-10-25 13:54:38" // 입금 마감일
            },
            "cashAuthNo": "", // 현금영수증 승인번호
            "cashNo": "", // 현금영수증 거래번호
            "tradeNo": "3000000", // 거래번호
            "escrowYn": "N", // 에스크로 결제 여부
            "payAmt": 185000, // PG결제 금액
            "sellerCouponAmt": 0, // 가맹점 발행쿠폰
            "pgCouponAmt": 0, // PG 쿠폰 금액
            "cardCouponAmt": 0, // 카드사 쿠폰 금액
            "pointAmt": 0, // PG 포인트
            "paymentKey": {
                "pgType": "KCP", // PG 유형
                "key": "key", // PG Key
                "etcInfos": {} // 기타 결제 키 관련 정보
            },
            "taxType": "DUTY", // 과세유형 (과세,면세,영세)
            "mobileInfo": { // 핸드폰 결제 정보
                "mobileNo": "010-1234-5678", // 결제 핸드폰 번호
                "mobileCompany": "" // 통신사
            },
            "naverPayInfo": { // 네이버 페이 결제 정보
                "paymentMeans": "", // 네이버 페이 결제 수단
                "paymentDueDate": "", // 입금 기한
                "paymentNumber":"", // PG승인번호
                "orderDiscountAmount": 1000, // 주문 할인액
                "generalPaymentAmount": 1000, // 일반결제수단최종결제금액
                "naverMileagePaymentAmount": 1000, // 네이버페이 포인트 최종 결제 금액
                "chargeAmountPaymentAmount": 1000, // 충전금최종결제금액
                "checkoutAccumulationPaymentAmount": 1000, // 네이버페이 적립금 최종 결제 금액
                "orderType": "", // 주문 유형 구분(네이버페이/통합장바구니)
                "payLocationType": "", // 결제 위치 구분(PC/MOBILE)
                "paymentCoreType": "", // 결제 구분(네이버결제/PG 결제)
                "payLaterPaymentAmount": 1000 // 후불결제 금액(네이버결제/PG 결제)
            }
        }
    }
}
```

{% endcode %}

***

#### <mark style="color:red;">\[주문상태변경]</mark>

| 이벤트 유형                | 이벤트명   |
| --------------------- | ------ |
| CHANGE\_ORDER\_STATUS | 주문상태변경 |

{% code overflow="wrap" %}

```java
// 샘플 데이터 및 파라미터 정의
[
    {
          "eventType": "CHANGE_ORDER_STATUS", //이벤트명
          "orderProductOptionNo": 12345, // 주문상품 옵션번호
          "orderNo": "202110110111111", // 주문번호
          "memberNo": 12345, // 회원번호
          "userInputs": [ // 구매자 입력형 옵션
              {
                "inputLabel":"색깔", //구매자 작성형 옵션 이름
                "inputValue":"검정색", //구매자 입력형 옵션 값
              }
          ],
          "serviceNo": 12345, // 서비스번호
          "mallNo": 12345, // 몰번호
          "deliveryNo": 12345, // 배송번호
          "deliveryTemplateNo": 50000, // 배송 템플릿 번호
          "deliveryInternationalYn":false, // 해외배송여부
          "mallProductNo": 100000000, // 상품번호
          "productName": "상품명",
          "mallOptionNo": 6000000, // 상품옵션번호
          "mallAdditionalProductNo": 0, // 추가 상품 번호
          "optionUseYn": "Y", // 옵션 사용 여부
          "optionName": "색상|사이즈", // 2 depth
          "optionValue": "빨강|XL", // 2 depth
          "imageUrl": "//rlyfaazj0.toastcdn.net/...", // 상품 이미지 url
          "orderCnt": 1, // 주문건수
          "originalOrderCnt": 1, // 최초 주문 수량
          "salePrice": 329000.00, // 판매 가격
          "immediateDiscountAmt": 144000.00, // 즉시 할인 가격
          "addPrice": 0.00, // 추가 금액
          "additionalDiscountAmt": 0.00, // 추가 할인 금액
          "partnerChargeAmt": 0.00, // 파트너 부담액
          "adjustedAmt": 185000.00, // 조정된 상품 금액
          "orderStatusType": "PAY_DONE", // 주문옵션상태
          "claimStatusType": null, // 클레임 상태
          "orderYmdt": "2021-10-25 13:53:18", // 주문일시
          "payYmdt": "2021-10-25 13:54:38", // 결제일시
          "orderAcceptYmdt": null, // 주문접수일시
          "releaseReadyYmdt": null, // 배송준비일시
          "releaseYmdt": null, // 배송일시
          "deliveryCompleteYmdt": null, // 배송완료일시
          "buyConfirmYmdt": null, // 구매확정일시
          "registerYmdt": "2021-10-25 13:53:18", // 주문옵션 생성일시
          "trackingKey": "platform=MO&rid=851184319&aid=641_1_3_1025&mid=TMS", // 주문추적키 (쇼핑몰에서 생성되어 주문번호를 특정하는 구분값)
          "deliveryCompanyType": "CJ", // 배송 업체
          "invoiceNo": : "1212", // 송장번호
          "receiverName": "홍길동", // 받는 사람 이름
          "zipCd": "12345", // 배송지 우편 번호
          "address": "경기도 성남시 분당구 대왕판교로645번길 12", // 배송지 주소
          "detailAddress": "16 NHN 플레이뮤지엄", // 배송지 상세 주소
          "jibunAddress": "경기도 성남시 분당구 대왕판교로645번길", // 배송지 지번 주소
          "receiverCity": "", // 배송지 해외(도시)
          "receiverState": "", // 배송지 해외(주)
          "contact1": "010-0000-0000", // 수령자 연락처1
          "contact2": "", // 수령자 연락처2
          "productManagementCd": "", // 상품관리 코드
          "optionManagementCd": "", // 옵션관리 코드
          "usesShippingInfoLaterInput": false, // 나중배송지 입력 여부
          "shippingInfoLaterInputContact": null, // 나중배송지 입력 전화 번호
          "encryptedShippingNo": null, // 나중배송지 입력 시 사용하는 암호화된 배송번호
          "retrieveInvoiceUrl": null // 배송조회 할 수 있는 url
          "commissionRate" : 0
          "isFreeGift": false, // 사은품 여부
          "updateAdminNo": 0, // 해당 주문의 상태를 마지막으로 바꾼 어드민의 번호
          "extraManagementCd": "", // 옵션의 추가관리코드 (상품 등록/수정에서 설정 가능)
          "order": {
          "extraData": "{"language": "KO"}",
          "currencyCode": "KRW",
          "exchangeRate": null
        },
          "claimNo": 123,
          "requestChannelType": "USER" // 상태변경이 요청된 채널 [SYSTEM, SERVICE, PARTNER, BATCH, USER, SERVER]
          "channelType": null // 유입 경로
          "originOrderOptionNo": 12344 // 이전 옵션번호
  }
]
```

{% endcode %}

***

#### <mark style="color:red;">\[수령자 정보 변경]</mark>

| 이벤트 유형           | 이벤트명      |
| ---------------- | --------- |
| UPDATE\_RECEIVER | 수령자 정보 변경 |

{% code overflow="wrap" %}

```java
// 샘플 데이터 및 파라미터 정의
{
    "eventType": "UPDATE_RECEIVER", // 이벤트 명
    "mallNo": 12345, // 쇼핑몰 번호
    "orderNo": "", // 주문 번호
    "shippings": [
      // 배송정보
      {
        shippingNo": 0, // 배송번호
        customsIdNumber": '', // 개인통관고유부호
        receiverAddress": {
          // 수령자 정보
          "zipCd": "12345", // 배송지 우편 번호
          "address": "경기도 성남시 분당구 대왕판교로645번길 12", // 배송지 주소
          "detailAddress": "16 NHN 플레이뮤지엄", // 배송지 상세 주소
          "jibunAddress": "경기도 성남시 분당구 대왕판교로645번길", // 배송지 지번 주소
          "receiverCity": "", // 배송지 해외(도시)
          "receiverState": "", // 배송지 해외(주)
          "contact1": "010-0000-0000", // 수령자 연락처1
          "contact2": "", // 수령자 연락처2
          "name": "홍길동", // 수령자 이름
          "shippingEtcInfo": {
            // 해외배송지 기타정보
            "receiverFirstName": "", // 수령자 FirstName
            "receiverLastName": "", // 수령자 LastName
            "orderAdditionalInfo": "", // 주문 추가 정보
          },
        },
        "countryCd": "", // 국가 코드
        "memo": "", // 배송 메모
      }
    ]
  }
```

{% endcode %}

***

#### <mark style="color:red;">\[업무메시지]</mark>

| 이벤트 유형                | 이벤트명     |
| --------------------- | -------- |
| ADD\_TASK\_MESSAGE    | 업무메시지 등록 |
| UPDATE\_TASK\_MESSAGE | 업무메시지 수정 |
| DELETE\_TASK\_MESSAGE | 업무메시지 삭제 |

{% code overflow="wrap" %}

```java
// 샘플 데이터 및 파라미터 정의
{
    "eventType": "ADD_TASK_MESSAGE", // 이벤트명
    "content": "content", // 이벤트시 작성된 내용
    "isDetail": true, // 상세 메시지 여부
    "taskMessage": {
      // 업무메시지 정보
      "taskMessageNo": 0, // 업무메시지 번호
      "taskMessageChannelType": "PARTNER", // 메시지 작성 채널
      "taskMessageStatusType": "PROCESSING", // 진행 상황
      "taskMessageType": "PAY", // 업무메시지 유형
      "fromTargetType": "PARTNER", // 발송자 타입
      "fromTargetNo": 0, // 발송자 번호
      "toTargetType": "PARTNER", // 담당자 타입
      "toTargetNo": 0, // 담당자 번호
      "content": "content", // 업무메시지 내용
      "orderNo": 0, // 주문 번호
      "orderProductOptionNo": 0, // 주문 옵션 번호
      "productName": "product-name", // 상품 명 (nullable)
      "registerYmdt": "2023-02-21 13:32:47", // 등록일시
      "updateYmdt": "2023-02-21 13:32:47", // 수정일시 (nullable)
      "completeYmdt": "2023-02-21 13:32:47", // 완료일시 (완료되지 않은 경우: null)
      "taskMessageDetails": [
        // 상세 메시지 정보
        {
          "taskMessageDetailNo": 0, // 업무메시지 상세 번호
          "taskMessageChannelType": "PARTNER", // 상세 메시지 작성 채널
          "content": "content", // 업무메시지 상세 내용
          "registerYmdt": "2023-02-21 13:32:47", // 등록일시
          "updateYmdt": "2023-02-21 13:32:47", // 수정일시 (nullable)
        }
      ]
    }
  }
```

{% endcode %}

***

#### <mark style="color:red;">\[장바구니 등록]</mark>

| 이벤트 유형    | 이벤트명    |
| --------- | ------- |
| ADD\_CART | 장바구니 등록 |

```java
// 샘플 데이터 및 파라미터 정의
{
    "eventType": "ADD_CART", 
    "mallNo": 1234, // 쇼핑몰번호
    "memberNo": 12345, // 회원번호
    "memberId": "회원아이디", // 회원아이디
    "products": [
        {
            "productNo": 12345, // 상품번호
            "productName": "상품명", // 상품명
            "optionUsed": true, // 옵션 사용여부
            "options": [
                {
                    "optionNo": 12345, // 옵션번호(옵션없는 상품은 null)
                    "optionName": "옵션명1|옵션명2". // 옵션명(옵션없는 상품은 null)
                    "optionValue": "옵션값1|옵션값2", // 텍스트옵션일 경우, 옵션 값에 사용자가 입력한 텍스트 옵션값 기재(옵션없는 상품은 null)
                    "orderCount": 1, // 장바구니 담긴 수량
                    "isRequired": true // 옵션 필수여부(옵션없는 상품은 null)
                }
            ]
        }
    ]
}
```

***

#### <mark style="color:red;">\[송장·택배사 등록/변경]</mark>

| 이벤트 유형          | 이벤트명         |
| --------------- | ------------ |
| UPDATE\_INVOICE | 송장·택배사 등록/변경 |

```java
{
    "eventType": "UPDATE_INVOICE",
    "mallNo": 1111,
    "data": {
       "eventType": "UPDATE_INVOICE",
       "mallNo": 1111,
       "orderNo": "202603292114119858",
       "invoices": [
          {
             "shippingNo": 123123, // 배송번호
             "invoiceNo": "123", // 송장번호
             "deliveryCompanyType": "CJ", // 택배사: CJ, POST, HANJIN, GTX, LOTTE, KGB, LOGEN ....
             "invoiceRegisterAdminNo": "111111",
             "invoiceRegisterAdminName": "관리자이름",
             "invoiceRegisterYmdt": "2026-05-18 20:41:51",
             "externalKey": null
          }
       ]
    }
}
```

***

### 6. 상품 관련

| 이벤트 유형           | 이벤트명        |
| ---------------- | ----------- |
| PRODUCT\_UPDATED | 상품 등록/수정/삭제 |

{% code overflow="wrap" %}

```java
// 샘플 데이터 및 파라미터 정의
{  
    "eventType": "PRODUCT_UPDATED", // 이벤트 유형
    "mallNo": 12345, // 쇼핑몰번호
    "productEventType": "CREATED" || "UPDATED" || "DELETED", // 등록 또는 수정 또는 삭제  
    "mallProductNos": [1000,20000], //상품번호  
}
```

{% endcode %}

***

### 7. 프로모션 관련

| 이벤트 유형           | 이벤트명  |
| ---------------- | ----- |
| COUPON\_ADDED    | 쿠폰 등록 |
| COUPON\_MODIFIED | 쿠폰 수정 |
| COUPON\_DELETED  | 쿠폰 삭제 |

{% code overflow="wrap" %}

```java
// 샘플 데이터 및 파라미터 정의
{
       "eventType": "COUPON_ADDED",
       "mallNo": 12345, // 쇼핑몰번호,
       "coupons": [
           {
               "couponNo": 11111, // 쿠폰번호
               "couponName": "쿠폰명",
               "couponIssueType": "DOWNLOAD", // 발급 유형 : 다운로드 발급 / 코드 발급(직접입력) / 코드 발급(자동생성) / 자동 발급
               "couponStatusType": "ISSUE_ING", // 발급 상태 : 발급대기 / 발급중 / 발급중지 / 발급종료
               "couponType": "CART" // 혜택 구분 : 상품적용 쿠폰 / 주문적용 쿠폰 / 기프트 쿠폰
           }
       ]
   }
```

{% endcode %}


# \[고도몰] 웹훅(webhook) 가이드

고도몰에서 제공되는 다양한 웹훅 가이드를 안내 드립니다.

## 목차

* [#undefined-1](#undefined-1 "mention")
* [#undefined-2](#undefined-2 "mention")
* [#undefined-3](#undefined-3 "mention")
* [#undefined-4](#undefined-4 "mention")
* [#undefined-5](#undefined-5 "mention")
  * [#id-1](#id-1 "mention")
  * [#id-2](#id-2 "mention")
  * [#id-3](#id-3 "mention")
  * [#id-4](#id-4 "mention")
  * [#id-5](#id-5 "mention")

***

## 이해하기

* 웹훅이란 서버에서 특정 이벤트 발생했을 때 다른 서비스나 응용프로그램으로 알림을 보내는 기능입니다.
* 이를 사용하면 특정 이벤트가 발생한 시점에 지정한 callback URL로 이벤트 정보를 수신할 수 있습니다.
* 주기적으로 데이터를 조회하지 않고 원하는 이벤트에 대한 정보만 수신할 수 있어서 웹훅은 리소스나 통신 측면에서 효율적입니다.

***

## 웹훅의 장점

* 웹훅의 가장 큰 장점은 원하는 이벤트가 발생했을 때만 데이터를 수신하여 효율적으로 데이터 통신을 할 수 있다는 점입니다.
* 이를 통해 서버와 클라이언트 간의 불필요한 통신을 줄이고, 서버의 부하를 최소화할 수 있습니다.
* 또한, 웹훅은 비동기적으로 작동하여 이벤트가 즉시 처리되므로 실시간에 가까운 정보 업데이트가 가능합니다.\
  이는 빠른 응답 시간이 필요한 애플리케이션에 특히 유리합니다.

***

## 웹훅 사용 사례

* **알림 시스템**: 결제 시스템에서 구매가 완료되었을 때, 사용자에게 이메일이나 문자로 알림을 보내는 경우.
* **데이터 동기화:** 여러 서비스 간의 데이터 일치를 유지하기 위해 이벤트 발생 시 자동으로 업데이트하는 경우.
* **자동화 작업**: 빌드시스템에서 코드 변경 시 자동으로 테스트 및 배포를 실행하는 경우.

위와 같은 사례들은 웹훅의 효율성을 잘 보여주며 다양한 분야에서 활용될 수 있습니다.

웹훅을 통해 우리는 이벤트 기반 자동화 모델을 구축할 수 있습니다. 이러한 자동화는 개발자의 개입을 최소화하고 시스템의 유지 보수를 용이하게 합니다. 충분한 유연성과 적응성을 제공하는 웹훅은 다양한 언어와 플랫폼에서 쉽게 통합될 수 있으며, 이는 개발 주기를 가속화시킵니다. 활용 가능한 API와 결합하면, 무한한 기능 확장이 가능하여 더욱 풍부한 사용자 경험을 제공할 수 있습니다.

{% hint style="warning" %}
웹훅 이벤트는 <mark style="color:red;">앱이 설치된 쇼핑몰에서 발생하는 이벤트 정보를 수신</mark>할 수 있으며,

장애가 발생하여 발생한 이벤트에 대해 웹훅(Webhook)을 수신하지 못하는 경우 웹훅이 재 전송되지 않습니다.

단, 수신하지 못한 웹훅은 [실패한 웹훅 조회하기 API](https://server-docs.godomall.com/?activeName=%EC%9D%B8%EC%A6%9D#/Webhook/get-webhooks-failed)로 조회할 수 있습니다.
{% endhint %}

그렇다면 고도몰에서는 어떠한 이벤트 항목의 웹훅을 제공하고 있을까요?

***

### 제공 이벤트 항목

| 이벤트 유형                            | 이벤트명               |
| --------------------------------- | ------------------ |
| CHANGE\_APP\_STATUS               | 앱 설치/삭제            |
| GD\_MEMBER\_LOGGED\_IN            | 회원 로그인             |
| GD\_MEMBER\_CREATED               | 회원 가입 완료           |
| GD\_MEMBER\_GRADE\_CHANGED        | 회원 등급 변경           |
| GD\_MEMBER\_INFO\_CHANGED         | 회원 정보 수정           |
| GD\_MEMBER\_WITHDRAW              | 회원 탈퇴              |
| GD\_MEMBER\_MILEAGE\_CHANGED      | 회원 마일리지 변경         |
| GD\_PRODUCT\_UPDATED              | 상품 등록/수정/삭제        |
| GD\_ORDER\_COMPLETED              | 결제 완료              |
| GD\_ORDER\_CREATED                | 입금대기 주문 생성         |
| GD\_ORDER\_GOODS\_STATUS\_CHANGED | 주문 상품 상태 변경        |
| GD\_CART\_UPDATED                 | 회원 장바구니 등록(비회원 제외) |

***

## 이벤트별 샘플 데이터와 코드 정의

### 1. 앱 관련

<table><thead><tr><th>이벤트 유형</th><th>이벤트명</th><th data-hidden></th></tr></thead><tbody><tr><td>CHANGE_APP_STATUS</td><td>앱 설치/삭제</td><td></td></tr></tbody></table>

<pre class="language-java"><code class="lang-java">// 샘플 데이터 및 파라미터 정의
{
<strong>        "eventType": "CHANGE_APP_STATUS", // not null
</strong>        "currentStatus": {앱설치상태}, // ("ACTIVE" || "DELETED")
        "appNo": {앱번호}, // not null
        "appInstalledNo": {앱설치번호}, // not null
        "mallNo": {샵바이 쇼핑몰번호}, // not null
        "shopNo": {샵바이/고도몰 상점번호}, // not null
        "solutionType": {솔루션 구분}, // not null, ("SHOPBY" || "GODO")
}
</code></pre>

***

### 2. 회원 관련

#### <mark style="color:red;">\[회원 로그인]</mark>

| 이벤트 유형                 | 이벤트명   |
| ---------------------- | ------ |
| GD\_MEMBER\_LOGGED\_IN | 회원 로그인 |

```java
// 샘플 데이터 및 파라미터 정의
{
        "eventType": "GD_MEMBER_LOGGED_IN", // not null
        "shopNo": 상점번호, // not null
        "trackingKey": "트래킹키", // nullable
        "memberNo": 회원번호, // not null
        "memberId": "회원아이디", // not null
}
```

***

#### <mark style="color:red;">\[회원 가입 완료, 회원 등급 변경, 회원 정보 수정, 회원 탈퇴]</mark>

| 이벤트 유형                     | 이벤트명     |
| -------------------------- | -------- |
| GD\_MEMBER\_CREATED        | 회원 가입 완료 |
| GD\_MEMBER\_GRADE\_CHANGED | 회원 등급 변경 |
| GD\_MEMBER\_INFO\_CHANGED  | 회원 정보 수정 |
| GD\_MEMBER\_WITHDRAW       | 회원 탈퇴    |

```java
// 샘플 데이터 및 파라미터 정의
{
        "eventType": 이벤트유형,  // not null
        "shopNo": 상점번호, // not null
        "trackingKey": "트래킹키", // nullable
        "memberNo": 회원번호,  // not null
        "memberId": "회원아이디",  // not null
        "memberName": "회원이름",  // not null
        "email": "이메일", // nullable
        "groupNo": "회원그룹번호", // not null
        "nickName": "닉네임", // nullable
}
```

***

#### <mark style="color:red;">\[회원 마일리지]</mark>

| 이벤트 유형                       | 이벤트명                                         |
| ---------------------------- | -------------------------------------------- |
| GD\_MEMBER\_MILEAGE\_CHANGED | <p>회원 마일리지 변경<br>(마일리지  적립, 소멸, 차감 시 발행)</p> |

```java
// 샘플 데이터 및 파라미터 정의
{
      "eventType": "GD_MEMBER_MILEAGE_CHANGED",  // not null
      "shopNo": "상점번호", // not nul 
      "sno": "마일리지 번호", // not null
      "memberSno": 회원 번호 // not null
      "mileageEventType": "마일리지이벤트 유형", // not null("EARN" || "EXPIRE" || DEDUCT)
      "mileage": "변경 마일리지", // not null
      "afterMileage": "변경후 최종 마일리지", // not null
      "mileageChangeDateTime": "마일리지 변경 일시", // not null
      "expirationDateTime": "마일리지 소멸 일시", // nullable
      "trackingKey": "트래킹키" // nullable
}
```

***

### 3. 상품 관련

| 이벤트 유형               | 이벤트명        |
| -------------------- | ----------- |
| GD\_PRODUCT\_UPDATED | 상품 등록/수정/삭제 |

```java
// 샘플 데이터 및 파라미터 정의
{
        "eventType": "GD_PRODUCT_UPDATED", // not null
        "shopNo": 상점번호, // not null
        "trackingKey": "트래킹키", // nullable
        "goodsNo": 상품번호, // not null (여러개인경우 ,로 연결)
        "goodsEventType": "이벤트타입", // not null, ("CREATED" || "UPDATED" || "DELETED")
        "timestamp": "발생일시" // not null
}
```

***

### 4. 주문 관련

#### <mark style="color:red;">\[결제 완료, 입금 대기 주문 생성]</mark>

| 이벤트 유형               | 이벤트명       |
| -------------------- | ---------- |
| GD\_ORDER\_COMPLETED | 결제 완료      |
| GD\_ORDER\_CREATED   | 입금대기 주문 생성 |

```java
// 샘플 데이터 및 파라미터 정의
{
        "eventType": "GD_ORDER_COMPLETED", // not null
        "shopNo": 상점번호, // not null
        "trackingKey": "트래킹키", // nullable
        "orderNo": 주문번호, // not null
        "memberNo": 회원번호, // not null
        "totalSettlePrice": 총 결제금액, // not null
        "orderTypeFl" : 주문 유형 // not null ("pc" || "mobile" || "write")
        "appOs" :  앱 주문시 휴대폰 OS // nullable ("ios" || "android" || "etc")
        "channelType" :  주문건 추적 채널타입 데이터// nullable: true
        "refererUrl" : 주문 생성 시점에 접속된 URL // not null
        "orderCustomerName" : 주문자명, // not null
        "orderDate" : 주문일자, // not null
        "orderCustomerPhone" : 주문자 핸드폰 번호 , // nullable
        "orderCustomerEmail" : 주문자 이메일, // nullable
        "depositorName" : 입금자명, // nullable
        "depositDeadline" : 입금 마감일, // nullable
        "taxReceiptType": 현금영수증/세금계산서 유형, // nullable("CASH_RECEIPT" || "TAX_INVOICE")
        "cashReceiptType": 현금 영수증 발행 용도, // nullable("EXPENSE_PROOF" || "INCOME_DEDUCTION")
        "authenticationCode": 인증번호 // nullable
}
```

***

#### <mark style="color:red;">\[주문 상품 상태 변경]</mark>

* 기존 주문 건의 상태 변경에 대한 웹훅으로 신규 생성된 주문 건에 대해서는 웹훅 발행되지 않습니다.
* \[기본설정 > 주문정책 > 주문상태설정] 에서 추가한 커스텀 주문 상태로 변경된 경우 웹훅 발행되지 않습니다.
* 웹훅은 동일한 주문 번호에 묶여있는 모든 상품(주문 상품 번호)의 정보가 포함되어 전송됩니다.\
  단, 송장일괄등록으로 배송 상태가 변경되거나, 클레임 처리(교환/환불/반품) 상품의 상태가 변경될 경우 주문 상품 번호 단위로 개별 발행 됩니다.&#x20;

| 이벤트 유형                            | 이벤트명        |
| --------------------------------- | ----------- |
| GD\_ORDER\_GOODS\_STATUS\_CHANGED | 주문 상품 상태 변경 |

```java
// 샘플 데이터 및 파라미터 정의
[
    {
        "eventType": "GD_ORDER_GOODS_STATUS_CHANGED", // not null
        "shopNo": 상점번호, // not nul 
        "orderNo": 주문 번호, // not null
        "orderGoodsNo": 주문 상품 번호, // not null,
        "orderGoodsStatus": "주문 상품 상태", // not null
        "statusChangeDateTime": "주문 상품 상태 변경일", // not null
        "paymentMethod": "결제수단" // not null
    }
]
```

***

### 5. 장바구니 관련

| 이벤트 유형            | 이벤트명                |
| ----------------- | ------------------- |
| GD\_CART\_UPDATED | 회원 장바구니 등록(비회원  제외) |

```java
// 샘플 데이터 및 파라미터 정의
{
        "eventType": "GD_CART_UPDATED", // not null,
        "shopNo": 상점번호, // not null,
        "actionType": 처리유형, // not null,
        "memberNo" : 회원번호 // not null,
        "goodsNo" : 상품번호 // not null,
        "goodsCnt" : 구매수량 // not null,
        "goodsOptionNo" : 상품 옵션 번호
        "goodsOptionText" :
        [
            {
                "goodsOptionTextNo" : 상품 텍스트 옵션 번호,
                "value" : 상품 텍스트 옵션 내용
            },
        ],
        "addGoods" :
        [
            {
                "addGoodsNo" : 추가상품 번호,
                "addGoodsCnt" : 추가상품 갯수
            },
        ],
        "updatedDateTime" : "처리 시간"
        "trackingKey": "트래킹키"
}
```

***

#### <mark style="color:$info;">\[참고] 주문 상품 상태 코드값</mark>

<table data-header-hidden><thead><tr><th width="372.181884765625">주문 상태</th><th>주문 상태 웹훅값</th></tr></thead><tbody><tr><td>입금대기</td><td>ORDER</td></tr><tr><td>결제완료</td><td>PAYMENT</td></tr><tr><td>상품준비중</td><td>GOODS_READY</td></tr><tr><td>구매발주</td><td>GOODS_PLACEMENT</td></tr><tr><td>상품입고</td><td>GOODS_RECEIVED</td></tr><tr><td>상품출고</td><td>GOODS_SHIPPED</td></tr><tr><td>배송중</td><td>DELIVERY</td></tr><tr><td>배송완료</td><td>DELIVERY_COMPLETE</td></tr><tr><td>구매확정</td><td>SETTLE</td></tr><tr><td>자동취소</td><td>CANCEL_AUTO</td></tr><tr><td>품절취소</td><td>CANCEL_OUT_OF_STOCK</td></tr><tr><td>관리자취소</td><td>CANCEL_ADMIN</td></tr><tr><td>고객취소요청</td><td>CANCEL_CUSTOMER_REQUEST</td></tr><tr><td>반품접수</td><td>BACK_REQUEST</td></tr><tr><td>반송중 (반품)</td><td>BACK_IN_TRANSIT</td></tr><tr><td>반품보류</td><td>BACK_ON_HOLD</td></tr><tr><td>반품회수완료</td><td>BACK_COMPLETE</td></tr><tr><td>교환접수</td><td>EXCHANGE_REQUEST</td></tr><tr><td>반송중 (교환)</td><td>EXCHANGE_IN_TRANSIT</td></tr><tr><td>재배송중</td><td>EXCHANGE_REDELIVERY</td></tr><tr><td>교환보류</td><td>EXCHANGE_ON_HOLD</td></tr><tr><td>교환완료</td><td>EXCHANGE_COMPLETE</td></tr><tr><td>환불접수</td><td>REFUND_REQUEST</td></tr><tr><td>환불보류</td><td>REFUND_ON_HOLD</td></tr><tr><td>환불완료</td><td>REFUND_COMPLETE</td></tr></tbody></table>

***

#### <mark style="color:$info;">\[참고] 결제 수단 코드값</mark>

| 에스크로 계좌이체     | EB |
| ------------- | -- |
| 에스크로 신용카드     | EC |
| 에스크로 가상계좌     | EV |
| 간편결제 계좌이체     | FB |
| 간편결제 신용카드     | FC |
| 간편결제 휴대폰      | FH |
| 간편결제 포인트      | FP |
| 간편결제 가상계좌     | FV |
| 간편결제 무통장입금    | FA |
| 무통장 입금        | GB |
| PAYPAL        | OP |
| VISA / MASTER | OV |
| JCB / AMEX    | OJ |
| ALIPAY        | OA |
| TENPAY        | OT |
| UNIONPAY      | OU |
| 계좌이체          | PB |
| 신용카드          | PC |
| 휴대폰           | PH |
| 가상계좌          | PV |
| 간편결제 카카오페이    | PK |
| 간편결제 후불결제     | PL |
| 간편결제 네이버페이    | PN |
| 토스페이          | PT |
| 페이코           | PP |
| 예치금           | GD |
| 마일리지          | GM |
| 전액할인          | GZ |
| 기타            | GR |


# 추천 콘텐츠

### **샵바이 공통**

{% content-ref url="/pages/yVj0vah21zjechnIEQtV" %}
[\[웹훅 추가\] 주문정보 웹훅(Webhook)이란?](/contents/recommended/webhook)
{% endcontent-ref %}

{% content-ref url="/pages/K8cfio1GMFK8watEEQ82" %}
[\[웹훅 추가\] 회원정보 변경 및 회원탈퇴](/contents/recommended/undefined-2)
{% endcontent-ref %}

{% content-ref url="/pages/BZSYLecslD6eziICzol9" %}
[\[웹훅 추가\] 앱 설치 및 삭제](/contents/recommended/undefined-3)
{% endcontent-ref %}

{% content-ref url="/pages/cx0N8eNaMjTiyMTDURL7" %}
[shop by API, POSTMAN에 추가하기](/contents/recommended/shop-by-api-postman)
{% endcontent-ref %}

{% content-ref url="/pages/R9r3ERT7Q2HgHFaxFQgX" %}
[\[공통\] 마이페이 API 화면가이드](/contents/recommended/mypay)
{% endcontent-ref %}

### **샵바이 베이직/프로**

{% content-ref url="/pages/ClGHvR8ljqaEdIY8CbIr" %}
[\[베이직/프로\] 카카오싱크 신청 가이드](/contents/recommended/undefined-1)
{% endcontent-ref %}

### **샵바이 프로/엔터프라이즈**

{% content-ref url="/pages/tzzVlY0O7hnMWrQH4bQU" %}
[\[프로/엔터프라이즈\] 쇼핑몰에 인스타그램 위젯을 적용해보세요!](/contents/recommended/undefined)
{% endcontent-ref %}

### **샵바이 엔터프라이즈**

{% content-ref url="/pages/ufLFgmppn0rxuLgYSiZp" %}
[\[엔터프라이즈\] 선물하기 기능 (배송지 나중입력)](/contents/recommended/prm_gift)
{% endcontent-ref %}

{% content-ref url="/pages/dbSLa3wlPjBmSLU6Hb5J" %}
[\[엔터프라이즈\] 카카오싱크 신청 가이드](/contents/recommended/prm_kakao-sync)
{% endcontent-ref %}

{% content-ref url="/pages/nKjqKg2KU8nSDA45uq5d" %}
[\[엔터프라이즈\] 카카오싱크 회원가입 API 화면가이드](/contents/recommended/prm_kakao-sync_login)
{% endcontent-ref %}

{% content-ref url="/pages/SXJI8ZDSjRy8uokEbrEd" %}
[\[엔터프라이즈\] 이니렌탈(렌탈결제) API 화면가이드](/contents/recommended/prm_inirental)
{% endcontent-ref %}

{% content-ref url="/pages/MpiXbboCdBeaIIhIefks" %}
[\[엔터프라이즈\] 외부 회원 연동 가이드](/contents/recommended/prm_member_guide)
{% endcontent-ref %}

{% content-ref url="/pages/cKho8U6QaLYGUMzm6DTk" %}
[\[엔터프라이즈\] 외부 적립금 전환 가이드](/contents/recommended/prm_mileage_transform_guide)
{% endcontent-ref %}

{% content-ref url="/pages/axcZNfRaMOQ6Hi2UT7sE" %}
[\[엔터프라이즈\] 외부 적립금 연동가이드](/contents/recommended/prm_mileage_guide)
{% endcontent-ref %}

{% content-ref url="/pages/QvuE0UuPgfOUkKvlthEf" %}
[\[엔터프라이즈\] PG신청 가이드 (2026/1/28 업데이트)](/contents/recommended/prm_pg_guide)
{% endcontent-ref %}

{% content-ref url="/pages/QPufVVQhiZYKSyA1wdkH" %}
[\[엔터프라이즈\] 카카오 픽셀 설치 가이드](/contents/recommended/prm_kakaopixel_guide)
{% endcontent-ref %}

{% content-ref url="/pages/b6EU43krBZ0V7s2roN5S" %}
[\[엔터프라이즈\]정기결제(배송) API 화면가이드](/contents/recommended/recurring-payment-api)
{% endcontent-ref %}

{% content-ref url="/pages/kEN9HF56pfO2zKQZ4c0j" %}
[\[엔터프라이즈\] 정기결제(배송) 변경 동의 관리 API 화면가이드](/contents/recommended/recurring-payments-change-api)
{% endcontent-ref %}


# \[간편 로그인] SNS 연동 기능 개발 가이드

간편 로그인 기능을 사용하기 위해, SNS 연동 프로세스를 소개합니다.

## 간편로그인 SNS 연동 프로세스

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

### **1) SNS 연동 정보 등록**

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

SNS 간편로그인 연동 기능을 사용하기 위해서는 아래 메뉴에서 연동 정보를 등록하셔야 합니다.

* shop by pro : \[설정 > 기본 정책 > 외부서비스 설정]
* shop by premium : \[서비스 관리 > 쇼핑몰 관리]

어드민에서 연동 설정된 제공사에 한해, 회원가입 페이지 및 로그인 페이지에서 간편 로그인 기능이 제공됩니다.

> **GET /malls** [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=admin/#/Mall/get-malls)
>
> ▶ 몰 정보 조회하기
>
> 쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.

* 어드민에 연동 설정이 되어있는 간편로그인 제공사 정보를 조회합니다.
* 해당 API 응답 값 중 openIdJoinConfig 내 providers 값을 통해 확인 가능합니다.

***

### 2) 간편 로그인 연동 URI 획득

간편 로그인 제공사(provider)이 각각 다르므로, provider 별 외부 화면을 노출하기 위해서는 먼저 아래 API를 호출하여 간편 로그인 연동 URI를 조회합니다.

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

* 해당 API 호출 시 3개 파라미터가 필요하며 각 파라미터에 대한 설명은 아래와 같습니다.
  * **provider**
    * 간편 로그인 제공사
    * 각 제공사 id 앞에 'ncp\_' 를 추가 (ex) ncp\_naver, ncp\_payco, ncp\_kakao, ncp\_facebook)
  * **state**
    * CSRF 공격 방지용 토큰
    * client에서 생성한 숫자, 영문 대소문자로 이루어진 6자리의 random string
  * **redirectUri**
    * 인증 성공 후 이동할 쇼핑몰의 리다이렉트 URI (인코딩 필수)
    * 형식: [https://{쇼핑몰](https://xn--{-y21fx0qvtv/) 도메인}/{callbackUrl}
  * **reauthenticate**
    * 재인증 여부
    * 최초 간편로그인 연동 시 false로 입력
    * 재인증 필요한 경우 true로 입력
* <mark style="color:blue;">**예시코드**</mark>
  * Request URI

    <pre data-overflow="wrap"><code>https://alpha-shop-api.e-ncp.com/oauth/login-url?provider=ncp_payco&#x26;redirectUri=https%3A%2F%2Fdevfe.shopby.co.kr%3A8283%2Fcallback%2Fauth-callback&#x26;state=Ixihzt
    </code></pre>
  * Responses

    <pre data-overflow="wrap"><code>{
      "loginUrl": "https://demo-id.payco.com/oauth2.0/authorize?serviceProviderCode=FRIENDS&#x26;userLocale=ko_KR&#x26;client_id=3RDuVJewHrYNLwHLVfHK&#x26;redirect_uri=https://devfe.shopby.co.kr:8283/callback/auth-callback.html&#x26;response_type=code",
      "sessionKey": null
    }
    </code></pre>

***

## 3) **간편 로그인 제공사 (Provider) 화면 노출**

획득한 간편 로그인 연동 URI 을 통해 간편 로그인 제공사 화면을 노출합니다.\
기본 스킨의 경우 팝업 형태로 간편 로그인 제공사 화면을 제공합니다.

이후 각 간편 로그인 제공사(provider) 정책에 따라, 인증 절차를 수행합니다.

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

***

## 4) **쇼핑몰 redirectUri로 이동**

간편 로그인 제공사 화면에서 인증에 성공 후, code 값과 함께 쇼핑몰 redirectUri 로 이동합니다.\
이를 통해 프론트 화면에도 각 간편 로그인 제공사에서의 인증 성공 여부를 전달합니다.

* <mark style="color:blue;">**예시코드**</mark>

  ```
  https://{쇼핑몰 도메인}/callback/auth-callback?code=XXXXXXXXXX
  ```


# \[공통] 마이페이 API 화면가이드

커스텀 스킨이 마이페이 기능을 사용하기 위해, shop API로 주문서 화면을 어떻게 구현할 수 있을지 안내하기 위한 콘텐츠입니다.

## 간단소개

* **기능요약**
  * 이니시스의 커스텀 간편 결제 서비스(마이 페이)를 통해 쇼핑몰 회원이 카드/ 계좌를 간편하게 등록 및 결제할 수 있도록 제공합니다.
  * 대상 솔루션: 샵바이 전용
  * 기능 배포일자:2023-08-21
* **기능상세**
  * 마이페이 사용을 위해서는 앱 설치가 필요합니다.
  * 마이페이 앱 설치 링크 : <https://apps.godo.co.kr/apps/845>

***

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

{% hint style="info" %}
아래 API들을 활용하여 마이페이 기능을 활용한 화면을 구현할 수 있습니다.
{% endhint %}

### **1) 주문서 화면**

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

**① 마이페이 버튼 출력**

> **▶ 주문서 조회하기**
>
> GET /order-sheets/{orderSheetNo} [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet)
>
> 주문서를 조회하는 API입니다.

* 해당 API를 호출하여 받은 응답 값 중 availablePayTypes에서 결제 수단 정보를 확인할 수 있습니다.
* 마이페이 앱(APP)에서 결제수단 노출 설정 여부 '사용함' 설정 시 pgTypes에 MY\_PAY이 포함됩니다.

***

**② 마이페이 커스텀 적용**

> **▶ 주문서 조회하기**
>
> GET /order-sheets/{orderSheetNo} [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet)
>
> 주문서를 조회하는 API입니다.

* 해당 API를 호출하여 받은 응답 값 중 myPayInfo에서 마이페이 앱(APP)에서 설정한 커스텀 정보를 확인 할 수 있습니다.
* 커스텀이 적용된 화면은 회원가입, 결제수단 등록, 비밀번호 변경 팝업에서 확인하실 수 있습니다.

> **▶ MYPay 등록된 결제수단 조회하기**
>
> GET /my-pay/payment-infos [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/MyPay/get-payment-infos)
>
> 등록된 결제수단을 조회하는 API입니다.

* 해당 API를 호출하여 받은 응답 값 중 paymentInfos에서 등록된 결제 수단 정보를 확인할 수 있습니다.
* 응답 값 중 code가 1002인 경우, 마이페이 간편결제 회원가입을 진행하지 않은 사용자입니다.

***

## 2) 회원가입 및 결제 수단 등록 화면

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

> **▶ 회원 등록하기**
>
> GET /my-pay/register-user [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/MyPay/get-register-user)
>
> 회원 등록 webUrl를 위한 정보를 조회합니다.

* 발급받은 accessToken을 사용하여 해당 API를 호출합니다.
* 들어가야 하는 provider : MyPayProvider / clientReturnUrl : 회원 등록 완료 후 client 이동 url
* 회원 가입을 하지 않은 경우 : 설정, 결제 수단 등록 버튼 클릭 시 회원 가입 팝업이 출력됩니다.

> **▶ 결제수단 등록하기**
>
> GET /my-pay/register-payment [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/MyPay/get-register-payment)
>
> 결제수단 등록 webUrl를 위한 정보를 조회합니다.

* 회원 가입이 되어 있는 경우 계좌 및 신용 · 체크 카드 등록 여부를 선택합니다.
* paymentInfos 값을 노출 처리합니다.

***

## 3) 결제 수단 설정 팝업 화면

<figure><img src="/files/ZB1dAUu5mZ1oCFcFibCa" alt=""><figcaption><p>마이페이 결제수단 설정 화면</p></figcaption></figure>

> **▶ 비밀번호 변경하기**
>
> GET /my-pay/modify-password [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/MyPay/post-modify-password)
>
> 비밀번호 변경파라미터 조회를 조회합니다.

***

> **▶ 등록된 결제 수단 삭제하기**
>
> DELETE /my-pay/payment-infos [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/MyPay/delete-payment-infos-pay-token)
>
> 등록된 결제수단을 삭제합니다.

* 선택된 결제 수단의 payToken값을 사용하여 해당 API를 호출합니다.
* 호출 성공 시 마이페이에 등록된 결제 수단 조회하기 API를 재 호출하여 결제 수단 정보를 갱신합니다.

***

> **▶ 회원 서비스 해제하기**
>
> DELETE /my-pay/users [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/MyPay/delete-user)
>
> 회원 서비스를 해제합니다.

* accessToken을 활용하여 해당 API를 호출 후 등록된 회원의 서비스를 해제합니다.
* 호출 성공 시 마이페이에 등록된 결제 수단 조회하기 API를 재 호출하여 결제 수단 정보를 갱신합니다.

***

> **▶ 중복 가입 회원 서비스 해제하기**
>
> DELETE /my-pay/user/by-key [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/MyPay/delete-user-by-key)
>
> 회원 서비스를 해제합니다.

* 마이페이 회원 등록 중 '이미 등록된 회원입니다.'라는 메시지가 나오는 경우에만, 해당 API를 통해 회원 서비스를 해지할 수 있습니다.
* 회원 서비스 해지할 사용자의 deleteKey를 활용하여 해당 API를 호출 후 등록된 회원의 서비스를 해제합니다. 이때 deleyKey는 회원 등록하기 진행 시, 중복 회원이면 응답 결과로 전달됩니다.

***

> **▶ API 호출 후 팝업창 띄우기** [**API 보기>**](https://shop-api.e-ncp.com/payments/ncp_pay.js)

* 위 라이브러리를 이용하시면, API 호출 후 webUrl을 이용한 UI 호출을 좀 더 손쉽게 하실 수 있습니다.
* 라이브러리 임포트 후에, 아래와 같은 방식으로 API 호출 및 UI 오픈을 자동으로 처리할 수 있습니다.

**NCPPay.requestMyPayApi(param, apiType)**

* param에는 각 API에 필요한 body 정보를 넣어주시면 됩니다.
* apiType은 아래와 같습니다.
  * REGISTER\_USER
  * REGISTER\_USER\_WITH\_PAYMENT
  * REGISTER\_PAYMEN
  * PAYMENT\_INFOS
  * MODIFY\_PASSWORD
  * DELETE\_USER
  * DELETE\_PAYMENT
  * MODIFY\_MAIN\_PAYMENT
  * DELETE\_USER\_BY\_KEY

***

### 참고 사항

1. 오로라 기본 스킨이나 react-components를 사용하고 있는 경우 스킨 패치가 필요합니다.
   * [마이페이 릴리즈 업데이트 확인하기>](https://skins.shopby.co.kr/shopby/aurora-skin/-/releases/v1.0.47)
2. 마이페이 기능을 간편하게 사용할 수 있도록 @shopby/react-components패키지에 마이페이컴포넌트를 제공합니다.
   * 마이페이용 컴포넌트 가이드는 추후 제공 예정입니다.
   * [기존 컴포넌트 가이드 확인하기>](https://nhnent.dooray.com/share/pages/WoOk8q6KT1K3MZcLSuyZsw/3530467794042524642)


# \[엔터프라이즈] 선물하기 기능 (배송지 나중입력)

샵바이 엔터프라이즈의 선물하기(배송지 나중입력) 기능을 사용하기 위해, 기능 상세설명 및 활용가능한 shop API를 안내하는 콘텐츠입니다.

## 간단소개

* 선물하기(배송지 나중입력) 기능
  * 적용 솔루션: 샵바이 엔터프라이즈 전용
  * 요약설명
    * 구매자가 주문 시점에 배송지 정보를 넣지 않고, 받는 사람 정보(이름/휴대폰번호)만 프론트에 입력합니다.
    * 이후 받는 사람의 휴대폰 번호로 배송지를 입력할 수 있는 URL이 전송되어, 받는 사람이 직접 배송지를 나중에 입력할 수 있는 기능입니다.

***

### 프로세스 상세 설명 <a href="#undefined" id="undefined"></a>

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

### (A) 결제

주문예약 API 호출 시 아래 항목을 전송합니다. [**API 보기 >**](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve)

* shippingAddress.usesShippingInfoLaterInput = true : 나중입력 사용여부
* shippingAddress.shippingInfoLaterInputContact : 수신자연락처
* shippingAddress 의 나머지 주소 정보는 `-` 로 전송

{% code overflow="wrap" %}

```
"receiverZipCd": "-",
"receiverAddress": "-",
"receiverDetailAddress": "-",
"receiverJibunAddress": "-",
"receiverContact1": "-"
```

{% endcode %}

***

### (B) SMS로 링크 발송

나중 배송 입력 기능을 사용하기 위해서는 아래와 같이 서비스어드민에서 설정이 필요합니다.

1. **배송지 입력 URL 설정**
   * \[서비스어드민> 서비스관리> 쇼핑몰관리 - 해당 쇼핑몰정보] 최하단 '배송 설정' 영역에서 '배송지 입력 URL'을 설정하실 수 있습니다.
   * 배송지 입력 URL은 주문 후 배송지를 나중에 입력하는 페이지 URL로써, SMS 발송 시에 해당 URL이 포함되어 선물 받은 고객이 URL 링크를 클릭하여 배송지를 입력할 수 있습니다.

{% hint style="success" %}
\[예시]

배송지 입력 URL이 <http://shoppingmall.com/orders/shipping-info?code=abcd1234> 인 경우\
<http://shoppingmall.com/orders/shipping-info?code=${encryptedShippingNo}> 로 입력하세요.
{% endhint %}

2. **배송지 입력 안내 자동 SMS 설정**
   * \[운영관리> SMS관리(포인트)> 자동 SMS설정] 주문배송 관련 메세지 중 '배송지 입력 안내' 템플릿을 사용함으로 설정하시면 선물 받는 분에게 배송지 입력 링크가 SMS로 발송됩니다.
   * 참고: 2023-01-02부터 샵바이프리미엄의 SMS 발송 방식이,  SMS 포인트 과금하여 문자 발송할 수 있도록 변경되었습니다.\
     ![](/files/TOx52g4UibwFuMZc6sXI)<br>

{% hint style="warning" %}
\[주의사항]

주문 완료 후, 배송지가 입력되기 전까지는 주문상태 ‘배송보류’ 유지되는 점 참고 부탁드립니다.
{% endhint %}

***

### (C) 선물받는 사람이 주소 입력

1. **주소입력**
   * 문자 발송 페이지에 주소를 입력하면, 나중입력 배송지 수정API 를 호출하여 배송지를 등록합니다.

> **▶ 나중입력 배송지 수정하기**
>
> PUT /later-input/shippings [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/LaterShippingInput/put-later-input-shippings)
>
> 암호화된 배송번호(encryptedShippingNo)로 나중에 입력된 배송지 정보를 수정하는 API입니다.

* 배송지 나중 입력 시 입력된 주소가 ‘지역별 추가 배송비’가 발생하는 지역인 경우, 최종 배송지 입력되지 않는 점 참고 부탁드립니다.
* (참고) 암호화된 배송번호(encryptedShippingNo)는, 문자 발송 시 배송지 입력 URL 파라미터에 포함되므로 쉽게 확인가능합니다.

***

2. **활용할 수 있는 shop API**
   * 아래 API들을 활용하여 선물하기(배송지 나중입력) 기능을 활용한 화면을 구현할 수 있습니다.

> **▶ 지역별 추가 배송비 목록 조회하기**
>
> GET /later-input/areafees [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/LaterShippingInput/get-later-input-areafees)
>
> 배송비템플릿 번호(templateNo) 또는 암호화된 배송번호(encryptedShippingNo)로 지역별 추가 배송비 목록을 조회하는 API 입니다.

* 선물받는 사람의 주소 입력 혹은 변경 시점에, 선물하기 가능/불가 지역 여부를 노출하기 위해 사용하는 API입니다.
* 지역별 추가 배송비가 발생하여 선물하기 불가한 지역인 경우, "지역별추가배송비 변동이 발생하는 주소지로는 변경이 불가합니다." alert이 발생합니다.\
  (FE 프론트단에서 문구로 노출할지 여부는 고객사에서 판단하여 처리가능합니다)

***

> **▶ 배송지 나중입력 주문 상세 조회하기**
>
> GET /later-input/order [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/LaterShippingInput/get-order-encrypted-shipping-no-later-input)
>
> 암호화된 배송번호(encryptedShippingNo)로 주문상세정보를 조회하는 API입니다.

* 선물하기(나중 배송지) 입력 페이지에서 선물받게 되는 주문에 관련된 정보(ex. 상품 정보 등)을 노출하기 위해 사용합니다.

***

> **▶ 나중입력 배송지 조회하기**
>
> GET /later-input/shippings [**API 보기>**](https://docs.shopby.co.kr/?url.primaryName=order/#/LaterShippingInput/get-later-input-shippings)
>
> 암호화된 배송번호(encryptedShippingNo)로 나중에 입력된 배송지 정보를 조회하는 API입니다.

* 배송지가 이미 입력되어 있는지 여부를 파악할 때 사용할 수 있습니다.
* 선물받는 사람이 이미 주소를 입력한 뒤 다시 해당 페이지에 접속했을 경우, 기존 입력된 정보를 노출하고 수정하게 하거나, 혹은 이미 입력완료 되었다고 실패처리할 수 있습니다.


# \[엔터프라이즈] 카카오싱크 신청 가이드

샵바이 엔터프라이즈에 카카오싱크 간편 가입 기능 연동을 어떻게 할 수 있는지 안내하기 위한 콘텐츠입니다.

## 간단소개

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

***

## 카카오싱크 신청&설정 방법 <a href="#undefined" id="undefined"></a>

#### ① 카카오싱크 연동 전 참고 사항

* 카카오크를 연동하기 위해서는 서비스어드민(SA)내 필수 정보 설정이 필요합니다.

**\[카카오 싱크 설정 관련 메뉴]**

* 서비스 관리 > 기초정보 관리 (회사명, 대표자명, 사업자 등록번호, 업태, 주소)

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

* 서비스관리 > 쇼핑몰 관리 > 쇼핑몰 수정 (쇼핑몰 도메인 정보, SNS 간편 회원가입 로그인 URL 설정)
  * 최소 1개 이상 필수 저장 필요

    <figure><img src="/files/9zq6s16dK1UQMketJhnm" alt=""><figcaption></figcaption></figure>
  * 쇼핑몰 도메인 정보에 저장된 도메인과 동일한 Redirect URI을 입력해 주세요.
    * 예) 쇼핑몰 도메인 정보 > PC 웹 도메인 정보 저장 시 SNS 간편 회원가입 로그인 URL 설정 > PC 웹 Redirect URI 정보 저장 필요<br>

      <figure><img src="/files/UZfNFvso3eGOwN6p67mu" alt=""><figcaption></figcaption></figure>
  * 서비스관리> 약관/개인정보처리방침 관리
    * 이용약관<br>

      <figure><img src="/files/H1Zcjp5SBQfPT810si96" alt=""><figcaption></figcaption></figure>
    * 개인정보 수집/동의 항목
      * 회원가입 시 개인정보 수집/이용 항목\[필수/선택], 개인정보 처리/위탁, 개인정보 제3자 제공<br>

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

***

#### ② 카카오싱크 앱 설치 방법

* 서비스 관리 > 쇼핑몰 관리> 쇼핑몰 수정 > SNS 간편 회원가입 설정 항목에서 "카카오싱크 설치"버튼을 클릭합니다.

{% hint style="warning" %}
이미 카카오 간편가입(로그인)을 사용 중인 경우 카카오싱크 연동 완료 시 카카오 간편가입은 자동으로 비활성화 처리되며, 쇼핑몰 회원은 카카오싱크로만 가입/로그인이 가능합니다.
{% endhint %}

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

* 이용 동의 항목을 확인 후 "동의 및 앱 실행" 버튼을 클릭합니다.

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

***

#### ③ 카카오싱크 앱 설정 방법

* 1\) 카카오싱크 앱 설치 완료 후 "카카오싱크 설정" 버튼을 클릭합니다.

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

* 2\) 카카오싱크 설정 팝업이 출력되면, "카카오싱크 연동" 버튼을 클릭합니다.

<figure><img src="/files/8e94X5fdnt1SfBSQE0nt" alt=""><figcaption></figcaption></figure>

* 3\) 사용할 카카오 계정으로 로그인합니다.

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

* 4\) 안내문을 확인하신 후 "동의하고 계속" 버튼을 클릭하여 카카오싱크 간편 설정을 진행합니다.

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

* 5\) 기존에 등록되어 있는 디밸로퍼스 앱이 없는 경우 새로운 앱을 생성합니다.

{% hint style="info" %}

* 기존 카카오 간편가입(로그인)을 사용 중인 경우 기존에 사용하고 있는 디벨로퍼스 앱을 동일하게 사용해 주세요.

  다른 앱으로 연동을 진행할 경우 기존 카카오 간편가입(로그인) 회원은 로그인할 수 없으며, 신규 회원으로 가입 처리됩니다.
* 쇼핑몰 이전 시 반드시 테스트용 디밸로퍼스 앱을 생성하시어 사전 테스트 진행 부탁드립니다.\
  테스트 완료 시 회원 DB 마이그레이션 작업이 필요하며, 마이그레이션 작업 완료 후 이전 쇼핑몰에서 사용하고 있던 디밸로퍼스 앱을 연결합니다. (마이그레이션 별도 요청 필요)
  {% endhint %}

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

> **쇼핑몰 정보 항목**
>
> * 쇼핑몰 로고: 가이드에 맞는 쇼핑몰 로고 이미지를 등록합니다.
> * 쇼핑몰, 회사 이름: 서비스 어드민에 등록된 정보가 출력됩니다.

* 6\) 카카오싱크에 연결할 채널을 선택하거나, 신규 채널을 생성합니다.
  * 이미 생성된 채널을 연결하려면 해당 채널 선택 후 "다음"버튼을 클릭합니다.

<figure><img src="/files/4YLW0Edrq4dQ2UiAulxe" alt=""><figcaption></figcaption></figure>

* 7\) 카카오 간편 가입 동의 화면에 노출할 카카오톡 채널 정보를 입력합니다.

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

> **카카오톡 채널 정보 항목**
>
> * 프로필 사진: 가이드에 맞는 채널의 프로필 사진을 등록합니다.
> * 채널 이름: 서비스 어드민에 등록된 쇼핑몰 명이 출력됩니다.
> * 검색용 아이디: 쇼핑몰의 카카오톡 채널을 검색할 때 사용되는 쇼핑몰 채널의 고유 아이디입니다.\
>   (쇼핑몰 채널의 고유 아이디이기 때문에 동일 아이디 생성은 불가합니다.)
> * 카테고리: 쇼핑몰에 맞는 카테고리를 설정합니다.

* 8\) 설정하고자 하는 디밸로퍼스 앱과 카카오톡 채널 정보가 맞는지 확인 후 "완료" 버튼을 클릭합니다.

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

* 9\) 카카오싱크 설정을 완료합니다.

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

***

**④ 카카오싱크 설정 확인**

* 카카오싱크 설정 완료 시 Rest API Key 값이 자동으로 입력됩니다.

<figure><img src="/files/9JXQmkO4gVp8qAFPlWnA" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
카카오싱크 설정까지 완료하신 경우 쇼핑몰 화면에서 카카오싱크를 통해 간편가입이 가능합니다.
{% endhint %}


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

샵바이 엔터프라이즈의 카카오싱크 기능을 사용하기 위해, shop 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`로 변경되면 로그인 처리합니다.


# \[엔터프라이즈] 이니렌탈(렌탈결제) API 화면가이드

샵바이 엔터프라이즈의 이니렌탈(렌탈결제) 기능을 사용하기 위해, shop API로 화면을 어떻게 구현할 수 있을지 안내하기 위한 콘텐츠입니다.

### 01. 간단소개  <a href="#id-01.-ea-b0-84-eb-8b-a8-ec-86-8c-ea-b0-9c" id="id-01.-ea-b0-84-eb-8b-a8-ec-86-8c-ea-b0-9c"></a>

* 기능요약
  * 이니렌탈(렌탈결제) 기능: 고액의 상품을 분할 납부하는 구독결제 방식의 결제 서비스
    * 이니렌탈은 상품금액을 분할하여 납부할 수 있는 렌탈 결제 수단입니다. 이니렌탈로 구매한 상품은 약정한 월 납부금액이 완납되면 소유권이 고객에게 이전됩니다.
  * 대상 솔루션: 샵바이 엔터프라이즈 전용
  * 기능 배포일자:2022-11-16
* 기능상세
  * 이니렌탈 상품 어드민 등록 및 활용방법은 아래 공지사항 내 첨부파일을 참고해주시길 바랍니다
  * SA(서비스어드민): [공지사항 보기 >](https://service.shopby.co.kr/board/popup/notice/148?noticeTarget=PLATFORM_TO_SERVICE)
  * BPA(파트너어드민): [공지사항 보기 >](https://partner.shopby.co.kr/board/popup/notice/149?noticeTarget=PLATFORM_TO_PARTNER)
  * [<mark style="color:red;">**서비스 신청 바로가기 >**</mark>](https://apps.godo.co.kr/apps/1339)

※ 쇼핑몰에서 직접 PG사(이니렌탈)에 렌탈결제 관련 key를 요청해야하며, 해당 key값 존재여부에 따라 '렌탈결제 사용여부'가 자동으로 세팅됩니다.

* key값 존재 시: 렌탈결제 '사용함'처리\
  ㄴ Front > 상품 상세페이지 : 이니렌탈 구매안내(월납부금액, 렌탈기간) 영역 노출\
  ㄴ Front > 주문서 작성/결제 : 렌탈상품 주문 가능
* key값 미존재 시: 렌탈결제 '사용안함'처리\
  &#x20;ㄴFront > 상품 상세페이지 : 이니렌탈 구매안내 영역 미노출 (API 호출 없음)\
  ㄴ Front > 주문서 작성/결제에서 렌탈상품 주문 불가 (결제수단 선택 불가)

***

### 02. (예시) API소개 및 화면 가이드 <a href="#id-02.-ec-98-88-ec-8b-9c-api-ec-86-8c-ea-b0-9c-eb-b0-8f-ed-99-94-eb-a9-b4-ea-b0-80-ec-9d-b4-eb-93-9c" id="id-02.-ec-98-88-ec-8b-9c-api-ec-86-8c-ea-b0-9c-eb-b0-8f-ed-99-94-eb-a9-b4-ea-b0-80-ec-9d-b4-eb-93-9c"></a>

아래 API들을 활용하여 이니렌탈(렌탈결제) 기능을 활용한 화면을 구현할 수 있습니다.<br>

#### 1)  상품 상세페이지 화면  <a href="#id-1-ec-83-81-ed-92-88-ec-83-81-ec-84-b8-ed-8e-98-ec-9d-b4-ec-a7-80-ed-99-94-eb-a9-b4" id="id-1-ec-83-81-ed-92-88-ec-83-81-ec-84-b8-ed-8e-98-ec-9d-b4-ec-a7-80-ed-99-94-eb-a9-b4"></a>

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

① 렌탈료 조회

■ [옵션 조회하기 API](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-product-options) 확인하기

```
GET /products/{productNo}/options
해당 상품번호에 대한 옵션 정보를 조회하는 API입니다
```

\- ✔ 해당 API를 호출하여 상품 상세페이지 진입 시, 상품의 렌탈기간 및 월납부 금액을 출력할 수 있습니다. (단, 렌탈결제 사용안함의 경우, API가 호출되지 않습니다)\
&#x20; 응답값 내 `multiLevelOptions(분리형옵션)> children> rentalInfo` 또는 `flatOptions(일체형옵션) > rentalInfo` 필드값을 활용하실 수 있습니다.\
&#x20; 만약 옵션이 있을 경우, 옵션 선택 시점에 해당 API를 호출하여 렌탈기간 및 월납부 금액을 출력합니다.

\- 월 납부 금액이 가장 적은 순으로 노출됩니다.\
&#x20;  (ex) 해당 상품의 금액이 240만원이고 렌탈계약을 12개월/24개월로 진행한 경우 아래와 같이 노출됨.\
&#x20;  월 100,000원(24개월)\
&#x20;  월 200,000원(12개월)

\- ✔ 렌탈상품은 한 주문에 1가지 옵션만 구매 가능합니다. (2개이상의 옵션상품은 선택 불가)\
&#x20; 만약 이미 1개의 옵션이 선택된 경우, 쇼핑몰 고객이 옵션을 추가로 선택하려고할 시 "렌탈 상품은 옵션단위로 1개의 수량만 주문가능합니다"라는 알럿메시지가 출력되어야합니다.\
\- 구매자 작성형 옵션은 등록가능합니다.

\- 렌탈상품은 현재 장바구니 기능을 제공하지 않습니다.\
\- 네이버페이 결제버튼은 노출되지 않습니다.

② 구매수량\
\- 렌탈 상품은 구매수량 1개만 선택가능합니다.

③ 렌탈 주문 (버튼)\
\- 렌탈 상품인 경우 \[렌탈 주문] 버튼이 출력됩니다.\
\- 버튼 클릭 시, 유효성 검사를 진행하고 주문서 작성페이지로 이동합니다.  \
\- ✔해당 버튼 클릭 시, 만약 ②에서 구매수량이 2개 이상일 경우 "구매수량이 제한되었습니다"와 같은 알럿메시지 노출이 필요합니다. \
&#x20; 만약 필수 옵션을 선택하지 않은 경우 "옵션을 선택해주세요"와 같은 알럿 메시지 노출이 필요합니다.&#x20;

\- 해당 버튼 클릭 시, 아래 API를 통해 선택한 상품 옵션에 대한 주문서가 생성됩니다.

■ [주문서 작성하기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/post-order-sheet) 확인하기

```
POST /order-sheets
주문을 진행할 상품정보를 전달하는 API입니다. 주문서 화면으로 이동하기 전 단계에서 호출해야 합니다.
```

Request body 내 `products > rentalInfos(렌탈정보)` 필드값을 활용하실 수 있습니다.\
응답 값으로 획득한 `주문서 번호 orderSheetNo`를 아래 문단에서 소개드릴 주문서 화면으로 전달합니다.

***

#### 2)  주문서 화면  <a href="#id-2-ec-a3-bc-eb-ac-b8-ec-84-9c-ed-99-94-eb-a9-b4" id="id-2-ec-a3-bc-eb-ac-b8-ec-84-9c-ed-99-94-eb-a9-b4"></a>

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

#### ① 주문서 조회 <a href="#e2-91-a0-ec-a3-bc-eb-ac-b8-ec-84-9c-ec-a1-b0-ed-9a-8c" id="e2-91-a0-ec-a3-bc-eb-ac-b8-ec-84-9c-ec-a1-b0-ed-9a-8c"></a>

■ [주문서 조회하기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet) 확인하기

```
GET /order-sheets/{orderSheetNo}
주문서번호로 주문 상품정보를 조회하는 API입니다.
```

\- 앞서 POST /order-sheets 주문서 생성 요청 API를 통해 획득한 orderSheetNo(주문서 번호)에 해당하는 주문 상품 상세 정보를 호출합니다.\
&#x20; ✔ 주문서 화면 내 , 이니렌탈(렌탈결제) 관련 항목은 응답 값 내 `rentalInfos(렌탈정보)`를 통해 구현할 수 있습니다.

\- 렌탈상품 주문 시, '이니렌탈' 이외의 결제수단은 사용이 불가합니다.(이니렌탈 외 다른 결제수단은 미노출)\
\- 렌탈결제 사용안함(미설정) 상태인 경우, 결제수단 선택이 비활성화됩니다.\
\- 렌탈 상품 구매 시, 쿠폰 및 적립금은 사용이 불가능합니다. (단, 구매금액에 대한 적립금은 일반상품과 동일하게 적립됩니다)\
&#x20;&#x20;

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

#### ② 결제하기 (버튼) <a href="#e2-91-a1-ea-b2-b0-ec-a0-9c-ed-95-98-ea-b8-b0-eb-b2-84-ed-8a-bc" id="e2-91-a1-ea-b2-b0-ec-a0-9c-ed-95-98-ea-b8-b0-eb-b2-84-ed-8a-bc"></a>

■  [주문하기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve) 확인하기

```
POST /payments/reserve
결제를 진행하는 API입니다.
```

\- 결제하기 버튼 클릭 시, 입력정보 전체 유효성 검사가 진행 됩니다.\
&#x20;  ✔ 만약 렌탈결제 사용안함(미설정)상태인 경우, 결제수단이 비활성화되어 렌탈상품 주문이 불가하므로 "결제 수단을 선택해주세요"와 같은 알럿 메시지가 출력되어야합니다.

\- 유효성 검사 완료 시, 이니렌탈에서 제공하는 렌탈페이 모듈이 호출 됩니다. (아래 이미지 참고)\
&#x20;  ✔ 해당 API의 Request body 내 `rentalInfo(렌탈 상품 정보)` 필드값을 통해 월렌탈료 및 렌탈기간을 전달하게 됩니다.\
&#x20; &#x20;

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

\ <br>

#### 3)  주문완료 화면  <a href="#id-3-ec-a3-bc-eb-ac-b8-ec-99-84-eb-a3-8c-ed-99-94-eb-a9-b4" id="id-3-ec-a3-bc-eb-ac-b8-ec-99-84-eb-a3-8c-ed-99-94-eb-a9-b4"></a>

<br>

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

■  [주문상세 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/get-profile-orders-order-no) API확인하기

```
GET /profile/orders/{orderNo}
주문번호로 주문 상세 데이터를 조회하는 API입니다.
```

\- ✔응답값 내 `payInfo > rentalInfo(렌탈정보)` 필드 값을 통해, 위 샘플 화면과 같은 주문완료 화면을 구현할 수 있습니다.

<br>

#### 4)  마이페이지 화면  <a href="#id-4-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-ed-99-94-eb-a9-b4" id="id-4-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-ed-99-94-eb-a9-b4"></a>

\
■  [주문상세 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/get-profile-orders-order-no) API 확인하기

```
GET /profile/orders/{orderNo}
주문번호로 주문 상세 데이터를 조회하는 API입니다.
```

\- ✔ 주문완료 화면과 동일한 API 필드값 사용하여 화면을 구성할 수 있습니다.

\
\- ✔마이페이지> 주문/취소/반품 내역 화면에서, 결제된 상품이 렌탈상품인 경우 상품명 앞에 `(렌탈상품)`이 출력되어야합니다.&#x20;

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

\
\- 마이페이지> 주문/취소/반품 화면에서 주문번호 클릭 시 출력되는 화면에서\
&#x20; 렌탈상품인 경우, 위와 같은 렌탈주문 관련 클레임 안내문구가 출력됩니다. (이니렌탈 고객센터로 이관하여 문의할 수 있는 안내문구 <https://www.inicis.com/personal_contact>)

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

\- 렌탈 상품 주문건은, 교환신청이 불가합니다. \
&#x20; ✔ \[교환신청]버튼 클릭 시 "렌탈주문은 교환이 불가합니다. 이니렌탈 고객센터를 통해 문의해주시기 바랍니다. (1800-1739)" 와 같은 알럿메시지 출력이 필요합니다.&#x20;

\
\- 렌탈 상품 주문건은, 배송완료 8일이 경과하였을 경우 반품신청이 불가합니다.\
&#x20; ✔ 이 경우, \[반품신청] 버튼 클릭 시, "배송완료 8일이 경과한 렌탈주문은 이니렌탈 고객 센터를 통해 문의해주시기 바랍니다. (1800-1739)" 와 같은 알럿메시지 출력이 필요합니다.&#x20;

\
\
\- 렌탈상품 주문건은, 결제수단에 '렌탈결제'가 노출됩니다.

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


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

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


# Oauth2.0 용 가이드

{% hint style="info" %} <mark style="color:red;">**일부 API는 2024년 11월 6일(수) 업데이트 되었습니다.**</mark> [**\[공지보기\]**](https://www.nhn-commerce.com/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/#/OAUTH2/post-oauth2-openid-token)

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

<br>

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

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

<https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2/post-oauth2-openid-token> API 를 이용하여 고객사의 토큰을 이용해 샵바이 액세스토큰과 샵바이 리프레시토큰을 발급받을 수 있습니다.

* 회원 엑세스토큰의 기본 유효 기간은 30 분이며,
* 회원 리프레시 토큰의 기본 유효 기간은 1 일 입니다
* keepLogin을 true로 요청한 경우, 회원 리프레시 토큰의 기본 유효 기간은 90일 입니다.

해당 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 필드로도 같이 전달합니다.
  * 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/#/OAUTH2/post-oauth2-openid-token>) 의 응답으로 유효하지 않은 토큰일 경우에도 오류(400)로 응답합니다.&#x20;

***

### 3. 토큰 갱신 <a href="#ea-b8-b0-eb-b3-b8-flow" id="ea-b8-b0-eb-b3-b8-flow"></a>

▶ [ 토큰 갱신 API 바로가기](https://docs.shopby.co.kr/?url.primaryName=auth/#/OAUTH2/put-oauth2-token)

### 헤드리스

AccessToken 과 RefreshToken을 직접 관리 해주셔야합니다.

보안상의 이유로 AccessToken은 일정 시간 후에 만료되므로, 지속적인 서비스 이용을 위해 주기적으로 갱신해야 합니다.

새로운 AccessToken을 발급(갱신)받기 위해서는 기존 AccessToken 과 RefreshToken이 필수입니다.

따라서, 기존 AccessToken을 별도로 저장 및 관리하고 있어야합니다.

RefreshToken도 마찬가지 이유로 별도로 저장 및 관리해야합니다.

### 오로라 개별 스킨

[OAuth 2.0 적용 가이드](/aurora-guide/api/shopbyapi/oauth2.0)

### 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/delete-profile)

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

***

### 5. 휴면처리 <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>) 호출을 반드시 해주세요.

***

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


# \[엔터프라이즈] 외부 적립금 전환 가이드

샵바이 엔터프라이즈 외부 적립금 전환 가이드

적립금 기능은 쇼핑몰 회원의 적립금을 조회/지급/차감할 수 있는 기능입니다. <br>

고객사에서 별도의 적립금 혹은 마일리지등의 혜택을 사용하고 있는 경우, 샵바이의 적립금으로 전환하여 사용할 수 있는 기능을 제공합니다.&#x20;

업데이트 일자: 2022. 10. 07

<br>

**\[ 적립금 전환 ]**

기본 FLOW

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

(참고) 적립금을 전환하는 개념이므로,\
샵바이 쇼핑몰에 적립금이 지급되면, 고객사 입장에서는 적립금이 차감되는 개념입니다.

***

**1. 적립금 전환**

[▶](https://server-docs.shopby.co.kr/?urls.primaryName=manage#/Profile%20%3E%20Accumulations/create-accumulations-member)[ ](https://server-docs.shopby.co.kr/?urls.primaryName=manage#/Profile%20%3E%20Accumulations/create-accumulations-member)[적립금 즉시 지급 API 바로가기 ](https://server-docs.shopby.co.kr/?url.primaryName=manage/#/Accumulations/create-accumulations-member)

고객사에서 별도의 적립금 혹은 마일리지등의 혜택을 사용하고 있는 경우, 샵바이의 적립금으로 전환하여 사용할 수 있습니다.

▶ Request

| 항목                  | 타입                | 필수여부         | 설명                                                                 |
| ------------------- | ----------------- | ------------ | ------------------------------------------------------------------ |
| <p>memberNo<br></p> | <p>Number<br></p> | <p>O<br></p> | <p>샵바이 회원번호 (memberId와 배타적)</p><p>- 미입력 시, memberId 필수로 입력<br></p> |
| <p>memberId<br></p> | <p>String<br></p> | <p>O<br></p> | <p>쇼핑몰 회원이 가입한 id</p><p>- 미입력 시, memberNo 필수로 입력<br></p>           |
| accumulationAmt     | <p>Number<br></p> | X            | 적립금 지급 금액                                                          |
| expireYmd           | String            | X            | 적립금 유효기간                                                           |

**Example**

{% code overflow="wrap" %}

```
{"memberNo" : 1,"memberId" : "test","accumulationAmt" : 1000,"expireYmd" : null}
```

{% endcode %}

***

**2. 적립금 반환**

[▶](https://server-docs.shopby.co.kr/?urls.primaryName=manage#/Profile%20%3E%20Accumulations/create-accumulations-member)[ ](https://server-docs.shopby.co.kr/?urls.primaryName=manage#/Profile%20%3E%20Accumulations/create-accumulations-member)[적립금 즉시 차감 API 바로가기 ](https://server-docs.shopby.co.kr/?url.primaryName=manage/#/Accumulations/delete-accumulations-member)

▶ Query parameter

| 항목                  | 타입                | 필수여부         | 설명                                                             |
| ------------------- | ----------------- | ------------ | -------------------------------------------------------------- |
| <p>memberNo<br></p> | <p>Number<br></p> | <p>O<br></p> | <p>샵바이 회원번호 (memberId와 배타적)</p><p>- 미입력 시, memberId 필수로 입력</p> |
| <p>memberId<br></p> | <p>String<br></p> | <p>O<br></p> | <p>쇼핑몰 회원이 가입한 id</p><p>- 미입력 시, memberNo 필수로 입력<br></p>       |
| accumulationAmt     | <p>Number<br></p> | X            | 적립금 차감 금액                                                      |
| entireSubtracted    | String            | X            | <p>전체 적립금 차감 여부</p><p>true 인 경우 해당 회원의 모든 적립금을 삭제함.</p>        |

***

**3. 적립금 조회**

[▶](https://server-docs.shopby.co.kr/?urls.primaryName=manage#/Profile%20%3E%20Accumulations/create-accumulations-member)[ ](https://server-docs.shopby.co.kr/?urls.primaryName=manage#/Profile%20%3E%20Accumulations/create-accumulations-member)[적립금 즉시 조회 API 바로가기 ](https://server-docs.shopby.co.kr/?url.primaryName=manage/#/Accumulations/get-accumulations-by-member)

▶ Query parameter

| 항목                          | 타입                | 필수여부         | 설명                                                                 |
| --------------------------- | ----------------- | ------------ | ------------------------------------------------------------------ |
| <p>memberNo<br></p>         | <p>Number<br></p> | O            | <p>샵바이 회원번호 (memberId와 배타적)</p><p>- 미입력 시, memberId 필수로 입력<br></p> |
| memberId                    | <p>String<br></p> | <p>O<br></p> | <p>쇼핑몰 회원이 가입한 id</p><p>- 미입력 시, memberNo 필수로 입력<br></p>           |
| <p>accumulationAmt<br></p>  | <p>Number<br></p> | <p>X<br></p> | <p>적립금 차감 금액<br></p>                                               |
| <p>entireSubtracted<br></p> | <p>String<br></p> | <p>X<br></p> | <p>전체 적립금 차감 여부</p><p>true인 경우 해당 회원의 모든 적립금을 삭제함.</p>             |
| <p>page<br></p>             | <p>Number<br></p> | <p>X<br></p> | <p>페이지 번호<br></p>                                                  |
| <p>pageSize<br></p>         | <p>Number<br></p> | X            | 한 페이지당 데이터 건수                                                      |
| <p>startYmd<br></p>         | <p>String<br></p> | X            | 시작일                                                                |
| <p>endYmd<br></p>           | String            | X            | 종료일                                                                |


# \[엔터프라이즈] 외부 적립금 연동가이드

## 외부 적립금이란? <a href="#ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-9d-b4-eb-9e-80-3f" id="ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-9d-b4-eb-9e-80-3f"></a>

#### 샵바이에 입점하고자하는 고객사에서 별도의 적립금(마일리지) 혜택을 이미 가지고 있는 경우, <a href="#ec-83-b5-eb-b0-94-ec-9d-b4-ec-97-90-ec-9e-85-ec-a0-90-ed-95-98-ea-b3-a0-ec-9e-90-ed-95-98-eb-8a-94-e" id="ec-83-b5-eb-b0-94-ec-9d-b4-ec-97-90-ec-9e-85-ec-a0-90-ed-95-98-ea-b3-a0-ec-9e-90-ed-95-98-eb-8a-94-e"></a>

고객사에서 진행할 수 있는 2가지 외부 적립금 호환 방식이 있습니다.

<br>

### (방법1) 외부 적립금 전환 <a href="#eb-b0-a9-eb-b2-951-ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-84-ed-99-98" id="eb-b0-a9-eb-b2-951-ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-84-ed-99-98"></a>

#### 개념 <a href="#ea-b0-9c-eb-85-90" id="ea-b0-9c-eb-85-90"></a>

고객사 시스템의 적립금을 샵바이 시스템의 적립금으로 '전환'하여, 샵바이 내부 프로세스에 따라 쇼핑몰 고객의 적립금을 지급/차감/조회할 수 있는 개념입니다.\ <br>

#### 상세설명 <a href="#ec-83-81-ec-84-b8-ec-84-a4-eb-aa-85" id="ec-83-81-ec-84-b8-ec-84-a4-eb-aa-85"></a>

샵바이에서는 이와 관련된 server API를 제공하고 있으며, 해당 API의 호출 주체는 고객사입니다.\
쇼핑몰 고객들이 기존의 적립금을 샵바이의 적립금으로 전환할 수 있는 프론트 구현이 필요합니다.\
자세한 API 내용은 [외부 적립금 전환 가이드](https://workspace.nhn-commerce.com/support/recommendedContents/23047)를 참고하시길 바랍니다.<br>

***

### (방법2) 외부 적립금 연동 <a href="#eb-b0-a9-eb-b2-952-ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-97-b0-eb-8f-99" id="eb-b0-a9-eb-b2-952-ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-97-b0-eb-8f-99"></a>

본 문서에서 아래 소개 드릴 방식입니다.<br>

#### 개념 <a href="#ea-b0-9c-eb-85-90" id="ea-b0-9c-eb-85-90"></a>

고객사에서 기존에 사용하던 적립금(마일리지)를 전환 절차 없이 그대로 사용할 수 있고, 샵바이에서 고객사의 외부적립금을 연동하는 개념입니다.

#### 상세설명 <a href="#ec-83-81-ec-84-b8-ec-84-a4-eb-aa-85" id="ec-83-81-ec-84-b8-ec-84-a4-eb-aa-85"></a>

고객사에서 아래에서 안내드릴 스펙에 따라 API를 개발하여 저희 측으로 uri 등을 전달주시면, 해당 API의 호출 주체는 저희 샵바이입니다.\
(ex) 적립금 조회 시, 샵바이에서 고객사에서 개발한 API를 호출하여 고객사의 DB를 조회합니다.\ <br>

#### 주의사항 <a href="#ec-a3-bc-ec-9d-98-ec-82-ac-ed-95-a-d" id="ec-a3-bc-ec-9d-98-ec-82-ac-ed-95-a-d"></a>

※ 단, 샵바이에서 API 호출 시, 고객사 서버에서 바로 응답되지 않는 성능 이슈가 발생하지 않도록 신경 써주시길 바랍니다.\
※ 적립금이 중복으로 지급될 수 있는 케이스에 대해 확인하시길 바랍니다. (아래 적립금 지급API '제약조건' 문단 확인)\ <br>

#### 연동 프로세스 <a href="#ec-97-b0-eb-8f-99-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a4" id="ec-97-b0-eb-8f-99-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a4"></a>

* step 1. 아래 안내드릴 API 스펙에 따라 고객사에서 API 개발
* step 2. \[NHN커머스> 고객센터> 1:1문의]를 통해 아래 정보들을 세팅요청 해주시길 바랍니다.  [1:1문의 바로가기>](https://support.nhn-commerce.com/inquiry/list)<br>

| 항목                                 | 샘플 (예시)                                           | 설명                                                     |
| ---------------------------------- | ------------------------------------------------- | ------------------------------------------------------ |
| domain                             | [https://sample-dev.com](https://sample-dev.com/) | 외부 개발사는 개발된 도메인 https 으로 제공해야 함                        |
| 1. 적립금 지급 uri                      | /accumulations/add                                | 필수                                                     |
| 2. 적립금 차감 uri                      | /accumulations/subtract                           | 필수                                                     |
| 3. 적립금 차감 롤백 uri                   | /accumulations/subtract-rollback                  | 필수                                                     |
| 4. 사용가능 적립금 조회 uri                 | /accumulations/available-amounts                  | 필수                                                     |
| 5. 적립금 내역 조회 uri                   | /accumulations                                    | (선택)                                                   |
| 필요한 header 값                       | token : 'abc'                                     | 샵바이 -> 외부 개발사 요청 시, 인증을 위해서 필요한 http request header의 값 |
| <p>(추가)</p><p>memberMappingKey</p> | MEMBER\_ID(default), MEMBER\_NO, CI               | 맴버 맵핑 키                                                |

* step 3. 아래 NHN커머스 샵바이 ACL 추가바랍니다.
  * 리얼 환경: 103.194.111.5, 115.89.203.145
* 2024-08-26 memberMappingKey 항목 추가되었습니다.<br>
* 샘플(예시)

```json
{
    "url": "https://sample-dev.com",
    "headers": {
        "Content-Type": "application/json"
    },
    "memberMappingKey": "MEMBER_NO",
    "externalAccumulationUriGroup": {
        "addUri": "/accumulations/add",
        "searchUri": "/accumulations",
        "subtractUri": "/accumulations/subtract",
        "subtractRollbackUri": "/accumulations/subtract-rollback",
        "getAvailableAmountUri": "/accumulations/available-amounts"
    }
}
```

***

## 적립금 적립/차감/롤백 다이어그램 <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-81-eb-a6-bd-2f-ec-b0-a8-ea-b0-90-2f-eb-a1-a4-eb-b0-b1-eb-8b-a4-ec-9" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-81-eb-a6-bd-2f-ec-b0-a8-ea-b0-90-2f-eb-a1-a4-eb-b0-b1-eb-8b-a4-ec-9"></a>

### 적립금 적립 프로세스 <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-81-eb-a6-bd-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a4" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-81-eb-a6-bd-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a4"></a>

<figure><img src="/files/8mhwKZujYFYo6naSN9pR" alt=""><figcaption></figcaption></figure>

***

### 적립금 차감/ 롤백 프로세스 <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-2f-eb-a1-a4-eb-b0-b1-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-2f-eb-a1-a4-eb-b0-b1-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a"></a>

<figure><img src="/files/6FqrLmz024OgUUM8xT4K" alt=""><figcaption></figcaption></figure>

***

## 1. 적립금 지급 (필수) <a href="#id-1.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a7-80-ea-b8-89-ed-95-84-ec-88-98" id="id-1.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a7-80-ea-b8-89-ed-95-84-ec-88-98"></a>

### 적립금 지급 API (개발 스펙 안내) <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-a7-80-ea-b8-89-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e-99-ec-95-88-eb-82" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-a7-80-ea-b8-89-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e-99-ec-95-88-eb-82"></a>

{% hint style="info" %}

* request 는 request body 로 전달
* 형태는 json
  {% endhint %}

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* POST

#### ■ request    <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

<table><thead><tr><th>attribute</th><th>name</th><th width="76.3685302734375">required</th><th>description</th><th>type</th></tr></thead><tbody><tr><td>memberKey</td><td>회원 연계 키</td><td>필수</td><td><p>연동시 사용한 유형의 값<br></p><p>(MEMBER_ID,MEMBER_NO,CI)</p></td><td>String</td></tr><tr><td>amount</td><td>적립금액</td><td>필수</td><td>적립금</td><td>Long</td></tr><tr><td>reason</td><td>적립 세부내역 사유</td><td>필수</td><td></td><td>String</td></tr><tr><td>reasonType</td><td>적립금 지급 사유</td><td>필수</td><td>enum 형식</td><td>String</td></tr><tr><td>expiredDateTime</td><td>적립금 만료일</td><td>필수</td><td></td><td>LocalDateTime : 'yyyy-MM-dd HH:mm:ss'</td></tr><tr><td>mappingKey</td><td>적립키</td><td>필수</td><td><p>롤백용으로 <br>사용하는 값</p><p></p><p>주문번호, 리뷰번호, 주문옵션 번호 또는 "0" 으로 전달</p></td><td>String</td></tr><tr><td>(추가) additionalMappingKey.orderNo<br></td><td>추가정보<br>(연관 주문번호)</td><td>선택</td><td>추가 연동키</td><td>Int(nullable)</td></tr><tr><td>(추가) additionalMappingKey.reviewNo<br></td><td>추가정보<br>(연관 상품리뷰번호)</td><td>선택</td><td>추가 연동키</td><td>Int(nullable)</td></tr><tr><td>(추가) additionalMappingKey.orderOptionNo</td><td>추가정보<br>(연관 주문옵션번호)</td><td>선택</td><td>추가 연동키 </td><td>Int(nullable)</td></tr><tr><td>requestId</td><td>멱등성 키</td><td>필수</td><td>동일한 값으로 재요청 시, 중복 처리하지 않고 정상 응답 변환 필요. </td><td>String</td></tr></tbody></table>

* 2023-07-24 reasonType 항목 추가되었습니다.&#x20;
* 2024-01-24 additionalMappingKey.orderNo, additionalMappingKey.reviewNo,additionalMappingKey.orderOptionNo 항목 추가됩니다. (2/20 배포완료)
* 2026-07-01 requestId 항목이 추가되었습니다.

#### ※ reasonType 코드 값 설명 <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

* 적립 - 적립 - 상품 주문 적립 (구매확정)\
  ADD\_AFTER\_PAYMENT
* 적립 - 적립 - 교환/추가결제 적립 (교환대상 가격 > 원주문 상품가격)\
  ADD\_AFTER\_REPLACE\_PAYMENT
* 적립 - 사이트 활동 적립 - 상품평 작성 완료\
  ADD\_POSTING
* 적립 - 수동적립\
  ADD\_MANUAL
* 적립 - 회원가입시 자동 적립\
  ADD\_SIGNUP
* 적립 - 생일축하 적립\
  ADD\_BIRTHDAY
* 적립 - 회원등급 적립\
  ADD\_GRADE
* 적립 - 등급 혜택 즉시 지급\
  ADD\_GRADE\_BENEFIT

***

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

#### 성공인 경우 <a href="#ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

| attribute | name   | required | description | type   |
| --------- | ------ | -------- | ----------- | ------ |
| no        | 지급 key | 필수       | 적립 연계키      | String |

#### 실패인 경우 <a href="#ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 400 으로 전달
* 보통의 경우 errorMessage로 전달된 실패사유를 사용자에게 노출하거나 로그로 남깁니다.
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

```json
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}
```

### 제약조건 <a href="#ec-a0-9c-ec-95-bd-ec-a1-b0-ea-b1-b4" id="ec-a0-9c-ec-95-bd-ec-a1-b0-ea-b1-b4"></a>

※ `생일자 적립금 지급`, `등급 적립금 지급` 정기 지급 시, 일 배치(daily batch)로 적립금을 지급합니다.\
단, 해당 정기지급은 `mappingKey`가 0으로 등록되어 있어 외부적립금 사용 시 중복 지급될 수 있습니다.

만약 '[적립금 전환 방식](https://shopby.works/support/recommendedContents/23047)'으로 NHN커머스 샵바이의 적립금을 사용할 경우,  적립금 지급 번호와 사유를 내부 코드로 관리하여 중복지급을 제외할 수 있으나\
본 문서에서 안내드리는 '외부 적립금 연동 방식' 을 사용할 경우, 지급코드를 별도로 관리하지 않기 때문에 중복 지급 될 수 있습니다.

(예시) 중복지급 될 수 있는 케이스\
&#x20;: \[고객이 1/1을 생일로 등록]-> \[1/1 일 배치를 통해 생일 적립금 지급]-> \[1/2에 고객이 생일을 1/3으로 변경]-> \[1/3 일 배치에서 생일 적립금 중복 지급]\ <br>

### 참고사항 <a href="#ec-b0-b8-ea-b3-a0-ec-82-ac-ed-95-a-d" id="ec-b0-b8-ea-b3-a0-ec-82-ac-ed-95-a-d"></a>

`적립금 차감 API` 및 `적립금 차감 롤백 API`는 존재하나,\
`적립금 적립 API`에 대한 `적립금 적립 롤백 API` 는 제공하지 않는 점 참고부탁드립니다.

따라서 이미 적립된 적립금을 차감하기 위해서는, 아래 문서에서 소개 드릴 `적립금 차감 API`를 개발하시길 바랍니다.

***

## 2. 적립금 차감 (필수) <a href="#id-2.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-ed-95-84-ec-88-98" id="id-2.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-ed-95-84-ec-88-98"></a>

### 적립금 차감 API (개발 스펙 안내) <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e-99-ec-95-88-eb-82" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e-99-ec-95-88-eb-82"></a>

{% hint style="info" %}

* request 는 request body 로 전달
* 형태는 json
  {% endhint %}

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* POST

#### ■ request <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

| attribute                          | name                       | required | description                                                       | type             |
| ---------------------------------- | -------------------------- | -------- | ----------------------------------------------------------------- | ---------------- |
| memberKey                          | 회원 연계 키                    | 필수       | <p>연동시 사용한 유형의 값<br></p><p>(MEMBER\_ID,MEMBER\_NO,CI)</p>         | String           |
| amount                             | 차감금액                       | 필수       | 적립금                                                               | Long ( 양수 )      |
| reason                             | 차감 사유                      | 필수       |                                                                   | String           |
| <p>reasonType<br></p>              | 직립금 차감 사유                  | 필수       | <p>enum 형식<br></p>                                                | String           |
| mappingKey                         | 차감키                        | 필수       | <p>롤백용으로 사용하는 값</p><p></p><p>주문번호, 리뷰번호, 주문옵션 번호 또는 "0" 으로 전달</p> | String           |
| additionalMappingKey.orderNo       | <p>추가정보<br>(연관 주문번호)</p>   | 선택       | 롤백용\*                                                             | Int(nullable)    |
| additionalMappingKey.reviewNo      | <p>추가정보<br>(연관 상품리뷰번호)</p> | 선택       | 롤백용\*                                                             | Int(nullable)    |
| additionalMappingKey.orderOptionNo | <p>추가정보<br>(연관 주문옵션번호)</p> | 선택       | 롤백용\*                                                             | Int(nullable)    |
| (추가) orderExtraData                | 주문추가정보(JsonString)         | 선택       | 주문 예약단계에서 shop api(url링크)에서 입력한 ExtraData를 그대로 바이패스               | String(nullable) |
| requestId                          | 멱등성 키                      | 필수       | 동일한 값으로 재요청 시, 중복 처리하지 않고 정상 응답 변환 필요                             | String           |

* 참고사항 (\*)\
  구매확정 후 반품 시, 이미 지급된 적립금 정보 확인을 위해 `적립금 차감 API`의 request 항목이 위와 같이 추가되었습니다.\
  외부적립금 연동 방식을 사용 중인 고객사의 경우, 새로 추가된 데이터에 대응 가능한 구조로 변경하시길 바랍니다.
* 2023-08-10 reasonType 항목 업데이트 되었습니다.&#x20;
* 2024-02-20 request > orderExtraData 항목이 신규 추가됩니다.&#x20;
* 2026-07-01 requestId 항목이 추가되었습니다.

#### ※ reasonType 코드 값 설명 <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

* 차감 - 사용 - 상품 주문 시 적립금 사용 (결제완료)\
  SUB\_PAYMENT\_USED
* 차감 - 사용 - 교환상품 추가 결제 시 적립금 사용 (추가결제 완료)\
  SUB\_EXTRA\_PAYMENT\_USED
* 차감 - 적립취소 - 상품평 삭제\
  SUB\_DELETE\_POSTING
* 차감 - 수동차감\
  SUB\_MANUAL\
  \ <br>
* 샘플 (예시)

{% code overflow="wrap" %}

```json
{
  "amount": 100,
  "reason": "테스트 차감",
  "memberKey": "test@abc.com",
  "mappingKey": "2022080117000000001",
  "additionalMappingKey": {
    "orderNo": "2022080117000000001",
    "reviewNo": "3",
    "orderOptionNo": "2"
  },
  "requestId": "subtract-test@abc.com-ORDER-202607021100123456"
}
```

{% endcode %}

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

성공인 경우

| attribute | name         | required | description | type   |
| --------- | ------------ | -------- | ----------- | ------ |
| no        | 차감롤백을 위한 key | 필수       | 연계키         | String |

***

## 3. 적립금 차감 롤백 (필수) <a href="#id-3.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-ec-84-a0-ed-83-9d" id="id-3.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-ec-84-a0-ed-83-9d"></a>

### 적립금 차감 롤백 API (개발 스펙 안내) <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e"></a>

{% hint style="info" %}

* request 는 request body 로 전달
* 형태는 json
* 불가능한 경우 적립으로 처리 ( <mark style="background-color:red;">※ 이 경우 적립금 유효기간은 유지되지 않음</mark> )
  {% endhint %}

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* POST

#### ■ request <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

| attribute     | name                                    | required | description                                                   | type          |
| ------------- | --------------------------------------- | -------- | ------------------------------------------------------------- | ------------- |
| no            | 차감 롤백을 위한 key                           | 필수       | <p>차감 시, 받은 response.no 값<br>전달<br></p><p>없는경우<br>주문번호 전달</p> | String        |
| mappingKey    | 차감롤백을 위한 mapping key                    | 필수       | <p>취소된 <br>주문번호 전달</p>                                        | String        |
| amount        | <p>취소금액  <br>(롤백금액)</p>                 | 필수       |                                                               | Int           |
| reason        | 롤백 사유                                   | 필수       |                                                               | String        |
| lastSubPayAmt | 남은 적립금                                  | 선택       | <p>부분 취소 시, <br>남은 적립금액</p>                                   | Int(nullable) |
| memberKey     | 연동시 사용한 유형의 값(MEMBER\_ID,MEMBER\_NO,CI) |          |                                                               | String        |
| requestId     | 멱등성 키                                   | 필수       | 동일한 값으로 재요청 시, 중복 처리하지 않고 정상 응답 변환 필요                         | String        |

* 2024-08-26 lastSubPayAmt 항목이 추가되었습니다.
* 2026-07-01 requestId 항목이 추가되었습니다.

{% hint style="success" %} <mark style="color:red;">**롤백 케이스 별 amount, lastSubPayAmt 예시**</mark>

* **case1. 전체 취소 시**
  * amount: 1,000
  * lastSubPayAmt: 1,000
* **case2. 100 point 부분 취소 시**
  * amount: 100
  * lastSubPayAmt: 1,000
    {% endhint %}

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

#### 성공인 경우 <a href="#ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 200

#### 실패인 경우 <a href="#ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 400
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

{% code overflow="wrap" %}

```json
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}

```

{% endcode %}

***

## 4. 사용가능 적립금 조회 (필수) <a href="#id-3.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-ec-84-a0-ed-83-9d" id="id-3.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-ec-84-a0-ed-83-9d"></a>

### 사용가능 적립금 조회 API (개발 스펙 안내) <a href="#ec-82-ac-ec-9a-a9-ea-b0-80-eb-8a-a5-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a1-b0-ed-9a-8c-api-ea-b0-9c-eb-b0" id="ec-82-ac-ec-9a-a9-ea-b0-80-eb-8a-a5-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a1-b0-ed-9a-8c-api-ea-b0-9c-eb-b0"></a>

{% hint style="info" %}

* request 는 request param으로 전달
* response 형태는 json
  {% endhint %}

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* GET

#### ■ request (parameter) <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

| attribute       | name                           | required | description                                               | type                                          |
| --------------- | ------------------------------ | -------- | --------------------------------------------------------- | --------------------------------------------- |
| memberKey       | 회원 연계 키                        | 필수       | <p>연동시 사용한 유형의 값<br></p><p>(MEMBER\_ID,MEMBER\_NO,CI)</p> | String                                        |
| expireStartYmdt | 만료조회 시작일(디폴트 : 오늘 - 30일)       | 선택       |                                                           | LocalDateTime(format : 'yyyy-MM-dd HH:mm:ss') |
| expireEndYmdt   | <p>만료조회 종료일 <br>(디폴트 : 오늘)</p> | 선택       |                                                           | LocalDateTime(format : 'yyyy-MM-dd HH:mm:ss') |

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

#### 성공인 경우 <a href="#ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

| attribute     | name         | required | description                                                                                                        | type           |
| ------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------ | -------------- |
| amount        | 사용 가능한 총 적립금 | 필수       |                                                                                                                    | Long           |
| expiresAmount | 만료예정 적립금     | 선택       | <p>조회기간(expireStartYmdt \~ expireEndYmdt) <br>동안 만료될 금액<br><br>(만료일이 expireStartYmdt보다 크고, expireEndYmdt보다 작음)</p> | Long(nullable) |

#### 실패인 경우 <a href="#ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 400
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

```json
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}
```

***

## 5. 적립금 내역 조회 (선택) <a href="#id-5.-ec-a0-81-eb-a6-bd-ea-b8-88-eb-82-b4-ec-97-a-d-ec-a1-b0-ed-9a-8c-ec-84-a0-ed-83-9d" id="id-5.-ec-a0-81-eb-a6-bd-ea-b8-88-eb-82-b4-ec-97-a-d-ec-a1-b0-ed-9a-8c-ec-84-a0-ed-83-9d"></a>

### 적립금 내역 조회 API (개발 스펙 안내) <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-eb-82-b4-ec-97-a-d-ec-a1-b0-ed-9a-8c-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e" id="ec-a0-81-eb-a6-bd-ea-b8-88-eb-82-b4-ec-97-a-d-ec-a1-b0-ed-9a-8c-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e"></a>

{% hint style="info" %}

* request 는 request param으로 전달
* response 형태는 json
  {% endhint %}

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* GET

#### ■ request (parameter) <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

| attribute     | name         | required | description                                                    | type                                          |
| ------------- | ------------ | -------- | -------------------------------------------------------------- | --------------------------------------------- |
| startDateTime | 검색 시작일       | 필수       |                                                                | LocalDateTime(format : 'yyyy-MM-dd HH:mm:ss') |
| endDateTime   | 검색 종료일       | 필수       |                                                                | LocalDateTime(format : 'yyyy-MM-dd HH:mm:ss') |
| searchType    | 검색 유형        | 필수       | 지급일 기준(REGISTERED),만료일 기준(EXPIRED)                             |                                               |
| type          | 검색 조건(지급/차감) | 선택       | <p>전체("null") - default, <br>지급("ADD"), <br>차감("SUBTRACT")</p> | String                                        |
| memberKey     | 회원 연계 키      | 선택       | null 이면 전체                                                     | String(nullable)                              |
| page          | 페이지 번호       | 필수       | 조회할 페이징 번호 (default 0)                                         |                                               |
| size          | 페이지 사이즈      | 필수       | <p>페이지당 조회할 content 개수 <br>( default 100 )</p>                 |                                               |

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

#### 성공인 경우 <a href="#ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

| attribute-level1 | attribute-level2 | name                           | required | description                  | type                                          |
| ---------------- | ---------------- | ------------------------------ | -------- | ---------------------------- | --------------------------------------------- |
| totalCount       | -                | <p>전체 데이터<br>건수</p>            | 선택       |                              | Int                                           |
| contents         | no               | 적립금 번호                         | 필수       | PK                           | Int                                           |
| contents         | memberKey        | 회원 연계 키                        | 필수       | 연계키                          | String                                        |
| contents         | type             | <p>지급/차감/<br>지급롤백/<br>차감롤백</p> | 필수       | 적립금                          | String                                        |
| contents         | amount           | 적립금액                           | 필수       | 적립금                          | Long                                          |
| contents         | reason           | 사유                             | 필수       |                              | String                                        |
| contents         | registerDateTime | 등록일                            | 필수       |                              | LocalDateTime(format : 'yyyy-MM-dd HH:mm:ss') |
| contents         | expiredDateTime  | 적립금만료일                         | 필수       |                              | LocalDateTime(format : 'yyyy-MM-dd HH:mm:ss') |
| contents         | mappingKey       | 적립키                            | 필수       | 롤백용                          | String(nullable)                              |
| contents         | totalAmount      | 적립/차감시점 잔여 적립금                 | 선택       |                              | Long(nullable)                                |
| contents         | extraData        | 추가 정보                          | 선택       | json 형태로 front에 추가적으로 노출할 정보 | Map\<String,Object> (nullable)                |

* 샘플(예시)

{% code overflow="wrap" %}

```json
{
  "totalCount" : 15,
  "contents" : [
     {
       "no" : "1",
        "memberKey" : "abc",
        "type" : "지급",
        "amount" : 100,
        "reason" : "상품평 작성 적립",
        "registerDateTime" : "2021-01-01 13:12:30",
        "expiredDateTime" : "2022-01-01 13:12:30",
        "mappingKey" : "20210501123456123",
        "totalAmount" : 1200,
        "extraData" : {
             "a" : "b",
             "C" : "D"
         }
     }
  ]
}
```

{% endcode %}

#### 실패인 경우 <a href="#ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 400
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

{% code overflow="wrap" %}

```json
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}
```

{% endcode %}


# Copy of \[프리미엄] 외부 적립금 연동가이드

## 외부 적립금이란? <a href="#ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-9d-b4-eb-9e-80-3f" id="ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-9d-b4-eb-9e-80-3f"></a>

#### 샵바이에 입점하고자하는 고객사에서 별도의 적립금(마일리지) 혜택을 이미 가지고 있는 경우, <a href="#ec-83-b5-eb-b0-94-ec-9d-b4-ec-97-90-ec-9e-85-ec-a0-90-ed-95-98-ea-b3-a0-ec-9e-90-ed-95-98-eb-8a-94-e" id="ec-83-b5-eb-b0-94-ec-9d-b4-ec-97-90-ec-9e-85-ec-a0-90-ed-95-98-ea-b3-a0-ec-9e-90-ed-95-98-eb-8a-94-e"></a>

고객사에서 진행할 수 있는 2가지 외부 적립금 호환 방식이 있습니다.

<br>

### (방법1) 외부 적립금 전환 <a href="#eb-b0-a9-eb-b2-951-ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-84-ed-99-98" id="eb-b0-a9-eb-b2-951-ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-84-ed-99-98"></a>

#### 개념 <a href="#ea-b0-9c-eb-85-90" id="ea-b0-9c-eb-85-90"></a>

고객사 시스템의 적립금을 샵바이 시스템의 적립금으로 '전환'하여, 샵바이 내부 프로세스에 따라 쇼핑몰 고객의 적립금을 지급/차감/조회할 수 있는 개념입니다.\ <br>

#### 상세설명 <a href="#ec-83-81-ec-84-b8-ec-84-a4-eb-aa-85" id="ec-83-81-ec-84-b8-ec-84-a4-eb-aa-85"></a>

샵바이에서는 이와 관련된 server API를 제공하고 있으며, 해당 API의 호출 주체는 고객사입니다.\
쇼핑몰 고객들이 기존의 적립금을 샵바이의 적립금으로 전환할 수 있는 프론트 구현이 필요합니다.\
자세한 API 내용은 [외부 적립금 전환 가이드](https://workspace.nhn-commerce.com/support/recommendedContents/23047)를 참고하시길 바랍니다.<br>

***

### (방법2) 외부 적립금 연동 <a href="#eb-b0-a9-eb-b2-952-ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-97-b0-eb-8f-99" id="eb-b0-a9-eb-b2-952-ec-99-b8-eb-b6-80-ec-a0-81-eb-a6-bd-ea-b8-88-ec-97-b0-eb-8f-99"></a>

본 문서에서 아래 소개 드릴 방식입니다.<br>

#### 개념 <a href="#ea-b0-9c-eb-85-90" id="ea-b0-9c-eb-85-90"></a>

고객사에서 기존에 사용하던 적립금(마일리지)를 전환 절차 없이 그대로 사용할 수 있고, 샵바이에서 고객사의 외부적립금을 연동하는 개념입니다.

#### 상세설명 <a href="#ec-83-81-ec-84-b8-ec-84-a4-eb-aa-85" id="ec-83-81-ec-84-b8-ec-84-a4-eb-aa-85"></a>

고객사에서 아래에서 안내드릴 스펙에 따라 API를 개발하여 저희 측으로 uri 등을 전달주시면, 해당 API의 호출 주체는 저희 샵바이입니다.\
(ex) 적립금 조회 시, 샵바이에서 고객사에서 개발한 API를 호출하여 고객사의 DB를 조회합니다.\ <br>

#### 주의사항 <a href="#ec-a3-bc-ec-9d-98-ec-82-ac-ed-95-a-d" id="ec-a3-bc-ec-9d-98-ec-82-ac-ed-95-a-d"></a>

※ 단, 샵바이에서 API 호출 시, 고객사 서버에서 바로 응답되지 않는 성능 이슈가 발생하지 않도록 신경 써주시길 바랍니다.\
※ 적립금이 중복으로 지급될 수 있는 케이스에 대해 확인하시길 바랍니다. (아래 적립금 지급API '제약조건' 문단 확인)\ <br>

#### 연동 프로세스 <a href="#ec-97-b0-eb-8f-99-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a4" id="ec-97-b0-eb-8f-99-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a4"></a>

* step 1. 아래 안내드릴 API 스펙에 따라 고객사에서 API 개발
* step 2. \[NHN커머스> 고객센터> 1:1문의]를 통해 아래 정보들을 세팅요청 해주시길 바랍니다.  [1:1문의 바로가기>](https://support.nhn-commerce.com/inquiry/list)<br>

| 항목                                 | 샘플 (예시)                                           | 설명                                                     |
| ---------------------------------- | ------------------------------------------------- | ------------------------------------------------------ |
| domain                             | [https://sample-dev.com](https://sample-dev.com/) | 외부 개발사는 개발된 도메인 https 으로 제공해야 함                        |
| 1. 적립금 지급 uri                      | /accumulations/add                                | 필수                                                     |
| 2. 적립금 차감 uri                      | /accumulations/subtract                           | 필수                                                     |
| 3. 적립금 차감 롤백 uri                   | /accumulations/subtract-rollback                  | 필수                                                     |
| 4. 사용가능 적립금 조회 uri                 | /accumulations/available-amounts                  | 필수                                                     |
| 5. 적립금 내역 조회 uri                   | /accumulations                                    | (선택)                                                   |
| 필요한 header 값                       | token : 'abc'                                     | 샵바이 -> 외부 개발사 요청 시, 인증을 위해서 필요한 http request header의 값 |
| <p>(추가)</p><p>memberMappingKey</p> | MEMBER\_ID(default), MEMBER\_NO, CI               | 맴버 맵핑 키                                                |

* step 3. 아래 NHN커머스 샵바이 ACL 추가바랍니다.
  * 리얼 환경: 103.194.111.5, 115.89.203.145
* 2024-08-26 memberMappingKey 항목 추가되었습니다.<br>
* 샘플(예시)

```java
{
    "url": "https://sample-dev.com",
    "headers": {
        "Content-Type": "application/json"
    },
    "memberMappingKey": "MEMBER_NO",
    "externalAccumulationUriGroup": {
        "addUri": "/accumulations/add",
        "searchUri": "/accumulations",
        "subtractUri": "/accumulations/subtract",
        "subtractRollbackUri": "/accumulations/subtract-rollback",
        "getAvailableAmountUri": "/accumulations/available-amounts"
    }
}
```

***

## 적립금 적립/차감/롤백 다이어그램 <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-81-eb-a6-bd-2f-ec-b0-a8-ea-b0-90-2f-eb-a1-a4-eb-b0-b1-eb-8b-a4-ec-9" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-81-eb-a6-bd-2f-ec-b0-a8-ea-b0-90-2f-eb-a1-a4-eb-b0-b1-eb-8b-a4-ec-9"></a>

### 적립금 적립 프로세스 <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-81-eb-a6-bd-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a4" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-a0-81-eb-a6-bd-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a4"></a>

<figure><img src="/files/8mhwKZujYFYo6naSN9pR" alt=""><figcaption></figcaption></figure>

***

### 적립금 차감/ 롤백 프로세스 <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-2f-eb-a1-a4-eb-b0-b1-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-2f-eb-a1-a4-eb-b0-b1-ed-94-84-eb-a1-9c-ec-84-b8-ec-8a-a"></a>

<figure><img src="/files/6FqrLmz024OgUUM8xT4K" alt=""><figcaption></figcaption></figure>

***

## 1. 적립금 지급 (필수) <a href="#id-1.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a7-80-ea-b8-89-ed-95-84-ec-88-98" id="id-1.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a7-80-ea-b8-89-ed-95-84-ec-88-98"></a>

### 적립금 지급 API (개발 스펙 안내) <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-a7-80-ea-b8-89-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e-99-ec-95-88-eb-82" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-a7-80-ea-b8-89-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e-99-ec-95-88-eb-82"></a>

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* POST
* request 는 request body 로 전달
* 형태는 json

#### ■ request    <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

| attribute                                          | name                       | required | desc                     |
| -------------------------------------------------- | -------------------------- | -------- | ------------------------ |
| memberKey                                          | 회원 연계 키                    | 필수       | 연계키                      |
| amount                                             | 적립금액                       | 필수       | 적립금                      |
| reason                                             | 적립 세부내역 사유                 | 필수       |                          |
| <p>reasonType<br></p>                              | 적립금 지급 사유                  | 필수       | enum 형식                  |
| expiredDateTime                                    | 적립금 만료일                    | 필수       |                          |
| mappingKey                                         | 적립키                        | 필수       | 주문번호, 리뷰번호, 옵션번호 중 하나의 값 |
| <p>(추가) additionalMappingKey.orderNo<br></p>       | <p>추가정보(연관 주문번호)<br></p>   | 선택       | 추가 연동키                   |
| <p>(추가) additionalMappingKey.reviewNo<br></p>      | 추가정보(연관 상품리뷰번호)            | 선택       | 추가 연동키                   |
| <p>(추가) additionalMappingKey.orderOptionNo<br></p> | <p>추가정보(연관 주문옵션번호)<br></p> | 선택       | 추가 연동키                   |

* 2023-07-24 reasonType 항목 추가되었습니다.&#x20;
* 2024-01-24 additionalMappingKey.orderNo, additionalMappingKey.reviewNo,additionalMappingKey.orderOptionNo 항목 추가됩니다. (2/20 배포완료)

#### ※ reasonType 코드 값 설명 <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

* 적립 - 적립 - 상품 주문 적립 (구매확정)\
  ADD\_AFTER\_PAYMENT
* 적립 - 적립 - 교환/추가결제 적립 (교환대상 가격 > 원주문 상품가격)\
  ADD\_AFTER\_REPLACE\_PAYMENT
* 적립 - 사이트 활동 적립 - 상품평 작성 완료\
  ADD\_POSTING
* 적립 - 수동적립\
  ADD\_MANUAL
* 적립 - 회원가입시 자동 적립\
  ADD\_SIGNUP
* 적립 - 생일축하 적립\
  ADD\_BIRTHDAY
* 적립 - 회원등급 적립\
  ADD\_GRADE
* 적립 - 등급 혜택 즉시 지급\
  ADD\_GRADE\_BENEFIT

***

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

#### 성공인 경우 <a href="#ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

| attribute | name   | required | desc   |
| --------- | ------ | -------- | ------ |
| no        | 지급 key | 필수       | 적립 연계키 |

#### 실패인 경우 <a href="#ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 400 으로 전달
* 보통의 경우 errorMessage로 전달된 실패사유를 사용자에게 노출하거나 로그로 남깁니다.
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

```
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}
```

### 제약조건 <a href="#ec-a0-9c-ec-95-bd-ec-a1-b0-ea-b1-b4" id="ec-a0-9c-ec-95-bd-ec-a1-b0-ea-b1-b4"></a>

※ `생일자 적립금 지급`, `등급 적립금 지급` 정기 지급 시, 일 배치(daily batch)로 적립금을 지급합니다.\
단, 해당 정기지급은 `mappingKey`가 0으로 등록되어 있어 외부적립금 사용 시 중복 지급될 수 있습니다.

만약 '[적립금 전환 방식](https://shopby.works/support/recommendedContents/23047)'으로 NHN커머스 샵바이의 적립금을 사용할 경우,  적립금 지급 번호와 사유를 내부 코드로 관리하여 중복지급을 제외할 수 있으나\
본 문서에서 안내드리는 '외부 적립금 연동 방식' 을 사용할 경우, 지급코드를 별도로 관리하지 않기 때문에 중복 지급 될 수 있습니다.

(예시) 중복지급 될 수 있는 케이스\
&#x20;: \[고객이 1/1을 생일로 등록]-> \[1/1 일 배치를 통해 생일 적립금 지급]-> \[1/2에 고객이 생일을 1/3으로 변경]-> \[1/3 일 배치에서 생일 적립금 중복 지급]\ <br>

### 참고사항 <a href="#ec-b0-b8-ea-b3-a0-ec-82-ac-ed-95-a-d" id="ec-b0-b8-ea-b3-a0-ec-82-ac-ed-95-a-d"></a>

`적립금 차감 API` 및 `적립금 차감 롤백 API`는 존재하나,\
`적립금 적립 API`에 대한 `적립금 적립 롤백 API` 는 제공하지 않는 점 참고부탁드립니다.

따라서 이미 적립된 적립금을 차감하기 위해서는, 아래 문서에서 소개 드릴 `적립금 차감 API`를 개발하시길 바랍니다.

***

## 2. 적립금 차감 (필수) <a href="#id-2.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-ed-95-84-ec-88-98" id="id-2.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-ed-95-84-ec-88-98"></a>

### 적립금 차감 API (개발 스펙 안내) <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e-99-ec-95-88-eb-82" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e-99-ec-95-88-eb-82"></a>

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* POST
* request 는 request body 로 전달
* 형태는 json

#### ■ request <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

| attribute                          | name                          | required | desc                                                                 |
| ---------------------------------- | ----------------------------- | -------- | -------------------------------------------------------------------- |
| memberKey                          | 회원 연계 키                       | 필수       | 연계키                                                                  |
| amount                             | 차감금액                          | 필수       | 적립금                                                                  |
| reason                             | 차감 사유                         | 필수       |                                                                      |
| <p>reasonType<br></p>              | <p>직립금 차감 사유<br></p>          | 필수       | <p>enum 형식<br></p>                                                   |
| mappingKey                         | 차감키                           | 필수       | 롤백용                                                                  |
| additionalMappingKey.orderNo       | 추가정보(연관 주문번호)                 | 선택       | 롤백용\*                                                                |
| additionalMappingKey.reviewNo      | 추가정보(연관 상품리뷰번호)               | 선택       | 롤백용\*                                                                |
| additionalMappingKey.orderOptionNo | 추가정보(연관 주문옵션번호)               | 선택       | 롤백용\*                                                                |
| <p>(추가) orderExtraData<br></p>     | <p>주문추가정보(JsonString)<br></p> | 선택       | <p>주문 예약단계에서 shop api(url링크)에서 입력한 ExtraData를 그대로 바이패스 합니다. <br></p> |

* 2024-02-20 request > orderExtraData 항목이 신규 추가됩니다.&#x20;
* 참고사항 (\*)\
  구매확정 후 반품 시, 이미 지급된 적립금 정보 확인을 위해 `적립금 차감 API`의 request 항목이 위와 같이 추가되었습니다.\
  외부적립금 연동 방식을 사용 중인 고객사의 경우, 새로 추가된 데이터에 대응 가능한 구조로 변경하시길 바랍니다.
* 2023-08-10 reasonType 항목 업데이트 되었습니다.&#x20;

#### ※ reasonType 코드 값 설명 <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

* 차감 - 사용 - 상품 주문 시 적립금 사용 (결제완료)\
  SUB\_PAYMENT\_USED
* 차감 - 사용 - 교환상품 추가 결제 시 적립금 사용 (추가결제 완료)\
  SUB\_EXTRA\_PAYMENT\_USED
* 차감 - 적립취소 - 상품평 삭제\
  SUB\_DELETE\_POSTING
* 차감 - 수동차감\
  SUB\_MANUAL\
  \ <br>
* 샘플 (예시)

{% code overflow="wrap" %}

```
{"amount" : 100,
"reason" : "테스트 차감",
"memberKey" : "test@abc.com",
"mappingKey" : "2022080117000000001",
"additionalMappingKey" : {
    "orderNo" : "2022080117000000001",
    "reviewNo" : "3",
    "orderOptionNo" : "2"
    }
}
```

{% endcode %}

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

성공인 경우

| attribute | name         | required | desc |
| --------- | ------------ | -------- | ---- |
| no        | 차감롤백을 위한 key | 필수       | 연계키  |

***

## 3. 적립금 차감 롤백 (필수) <a href="#id-3.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-ec-84-a0-ed-83-9d" id="id-3.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-ec-84-a0-ed-83-9d"></a>

### 적립금 차감 롤백 API (개발 스펙 안내) <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e" id="ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e"></a>

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* POST
* request 는 request body 로 전달
* 형태는 json
* 불가능한 경우 적립으로 처리 (`※ 이 경우 적립금 유효기간은 유지되지 않음)`

#### ■ request <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

| attribute     | name                 | required | desc                                        |
| ------------- | -------------------- | -------- | ------------------------------------------- |
| no            | 차감 롤백을 위한 key        | 필수(배타적)  | 차감 연계키 (타임아웃으로 인한 롤백 시 차감 시 호출한 mappingKey) |
| mappingKey    | 차감롤백을 위한 mapping key | 필수(배타적)  | 둘 중 하나는 필수(`no` or `mappingKey)`            |
| amount        | 롤백금액                 | 필수       |                                             |
| reason        | 롤백 사유                | 필수       |                                             |
| lastSubPayAmt | 남은 적립금               | 선택       | 부분 취소 시, 남은 적립금액                            |

* 2024-08-26 lastSubPayAmt 항목 추가되었습니다.

{% hint style="success" %} <mark style="color:red;">**롤백 케이스 별 amount, lastSubPayAmt 예시**</mark>

* **case1. 전체 취소 시**
  * amount: 1,000
  * lastSubPayAmt: 1,000
* **case2. 100 point 부분 취소 시**
  * amount: 100
  * lastSubPayAmt: 1,000
    {% endhint %}

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

#### 성공인 경우 <a href="#ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 200

#### 실패인 경우 <a href="#ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 400
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

{% code overflow="wrap" %}

```
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}

```

{% endcode %}

***

## 4. 사용가능 적립금 조회 (필수) <a href="#id-3.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-ec-84-a0-ed-83-9d" id="id-3.-ec-a0-81-eb-a6-bd-ea-b8-88-ec-b0-a8-ea-b0-90-eb-a1-a4-eb-b0-b1-ec-84-a0-ed-83-9d"></a>

### 사용가능 적립금 조회 API (개발 스펙 안내) <a href="#ec-82-ac-ec-9a-a9-ea-b0-80-eb-8a-a5-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a1-b0-ed-9a-8c-api-ea-b0-9c-eb-b0" id="ec-82-ac-ec-9a-a9-ea-b0-80-eb-8a-a5-ec-a0-81-eb-a6-bd-ea-b8-88-ec-a1-b0-ed-9a-8c-api-ea-b0-9c-eb-b0"></a>

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* GET
* request 는 request param으로 전달
* response 형태는 json

#### ■ request <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

| attribute       | name                      | required | desc |
| --------------- | ------------------------- | -------- | ---- |
| memberKey       | 회원 연계 키                   | 필수       | 연계키  |
| expireStartYmdt | 만료조회 시작일 (디폴트 : 오늘 - 30일) | 선택       |      |
| expireEndYmdt   | 만료조회 종료일 (디폴트 : 오늘)       | 선택       |      |

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

#### 성공인 경우 <a href="#ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

| attribute     | name               | required | desc |
| ------------- | ------------------ | -------- | ---- |
| amount        | 사용 가능한 총 적립금       | 필수       |      |
| expiresAmount | 만료예정 적립금 (없을 경우 0) | 선택       |      |

#### 실패인 경우 <a href="#ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 400
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

```
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}
```

***

## 5. 적립금 내역 조회 (선택) <a href="#id-5.-ec-a0-81-eb-a6-bd-ea-b8-88-eb-82-b4-ec-97-a-d-ec-a1-b0-ed-9a-8c-ec-84-a0-ed-83-9d" id="id-5.-ec-a0-81-eb-a6-bd-ea-b8-88-eb-82-b4-ec-97-a-d-ec-a1-b0-ed-9a-8c-ec-84-a0-ed-83-9d"></a>

### 적립금 내역 조회 API (개발 스펙 안내) <a href="#ec-a0-81-eb-a6-bd-ea-b8-88-eb-82-b4-ec-97-a-d-ec-a1-b0-ed-9a-8c-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e" id="ec-a0-81-eb-a6-bd-ea-b8-88-eb-82-b4-ec-97-a-d-ec-a1-b0-ed-9a-8c-api-ea-b0-9c-eb-b0-9c-ec-8a-a4-ed-8e"></a>

#### ■ method <a href="#e2-96-a0-method" id="e2-96-a0-method"></a>

* GET
* request 는 request param으로 전달
* response 형태는 json

#### ■ request <a href="#e2-96-a0-request" id="e2-96-a0-request"></a>

| attribute     | name                     | required | desc                                           |
| ------------- | ------------------------ | -------- | ---------------------------------------------- |
| startDateTime | 검색 시작일                   | 필수       |                                                |
| endDateTime   | 검색 종료일                   | 필수       |                                                |
| searchType    | 기준일(지급일기준 or 만료일 기준)     | 필수       | registred/expired                              |
| type          | 검색 조건(지급/차감)             | 선택       | <p>null이면 전체<br>add이면 적립<br>subtract 이면 차감</p> |
| memberKey     | 회원 연계 키                  | 선택       | null 이면 전체                                     |
| page          | 페이징을 위한 페이지 번호           | 필수       | 디폴트는 0                                         |
| size          | 페이징을 위한 한 페이지당 entity 개수 | 필수       | 디폴트는 100                                       |

#### ■ response <a href="#e2-96-a0-response" id="e2-96-a0-response"></a>

#### 성공인 경우 <a href="#ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-84-b1-ea-b3-b5-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

| attribute-level1 | attribute-level2 | name            | required | desc                         |
| ---------------- | ---------------- | --------------- | -------- | ---------------------------- |
| totalCount       | -                | 전체 데이터 건수       | 선택       |                              |
| contents         | no               | 적립금 번호          | 필수       | PK                           |
| contents         | memberKey        | 회원 연계 키         | 필수       | 연계키                          |
| contents         | type             | 지급/차감/지급롤백/차감롤백 | 필수       | 적립금                          |
| contents         | amount           | 적립금액            | 필수       | 적립금                          |
| contents         | reason           | 사유              | 필수       |                              |
| contents         | registerDateTime | 등록일             | 필수       |                              |
| contents         | expiredDateTime  | 적립금만료일          | 필수       |                              |
| contents         | mappingKey       | 적립키             | 필수       | 롤백용                          |
| contents         | totalAmount      | 적립/차감시점 잔여 적립금  | 선택       |                              |
| contents         | extraData        | 추가 정보           | 선택       | json 형태로 front에 추가적으로 노출할 정보 |

* 샘플(예시)

{% code overflow="wrap" %}

```
{
  "totalCount" : 15,
  "contents" : [
     {
       "no" : "1",
        "memberKey" : "abc",
        "type" : "지급",
        "amount" : 100,
        "reason" : "상품평 작성 적립",
        "registerDateTime" : "2021-01-01 13:12:30",
        "expiredDateTime" : "2022-01-01 13:12:30",
        "mappingKey" : "20210501123456123",
        "totalAmount" : 1200,
        "extraData" : {
             "a" : "b",
             "C" : "D"
         }
     }
  ]
}
```

{% endcode %}

#### 실패인 경우 <a href="#ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0" id="ec-8b-a4-ed-8c-a8-ec-9d-b8-ea-b2-bd-ec-9a-b0"></a>

* http code 400
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

{% code overflow="wrap" %}

```
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}
```

{% endcode %}


# \[엔터프라이즈] 사은품 API 화면가이드

```
샵바이 엔터프라이즈의 사은품 기능을 사용하기 위해, 
shop API로 화면을 어떻게 구현할 수 있을지 안내하기 위한 콘텐츠입니다.
```

\
**01. 간단소개**&#x20;

* 기능요약
  * 쇼핑몰 내 등록된 상품을 서비스어드민에서 사은품으로 지정하여, 지급조건 충족 시 사은품으로 지급할 수 있는 기능입니다.
  * 대상 솔루션: 샵바이프리미엄 전용
  * 기능 배포일자:2022-06-14
* 기능상세
  * 사은품 기능 어드민 설정 및 활용방법은 아래 공지사항 내 첨부파일을 참고해주시길 바랍니다
  * SA(서비스어드민): <https://service.e-ncp.com/board/popup/notice/261>
  * BPA(파트너 어드민): <https://partner.e-ncp.com/board/popup/notice/262>

***

**02. (예시) API소개 및 화면 가이드** \
아래 API들을 활용하여 사은품기능을 활용한 화면을 구현할 수 있습니다.

1\. 상품 상세페이지 화면&#x20;

■ [사은품 지급가능한 조건 조회 API](https://docs.shopby.co.kr/?url.primaryName=product/#/FreeGift/get-free-gift-condition) 확인하기

```
GET /free-gift-condition/{productNo}
상품번호에 해당하는 지급가능한 조건 조회하는 API입니다.
```

상품 상세페이지에서 해당 상품 구매 시, 사은품으로 설정된 상품의 지급조건 정보를 조회할 수 있습니다.

▽ 예시 화면 (사은품 안내영역 제공)

<br>

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

사은품 지급조건을 만족하는 상품이고 사은품 지급조건이 현재 지급 가능한 상태인 경우, 상품 상세페이지에서 사은품 지급조건을 안내합니다.

* (참고) 상품 상세페이지에서 사은품 영역이 노출되는 어드민 조건
  * 파트너사 프로모션 동의여부 체크
  * 대상 상품의 프로모션 가능여부가 '가능'이며 사은품에 체크
  * 쇼핑몰의 사은품 사용여부가 '사용함'
  * 지급상태가 '지급중'인 사은품 지급조건 중 해당 상품이 대상상품으로 설정된 지급조건이 있는지 체크
  * 사은품으로 지정된 원 상품의 전시상태가 '전시안함'이거나 프론트 '미노출'인 경우에도 사은품으로 지급됨

▽ 예시 화면\ <br>

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

* 위 예시화면의 '지급조건'은 `giveConditionExplain(지급조건 설명)`을 활용가능하며, 지급조건이 복수개인 경우 지급조건을 모두 노출합니다.
* 위 예시화면 최하단의 안내문구 영역은 API를 활용하지않고 자유롭게 구현할 수 있습니다.

***

2\. 주문서 작성/결제 화면

주문서 작성/결제 화면 상세 가이드는 아래 스킨 개발 가이드를 참고해주시기 바랍니다.

* 오로라 개별형 스킨 개발 가이드 : [바로가기 > ](https://workspace-help.nhn-commerce.com/aurora-guide/api-1/order-sheet-form#undefined-16)
* 오로라 통합형 스킨 개발 가이드: [바로가기 >](https://nhnent.dooray.com/share/pages/WoOk8q6KT1K3MZcLSuyZsw/3520341896217443973)

***

3\. 마이페이지 화면

■  [주문리스트 조회하기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/get-profile-orders) 확인하기

```
GET /profile/orders
시작일과 종료일 사이의 주문리스트를 조회하는 API입니다.
```

마이페이지에서 주문했던 상품 목록 조회시, 해당 상품이 사은품인지 여부를\
items > orderOptions> `isFreeGift`로 리턴합니다.

\
▽ 예시 화면 (마이페이지 주문내역)\ <br>

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

\
위 예시 화면과 같이, API를 활용하여 마이페이지에서 사은품 여부를 표시할 수 있습니다.

사은품은 주문상태가 결제완료인 시점에 주문서에 추가되며 \
(입금대기인 상태인 경우 추가되지 않으며, 주문시점에 지급 옵션으로 저장되었으나 실제 지급 시점에 사은품이 지급 불가한 상태인 경우에도 추가되지 않습니다.)\
마이페이지에서는 주문서에 추가된 이후부터 지급된 사은품 확인이 가능합니다.

\
또한 마이페이지 주문내역 화면에서 지급된 사은품 정보 확인 및 클레임 처리 기능을 제공하고 있습니다.\
지급된 사은품의 대한 취소/반품 처리가 가능합니다. (※단, 사은품 교환기능 미지원)\
다른 상품과 함께 클레임 처리하거나, 사은품 개별 클레임 처리가 가능합니다.

{% hint style="info" %}
**여기서 잠깐, 꼭 참고해주세요!**

사은품의 경우 상품후기 작성이 불가하며, 사은품 교환 기능은 제공되지 않습니다.

마이페이지 > 메인, 주문목록/배송조회, 주문상세 페이지에서 사은품의 상품후기 작성이 불가하며\
마이페이지 > 나의 상품후기 페이지에서 \[상품선택] 클릭하여 상품 선택 팝업 출력 시 사은품은 리스트에 노출되지 않습니다.

위 마이페이지 주문내역 화면에서, 사은품 상품후기 작성/교환버튼 클릭 시, 불가하다는 alert을 출력하는 등의 방법으로 처리 가능합니다.
{% endhint %}


# \[엔터프라이즈] PG신청 가이드 (2026/1/28 업데이트)

&#x20;업데이트 일자: 2026. 01. 28<br>

```
샵바이 엔터프라이즈의 경우, 고객사가 각 PG사 페이지에서 직접 가입 후 워크스페이스를 통해 PG키를 세팅해야하는 구조로 되어있어쇼핑몰 PG신청의 어려움을 해소하기 위해 작성된 콘텐츠입니다. ※ 2023/5/2 샵바이 그랜드 오픈 업데이트 이후부터는 NHN커머스> 부가서비스를 통해서 PG 신청이 가능합니다.   '리얼 PG사별 신청 방법 안내' 내용 참고하시어 PG 사 신규 신청을 원하시는 경우 부가서비스 메뉴에서 신청해 주시기 바랍니다.    네이버페이 외 PG 신청하신 경우, 신청하신 PG사의 결제수단 사용 설정은 1:1문의를 통해 요청해 주시기 바랍니다. ※ 2023/9/12 서비스어드민에 네이버페이 주문형/결제형 설정 기능이 추가되었습니다.     자세한 내용은 아래 공지사항 참고 부탁드립니다. ※ 2023/11/29 스토어>앱스토어에 카카오페이 앱이 추가되었습니다.    카카오페이 앱 설치 후 서비스어드민>앱리스트> 실행에서 PG 신청하실 수 있습니다.  ※ 샵바이프리미엄 이용 시 헤드리스(headless)로 쇼핑몰을 운영하는 경우,       서비스어드민 아래 메뉴 내 항목들을 반드시 헤드리스 쇼핑몰 정보 기준으로 도메인 정보를 입력하셔야 하는 점 참고 부탁드립니다. .       [서비스관리 > 쇼핑몰 관리 > 쇼핑몰  수정 > '쇼핑몰 도메인 정보'] > PC 웹 도메인, 모바일 웹 도메인       [서비스관리 > 쇼핑몰 관리 > 쇼핑몰  수정 > '상품 설정'] > 상품 상세 URL       [서비스관리 > 쇼핑몰 관리 > 쇼핑몰  수정 > 'SNS 간편 회원가입 로그인 URL 설정'] > PC 웹, 모바일웹       [서비스관리 > 쇼핑몰 관리 > 쇼핑몰  수정 > '배송 설정'] > 배송지 입력 URL       [전시관리 > 팝업 관리 > 팝업창 등록 > PC웹,모바일웹,모바일앱] > 기타 페이지[관리]  
```

### 목차  <a href="#eb-aa-a9-ec-b0-a8" id="eb-aa-a9-ec-b0-a8"></a>

* 샵바이 엔터프라이즈 PG사별 수수료 안내<br>
* 리얼 PG사별 신청 방법 안내

  * 일반 PG 신청 방법 (NHN KCP / KG 이니시스 / 토스 페이먼츠 / 나이스페이 / 이지페이 / 갤럭시아머니트리)&#x20;
  * 간편결제 PAYCO / KAKAO PAY 신청 방법
  * NAVER PAY (결제형) 신청 방법
  * 정기결제 (배송) 신청 방법

※ 샵바이 엔터프라이즈에서 제공되었던 alpha 환경 지원 서비스가 2023년 6월 30일자로 종료되었습니다.\
&#x20;    테스트/개발 필요하신 경우 리얼 환경에서 쇼핑몰을 추가 등록 기능을 이용하여 사용 부탁드립니다. \
&#x20;    \- 관련 공지사항 : [공지사항 바로가기 >](https://www.godo.co.kr/support/board/35/40/196)    [워크스페이스 API문서 변경사항 바로가기 >](https://shopby.works/support/notice/213335)\
\ <br>

### 1. 샵바이 엔터프라이즈 PG 사별 결제 수수료 안내  <a href="#id-2.-ec-95-8c-ed-8c-8c-ed-99-98-ea-b2-bd_pg-ec-84-b8-ed-8c-85-eb-b0-a9-eb-b2-95" id="id-2.-ec-95-8c-ed-8c-8c-ed-99-98-ea-b2-bd_pg-ec-84-b8-ed-8c-85-eb-b0-a9-eb-b2-95"></a>

* NHN KCP / KG 이니시스 / 토스 페이먼츠 / 나이스페이 / 이지페이 / 갤럭시아머니트리

| 결제타입  | PG 수수료(VAT별도)                        |
| ----- | ------------------------------------ |
| 신용카드  | 일반 3.5% (영중소 우대 수수료율은 계약 후 자동 처리 진행) |
| 계좌이체  | 1.8%                                 |
| 가상계좌  | 300원                                 |
| 휴대폰   | PG사별 정산 주기에 따름                       |
| 현금영수증 | 무료 (오프라인 단말기 별도 신청 가능)               |

* PAYCO

| 결제타입    | PG 수수료 (VAT별도)                       |
| ------- | ------------------------------------ |
| 간편 신용카드 | 일반 3.5% (영중소 우대 수수료율은 계약 후 자동 처리 진행) |

* KAKAO PAY<br>

| 결제타입     | PG 수수료(VAT별도)                        |
| -------- | ------------------------------------ |
| 신용카드     | 일반 3.5% (영중소 우대 수수료율은 계약 후 자동 처리 진행) |
| 카카오페이 머니 | 3.5%                                 |

* NAVER PAY (결제형)&#x20;

| 결제타입      | PG 수수료 (VAT 포함)                       |
| --------- | ------------------------------------- |
| 신용카드      | 일반 3.74% (영중소 우대 수수료율은 계약 후 자동 처리 진행) |
| 계좌이체      | 1.65%                                 |
| 가상계좌      | 1%                                    |
| 휴대폰       | 3.85%                                 |
| 네이버페이 포인트 | 3.74%                                 |

* 정기결제 (배송)&#x20;

| 결제타입 | PG 수수료 (VAT 포함)                      |
| ---- | ------------------------------------ |
| 신용카드 | 일반 3.5% (영중소 우대 수수료율은 계약 후 자동 처리 진행) |

### 2. 일반 PG 신청 방법  <a href="#id-4.-eb-a6-ac-ec-96-bc-ed-99-98-ea-b2-bd_nhn-kcp-ec-84-b8-ed-8c-85-eb-b0-a9-eb-b2-95" id="id-4.-eb-a6-ac-ec-96-bc-ed-99-98-ea-b2-bd_nhn-kcp-ec-84-b8-ed-8c-85-eb-b0-a9-eb-b2-95"></a>

* **PG 신청**\
  [NHN커머스 > 부가서비스 > 전자결제(PG) > 샵바이 enterprise(탭)](https://www.godo.co.kr/echost/power/add/payment/pg-intro.gd?bn=GNB#readypremium)에서 아래 PG사 신청 가능합니다.

  * 신청 PG사 : NHN KCP, KG이니시스, 토스 페이먼츠, 나이스페이, 이지페이, 갤럭시아머니트리
  * 신청 방법 : 통합회원 계정으로 로그인 후 PG사를 선택하여 \[신청하기] 버튼 클릭 후 신청하시면 PG사로부터 심사 승인 절차가 진행됩니다.

  **※** 단, 만약 샵바이 엔터프라이즈 헤드리스(headlss)버전 사용하는 경우, 사용하려는 도메인을 추가로 일대일문의를 통해 전달주시길 바랍니다.\
  전달주신 도메인으로 NHN커머스 담당자가 도메인을 변경처리하여 PG신청 가능합니다.<br>
* **신청정보 확인**\
  NHN커머스 [마이페이지> 전자결제서비스](https://www.godo.co.kr/mygodo/myGodo_pgMain.php)에서 서비스 상태 및 솔루션 상태 확인이 가능합니다.\
  \
  **※** 기존 PG사이트를 통해 PG신청 후 1:1문의를 통해 쇼핑몰에 세팅하신 경우 마이페이지에서 PG정보 확인되지 않습니다.       \
  2023/5/2 이후 `NHN커머스 > 부가서비스`를 통해 신청하신 정보만 마이페이지에서 확인 가능한 점 참고 부탁드립니다.<br>
* **솔루션(서비스어드민) 연동**&#x20;
  * PG 신청 시 `솔루션 전자결제 설정 > 즉시 설정(처음 신청시)` 선택하시면 신청하신 PG가 솔루션에 자동 연동됩니다.
  * PG 신청정보는 아래 메뉴에서 확인 가능합니다.&#x20;
    * 서비스어드민 > 서비스관리 > 전자결제(PG) 설정
    * [NHN커머스> 마이페이지> 전자결제서비스](https://www.godo.co.kr/mygodo/myGodo_pgMain.php) : \
      \[이용설정] 버튼을 클릭하면 솔루션에 연동할 PG사를 설정할 수 있습니다.\
      **※** 서비스어드민에서 PG사 결제수단 사용 설정할 수 있는 메뉴는 제공 예정입니다.\
      해당 메뉴 제공전까지는 워크스페이스 1:1문의를 통해 쇼핑몰번호와 사용하실 결제수단을 전달해 주시기 바랍니다.
    * (참고1) PG사별 가상계좌 입금 통보 URL 설정\
      PG사 관리자에서 가상계좌 입금내역을 통보받을 수 있도록 입금통보 URL이 등록되어야, 샵바이어드민에서 노티를 받을 수 있습니다. (이지페이, 토스 페이먼츠, 갤럭시아머니트리 PG사는 자동 등록됩니다.)\
      가상계좌 결제수단을 이용하시는 경우 각 PG사별로 아래 URL 입력하시기 바랍니다.\
      ※ 입금통보 URL 등록 전인, 기존 입금된 건들은 수동으로 입금처리 해야하는 점 참고부탁드립니다.
      * NHN KCP
        * 메뉴위치 :  `KCP 관리자 > 상점정보 관리> 정보변경 > 공통 URL 정보`에서 공통 URL 변경 전 항목에 아래 URL 입력 부탁드립니다.
        * 입금통보 URL : <https://shop-api.e-ncp.com/payments/kcp/callback>
      * KG 이니시스
        * 메뉴위치 : `이니시스 가맹점관리자 > 결제수단 정보 > 가상계좌 입금통보 URL 정보`에서 공통 URL 변경 전 항목에 아래 URL 입력 부탁드립니다.
        * 입금통보 URL : <https://shop-api.e-ncp.com/payments/inicis/callback>&#x20;
        * 참고 가이드: <https://manual.inicis.com/pay/etc-noti.html#popup_23>
      * 나이스페이
        * 메뉴위치 : `나이스페이 PG관리자 > 가맹점 정보 > 기본정보 > 결제데이터 통보`의 "가상계좌 항목"에 URL/IP 입력 후 저장 부탁드립니다.
        * 입금통보 URL : <https://shop-api.e-ncp.com/payments/nicepay/callback>
    * (참고2) KG이니시스 가상계좌 취소 안내&#x20;
      * KG이니시스 가상계좌 취소 진행을 위해 하기 경로에서 가상계좌 환불서비스 신청을 별도로 해주셔야 합니다.
      * ※ 이니시스의 가상계좌 환불서비스를 신청하지 않고 가상계좌 주문건 취소 진행 시 \
        &#x20;   "PG사 환불에 실패하였습니다. (환불서비스 이용 가맹점이 아닙니다.)" 얼럿이 노출됩니다.
      * 이니시스 가상계좌 환불서비스 신청 경로

        이니시스 가맹점관리자 > 상단 우측 변경/추가 > 1. 서비스 추가 및 변경 > 1.2.1 지불수단 추가 및 변경 > 3. 가상계좌 사용, 환불서비스(부분취소 포함) 사용 > 신청하기

<br>

### 3. 간편결제 PAYCO / KAKAO PAY 신청 방법 <a href="#id-5.-eb-a6-ac-ec-96-bc-ed-99-98-ea-b2-bd_kg-ec-9d-b4-eb-8b-88-ec-8b-9c-ec-8a-a4-ec-84-b8-ed-8c-85-eb-b" id="id-5.-eb-a6-ac-ec-96-bc-ed-99-98-ea-b2-bd_kg-ec-9d-b4-eb-8b-88-ec-8b-9c-ec-8a-a4-ec-84-b8-ed-8c-85-eb-b"></a>

* [NHN커머스> 부가서비스> 간편결제> 샵바이 enterprise(탭)](https://www.godo.co.kr/echost/power/add/payment/easypg-intro.gd?bn=menubar#readypremium)에서 아래 PG사 신청 가능합니다. \
  \- 신청 PG사 :  PAYCO \
  \- 신청 방법 : 통합회원 계정으로 로그인 후 PG사를 선택하여 \[신청하기] 버튼 클릭 후 신청하시면 PG사로부터 심사 승인 절차가 진행됩니다.\ <br>
* [NHN커머스> 스토어> 앱스토어 > 결제/금융](https://apps.godo.co.kr/apps/1175) 에서 앱 설치 후 신청 가능합니다. \
  \- 신청 PG사 :  KAKAO PAY\
  \- 신청 방법 : 서비스어드민 > 앱 리스트 > 실행 후 PG 신청 정보를 입력하시면 PG사로부터 심사 승인 절차가 진행됩니다.\ <br>
* 신청정보 확인 :\
  &#x20;NHN커머스 [마이페이지> 전자결제서비스](https://www.godo.co.kr/mygodo/myGodo_pgMain.php)에서 서비스 상태 및 솔루션 상태 확인이 가능합니다.\
  &#x20;※ 기존 PG사이트를 통해 PG신청 후 1:1문의를 통해 쇼핑몰에 세팅하신 경우 마이페이지에서 PG정보 확인되지 않습니다. \
  &#x20;5/2 이후 NHN커머스> 부가서비스를 통해 신청하신 정보만 마이페이지에서 확인 가능한 점 참고 부탁드립니다. \ <br>
* 솔루션(서비스어드민)  연동 :\
  \- PG 신청 시 솔루션 전자결제 설정> 즉시 설정(처음 신청시) 선택하시면 신청하신 PG가 솔루션에 자동 연동됩니다.\
  \- [마이페이지> 전자결제서비스](https://www.godo.co.kr/mygodo/myGodo_pgMain.php) 에서 \[이용설정] 버튼을 클릭하면 솔루션에 연동할 PG사를 설정할 수 있습니다.\
  ※ 서비스어드민에서 PG사 연동 정보 확인할 수 있는 메뉴는 제공예정입니다.\
  해당 메뉴 제공전까지 PG 사 해지 및 과세 정보 변경이 필요하신 경우에는 워크스페이스 1:1문의를 통해 쇼핑몰번호와 함께 문의주시기 바랍니다.

### 4. 네이버페이(결제형) 세팅 방법  <a href="#id-6.-eb-a6-ac-ec-96-bc-ed-99-98-ea-b2-bd_-ed-86-a0-ec-8a-a4-ed-8e-98-ec-9d-b4-eb-a8-bc-ec-b8-a0-ec-84" id="id-6.-eb-a6-ac-ec-96-bc-ed-99-98-ea-b2-bd_-ed-86-a0-ec-8a-a4-ed-8e-98-ec-9d-b4-eb-a8-bc-ec-b8-a0-ec-84"></a>

* [NHN커머스> 부가서비스> 네이버페이> 네이버페이 결제형(탭)](https://www.godo.co.kr/echost/power/add/payment/naverpay-intro.gd?bn=menubar)에서 신청 가능합니다. \
  \* 네이버페이 결제형 입점 신청 양식에서 '자사몰 형태' 항목을 '호스팅 업체를 통해 홈페이지를 운영' 선택 및 `샵바이 프리미엄(NHN커머스)` 입력하시기 바랍니다.\
  ![](https://rlyfaazj0.toastcdn.net/20230627/092348.966182000/assets_a73e01a1c6a34697ab20d49c30aab093_1dbf517106fd4b7f84e0414088d6ce4a.png)\ <br>
* 신청정보 확인 :\
  &#x20;PG신청이 완료되면 네이버페이로부터 안내 메일이 발송되며 네이버페이센터에서도 확인 가능합니다.  \ <br>
* 솔루션(서비스어드민)  연동 : \
  1\) 아래 메뉴에서 네이버페이 주문형/결제형 사용여부 및 세팅 정보를 설정하실 수 있습니다. \
  &#x20;   \- 메뉴 위치 : 서비스 관리 > 네이버페이 설정\
  &#x20;   \- 설정 항목 : 사용여부, 네이버페이센터 가맹점 ID, 가맹점 인증키, 버튼 인증키\
  &#x20;   ※ 네이버 공통 인증키 설정이 필요하신 경우 1:1문의로 요청하시기 바랍니다.\
  \
  2\) 아래 메뉴에서 네이버페이 주문형/결제형 버튼 노출 여부를 설정하실 수 있습니다.  \
  &#x20;   \- 메뉴 위치 : 서비스 관리 > 쇼핑몰 관리 > 쇼핑몰 수정 > 네이버페이 설정\
  &#x20;   ※ 네이버페이 주문형/결제형 사용 여부가 \`사용함\`인 경우에만 네이버페이 결제수단 노출 설정이 가능합니다.\
  \ <br>
* 참고사항
  * 결제형 : 주문서 페이지 내 결제수단으로 네이버페이 선택하여 결제 진행&#x20;
  * 주문형 : 쇼핑몰 상품 상세페이지에서 네이버페이 센터로 이동하여 결제 진행

### 5. 정기결제 (배송) 신청 방법 <a href="#id-5.-eb-a6-ac-ec-96-bc-ed-99-98-ea-b2-bd_kg-ec-9d-b4-eb-8b-88-ec-8b-9c-ec-8a-a4-ec-84-b8-ed-8c-85-eb-b" id="id-5.-eb-a6-ac-ec-96-bc-ed-99-98-ea-b2-bd_kg-ec-9d-b4-eb-8b-88-ec-8b-9c-ec-8a-a4-ec-84-b8-ed-8c-85-eb-b"></a>

* [NHN커머스> 부가서비스> 정기결제(배송)> 샵바이 enterprise(탭)](https://www.godo.co.kr/echost/power/add/payment/periodic-payment.gd#readypremium)에서 아래 PG사 신청 가능합니다. \
  \- 신청 PG사 : NHN KCP\
  \- 신청 방법 : 통합회원 계정으로 로그인 후 PG사를 선택하여 \[신청하기] 버튼 클릭 후 신청하시면 PG사로부터 심사 승인 절차가 진행됩니다.


# \[엔터프라이즈] 카카오 픽셀 설치 가이드

샵바이 엔터프라이즈 FE에 카카오에서 제공하는 전환추적 서비스 사용을 위해 카카오 픽셀 설치를 어떻게 할 수 있는지 안내하기 위한 콘텐츠입니다.

**01. 간단소개**&#x20;

* 기능 요약
  * 샵바이 엔터프라이즈 FE에 카카오 픽셀을 설치해 최적의 잠재 고객을 파악하고, 광고 성과 측정을 할 수 있습니다.
  * 카카오 픽셀 상세 가이드 : <https://kakaoad.github.io/kakao-pixel/Documentation.html>
  * 대상 솔루션: 샵바이 엔터프라이즈 전용\
    ※ 샵바이 프로의 경우 셀러어드민 내 등록된 "카카오 픽셀" 앱 다운로드를 통해 사용 가능합니다. (추후 오픈 예정)

***

**02.  카카오 픽셀 설치 가이드**<br>

**1. Track ID 발급**\
카카오 픽셀을 이용하기 위해서는, 고유 식별값(Track ID)이 필요합니다.\
식별값(Trrack ID) 발급 방법은 하기와 같습니다.

(1) [https://business.kakao.com](https://business.kakao.com/login)에서 회원 가입\
(2) <https://business.kakao.com/pixel> 페이지에서 식별값(Track ID) 발급&#x20;

**2. 방문 이벤트 설치**

* 모든 웹페이지에 설치(공통)

{% code overflow="wrap" %}

```
<script type="text/javascript" charset="UTF-8" src="//[t1.daumcdn.net/kas/static/kp.js](http://t1.daumcdn.net/kas/static/kp.js)"></script>
<script type="text/javascript">
      kakaoPixel('발급받은 Track ID 입력').pageView();
      kakaoPixel.setServiceOrigin('20005’); //카카오 픽셀에서 NHN 커머스 샵바이 솔루션 구분용 코드
</script>
```

{% endcode %}

\
**3. 회원가입 이벤트 설치**

* 회원가입 완료 페이지에 설치

{% code overflow="wrap" %}

```
<script type="text/javascript" charset="UTF-8" src="//[t1.daumcdn.net/kas/static/kp.js](http://t1.daumcdn.net/kas/static/kp.js)"></script>
<script type="text/javascript">
      kakaoPixel('발급받은 Track ID 입력').pageView();
      kakaoPixel.setServiceOrigin('20005’); //카카오 픽셀에서 NHN 커머스 샵바이 솔루션 구분용 코드
      kakaoPixel('발급받은 Track ID 입력').completeRegistration();
</script>
```

{% endcode %}

\
**4. 검색 이벤트 설치**

* 검색 결과 페이지에 설치

{% code overflow="wrap" %}

```
<script type="text/javascript" charset="UTF-8" src="//[t1.daumcdn.net/kas/static/kp.js](http://t1.daumcdn.net/kas/static/kp.js)"></script>
<script type="text/javascript">
      kakaoPixel('발급받은 Track ID 입력').pageView();
      kakaoPixel.setServiceOrigin('20005’); //카카오 픽셀에서 NHN 커머스 샵바이 솔루션 구분용 코드
      kakaoPixel('발급받은 Track ID 입력').search({
        keyword: '검색 키워드 입력'
      });
</script>
```

{% endcode %}

\
**5. 콘텐츠/ 상품 조회 이벤트 설치**

* 콘텐츠(리스트) 페이지, 상품 상세 페이지에 설치

{% code overflow="wrap" %}

```
<script type="text/javascript" charset="UTF-8" src="//[t1.daumcdn.net/kas/static/kp.js](http://t1.daumcdn.net/kas/static/kp.js)"></script>
<script type="text/javascript">
      kakaoPixel('발급받은 Track ID 입력').pageView();
      kakaoPixel.setServiceOrigin('20005’); //카카오 픽셀에서 NHN 커머스 샵바이 솔루션 구분용 코드
      kakaoPixel('발급받은 Track ID 입력').viewContent({
        id: '상품번호 입력'
      });
</script>
```

{% endcode %}

\
**6. 장바구니 추가 이벤트 설치**

* 장바구니 추가 버튼에 설치
  * 장바구니 추가 버튼 클릭 시 동적으로 스크립트가 작동하는 방식으로 구현이 필요합니다.

{% code overflow="wrap" %}

```
<script type="text/javascript" charset="UTF-8" src="//[t1.daumcdn.net/kas/static/kp.js](http://t1.daumcdn.net/kas/static/kp.js)"></script>
<script type="text/javascript">
    kakaoPixel.setServiceOrigin('20005’); //카카오 픽셀에서 NHN 커머스 샵바이 솔루션 구분용 코드
    kakaoPixel('발급받은 Track ID 입력').addToCart({
        id: '상품번호 입력'
      });
</script>
```

{% endcode %}

\
**7. 관심상품 추가 이벤트 설치**

* 관심상품 추가 버튼에 설치
  * 관심상품 추가 버튼 클릭 시 동적으로 스크립트가 작동하는 방식으로 구현이 필요합니다.

{% code overflow="wrap" %}

```
<script type="text/javascript" charset="UTF-8" src="//[t1.daumcdn.net/kas/static/kp.js](http://t1.daumcdn.net/kas/static/kp.js)"></script>
<script type="text/javascript">
      kakaoPixel.setServiceOrigin('20005’); //카카오 픽셀에서 NHN 커머스 샵바이 솔루션 구분용 코드
      kakaoPixel('발급받은 Track ID 입력').addToWishList({
        id: '상품번호 입력'
      });
</script>
```

{% endcode %}

\
**8. 장바구니 보기 이벤트 설치**

* 장바구니 페이지에 설치

{% code overflow="wrap" %}

```
<script type="text/javascript" charset="UTF-8" src="//[t1.daumcdn.net/kas/static/kp.js](http://t1.daumcdn.net/kas/static/kp.js)"></script>
<script type="text/javascript">
      kakaoPixel('발급받은 Track ID 입력').pageView();
      kakaoPixel.setServiceOrigin('20005’); //카카오 픽셀에서 NHN 커머스 샵바이 솔루션 구분용 코드
      kakaoPixel('발급받은 Track ID 입력').viewCart();
</script>
```

{% endcode %}

\
**9. 구매 이벤트 설치**

* 결제 완료 페이지에 설치
  * 최종 결제 금액
    * 총 상품 금액 - 총 할인 금액 = 최종 결제금액
    * 총 상품 금액 : 전체 상품 금액 + 배송비 + 옵션가 + 텍스트 옵션가
    * 총 할인 금액 : 즉시할인 + 추가할인 + 상품 쿠폰 할인 + 장바구니 쿠폰 할인 + 장바구니 배송비쿠폰 할인 금액
  * 상품명
    * 옵션 상품인 경우 상품명\_옵션명으로 전송합니다. (ex. 티셔츠\_검정)
    * 구매자작성형 옵션명은 전송하지 않습니다.
  * 상품 가격
    * 판매가 +  옵션 가격을 포함한 금액
    * (상품 판매가 + 옵션 가격 ) \* 상품 개수
    * 각 상품의 할인 금액은 적용하지 않습니다. (ex. 상품 추가 할인, 상품쿠폰(플러스쿠폰 포함), 장바구니쿠폰, 장바구니 배송비쿠폰)
  * 화폐 단위의 기본 값은 KRW입니다.

{% code overflow="wrap" %}

```
<script type="text/javascript" charset="UTF-8" src="//[t1.daumcdn.net/kas/static/kp.js](http://t1.daumcdn.net/kas/static/kp.js)"></script>
<script type="text/javascript">
      kakaoPixel('발급받은 Track ID 입력').pageView();
      kakaoPixel.setServiceOrigin('20005’); //카카오 픽셀에서 NHN 커머스 샵바이 솔루션 구분용 코드
      kakaoPixel('발급받은 Track ID 입력').purchase({
        total_quantity: "상품 개수", 
        total_price: "총 결제 금액",
        currency: "화폐 단위",
        products: [
            { id: "상품번호 입력", name: "상품명1", quantity: "상품 개수", price: "결제 금액"},
            { id: "상품번호 입력", name: "상품명2", quantity: "상품 개수", price: "결제 금액"}
        ]
    });
</script>
```

{% endcode %}


# \[엔터프라이즈]정기결제(배송) API 화면가이드

{% code overflow="wrap" %}

```
샵바이 엔터프라이즈의 정기결제(배송) 기능을 사용하기 위해, shop API로 화면을 어떻게 구현할 수 있을지 안내하기 위한 콘텐츠입니다.
```

{% endcode %}

#### 01. 간단소개 <a href="#id-01.-ea-b0-84-eb-8b-a8-ec-86-8c-ea-b0-9c" id="id-01.-ea-b0-84-eb-8b-a8-ec-86-8c-ea-b0-9c"></a>

* 기능요약
  * 쇼핑몰 내 등록된 상품을 서비스어드민에서 정기결제(배송)상품으로 지정하여, 고객이 신청한 주문은 정기결제(배송) 해지일까지 희망배송일 마다 자동생성하는 기능입니다.\ <br>

#### 02. API 소개 및 화면 가이드 <a href="#id-02.-api-ec-86-8c-ea-b0-9c-eb-b0-8f-ed-99-94-eb-a9-b4-ea-b0-80-ec-9d-b4-eb-93-9c" id="id-02.-api-ec-86-8c-ea-b0-9c-eb-b0-8f-ed-99-94-eb-a9-b4-ea-b0-80-ec-9d-b4-eb-93-9c"></a>

아래 API들을 활용하여 정기결제(배송)기능을 활용한 화면을 구현할 수 있습니다.

들어가기 앞서, 정기배송(결제)사용 여부를 응답하는 API를 소개합니다.

■ [주문설정 값 가져오기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderConfiguration/get-order-configuration) 확인하기

```
GET /order-configs
주문 설정값을 조회하는 API 입니다.
```

해당 API는 로그인 여부와 상관없이, 몰에 어느 페이지든 초기 진입 시 설정 값을 캐시로 저장합니다.

응답 값 내 `useRecurringPayment 몰 정기배송(결제) 사용 여부` 값을 통해, 해당 몰이 정기결제를 사용하는 몰인지 판단할 수 있습니다.\
정기결제를 사용하는 몰이면서 동시에 정기결제에 해당하는 상품인 경우, 아래 안내 드릴 '상품 상세페이지 화면'에서 정기배송 장바구니를 위한 UI를 노출해야 합니다.

응답 값 내 `recurringPaymentFreeGiftIssueType 정기결제 사은품 지급 기준` 값을 통해, 해당 쇼핑몰의 정기결제 사은품 지급 기준을 판단할 수 있습니다.\
RECURRING\_PAYMENT\_NO -> 정기결제 신청 번호 기준으로 사은품 지급\
RECURRING\_PAYMENT\_GROUP\_NO -> 정기결제 그룹 번호 기준으로 사은품 지급

<br>

#### 1) 상품 상세페이지 화면 <a href="#id-1-ec-83-81-ed-92-88-ec-83-81-ec-84-b8-ed-8e-98-ec-9d-b4-ec-a7-80-ed-99-94-eb-a9-b4" id="id-1-ec-83-81-ed-92-88-ec-83-81-ec-84-b8-ed-8e-98-ec-9d-b4-ec-a7-80-ed-99-94-eb-a9-b4"></a>

서비스 어드민 > 상품관리 > 정기결제(배송) 상품관리에서 정기결제(배송)상품으로 등록하였을 경우\
위와 같이 정기배송 상품금액 출력 및 정기결제 장바구니 담기 기능을 화면에 구현할 수 있습니다.

<br>

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

■ [상품 상세조회 API](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-product) 확인하기

```
GET /products/{productNo}
해당 상품 번호에 대한 상세, 이미지, 옵션 정보를 조회하는 API입니다
```

`regularDelivery (정기 결제 정보)` 값이 null로 리턴 될 경우, 정기결제(배송)상품이 아니라는 것을 판단할 수 있습니다.

응답 값 내 `regularDelivery (정기 결제 정보)` 값을 통해 즉시할인이 적용된 금액을 조회할 수 있습니다. 이를 바탕으로 정기배송 상품금액을 화면에 출력합니다.

참고로, 정기결제(배송) 상품의 경우 원 상품에 설정된 즉시할인가는 적용되지 않으며,\
서비스어드민 > 정기결제(배송)상품 관리> 정기결제(배송)상품 등록> 상품할인 설정에서 적용한 즉시할인이 상품할인에 적용됩니다.

\
\
■ [정기결제 장바구니 담기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments-cart) 확인하기

```
POST /recurring-payments/cart 
로그인된 유저의 장바구니에 해당 상품 및 옵션, 수량을 입력하는 API입니다
```

* 정기결제 장바구니 버튼클릭 시, 상품금액이 500원인지 확인 후 장바구니 담기 완료 처리합니다.
* 옵션가를 포함한 정기결제 즉시할인 적용가가 500원 미만인 경우, 정기결제건으로 처리가 불가합니다. (장바구니 담기 불가)\
  이 경우, "상품가격 또는 할인금액 등 상품정보가 변경되었습니다. 다시 확인하시고 구매해 주세요."와 같은 알럿메시지가 출력되어야 합니다.
* 옵션이 필수이나, 옵션을 선택하지 않은 경우 '옵션을 선택해주세요'와 같은 알럿을 출력할 수 있습니다.

\ <br>

#### 2) 장바구니 화면 <a href="#id-2-ec-9e-a5-eb-b0-94-ea-b5-ac-eb-8b-88-ed-99-94-eb-a9-b4" id="id-2-ec-9e-a5-eb-b0-94-ea-b5-ac-eb-8b-88-ed-99-94-eb-a9-b4"></a>

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

■ [정기결제 장바구니 조회 API](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cart) 확인하기

```
GET /recurring-payments/cart 
로그인된 유저의 정기결제 장바구니 목록을 조회하는 API 입니다
```

예시 장바구니 화면 내에서 '정기배송' 탭을 구현할 때 호출하는 API입니다.\
응답 값 내 deliveryGroups > orderProducts > orderProductOptions > `adjustableDeliveryCycle` 를 통해 정기결제 상품의 '배송 주기'를 화면에 출력할 수 있습니다.\
배송주기는 서비스어드민>상품관리>정기결제(배송) 상품관리에 등록된 배송주기가 출력됩니다.

참고로 장바구니 화면 내 '일반배송' 탭을 구현할 때는 해당 `GET/cart` API를 호출하면 됩니다. (참고:[장바구니 화면 가이드 보러가기](https://workspace-help.nhn-commerce.com/aurora-skinguide/api-1/cart))\
응답 값 배열을 `GET /recurring-payments/cart` 와 `GET/cart`가 서로 동일하게 맞추기 위해 `GET/cart` 에서도 `recurringDeliveryCycles (정기결제 배송주기)`를 내려주고 있으나\
기본적으로 정기결제 장바구니 화면은 `GET /recurring-payments/cart` 으로 구현하실 수 있습니다.

※ 500원 미만의 상품이 장바구니에 등록되어 있는 경우 장바구니 리스트에 구매 불가 상품으로 표시가 필요합니다. (아래 이미지 참고)<br>

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

■ [정기결제 다음배송일자 조회하기 API ](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-next-recurring-date)확인하기

```
GET /recurring-payments/next-recurring-date
정기결제 다음 배송일자를 조회하는 API 입니다.
```

해당 API를 호출하여, 예시 장바구니 화면 내 '정기배송 첫 배송 예정일' 을 구현할 수 있습니다.\
배송주기와 배송일, 배송요일을 기준으로 첫 정기배송일을 출력합니다.

계산 된 배송 예상일이 현재보다 +2일 이내인 경우, 다음 주기에 배송됩니다.

\
<참고사항>

* 배송 예정일 3일전
  * 신청 상품이 결제 가능인 경우 (정상) : sms 또는 email 설정에 따라 정기결제 상품에 대해 결제 예정 내용을 발송 요청
  * 신청 상품이 판매 불가인 경우 (비정상) : 정기결제 상품의 상태를 '시스템 해지(`SYSTEM_CLOSED`)' 로 강제 변경 (sms, email 발송 요청 없음)
* 배송 예정일 2일전
  * 신청 상품이 결제 가능인 경우 (정상) : 주문서 생성 및 PG결제
  * 신청 상품이 판매 불가인 경우 (비정상) : 정기결제 상품의 상태를 '시스템 해지(`SYSTEM_CLOSED)`' 로 강제 변경 (sms, email 발송 요청 없음)
  * 신청 상품이 결제 불가인 경우 (비정상) : 주문서 생성 > 주문서 상태 결제 실패 처리 > 정기결제 상품의 상태를 '시스템 일시정지(`SYSTEM_PAUSED`)' 로 강제 변경 (sms, email 발송은 결제 실패 안내 설정 시 발송 요청)

\
\
■ [정기결제 장바구니 수정하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-cart) API 확인하기

```
PUT /recurring-payments/cart
장바구니 목록에서 장바구니를 수정하는 API 입니다.
```

장바구니 화면 내 구매 '수량'을 변경하는 API입니다.

\
\
■ [정기결제 장바구니 삭제하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/delete-recurring-payments-cart) API 확인하기

```
DELETE /recurring-payments/cart
장바구니 목록에서 장바구니를 삭제하는 API 입니다.
```

장바구니 화면 내 '삭제' 버튼 클릭 시 호출되는 API입니다.

\
\
■ [정기결제 장바구니에서 선택된 상품금액 계산하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cart-calculate) API 확인하기

```
GET /recurring-payments/cart/calculate 
장바구니에서 선택된 상품만 계산하여 금액을 응답하는 API 입니다.
```

장바구니에서 선택된 상품(cartNo) 금액을 계산합니다.\
cartNo은 `GET /cart`API 내 상품 옵션 별로 `orderProductOptions`에서 확인 가능합니다.

장바구니 리스트에서 좌측 체크박스에 '체크 된 항목이 변경될 때마다' 실시간으로 금액 정보를 계산합니다.

\
\
■ [정기결제 장바구니에서 선택된 항목만 그룹별로 재계산하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cart-subset) API 확인하기

```
GET /recurring-payments/cart/subset
장바구니에서 선택된 상품만 계산하여 장바구니 상품정보와 금액을 함께 응답하는 API 입니다.
```

GET /recurring-payments/cart/calculate는 장바구니 목록에서 체크박스 체크/해제 시 선택된 상품의 금액정보만 재계산하여 내려주는 반면\
GET /recurring-payments/cart/subset은 금액정보 뿐 아니라, 배송 그룹별로 나뉜 상품정보까지 함께 내려준다는 차이가 있습니다.\
즉, 해당 API는 delievery groups에 대한 정보가 있어서, 장바구니 체크박스 체크/해제 시 배송그룹 조건으로 인한 배송비 변동(ex조건부 무료배송)도 함께 업데이트 가능합니다.

\
■ [정기결제 주문서 등록](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments-order-sheets) API 확인하기

```
POST /recurring-payments/order-sheets
정기결제 주문을 진행할 상품정보를 전달하는 API입니다.
```

예시 장바구니 화면 내에서 '정기배송 신청' 버튼 클릭 시 호출하는 API로,\
장바구니 목록에서 체크박스 선택된 상품을 기준으로 정기결제 주문서를 생성합니다.

예시 화면 내 '바로구매'를 클릭할 경우에도, 해당 상품만을 기준으로 정기결제 주문서를 생성합니다.

참고로, 주문서에서 상품이 500원 미만이 된 경우 정기배송 신청 시 alert msg "유효하지 않은 정기결제 할인가가 적용되었습니다."를 출력하셔야합니다.<br>

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

#### 3) 주문서 화면 <a href="#id-3-ec-a3-bc-eb-ac-b8-ec-84-9c-ed-99-94-eb-a9-b4" id="id-3-ec-a3-bc-eb-ac-b8-ec-84-9c-ed-99-94-eb-a9-b4"></a>

\
![Inline-image-2024-07-04 11.09.29.778.png](https://nhnent.dooray.com/share/pages/-I6Jm8mqQVCon3pE_YgqIg/attach-files/3839934784118481310)

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

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

■ [정기결제 주문서 조회](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-order-sheets-order-sheets-no) API 확인하기

```
GET /recurring-payments/order-sheet/{orderSheetNo}
정기결제 주문서를 조회하는 API입니다.
```

장바구니 화면에서 등록한 배송주기, 배송일, 배송요일, 첫배송 예정일, 정기결제 사은품을 출력합니다.

참고로 주문서 화면에 진입한 뒤, 정기결제가가 500원 미만으로 변경된 뒤 새로고침하면 에러가 발생합니다. (아래 이미지 참고)

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

\
\
■ [배송지 목록 가져오기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/get-profile-shipping-addresses) API 확인하기

```
GET /shop/profile/shipping-addresses
주소지 정보를 조회하는 API 입니다.
```

응답 값 내 `recurringPaymentAddresses (정기결제 배송지)` 필드값을 활용합니다.\
주문서 화면 내 배송지선택 항목은 미선택된 상태가 디폴트이고\
정기결제 신청 시 마다, 정기배송지 관리 레이어(아래 이미지 참고)에서 선택하도록 구현합니다.<br>

<figure><img src="/files/3y7jVjN37XDbTQXFLiNj" alt=""><figcaption></figcaption></figure>

\
■ [배송지 등록하기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/post-profile-shipping-addresses) API 확인하기

```
POST /profile/shipping-addresses
주소지 정보를 추가하는 API 입니다.
```

새 배송지를 추가하는 '배송지 추가버튼'을 구현할 수 있는 API입니다.\
배송지 추가 개수는 기존 배송지관리 화면과 동일하게 적용됩니다 ([가이드](https://shopby.works/guide/dev-cover/order#payment-info) 내 C.배송지 정보 참고)\
Request Body 내 `addressType 배송지타입` > `RECURRING_PAYMENT 정기결제 배송주소`를 통해 정기배송지 여부를 실어보냅니다.

\
\
■ [배송지 수정하기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/put-profile-shipping-addresses-address-no) API 확인하기

```
PUT /shop/profile/shipping-addresses/{addressNo}
선택한 주소지 정보를 수정하는 API 입니다.
```

'수정버튼'을 구현할 수 있는 API입니다.\
Request Body 내 `addressType 배송지타입` > `RECURRING_PAYMENT 정기결제 배송주소`를 통해 정기배송지 여부를 실어보냅니다.\
단, 정기배송지로 등록된 배송지는 수정이 불가하며, "해당 배송주소로 신청된 정기배송 건이 있어 수정 불가합니다. 정기배송 해지 후 수정해주시기 바랍니다"와 같은 알럿메시지를 출력해야합니다.

\
\
■ [배송지 삭제하기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/delete-profile-shipping-addresses-address-no) API 확인하기

```
DELETE /shop/profile/shipping-addresses/{addressNo}
등록한 주소지 정보를 삭제하는 API 입니다.
```

'삭제 버튼'을 구현할 수 있는 API입니다.\
호출 시 파라미터 내 `addressNo 배송지 번호`를 삭제하게 되는데, 해당 값은 정기배송지 여부와 상관없는 고유 값이므로 정기배송지 여부를 별도로 요청보내지 않는 점을 참고부탁드립니다.\
정기배송지로 등록된 배송지는 삭제 불가하며, 삭제가 불가하다는 알럿메시지를 출력해야합니다.

\
\
■ [정기결제 카드 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cards) API 확인하기

```
GET /recurring-payments/cards
모든 정기결제 카드를 조회하는 API 입니다.
```

회원의 모든 정기결제 카드를 조회할 수 있습니다. (최대 5개)\
마이페이지> 정기배송관리 > 결제카드 관리 에 등록된 카드 정보를 출력합니다.\
회원에게 등록된 정기결제 카드가 없을 시 빈 리스트를 응답하며, 등록된 카드정보가 없는 경우 카드 등록 버튼을 노출해야합니다.

***

## 정기결제 카드 등록 방법 (KCP, KSNET) <a href="#ec-a0-95-ea-b8-b0-ea-b2-b0-ec-a0-9c-ec-b9-b4-eb-93-9c-eb-93-b1-eb-a1-9d-eb-b0-a9-eb-b2-95-kcp-ksnet" id="ec-a0-95-ea-b8-b0-ea-b2-b0-ec-a0-9c-ec-b9-b4-eb-93-9c-eb-93-b1-eb-a1-9d-eb-b0-a9-eb-b2-95-kcp-ksnet"></a>

정기결제 카드를 등록하는 방법은 두 가지 입니다. 사용하시는 PG사에 알맞은 방법을 택일해서 사용하세요.

* \[KCP] 정기결제 스크립트를 실행해서 등록하기
  * [#kcp-ncp\_pay.js](#kcp-ncp_pay.js "mention")
* \[KSNET] 정기결제 카드 등록하기 API를 활용해 등록하기
  * [#ksnet-api](#ksnet-api "mention")

***

### ■ **\[KCP]** 정기결제 스크립트 실행 방법 (ncp\_pay.js )

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

이를 구현하기 위해서는 결제모듈 javascript를 제공하고 있는데, (참고: 일반 결제 [결제편의모듈 가이드](https://workspace-help.nhn-commerce.com/aurora-skinguide/api-1/order-sheet-form#javascript))

정기결제 모듈을 실행하기 위해서는, KCP에서 정기결제용 PG key / siteCd / kcpGroupId 3가지 정보 발급받은 뒤 NHN커머스로 전달하여 세팅요청이 필요합니다.\
일반결제 KCP의 PG key가 이미 세팅되어 있더라도 정기결제용 PG key 별도 발급이 필요합니다.

\
\
`Step 1` **NCPPay 모듈 import**

* ncp\_pay.js 로드

```
<script src="https://shop-api.e-ncp.com/payments/ncp_pay.js"></script>
```

\
\
`Step 2` **각 PG 사에서 제공하는 결제 모듈 javascript 를 로드**\
정기결제의 경우, 아래 KCP 모듈을 로드합니다.

```
const payScripts = {
    real: [
        'https://pay.kcp.co.kr/plugin/payplus_web.jsp'
    ],
};
```

\
\
`Step 3` **NCPPay.setConfiguration 값 입력**\
아래 설명을 참고하여 Configuration 값을 입력합니다.

```
NCPPay.setConfiguration({
    'clientId': ncp.clientId, // shopby에서 발급받은 clientId
    'confirmUrl': 'payment-confirm.html', // 결과를 리턴받을 url
    'platform': 'PC', // 'PC or MOBILE_WEB or MOBILE_APP'
    'shopbyAuthorization' : accessToken ? `Bearer ${accessToken}` : '', // Oauth2 인증 방식을 사용시 인증 헤더 구분 값
    'accessToken': '', // Oauth 인증 방식을 사용시 인증 헤더 구분 값
});
```

\
참고로 `clienId`는, 쇼핑몰 사이트를 출력하기 위해 할당된 각 상점의 쇼핑몰 구분 값입니다.\
(프론트에서 API호출 시 해당하는 쇼핑몰을 판단할 수 있는 key값)

* 샵바이프로: `enviroment.json` 내 `clientId` 값으로 확인 가능합니다.
* 샵바이프리미엄: 서비스어드민 > 서비스관리 > 쇼핑몰관리 > (쇼핑몰 선택) > 개발연동정보 > 클라이언트 아이디에서 확인 가능합니다.

단, 각 PG에서 제공하는 아래와 같은 예시코드를 javascript코드로 입력해야합니다.

```
<script type="text/javascript" src="https://testpay.kcp.co.kr/plugin/payplus_web.jsp"></script> 
<script type="text/javascript" src="http://wcs.naver.net/wcslog.js"></script>
```

\
\
`Step 4` **NCPPay.reserveRecurringPaymentKey() 메소드 호출**

파라미터로 recurringPaymentRedirectUrl, successCallback, failCallback를 전달하면됩니다.

* `recurringPaymentRedirectUrl` : 진행 후 돌아올 URL
* `successCallback`: 성공 시 진행할 콜백 함수
* `failCallback`: 실패 시 진행할 콜백 함수

### ■ **\[KSNET]** [정기결제 카드 등록하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments-card) API 호출 방법

```
POST /recurring-payments/card
정기결제 카드를 등록하는 API 입니다.
사용중인 PG가 비 인증 방식으로 정기결제 카드를 등록하는 경우 사용 가능합니다.
```

위 API 를 호출하기 위해서는, KSNET에서 PG key를 발급받은 뒤 NHN커머스로 전달하여 세팅요청이 필요합니다.

<figure><img src="/files/9j4QJNx3NMlWe66BPHWf" alt=""><figcaption></figcaption></figure>

\
■ [적용 중인 몰 약관 조회하기](https://docs.shopby.co.kr/?url.primaryName=manage/#/Terms/search-used-terms) API 확인하기

```
GET /terms
해당 쇼핑몰의 약관을 조회하는 API 입니다.
```

파라미터 `REGULAR_PAYMENT_USE: 정기결제(배송) 이용약관` 과 `AUTO_APPROVAL_USE: 자동 승인 이용약관`를 활용하여,\
서비스 어드민 > 서비스관리 > 약관/개인정보처리방침 관리 > 이용약관 - 정기결제(배송) 이용약관/ 자동 승인 이용약관 내용을 출력합니다.

\
\
■ [정기결제 신청하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments) API 확인하기

```
POST /recurring-payments
정기결제를 신청하는 API입니다.
```

주문서 화면에서 최종적으로 '정기배송 신청'버튼 클릭 시 호출되는 API입니다.\
사은품 지급 가능 여부, 배송지 등록여부, 정기결제카드 등록여부 및 약관동의 여부 유효성 검사 후 정기결제를 신청합니다.\
메인카드로 사용할 카드번호를 입력하지 않으면, 회원의 가장 우선순위가 높은 카드가 메인카드로 지정됩니다.

* 카드가 등록되어있지 않거나 약관동의를 하지 않은 경우 알럿메시지를 출력해야합니다.
* 주문서 내부에서 결제하기 버튼 클릭 시, 500원인지 유효성 체크하여 알럿메시지를 출력해야합니다.

정기결제 신청 시, 서비스어드민>주문관리>정기결제(배송)신청 내역 관리 및\
고객 마이페이지> 정기배송관리> 정기배송 신청관리에 등록됩니다.

\ <br>

#### 3-1) 정기결제 주문완료 화면 <a href="#id-3-1-ec-a0-95-ea-b8-b0-ea-b2-b0-ec-a0-9c-ec-a3-bc-eb-ac-b8-ec-99-84-eb-a3-8c-ed-99-94-eb-a9-b4" id="id-3-1-ec-a0-95-ea-b8-b0-ea-b2-b0-ec-a0-9c-ec-a3-bc-eb-ac-b8-ec-99-84-eb-a3-8c-ed-99-94-eb-a9-b4"></a>

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

정기배송 신청 완료 시 신청정보 확인하는 주문완료 화면입니다.\
위에서 소개드린 `POST /recurring-payments` 정기결제 신청하기 API 응답 값을 로컬스토리지에 잠시 저장하고 있다가, 주문완료 페이지 도달 시 사용합니다. (사용 후 로컬스토리지에서 제거)\
예시 화면에서는 상품별 신청정보와 상품명 및 배송지정보(배송지 관리에서 선택한 배송지의 받는사람,주소,휴대폰번호) 등을 출력하였습니다.

\ <br>

#### 4) 마이페이지 화면 <a href="#id-4-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-ed-99-94-eb-a9-b4" id="id-4-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-ed-99-94-eb-a9-b4"></a>

\ <br>

#### 4-1) 마이페이지 > 주문목록/배송조회 <a href="#id-4-1-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-3e-ec-a3-bc-eb-ac-b8-eb-aa-a9-eb-a1-9d-eb-b0-b0-ec" id="id-4-1-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-3e-ec-a3-bc-eb-ac-b8-eb-aa-a9-eb-a1-9d-eb-b0-b0-ec"></a>

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

■ [주문 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/get-profile-orders) API 확인하기

```
GET /profile/orders
시작일 종료일 사이의 주문리스트를 조회하는 API 입니다.
```

마이페이지에서, 결제된 상품이 고객이 신청한 정기결제(배송) 상품인 경우 상품명 앞에 '정기배송 상품'임을 예시화면과 같이 출력할 수 있습니다.

참고로 매일 09시에 2일 뒤 배송 예정건에 대해 주문을 생성하므로 (ex. 정기배송 예정일이 25일이면 23일 09시에 주문생성)\
위와 같은 주문목록/배송목록은 배송예정일 2일전에 주문서 생성 시 조회할 수 있는 화면이며, 이 시점에 주문일자=결제일자로 화면이 조회됩니다.

\ <br>

#### 4-2) 마이페이지 > 정기배송 관리 > 정기배송 신청관리 <a href="#id-4-2-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-3e-ec-a0-95-ea-b8-b0-eb-b0-b0-ec-86-a1-ea-b4-80-eb" id="id-4-2-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-3e-ec-a0-95-ea-b8-b0-eb-b0-b0-ec-86-a1-ea-b4-80-eb"></a>

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

■ [정기결제 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments) API 확인하기

```
GET /recurring-payments
정기결제를 조회하는 API입니다.
```

마이페이지 내 정기배송관리 메뉴에서, 정기결제 신청내역을 확인할 수 있습니다.\
참고로 \[배송일 / 배송지 / 카드번호] 가 동일한 경우에만 같은 주문으로 생성됩니다.

<참고>\
`statusType (정기결제 상태 타입)`

* 정기결제는 1가지의 상태만 갖습니다.

ACTIVE -> 이용중\
SYSTEM\_CLOSED -> 정기결제가 불가능한 상품 등의 이유로 시스템상에서 정기결제가 해지된 경우\
ADMIN\_CLOSED -> 관리자가 정기결제를 해지한 경우\
USER\_CLOSED -> 사용자가 직접 정기결제를 해지한 경우\
ROUND\_FINISHED -> 정기결제 종료회차가 도래하여 해지된 경우\
SYSTEM\_PAUSED -> 결제실패 등의 이유로 시스템상에서 정기결제가 일시정지된 경우\
ADMIN\_PAUSED -> 관리자가 정기결제를 일시정지한 경우\
USER\_PAUSED -> 사용자가 직접 정기결제를 일시정지한 경우

\
`nextActions (다음에 할 수 있는 작업)` -

* 정기결제는 다음 값에 해당하는 작업을 할 수 있습니다.

PAUSE -> 일시정지\
RESUME -> 일시정지 해제\
SKIP -> 회차 건너뛰기\
CHANGE\_DELIVERY\_INFO -> 배송정보 변경\
CHANGE\_GIFT\_INFO -> 사은품 정보 변경\
CLOSE -> 해지하기

\
`recurringPaymentGroupNo (정기결제 신청 그룹 번호)`

* 동시에 신청한 정기결제의 경우, 동일한 신청 그룹 번호를 갖습니다.
* `GET /order-configs` 응답값이 recurringPaymentFreeGiftIssueType = RECURRING\_PAYMENT\_GROUP\_NO 인 경우에만 유효한 값입니다.

\
\
■ [정기결제 상세 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-recurring-payment-id) API 확인하기

```
GET /recurring-payments/{recurringPaymentId}
정기 결제 상세 조회 API 입니다.
```

`배송정보 변경` 레이어를 띄우기 위한 값을 내려받을 수 있습니다.<br>

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

\
■ [정기결제 배송정보 변경하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-delivery) API 확인하기

```
PUT /recurring-payments/{recurringPaymentId}/info
정기 결제 정보를 수정하는 API 입니다.
```

예시 화면 내 '배송정보 변경' 버튼 클릭 시 위와 같은 레이어를 통해 정기결제의 배송정보를 변경할 수 있습니다.\
변경을 원치 않는 정보는 null 로 요청해 주세요.\
서비스 어드민에서 정기결제 변경 히스토리를 조회할 수 있습니다.

**`1. 상품 변경`**\
상품 변경 시 새로운 배송 주기 정보도 같이 입력해야 합니다.\
상품 수정 시 변경되는 상품의 사은품으로 자동 변경됩니다.\
변경 버튼 클릭 시 [변경 가능한 정기 결제 상품 조회하기](https://docs.shopby.co.kr/?url.primaryName=product/#/Product/get-products-regular-delivery) API를 호출하여 변경가능한 상품을 보여주세요.

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

<figure><img src="/files/9f92hLkwPoyuN9hgIXzt" alt=""><figcaption></figcaption></figure>

\
**`2. 배송지 변경`**\
변경 할 정기 결제 주소지를 입력해야 합니다.\
변경 버튼 클릭 시 [배송지 목록 가져오기](https://docs.shopby.co.kr/?url.primaryName=order/#/ShippingAddress/get-profile-shipping-addresses) API를 호출하여 변경가능한 배송지를 보여주세요.

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

\
**`3. 결제 정보 변경`**\
요청한 카드가 해당 정기 결제의 메인 카드가 됩니다.\
변경 버튼 클릭 시 [정기결제 카드 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cards) API를 호출하여 변경가능한 카드를 보여주세요.

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

**`4. 배송 주기 변경`**\
정기 결제 상품에 대해 설정할 수 있는 배송 주기를 입력해야 합니다.\
위의 `정기결제 상세 조회` API 응답값의 adjustableDeliveryCycle 로 내려오는 값만 요청할 수 있습니다.

* 정기결제의 배송 주기를 변경하는 경우 변경 주기에 해당하는 날짜를 계산하여 `배송 예상일` 이 변경됩니다.
  * 정기결제 배송 주기 변경 시 이전 배송일 기준으로 변경되는 주기에 해당하는 날짜를 계산 (A)
    * 이전 배송일이 없는 경우 정기결제 최초 신청일이 기준이 됩니다.
  * (A) 가 변경일을 기준으로 배송 가능한 날짜면 해당 날짜에 배송
  * (A) 가 변경일을 기준으로 배송이 불가능하면, 변경일을 신청일로 보고 배송 예상일 계산
  * 주기 변경일이 배송 예상일이 포함된 주/달인 경우 동일한 주/달에 중복 배송되는 현상을 방지하기 위해 한 주기 이후로 계산
* 정해진 `배송 예상일`에 배송이 된 후, 새로운 배송주기로 다음 `배송 예상일`이 계산됩니다.

\
\
**`5. 종료 회차 변경`**\
정기 결제의 종료 회차를 설정하지 않으려면 0으로 보내주세요.

\
\
■ [정기결제 상태 변경](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-status) API 확인하기

```
PUT /recurring-payments/{recurringPaymentId}/status
정기결제의 상태를 변경하는 API 입니다.
```

아래와 같은 상태변경만 가능합니다.

이용중 (ACTIVE) -> 일시중지 (USER\_PAUSED)\
일시중지 (USER\_PAUSED) -> 이용중 (ACTIVE)

\
\
■ [정기결제 사은품 조회](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-recurring-payment-id-gifts) API 확인하기

```
GET /recurring-payments/{recurringPaymentId}/gifts
정기 결제 사은품을 조회하는 API 입니다.
```

사은품 정보 변경 레이어를 띄우기 위한 값을 내려받을 수 있습니다.

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

\
\
■ [정기결제 사은품 변경](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-gifts) API 확인하기

```
PUT /recurring-payments/gifts
정기 결제 사은품을 변경하는 API 입니다.
```

* 최초 정기결제 신청 시 선택할 수 있었던 사은품 중에서 선택할 수 있습니다.
* `GET /order-configs` 응답값이 recurringPaymentFreeGiftIssueType = RECURRING\_PAYMENT\_GROUP\_NO 인 경우\
  recurringPaymentGroupNo 값이 동일한 정기결제들을 동시에 요청해주세요.

\
\
■ [정기결제 회차 건너뛰기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-skip-next) API 확인하기

```
POST /recurring-payments/{recurringPaymentId}/skip/next
정기결제의 다음 회차를 건너뛰도록 설정합니다.
```

회차 건너뛰기 설정 시, 돌아오는 배송 예정일에 결제가 이루어지지 않고 회차도 증가하지 않습니다.

\
\
■ [정기결제 해지하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-close-recurring-payment-no) API 확인하기

```
PUT /recurring-payments/close/{recurring-payment-no}
정기결제를 해지 처리하는 API 입니다.
```

예시화면 내 '해지하기'버튼 클릭 시 아래와 같은 레이어를 통해 closeReasonType(해지사유)를 선택할 수 있으며,\
'해지'버튼 클릭 시 해지여부에 대한 컨펌창 호출 후 고객 최종 확인을 거쳐 상태 값이 업데이트 됩니다.

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

#### 4-3) 마이페이지 > 정기배송관리 > 결제카드관리 <a href="#id-4-3-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-3e-ec-a0-95-ea-b8-b0-eb-b0-b0-ec-86-a1-ea-b4-80-eb" id="id-4-3-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-3e-ec-a0-95-ea-b8-b0-eb-b0-b0-ec-86-a1-ea-b4-80-eb"></a>

<figure><img src="/files/7JnHItVloKE0EqCTHuP3" alt=""><figcaption></figcaption></figure>

\
\
■ [정기결제 카드 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-cards) API 확인하기

```
GET /recurring-payments/cards
정기결제 카드를 조회하는 API 입니다.
```

주문서 화면에서 이미 소개드린 API로, 등록된 카드정보를 출력합니다.\
만약 등록된 카드정보가 없을 경우 카드등록 버튼(아래 예시 참고)을 노출해야 합니다.\
카드등록은 주문서 화면의 정기결제 카드 등록 방법 (KCP, KSNET) 참고해주세요.

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

\
\
■ [정기결제 카드 우선순위 변경](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-card) API 확인하기

```
PUT /recurring-payments/card/priority
정기결제 카드의 우선순위를 변경하는 API 입니다.
```

* 모든 카드의 우선순위를 입력해야 합니다.
* 정기결제에 실패하는 경우, 카드의 우선순위에 따라 다음으로 결제를 시도할 카드가 결정됩니다.

\
\
■ [정기결제 카드 삭제하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/delete-recurring-payments-card-card-no) API 확인하기

```
DELETE /recurring-payments/card/{cardNo}
정기결제 카드를 삭제하는 API 입니다.
```

정기결제 신청 상품이 모두 해지된 경우에만 카드삭제가 가능하며,\
만약 정기결제 상품이 있는 경우 "카드 정보를 삭제하시려면 정기배송 상품을 먼저 해지해주세요"와 같은 알럿이 출력되어야합니다.

\
\
■ [정기결제 메인 카드 설정](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-card-card-no-main) API 확인하기

```
PUT /recurring-payments/card/{cardNo}/main
정기결제 메인 카드를 설정하는 API 입니다.
```

* 메인 카드는 우선순위가 1로 설정됩니다.

\
\ <br>

#### 4-4) 마이페이지 > 배송지관리 > 정기배송지 관리 <a href="#id-4-4-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-3e-eb-b0-b0-ec-86-a1-ec-a7-80-ea-b4-80-eb-a6-ac-3e" id="id-4-4-eb-a7-88-ec-9d-b4-ed-8e-98-ec-9d-b4-ec-a7-80-3e-eb-b0-b0-ec-86-a1-ec-a7-80-ea-b4-80-eb-a6-ac-3e"></a>

※마이페이지 내 정기배송지 관리화면 호출API는, 위 주문서 화면에서 이미 안내드린 내용과 동일합니다.


# \[엔터프라이즈] 정기결제(배송)               선물하기 API 화면가이드

{% code overflow="wrap" %}

```
샵바이 엔터프라이즈의 정기결제(배송) 기능과 선물하기(배송지 나중입력) 기능을 결합하여 활용할 수 있도록 기능 설명 및 활용 가능한 shop API를 안내하는 콘텐츠입니다.

해당 기능을 사용하시려면 아래 소개해드리는 API를 활용하여 별도 스킨 개발이 필요합니다.
```

{% endcode %}

### 01. 간단소개

* 샵바이 엔터프라이즈 전용
* 기능 요약
  * 정기배송 장바구니에서 선물하기가 가능합니다.
    * 종료회차를 설정한 정기배송 상품은 선물하기가 가능합니다.
    * 선물하기를 선택한 경우 선물받는 사람의 이름, 휴대폰번호만 입력합니다.
  * 선물하기 신청 완료 시 선물받는 사람의 휴대폰번호로 배송지를 입력할 수 있는 URL이 전송되어, 선물받는 사람이 직접 배송지를 등록하고 사은품을 선택할 수 있습니다. 정기결제(배송) 신청은 이용대기 상태로 생성됩니다.
  * 선물받는 사람이 배송지 입력(선물 수락) 완료 시 이용중 상태로 업데이트되며, 배송주기에 맞춰 종료 회차까지 자동으로 정기주문이 생성됩니다.
  * 선물받는 사람이 선물 정보와 정기배송 주문을 조회할 수 있도록 제공하며 정기주문 상태가 배송중, 배송완료인 경우 배송 조회도 가능합니다.
  * 선물하기 정기주
  * 문의 클레임은 주문자가 신청할 수 있습니다. 단 배송중, 배송완료인 주문의 배송 조회는 불가합니다.
  * 선물하기 정기주문도 정기배송 신청관리에서 조회 및 관리가 가능합니다. 단 배송지 정보와 사은품 정보는 수정 불가합니다.

***

### 02. 프로세스

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

***

### 03. 선물하기(배송지 나중입력) 설정

선물하기(배송지 나중입력) 기능을 사용하기 위해서는 서비스어드민에서 설정이 필요합니다.

#### <mark style="background-color:blue;">1) 정기결제(배송) 배송지 입력 URL 설정</mark>

* 경로
  * 서비스어드민 > 서비스관리 > 쇼핑몰관리 > 쇼핑몰 수정
* \[배송 설정] 영역에서 '정기결제(배송) 배송지 입력 URL'을 설정할 수 있습니다.
* '정기결제(배송) 배송지 입력 URL'은 선물받는 사람이 신청 정보(배송지 정보, 사은품 정보)를 입력할 수 있는 페이지 URL로써 '정기배송 배송지 입력 안내' 알림에 해당 URL이 포함되어 선물받는 사람에게 발송됩니다.

#### <mark style="background-color:blue;">2) 정기배송 배송지 입력 안내 자동 알림(SMS/알림톡) 설정</mark>

* 경로
  * 서비스어드민 > 운영관리 > SMS관리 > 자동 SMS설정
  * 서비스어드민 > 운영관리 > 카카오알림톡 > 알림톡 사용설정
* \[주문배송 관련] 메세지 중 '정기배송 배송지 입력 안내' 템플릿을 '사용함'으로 설정하시면 정기결제(배송) 선물하기 신청 완료 시점에 선물받는 사람에게 배송지 주소 입력 링크가 발송됩니다.
* `gift.address(배송지 주소 입력 url)`는 '정기결제(배송) 배송지 입력 URL'에 설정한 값으로 치환됩니다.

<참고>

* 신청내역은 \[서비스어드민 > 주문관리 > 정기결제(배송) 신청 관리]에서 조회가 가능합니다.
* 배송지가 입력되지 않은 정기결제(배송) 신청 건의 이용상태는 '이용대기'로 유지됩니다.
* '배송지 미입력 주문 자동취소' 기능을 설정한 경우 설정 일자 도래 시점까지 배송지가 입력되지 않은 경우 시스템 해지 처리됩니다.

#### <mark style="background-color:blue;">3) 정기배송 선물수락 완료 안내 자동 알림(SMS/알림톡) 설정</mark>

* 경로
  * 서비스어드민 > 운영관리 > SMS관리 > 자동 SMS설정
  * 서비스어드민 > 운영관리 > 카카오알림톡 > 알림톡 사용설정
* \[주문배송 관련] 메세지 중 '정기배송 선물수락 완료 안내' 템플릿을 '사용함'으로 설정하시면 정기결제(배송) 선물수락 완료 시점에 주문자와 선물받는 사람에게 알림이 발송됩니다.

#### <mark style="background-color:blue;">4) 선물 수락 개인정보 수집/이용 약관</mark>

* 경로
  * 서비스어드민 > 서비스관리 > 약관/개인정보처리방침 관리 > 개인정보 수집/동의 항목
* \[필수] 선물수락 개인정보 수집/이용 항목을 활용하여 배송지 나중 입력(선물 수락) 시 선물받는 사람에게 개인정보 수집 및 이용 동의를 수집 받을 수 있습니다.

***

### 04. API 소개 및 화면 가이드

{% hint style="success" %}
**정기결제(배송) 기본 기능 적용 방법은** [**정기결제(배송) API 화면가이드**](https://workspace-help.nhn-commerce.com/recommendedcontents/contents/recurring-payment-api)**를 참고하세요.**
{% endhint %}

#### <mark style="background-color:blue;">1) 장바구니 화면</mark>

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

■ [정기결제 주문서 작성하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments-order-sheets) API 확인하기

```
POST /recurring-payments/order-sheets
정기결제 주문을 진행할 상품정보를 전달하는 API입니다.
```

예시 장바구니 화면 내에서 하단의 \[선물하기] 버튼 클릭 시 호출하는 API로, 장바구니 목록에서 체크박스 선택된 상품을 기준으로 정기결제 주문서를 생성합니다.

예시 화면 내 각 상품 당 \[선물하기] 버튼을 클릭할 때도, 해당 상품만을 기준으로 정기결제 주문서를 생성합니다.

API 호출 시 정기결제 선물하기 여부를 `true`로 전달하여야 정기결제 선물하기 주문서로 생성됩니다.\
또한, 정기결제 선물하기의 경우 주문서 등록 시 종료 회차를 필수로 전달해 주셔야 합니다. 자세한 내용은 API 문서에서 확인하실 수 있습니다.

```
isPresent: boolean // 정기결제 선물하기 여부. true로 전달하여야 정기결제 선물하기로 주문서 등록 가능.
products[].recurringPaymentLastRound: number // 정기결제 종료 회차.
```

#### <mark style="background-color:blue;">2) 주문서 화면</mark>

**(2-1) 주문서 작성/결제 화면**

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

■ [정기결제 주문서 가져오기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-order-sheets-order-sheets-no) API 확인하기

```
GET /recurring-payments/order-sheet/{orderSheetNo}
정기결제 주문서를 조회하는 API입니다.
```

장바구니 화면에서 등록한 배송 주기, 배송일, 배송 요일, 정기결제 사은품을 출력합니다.

정기결제 선물하기 주문서의 경우, API 호출 시 정기결제 선물하기 여부를 `true`로 전달하여야 합니다.

```
isPresent: boolean // 정기결제 선물하기 여부. true로 보내야 선물하기 주문서 조회 가능.
```

■ [정기결제 신청하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments) API 확인하기

```
POST /recurring-payments
정기결제를 신청하는 API입니다.
```

주문서 화면에서 최종적으로 \[정기배송 신청] 버튼 클릭 시 호출되는 API입니다.

정기결제 선물하기의 경우 선물받는 사람 정보, 정기 결제 카드 등록 여부 및 약관 동의 여부 유효성 검사 후 정기결제를 신청합니다.

정기결제 선물하기의 선물받는 사람 정보를 넘기기 위해 다음 값을 API로 보내야 합니다. 자세한 내용은 API 문서에서 확인하실 수 있습니다.

```
receiverInfoForPresent: {
    receiverContact: string // 선물받는 사람 연락처. ex) '01012341234'
    receiverName: string // 선물받는 사람 이름. ex) '홍길동'
}
```

배송지 주소는 선물받는 사람이 입력할 정보이기 때문에 기존 배송지 정보를 보내던 `주소 번호(addressNo)`는 정기결제 선물하기일 때 값을 보내지 않도록 처리해 주시면 됩니다.

정기결제 선물하기 신청 시, 정기결제 일반 신청과 동일하게 서비스어드민 > 주문관리 > 정기결제(배송)신청 내역 관리 및 고객 마이페이지 > 정기배송관리 > 정기배송 신청관리에 등록됩니다.

**(2-2) 주문완료 화면**

<figure><img src="/files/99lpR4oDyUAvDwz2Ao3O" alt=""><figcaption></figcaption></figure>

정기결제 신청 완료 시 신청 정보를 확인하는 주문 완료 화면입니다.

정기결제 선물하기의 경우 배송지 정보에 받는사람(이름)과 휴대폰번호에 마스킹이 적용됩니다.

예시 화면에서는 받는사람(이름)과 휴대폰번호만 노출하도록 처리하였습니다.

#### <mark style="background-color:blue;">3) 마이페이지 화면</mark>

**(3-1) 마이페이지 > 정기배송관리 > 정기배송 신청관리**

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

정기결제 선물하기 신청 후 선물받는 사람이 배송지 입력을 하지 않은 경우, 이용대기 상태로 정기결제 신청 건이 추가됩니다.\
선물받는 사람이 배송지를 입력하여 선물 수락이 완료된 경우, 이용중 상태로 변경되며 배송 예정일에 맞춰 주문/배송이 진행됩니다.

■ [정기결제 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments) API 확인하기

```
GET /recurring-payments
정기결제를 조회하는 API입니다.
```

주문자는 마이페이지 내 정기배송관리 메뉴에서, 정기결제 신청 내역을 확인할 수 있습니다.

<참고>

* `statusType (정기결제 상태 타입)`
  * 정기결제 선물하는 다음의 상태 중 1가지의 상태만 갖습니다.
    * `WAITING` -> 이용대기 (선물받는 사람이 아직 정기결제 선물하기 배송지 입력을 하지 않은 경우)
    * `ACTIVE` -> 이용중
    * `SYSTEM_CLOSED` -> 정기결제가 불가능한 상품 등의 이유로 시스템상에서 정기결제가 해지된 경우
    * `ADMIN_CLOSED` -> 관리자가 정기결제를 해지한 경우
    * `USER_CLOSED` -> 주문자가 직접 정기결제를 해지한 경우
    * `ROUND_FINISHED` -> 정기결제 종료 회차가 도래하여 해지된 경우
    * `SYSTEM_PAUSED` -> 결제실패 등의 이유로 시스템상에서 정기결제가 일시정지된 경우
    * `ADMIN_PAUSED` -> 관리자가 정기결제를 일시정지한 경우
    * `USER_PAUSED` -> 주문자가 직접 정기결제를 일시정지한 경우
  * 이용대기 상태는 정기결제 선물하기에서만 사용되는 정기결제 상태입니다. 선물받는 사람이 배송지 입력을 완료한 경우 다음과 같이 변경됩니다.
    * &#x20;`WAITING(이용대기)` -> `ACTIVE(이용중)`
  * 그 외의 정기결제 상태는 일반 정기결제와 동일하게 적용됩니다.
* `nextActions (다음에 할 수 있는 작업)`
  * 정기결제 선물하기는 다음 값에 해당하는 작업을 할 수 있습니다.
    * `PAUSE` -> 일시정지
    * `RESUME` -> 일시정지 해제
    * `SKIP` -> 회차 건너뛰기
    * `CHANGE_DELIVERY_INFO` -> 배송정보 변경
    * `CLOSE` -> 해지하기
* `gifts (선택된 사은품)`

  * 정기결제 선물하기인 경우 사은품은 선물받는 사람이 선택할 수 있으며, 사은품 정보 변경 기능이 제공되지 않습니다.
  * 선물받는 사람이 배송지 입력을 하면서 선택한 사은품 혹은 서비스 어드민에서 선택한 사은품을 보여줍니다. 예시 화면에서는 사은품 조회 버튼 클릭 시 노출됩니다.
  *

  ```
  <figure><img src="/files/v1ghpIfhYgPhPJQvgoPu" alt=""><figcaption></figcaption></figure>
  ```

■ [정기 결제 상세 조회](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-recurring-payment-id) API 확인하기

```
GET /recurring-payments/{recurringPaymentId}
정기 결제 상세 조회 API 입니다.
```

배송정보 변경 레이어를 띄우기 위한 값을 내려받을 수 있습니다.

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

■ [정기 결제 배송 정보 변경](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-delivery) API 확인하기

```
PUT /recurring-payments/{recurringPaymentId}/info
정기 결제 정보를 수정하는 API 입니다.
```

예시 화면 내 \[배송정보 변경] 버튼 클릭 시 위와 같은 레이어를 통해 정기결제의 배송정보를 변경할 수 있습니다.\
변경을 원치 않는 정보는 `null` 로 요청해 주시면 됩니다.

정기결제 선물하기 이용대기 상태인 경우 결제 정보와 종료 회차만 변경 가능합니다.

정기결제 선물하기인 경우 종료 회차가 필수값이기 때문에 미설정하거나, 현재 회차보다 작은 회차로 설정할 경우 API에서 예외 처리됩니다.

배송지는 선물받는 사람이 입력한 주소로 정해지며, 주문자는 이를 변경할 수 없으므로 정기결제 선물하기인 경우 `주소 번호(addressNo)`를 `null`로 요청해 주세요.

다른 부분들은 모두 기존 정기결제 일반 신청과 동일합니다.

정기결제 배송 정보 변경 시 서비스 어드민에서 변경 히스토리를 조회할 수 있습니다.

**(3-2) 마이페이지 > 주문목록/배송조회**

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

■ [주문 리스트 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/get-profile-orders) API 확인하기

```
GET /profile/orders
시작일 종료일 사이의 주문리스트를 조회하는 API 입니다.
```

정기결제 선물하기일 때 배송중/배송완료인 경우, 주문자는 배송조회가 불가능합니다. 그 외 기본적인 내용은 정기결제 API 화면 가이드의 내용과 동일합니다.

**(3-3) 마이페이지 > 주문목록/배송조회 > 주문/배송상세**

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

■ [주문 상세 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/MyOrder/get-profile-orders-order-no) API 확인하기

```
GET /profile/orders/{orderNo}
주문번호로 상세 데이터를 조회하는 API 입니다.
```

주문목록/배송조회와 동일하게 정기결제 선물하기의 배송중/배송완료인 경우, 배송조회가 불가능하며

배송지 정보에 받는사람(이름)과 휴대폰번호에 마스킹이 적용됩니다.

예시 화면에서는 배송지 정보에 받는사람(이름)과 휴대폰번호만 노출하도록 처리하였습니다.

#### <mark style="background-color:blue;">4) 선물수락(배송지 나중입력) 화면</mark>

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

정기결제 선물하기 배송지 입력 화면 예시입니다. SMS 혹은 카카오 알림톡으로 전달받은 링크 클릭 시 이동하는 화면입니다.

■ [정기 결제 선물하기 나중 입력 배송지 정보 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-later-input-shippings) API 확인하기

```
GET /recurring-payments/later-input/shippings
정기 결제 선물하기에서 나중 입력 배송지 정보를 조회하는 API 입니다.
```

정기결제 선물하기 배송지 입력 화면에서 선물정보(주문자 정보, 정기결제 정보(상품 정보, 배송 정보, 사은품 정보, 종료회차 정보))와 배송지 정보(받는사람, 주소, 휴대폰번호, 전화번호, 배송메모), 약관 정보를 출력합니다.

<참고>

* `정기 결제 그룹번호(recurringPaymentGroupNo)`는 SMS 혹은 카카오 알림톡 발송 시 정기결제 선물하기 배송지 입력 URL 파라미터에 포함되므로 쉽게 확인할 수 있습니다.
* 이용대기 상태에서만 나중 입력 배송지 정보 조회가 가능합니다.
* `사은품 지급조건(recurringPayments[].giftCondition)`은 서비스어드민 > 상품관리 > 정기결제(배송) 상품 관리 > 사은품 설정의 지급 옵션 수량에 따라 달라지며, `정기결제 사은품 리스트(recurringPayments[].freeGifts)` 의 `사은품 선택 여부(selected)`로 선택된 사은품 여부를 알 수 있습니다.
* `선물수락 개인정보 수집/이용 동의(PI_GIFT_ACCEPT_COLLECTION_AND_USE)`를 활용하여 서비스어드민 > 서비스관리 > 약관/개인정보처리방침 관리 > 개인정보 수집/동의 항목 - 선물수락 개인정보 수집/이용 항목 내용을 출력합니다.
* 지역별 추가 배송비가 발생하여 선물하기 불가한 지역인 경우, 유효성 체크하여 알럿 메시지를 출력해야합니다.

■ [정기 결제 선물하기 나중 입력 배송지 정보 수정하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/put-recurring-payments-later-input-shippings) API 확인하기

```
PUT /recurring-payments/later-input/shippings
정기 결제 선물하기에서 나중 입력 배송지 정보를 수정하는 API 입니다.
```

사은품 정보, 비밀번호, 배송지 정보, 약관 동의 여부 유효성 검사 후 정기배송 선물 수락이 완료됩니다.

<참고>

* `정기 결제 그룹번호(recurringPaymentGroupNo)`는 SMS 혹은 카카오 알림톡 발송 시 정기결제 선물하기 배송지 입력 URL 파라미터에 포함되므로 쉽게 확인할 수 있습니다.

#### <mark style="background-color:blue;">5) 선물받은 정기배송 관리 화면</mark>

선물받는 사람이 배송지를 입력하여 선물 수락이 완료된 경우, 카카오 알림톡 혹은 SMS로 선물 보낸 분/받는 분에게 정기결제 신청그룹번호가 담긴 정기배송 선물수락 완료 안내가 발송됩니다.

**(5-1) 로그인 화면**

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

■ [정기결제 선물하기 수령자 주문 토큰 발급하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments-group-for-guest) API 확인하기

```
POST /recurring-payments/{recurringPaymentGroupNo}/guest
정기 결제 선물하기 주문 조회용 토큰을 발급하는 API 입니다.
```

예시 화면에서 \[확인] 버튼 클릭 시 요청하는 API입니다.

신청그룹번호, 이름, 비밀번호를 입력하여 토큰을 발급받습니다. 발급받은 토큰과 신청그룹번호를 이용하여 선물받은 정기배송 관리 화면에 접근 가능합니다.

신청그룹번호의 경우, 정기배송 선물수락 완료 안내 카카오 알림톡 혹은 SMS에 포함되어 쉽게 확인하실 수 있습니다.

**(5-2) 선물받은 정기배송 관리**

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

■ [정기결제 선물하기 수령자 주문 상세 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-group-for-guest) API 확인하기

```
GET /recurring-payments/{recurringPaymentGroupNo}/guest
정기 결제 선물하기 주문 상세 조회 API 입니다.
```

`guestToken`에는 위의 정기결제 선물하기 수령자 주문 토큰 발급하기 API에서 발급받은 토큰을, `recurringPaymentGroupNo`에는 신청그룹번호를 넘겨주어 선물받은 정기배송 정보를 조회할 수 있습니다.

선물정보, 배송지 정보, 주문목록/배송조회 정보를 출력합니다. 주문목록/배송조회에서 배송중/배송완료 상태의 경우, 배송조회가 가능합니다.


# \[엔터프라이즈] 정기결제(배송) 변경 동의 관리 API 화면가이드

```
샵바이 엔터프라이즈의 정기결제(배송) 변경 동의 관리 기능을 사용할 수 있도록 기능 설명 및 
활용 가능한 shop API를 안내하는 콘텐츠입니다.

해당 기능을 사용하시려면 아래 소개해드리는 API를 활용하여 별도 화면 구현작업이 필요합니다.
```

### 01. 간단소개

* 샵바이 엔터프라이즈 전용
* 기능 요약
  * 정기결제(배송) 상품의 가격 변경 시, 고객에게 변경 내용을 사전에 안내하고 동의 여부를 관리할 수 있는 기능입니다.
  * 변경된 가격으로 결제가 진행되기 전까지 변경 내용에 대한 동의 절차를 거쳐야 하며, 동의 여부는 쇼핑몰  화면에서 선택할 수 있습니다.
  * 안내된 마감기한 내 동의 시 정기결제(배송)가 변경된 가격으로 유지되며, 무응답하거나 미동의할 경우 정기결제(배송)는 자동 해지됩니다.

{% hint style="success" %}
**동의 화면 노출 경로**

* 주문서 작성 / 결제
  * 신규로 신청하는 정기배송 상품의 가격 변동이 예정되어 있을 경우
* 마이페이지 > 회원정보 > \[T]정기배송 신청관리
  * 주문목록/배송조회
    * 이용중인 정기배송 상품의 가격 변동이 예정되어 있을 경우
  * 일시정지 해제
    * 가격 변동이 예정된 정기배송 상품을 일시정지 해제하는 경우
  * 배송정보 변경
    * 가격 변동이 예정된 정기배송 상품으로 변경하는 경우
      {% endhint %}

***

### 02. API 소개 및 화면 가이드

아래 API들을 활용하여 정기결제(배송) 변경 동의 관리 기능을 활용한 화면을 구현할 수 있습니다.

#### <mark style="background-color:blue;">1) 주문서 작성/결제 화면</mark>

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

■ [정기결제 주문서 가져오기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments-order-sheets-order-sheets-no) API 확인하기

```
GET /recurring-payments/order-sheet/{orderSheetNo}
정기결제 주문서를 조회하는 API입니다.
```

* 정기결제 신청 시, 선택된 상품 중 가격 변동이 예정되어 있을 경우 사용자에게 동의 받을 화면을 구현할 수 있습니다.
* 가격 변동이 예정된 상품 데이터는 해당 API의 응답값 내 **recurringPaymentChangeAgreements** 필드에 포함되어 있습니다.

해당 응답 데이터를 활용하여 정기결제 신청 시 동의 안내 팝업창을 노출하고, 사용자의 정기결제 변경 동의여부를 수집해 주세요.

■ [정기결제 신청하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments) API 확인하기

```
POST /recurring-payments
정기결제를 신청하는 API입니다.
```

정기결제 주문서 가져오기 API의 응답으로 가져온

* 동의서 정보
* 사용자의 동의 응답

위 두 가지 정보를 **recurringPaymentChangeAgreements** 파라미터에 담아 정기결제 신청하기 API를 호출해야 합니다.

#### <mark style="background-color:blue;">2) 마이페이지 화면</mark>

**(2-1) 정기배송 신청관리 > 배송목록/조회**

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

■ [정기결제 조회하기](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/get-recurring-payments) API 확인하기

```
GET /recurring-payments
정기결제를 조회하는 API입니다.
```

* 이용중인 정기배송 상품의 가격 변동이 예정 되어 있을 경우 동의 화면을 구현할 수 있습니다.
* 가격 변동이 예정된 상품 데이터는 해당 API의 응답값 내 **recurringPaymentChangeAgreements** 필드에 포함되어 있습니다.

■ [정기결제 상품 변경 안내 응답 수집](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/patch-recurring-payments-recurring-payment-id-notices-agreement) API 확인하기

```
PATCH /recurring-payments/{recurringPaymentId}/notices/agreement
고객이 선택한 동의여부를 반영하는 API입니다.
```

* 구현된 화면에서 동의여부를 선택하면, 정기결제 변경 공지 동의/미동의 응답 제출 API를 호출하여 응답 이력을 저장 및 업데이트합니다.

**(2-2) 정기배송 신청관리 > 일시정지 해제**

<figure><img src="/files/4QDaTMFgXyrDeosHluwi" alt=""><figcaption></figcaption></figure>

■ [정기결제 상품 변경 안내 응답 수집](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/patch-recurring-payments-recurring-payment-id-notices-agreement) API 확인하기

```
PATCH /recurring-payments/{recurringPaymentId}/notices/agreement
고객이 선택한 동의여부를 반영하는 API입니다.
```

* 일시정지 해제 시 노출되는 팝업에서 동의 여부를 선택하면, 정기결제 변경 공지 동의/미동의 응답 제출 API를 호출하여 이전 응답 이력을 저장 및 업데이트합니다.

{% hint style="danger" %} <mark style="color:red;">**미동의 시에는 변경된 가격으로 정기결제를 유지하지 않는 것으로 간주되어, 이용상태가 일시정지로 유지됩니다.**</mark>
{% endhint %}

**(2-3) 정기배송 신청관리 > 배송정보 변경**

<figure><img src="/files/6x2fOdPefjKArECVDA2J" alt=""><figcaption></figcaption></figure>

■ [정기결제 상품 변경 안내 조회](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/post-recurring-payments-recurring-payment-id-notices-search) API 확인하기

```
POST /recurring-payments/{recurringPaymentId}/notices/search
상품의 정기결제 가격 변경 동의 등록여부를 조회하는 api 입니다.
```

* 가격변동이 예정된 정기배송 상품으로 변경하는 경우 동의 화면을 구현할 수 있습니다.
* 가격 변동이 예정된 상품 데이터는 정기결제 변경 안내 대상 조회 API를 통해 가져올 수 있습니다.

■ [정기결제 상품 변경 안내 응답 수집](https://docs.shopby.co.kr/?url.primaryName=order/#/RecurringPayment/patch-recurring-payments-recurring-payment-id-notices-agreement) API 확인하기

```
PATCH /recurring-payments/{recurringPaymentId}/notices/agreement
고객이 선택한 동의여부를 반영하는 API입니다.
```

* 상품 변경 시 노출되는 팝업에서 동의여부를 선택하면, 정기결제 변경 공지 동의/미동의 응답 제출 API를 호출하여 이전 응답 이력을 저장 및 업데이트합니다.

{% hint style="danger" %} <mark style="color:red;">**미동의 시에는 변경된 가격으로 정기결제를 유지하지 않는 것으로 간주되어, 선택한 상품으로 변경되지 않습니다.**</mark>
{% endhint %}


# \[프로/엔터프라이즈] 쇼핑몰에 인스타그램 위젯을 적용해보세요!

&#x20;업데이트 일자: 2022. 04. 25<br>

```
[API 소개]

최근 업데이트된 주요 API에 대해 소개하고 
해당 API에 대한 문의나 활용 방법을 함께 논의하기 위해 작성된 콘텐츠 입니다. 
활용 시 쇼핑몰 매출 상승에 임팩트가 있는 API를 중점적으로 소개할 예정입니다. 

앞으로도 지속적으로 API 관련 콘텐츠를 업로드할 예정이니
API에 대해 더 궁금한 점을 아래 댓글을 통해 알려주시면, 다음 콘텐츠에 반영될 수 있습니다.
```

<br>

#### 인스타그램 위젯기능 및 API <a href="#ec-9d-b8-ec-8a-a4-ed-83-80-ea-b7-b8-eb-9e-a8-ec-9c-84-ec-a0-af-ea-b8-b0-eb-8a-a5-eb-b0-8f-api" id="ec-9d-b8-ec-8a-a4-ed-83-80-ea-b7-b8-eb-9e-a8-ec-9c-84-ec-a0-af-ea-b8-b0-eb-8a-a5-eb-b0-8f-api"></a>

#### 01. 간단 소개 <a href="#ea-b0-84-eb-8b-a8-ec-86-8c-ea-b0-9c" id="ea-b0-84-eb-8b-a8-ec-86-8c-ea-b0-9c"></a>

* 기능 요약\
  쇼핑몰 인스타그램 계정을 생성 후, 인스타그램 연동을 하면 게시물을 쇼핑몰에 노출 시킬 수 있습니다.<br>
* 기능 추가 방법\
  \- 샵바이 프로: 어드민> 설정> 기본정책> 외부서비스 설정 내 각 쇼핑몰 별로 연동 가능\
  \- 샵바이 프리미엄: 서비스 어드민 > 서비스관리 > 쇼핑몰 관리 > 서비스 수정 페이지에서 각 쇼핑몰 별로 설정 가능\
  (참고: [인스타그램 위젯 기능 추가 안내](https://www.nhn-commerce.com/customer/patch-view.gd?sno=4023))\ <br>
* 왜 만들었을까?\
  인스타그램 기반으로 성장한 인플루언서 쇼핑몰이거나, 인스타그램 소통이 활발한 쇼핑몰에서 핵심적인 기능입니다.\
  쇼핑몰 브랜딩 특색을 나타낼 수 있는 것은 물론, 인스타그램 계정을 노출하여 팔로우 수를 늘릴 수 있습니다.\
  인스타그램 해당 포스팅으로 즉시 링크 이동이 가능하므로, 구매 욕구를 상승시키는 인스타그램 피드나 이벤트 마케팅, 사용자 리뷰 등을 노출할 수 있습니다.\
  스킨(skin) 커스텀 시 중요도가 높은 매출상승 관련 API입니다.

<br>

<br>

▼ PC화면 예시<br>

![](https://rlyfaazj0.toastcdn.net/20220425/114358.431967000/image.png)

▼ 모바일화면 예시

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

#### 02. API 소개 <a href="#api-ec-86-8c-ea-b0-9c" id="api-ec-86-8c-ea-b0-9c"></a>

■ [instagram 피드 조회 API 바로 확인하기](https://docs.shopby.co.kr/?url.primaryName=manage/#/Instagram/get-instagram-media)&#x20;

```
GET /shopby/instagram/media 
위젯을 통해 인스타그램 피드(게시글 목록)을 조회하는 API입니다.
```

위 하이퍼링크를 통해 API 문서를 직접 확인해보세요. 해당 API의 파라미터, 응답 값 등 상세 내용을 확인할 수 있습니다.\
이 중 일부 추가 설명이 필요한 응답 값에 대해서 아래 안내 드립니다.

\
■ 응답 값(Responses) 소개\
→  해당 API는 페이스북과 통신한 API 값을 가공 없이 내려주고 있습니다.\
&#x20;   (참고: <https://developers.facebook.com/docs/instagram-basic-display-api/reference/media?locale=ko_KR>)\ <br>

* `media_type`: 미디어 유형으로 IMAGE(이미지), VIDEO(동영상),  CAROUSEL\_ALBUM(스와이프를 통한 여러 사진 또한 동영상 포스팅) 유형으로 응답됩니다.\
  &#x20; 인스타그램 릴스(Reels, 15분 미만의 짧은 동영상 포스팅)의 경우 현시점에서는 페이스북에서 응답 값으로 제공하고 있지 않습니다.\
  &#x20; IPTV 역시 제공되지 않습니다.
* `media_url`: 해당 미디어의 위치 URL입니다.
* `permalink`: 인스타그램 개별 포스팅 링크로, 쇼핑몰에서 개별 포스팅 클릭 시 해당 포스팅으로 링크 이동합니다.\ <br>

■ [API 호출 URI](https://shopby.works/guide/dev-cover/call-api?lv=6)\
\- 잠깐, 만약 샵바이 API를 어떻게 호출하는지 모른다면 위 가이드 문서부터 참고해보세요.

\ <br>

#### 03. 꼭 참고해주세요 <a href="#ea-bc-a-d-ec-b0-b8-ea-b3-a0-ed-95-b4-ec-a3-bc-ec-84-b8-ec-9a-94" id="ea-bc-a-d-ec-b0-b8-ea-b3-a0-ed-95-b4-ec-a3-bc-ec-84-b8-ec-9a-94"></a>

* 페이스북 비지니스 계정이 아닌 개인 계정도 연동 가능합니다.
* 쇼핑몰에 연동된 인스타그램 썸네일 클릭 시 해당 게시물 URL로 새 창 링크 이동됩니다.
* 이미지 캐시의 경우 1시간마다 자동 갱신됩니다. 인스타그램에 게시한 포스팅이 즉시 쇼핑몰에 적용되지 않더라도 놀라지 마세요!\ <br>
* 스킨 패치 (샵바이프로)\
  NHN커머스에서 직접 관리하는 기본 스킨(스킨명:Another)이 아닌, 고객사/외부 에이전시를 통해 자유롭게 커스텀된 스킨의 경우\
  스킨 내 변경 소스가 적용되지 않습니다.\
  따라서 샵바이프로는 샵바이프리미엄과 다르게 스킨을 통해 해당 기능이 제공되므로 스킨패치가 필요합니다. (ZIP, GIT방식 모두 동일합니다.)
* 스킨 패치(skin patch)란: 쇼핑몰 기능 개선/신규 기능 추가에 따른 쇼핑몰 스킨을 업데이트를 의미합니다. \
  NHN커머스 쇼핑몰은 각각의 쇼핑몰 특성에 맞게 자유롭게 디자인 작업을 진행하여 운영되기 때문에, 시각적으로 표현되는 쇼핑몰 스킨을 일괄적으로 수정할 수 없습니다. 따라서 스킨패치는 필요에 따라 운영자가 직접 진행해야 합니다.\ <br>
* 스킨 패치 소스와 내용에 대해서는  `샵바이 스킨 패치 릴리즈 노트` 링크를 참고하시길 바랍니다.\
  ■ [샵바이 스킨 패치 릴리즈 노트](https://gitlab-themes.shopby.co.kr/nhn-commerce-fe/releases/shopby-pro-easy-skin/-/releases/v1.1.0) \ <br>
* 샵바이 프로 \
  \- 인스타그램에 등록된 게시글이 12개 미만일 시, 등록된 게시글만큼 위젯에 출력됩니다.\
  \- 아래와 같은 case에서, 쇼핑몰 화면 내 인스타그램 위젯 영역이 자동으로 숨김처리 됩니다.\
  ① 유효하지 않은 토큰 및 통신오류로 인한 에러 발생 시\
  ② 관리자가 직접 어드민에서 연동해제 시\
  ③ 게시글이 없는 인스타그램 계정이 연동될 시\ <br>
* 샵바이 프리미엄\
  \- 샵바이프로와 달리 샵바이프리미엄은, 위와 같은 case의 처리방식을 각 고객사/개발사의 개발 과정에서 자유롭게 구현 가능합니다.

<br>

<br>

#### 04. API 활용 방법 <a href="#api-ed-99-9c-ec-9a-a9-eb-b0-a9-eb-b2-95" id="api-ed-99-9c-ec-9a-a9-eb-b0-a9-eb-b2-95"></a>

\
현재 샵바이프로에서 제공하는 인스타그램 위젯을 자유롭게 변형하여 스킨(skin)을 수정해보세요.

\
기본 스킨에서는 인스타그램 위젯을 PC(6\*2) / 모바일 (3\*4)로 노출하고 있으나,  그리드 모양을 변형하거나 '더보기'를 통해 감추기를 구현하는 등 자유롭게 수정 가능합니다.  (인스타그램 포스팅 노출 개수에는 제한이 없습니다.)\
API를 통한 노출 영역 위치도 자유롭게 수정 가능합니다.

\
스킨 코드 관련해서 아래 내용을 참고하실 수 있습니다!\
위에서 소개드린 샵바이프로의 [스킨패치 릴리즈노트](https://gitlab-themes.shopby.co.kr/nhn-commerce-fe/releases/shopby-pro-easy-skin/-/releases/v1.1.0)에서\
'업데이트 내용'으로 들어가서 코멘트나 'Changes'를 확인하면 스킨 코드를 수정하는데 도움을 받으실 수 있을 거에요.

\ <br>

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

`width : 16.6666%` 속성은 한 열에 콘텐츠를 몇의 비율로 표시할지 결정합니다.\
한 열에 6개의 콘텐츠가 아닌 4개의 콘텐츠를 표시하고자 할 경우 뷰포트의 너비 100% 를 4로 나눈 `width: 25%` 로 표기합니다.

<br>

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

연동된 인스타그램의 콘텐츠 개수(`data.length`)가 0 이라면 인스타그램 콘텐츠 섹션 자체를 렌더링하지 않습니다.

![](https://rlyfaazj0.toastcdn.net/20220425/120406.788490000/image.png)

`this.getHTMLTemplate()` 의 두번째 인자는 몇 개의 콘텐츠를 슬라이스해서 사용할지 결정합니다.\
가령 이 값이 16이라면 콘텐츠가 16개 이상일 때 16개의 인스타그램 콘텐츠 템플릿을 생성합니다.\
존재하는 인스타그램 연동 콘텐츠의 개수가 16 미만이라면, 존재하는 콘텐츠의 개수만큼 인스타그램 콘텐츠 템플릿을 생성합니다.


# \[베이직/프로] 카카오싱크 신청 가이드

솔루션에 카카오싱크 간편 가입 기능 연동을 어떻게 할 수 있는지 안내하기 위한 콘텐츠입니다.

## 간단소개

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

***

## 카카오싱크 신청&설정 방법 <a href="#undefined" id="undefined"></a>

#### ① 카카오싱크 연동 전 참고 사항

* 솔루션에서 카카오 로그인을 사용 중이었던 경우, 반드시 kakao developers에 접속하시어\ <mark style="color:red;">**내 애플리케이션> 카카오싱크를 연결할 앱> 보안> Client Secret> 활성화 상태를**</mark><mark style="color:red;">**&#x20;**</mark><mark style="color:red;">**`사용안함`**</mark><mark style="color:red;">**&#x20;**</mark><mark style="color:red;">**또는 삭제 처리**</mark>해 주시기 바랍니다.

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

* 카카오싱크를 연동하기 위해서는 솔루션 서비스어드민 내 필수 정보 설정이 필요합니다.

**\[카카오싱크 설정 관련 메뉴]**

* 설정> 기본정책> 기본정보 (회사명, 대표자명, 사업자등록번호, 업태, 업종, 사업장 주소)

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

* 설정> 기본정책> 약관/개인정보처리방침 관리

  * 이용약관

  <figure><img src="/files/46uUTOxhz0VNyvPAZHq4" alt=""><figcaption></figcaption></figure>

  * 개인정보 수집/동의 항목
    * 회원가입 시 개인정보 수집/이용 항목\[필수/선택], 개인정보 처리/위탁, 개인정보 제3자 제공

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

***

#### ② 카카오싱크 앱 설치 방법

* 워크스페이스> 앱스토어에 접속 후 \`카카오싱크\` 앱 "설치하기" 버튼을 클릭합니다. [앱스토어 바로가기> ](https://apps.godo.co.kr/apps/255)

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

* 로그인 후 설치를 원하시는 쇼핑몰을 선택하고 "설치" 버튼을 클릭합니다.

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

* 이용 동의 항목을 확인 후 "동의 및 앱 실행" 버튼을 클릭합니다.

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

***

#### ③ 카카오싱크 앱 설정 방법

* 1\) 카카오싱크 앱 설치 완료 후 앱 서비스> 앱 리스트에 설치된 카카오싱크 앱 "실행" 버튼을 클릭합니다.

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

* 2\) 카카오싱크 설정 팝업이 출력되면, "카카오싱크 연동" 버튼을 클릭합니다.

<figure><img src="/files/8e94X5fdnt1SfBSQE0nt" alt=""><figcaption></figcaption></figure>

* 3\) 사용할 카카오 계정으로 로그인합니다.

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

* 4\) 안내문을 확인하신 후 "동의하고 계속" 버튼을 클릭하여 카카오싱크 간편 설정을 진행합니다.

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

* 5\) 기존에 등록되어 있는 디밸로퍼스 앱이 없는 경우 새로운 앱을 생성합니다.

{% hint style="info" %}

* 기존 카카오 간편가입(로그인)을 사용 중인 경우 기존에 사용하고 있는 디벨로퍼스 앱을 동일하게 사용해 주세요.

  다른 앱으로 연동을 진행할 경우 기존 카카오 간편가입(로그인) 회원은 로그인할 수 없으며, 신규 회원으로 가입 처리됩니다.
* 쇼핑몰 이전 시 반드시 테스트용 디밸로퍼스 앱을 생성하시어 사전 테스트 진행 부탁드립니다.\
  테스트 완료 시 회원 DB 마이그레이션 작업이 필요하며, 마이그레이션 작업 완료 후 이전 쇼핑몰에서 사용하고 있던 디밸로퍼스 앱을 연결합니다. (마이그레이션 별도 요청 필요)
  {% endhint %}

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

> **쇼핑몰 정보 항목**
>
> * 쇼핑몰 로고: 가이드에 맞는 쇼핑몰 로고 이미지를 등록합니다.
> * 쇼핑몰, 회사 이름: 서비스 어드민에 등록된 정보가 출력됩니다.

* 6\) 카카오싱크에 연결할 채널을 선택하거나, 신규 채널을 생성합니다.
  * 이미 생성된 채널을 연결하려면 해당 채널 선택 후 "다음"버튼을 클릭합니다.

<figure><img src="/files/4YLW0Edrq4dQ2UiAulxe" alt=""><figcaption></figcaption></figure>

* 7\) 카카오 간편 가입 동의 화면에 노출할 카카오톡 채널 정보를 입력합니다.

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

> **카카오톡 채널 정보 항목**
>
> * 프로필 사진: 가이드에 맞는 채널의 프로필 사진을 등록합니다.
> * 채널 이름: 서비스 어드민에 등록된 쇼핑몰 명이 출력됩니다.
> * 검색용 아이디: 쇼핑몰의 카카오톡 채널을 검색할 때 사용되는 쇼핑몰 채널의 고유 아이디입니다.\
>   (쇼핑몰 채널의 고유 아이디이기 때문에 동일 아이디 생성은 불가합니다.)
> * 카테고리: 쇼핑몰에 맞는 카테고리를 설정합니다.

* 8\) 설정하고자 하는 디밸로퍼스 앱과 카카오톡 채널 정보가 맞는지 확인 후 "완료" 버튼을 클릭합니다.

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

* 9\) 카카오싱크 설정을 완료합니다.

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

***

**④ 카카오싱크 설정 확인**

* 카카오싱크 설정 완료 시 Rest API Key 값이 자동으로 입력됩니다.

<figure><img src="/files/9JXQmkO4gVp8qAFPlWnA" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
카카오싱크 설정까지 완료하신 경우 쇼핑몰 화면에서 카카오싱크를 통해 간편가입이 가능합니다.
{% endhint %}


# \[웹훅 추가] 주문정보 웹훅(Webhook)이란?

```
샵바이에서 제공하는 웹훅(WebHook)에 대해 안내하기 위한 콘텐츠입니다.
업데이트 : 2023.10.25
```

### 목차 <a href="#eb-aa-a9-ec-b0-a8" id="eb-aa-a9-ec-b0-a8"></a>

1\. 웹훅(WebHook)이란\
2\. 주문정보 웹훅이란\
&#x20;   -2.1. 주문생성 웹훅\
&#x20;   -2.2. 주문상태 변경 웹훅\
3\. 사용 요청 어떻게 하나요?

### 1. 웹훅(WebHook)이란 <a href="#id-1.-ec-9b-b9-ed-9b-85-webhook-ec-9d-b4-eb-9e-80" id="id-1.-ec-9b-b9-ed-9b-85-webhook-ec-9d-b4-eb-9e-80"></a>

* 개념설명\
  서버에서 특정 이벤트 발생 시 외부서버로 정보를 알릴 수 있는 매커니즘입니다.\
  Webhook은 서버에서 이벤트 발생 시 외부서버에서 미리 지정해놓은 callback URI에 POST HTTP로 이벤트 관련 정보를 보냅니다.\
  따라서 외부서버 입장에서는 지속적으로 데이터를 폴링(polling)하여 불필요한 정보를 받는 대신, Webhook을 활용하여 중요 이벤트가 발생했을 때만 정보를 수신하여 처리할 수 있습니다.

\ <br>

* shopby에서 제공하는 웹훅은?\
  shopby에서는 아래 안내드릴 '주문정보 웹훅'을 제공하고 있습니다.

### 2. 주문정보 웹훅이란? <a href="#id-2.-ec-a3-bc-eb-ac-b8-ec-a0-95-eb-b3-b4-ec-9b-b9-ed-9b-85-ec-9d-b4-eb-9e-80-3f" id="id-2.-ec-a3-bc-eb-ac-b8-ec-a0-95-eb-b3-b4-ec-9b-b9-ed-9b-85-ec-9d-b4-eb-9e-80-3f"></a>

* 요약\
  shopby에서 `1) 새로운 주문이 발생하거나` `2) 주문의 상태가 변경될 때`\
  상태가 변경된 주문의 정보를 `웹훅을 통해` 등록된 고객사의 외부 URI로 알려주는 REST API call입니다.

<br>

* 지원 가능한 method: `POST / PUT`
* 웹훅 발행시점\
  주문정보 웹훅에는 아래 2가지 유형의 이벤트가 있습니다.

1. `주문 생성`\
   → 고객이 주문을 최초 생성했을 때 생성된 주문의 정보를 웹훅을 통해 전달
2. `주문상태 변경`\
   → 주문상태(orderStatusType) 또는 클레임상태(claimStatusType)가 변경되었을 때 정보를 웹훅을 통해 전달

![](https://rlyfaazj0.toastcdn.net/20220607/180941.376212000/image.png)\ <br>

* 주문 상태 (orderStatusType)\
  주문생성 또는 주문상태 변경 웹훅 Request Body 내 주문상태(orderStatusType)에 포함된 코드는 아래와 같습니다.

| 구분    | 주문상태코드            | 한글명   | 비고                            |
| ----- | ----------------- | ----- | ----------------------------- |
| 정상상태  | DEPOSIT\_WAIT     | 입금대기  | 무통장, 가상계좌 거래인 경우 입금 전 상태      |
| 정상상태  | PAY\_DONE         | 결제완료  | 결제를 완료한 상태                    |
| 정상상태  | PRODUCT\_PREPARE  | 상품준비중 | 상품을 보낼 준비를 하는 boxing 단계       |
| 정상상태  | DELIVERY\_PREPARE | 배송준비중 | 송장번호를 할당하는 단계                 |
| 정상상태  | DELIVERY\_ING     | 배송중   | 택배를 보낸 상태                     |
| 정상상태  | DELIVERY\_DONE    | 배송완료  | 택배가 도착한 상태                    |
| 정상상태  | BUY\_CONFIRM      | 구매확정  | 고객이 구매확정 했거나, 구매확정이 자동완료 된 상태 |
| 클레임상태 | CANCEL\_DONE      | 취소완료  | 배송 전 취소 신청하여 환불이 완료된 상태       |
| 클레임상태 | RETURN\_DONE      | 반품완료  | 배송 후 반품되어 환불이 완료된 상태          |
| 클레임상태 | EXCHANGE\_DONE    | 교환완료  | 교환이 완료된 상태                    |

\* 클레임상태(claimStatusType)에 포함된 코드는 [회원 클레임 목록 조회하기 API](https://docs.shopby.co.kr/?url.primaryName=claim/#/Member/get-profile-claims:~:text=%ED%81%B4%EB%A0%88%EC%9E%84%EC%83%81%ED%83%9C%20\(nullable\)-,Enum%3A,-%5B%20CANCEL_NO_REFUND%3A%20Cancel)에서 claimStatusType Eunm에 표시된 코드를 참고해 주시기 바랍니다.

### 2.1 주문생성 <a href="#id-2.1-ec-a3-bc-eb-ac-b8-ec-83-9d-ec-84-b1" id="id-2.1-ec-a3-bc-eb-ac-b8-ec-83-9d-ec-84-b1"></a>

* 발행 시점\
  주문발생 시 (`입금대기` 또는 `결제 완료`)\
  단 배송 없이 주문되는 상품일 경우, 주문생성과 동시에 `배송완료(DELIVERY_DONE)`로 처리됩니다.
* '(2-2) 주문상태 변경 웹훅'과 차이점
  * 주문생성 웹훅은 주문단위로, 여러 개의 주문 상품과 각 주문상품 내 여러 옵션이 하나로 묶여서 처리됩니다.
  * Request Body에 결제정보 관련 주문 정보를 함께 전달합니다.
* Request Body

{% code overflow="wrap" %}

```
{
    "eventType": "CREATE_ORDER", //이벤트명
    "order": {
            "orderNo": "2021100201234567890", // 주문번호
            "mallNo": 30973, // 몰번호
            "serviceNo": 30388, // 서비스 번호
            "memberNo": 8411244, // 회원번호
            "memberYn": "Y", // 회원여부
            "ordererName": "홍길동", // 주문자명
            "ordererContact1": "010-1234-1234", // 주문자 핸드폰 번호
            "ordererContact2": "010-1234-1234", // 주문자 전화 번호
            "ordererEmail": "[honggildong@naver.com](mailto:honggildong@naver.com)", // 주문자 이메일
            "payType": "CREDIT_CARD", // PG타입(페이코/KCP 등)
            "pgType": "KCP", // 결제타입(페이코/신용카드 등)
            "platformType": "MOBILE_WEB", // 플렛폼 타입 (PC/MOBILE_WEB 등)
            "lastPayAmt": 185000.00, // 최종결제금액
            "lastSubPayAmt": 0.00, // 최종 적립금 결제금액
            "lastStandardAmt": 329000.00, // 최종상품금액(할인제외)
            "lastDeliveryAmt": 0.00, // 최종배송금액
            "lastRemoteDeliveryAmt": 0.00, // 최종지역별추가배송금액
            "lastImmediateDiscountAmt": 144000.00, // 최종즉시할인금액
            "lastAdditionalDiscountAmt": 0.00, // 최종추가할인금액
            "lastCartCouponDiscountAmt": 0.00, // 최종주문쿠폰할인금액
            "lastProductCouponDiscountAmt": 0.00, // 최종상품쿠폰할인금액
            "lastTaxFreeAmt": 0.00, // 최종비과세금액
            "lastTaxableAmt": 168181.00, // 최종과세금액
            "lastVatAmt": 16819.00, // 최종부과세액
            "firstSalesTaxAmt": 0.00, // 최초부과세액
            "lastSalesTaxAmt": 0.00, // 최종부과세액
            "firstCustomsDutyAmt": 0.00, // 최초관부가세
            "lastCustomsDutyAmt": 0.00, // 최종관부가세
            "registerYmdt": "2021-10-25 13:53:18", // 등록일
            "trackingKey": "trackingKey", // 쇼핑채널링-추적키
            "cartCouponIssueNo": 12, // 장바구니쿠폰 발급 번호
            "extraData": "", // 추가 정보
            "orderProducts": [
                    {
                            "orderProductNo": 50000000, // 주문상품번호
                            "mallProductNo": 100000000, // 상품번호
                            "productName": "상품명",
                            "productManagementCd": "", // 상품관리 코드
                            "hsCode": "",
                            "eanCode": null,
                            "partnerNo": 50000, // 파트너 번호
                            "lastProductCouponDiscountAmt": 0.00, // 상품 쿠폰 할인액
                            "productCouponIssueNo": 13, // 사용한 상품 쿠폰 번호
                            "orderProductOptions": [
                              {
                                "orderProductOptionNo": 5062925, // 주문상품옵션번호
                                "orderNo": "2021100201234567890", // 주문번호
                                "memberNo": 100000, // 회원번호
                                "serviceNo": 30000, // 서비스 번호
                                "mallNo": 1000, // 몰번호
                                "mallProductNo": 10000000, // 상품번호
                                "productName": "상품명",
                                "mallOptionNo": 6000000, // 상품옵션번호
                                "mallAdditionalProductNo": 0, // 추가 상품 번호
                                "optionUseYn": "Y", // 옵션 사용 여부
                                "optionName": "옵션명",
                                "optionValue": "옵션값",
                                "imageUrl": "//rlyfaazj0.toastcdn.net/...", // 상품 이미지 url
                                "orderCnt": 1, // 주문건수
                                "originalOrderCnt": 1, // 최초 주문 수량
                                "salePrice": 329000.00, // 판매 가격
                                "immediateDiscountAmt": 144000.00, // 즉시 할인 가격
                                "addPrice": 0.00, // 추가 금액
                                "additionalDiscountAmt": 0.00, // 추가 할인 금액
                                "partnerChargeAmt": 0.00, // 파트너 부담액
                                "adjustedAmt": 185000.00, // 조정된 상품 금액
                                "orderStatusType": "PAY_DONE", // 주문옵션상태
                                "claimStatusType": null, // 클레임 상태
                                "orderYmdt": "2021-10-25 13:53:18", // 주문일시
                                "payYmdt": "2021-10-25 13:54:38", // 결제일시
                                "orderAcceptYmdt": null, // 주문접수일시
                                "releaseReadyYmdt": null, // 배송준비일시
                                "releaseYmdt": null, // 배송일시
                                "deliveryCompleteYmdt": null, // 배송완료일시
                                "buyConfirmYmdt": null, // 구매확정일시
                                "registerYmdt": "2021-10-25 13:53:18", // 주문옵션 생성일시
                                "trackingKey": "platform=MO&rid=851184319&aid=641_1_3_1025&mid=TMS", // 주문추적키 (쇼핑몰에서 생성되어 주문번호를 특정하는 구분값)
                                "deliveryNo": 400000, // 배송번호
                                "optionManagementCd": "", // 옵션 관리 코드
                                "isFreeGift": false, // 사은품 여부
                                "deliveryTemplateNo": 50000, // 배송 템플릿 번호
                                "deliveryCompanyType": "CJ", // 배송 업체
                                "invoiceNo": null, // 송장번호
                                "receiverName": "홍길동", // 받는 사람 이름
                                "usesShippingInfoLaterInput": false, // 나중배송지 입력 여부
                                "shippingInfoLaterInputContact": null, // 나중배송지 입력 전화 번호
                                "encryptedShippingNo": null, // 나중배송지 입력 시 사용하는 암호화된 배송번호
                                "shippingEmptAutoCancelYmdt" : "2023-10-25 13:54:38", // 배송지 미입력 시 자동 주문취소 일시
                              }
                            ]
                    }
            ]
    },
    "pay": {
            "pgType": "KCP", // PG 타입
            "payType": "CREDIT_CARD", // 결제 유형
            "payYmdt": "2021-10-25 13:54:38", // 결제일시
            "payStatusType": "DONE", // 결제상태
            "payInfoJson": null, // 결제 정보 JSON
            "payInfo": {
                    "payType": "CREDIT_CARD", // 결제 유형
                    "cardInfo": {
                            "cardCompany": "SHINHAN", // 카드사
                            "cardCode": "CCLG", // PG 카드사 코드(PG별로 다름)
                            "cardName": "신한카드", // 카드사명
                            "approveYmdt": "2021-10-25 13:54:38", // 결제승인시간
                            "cardNo": "*****", // 카드번호
                            "cardApprovalNumber": "****", // 결제승인번호
                            "noInterest": true, // 무이자여부
                            "installmentPeriod": 5, // 할부기간
                            "cardAmt": 185000 // 신용카드 결제금액
                    },
                    "bankInfo": {
                            "bank" : "KDB", // 은행
                            "bankCode": "", // PG 은행코드 (PG별로 다름)
                            "bankName": "", // 은행명
                            "account": "", // 계좌번호
                            "bankAmt": 1000, // 입금해야할 금액
                            "depositAmt": 1000, // 실제 입금금액
                            "depositYmdt": "2021-10-25 13:54:38", // 입금일시
                            "remitterName": "", // 입금자명
                            "depositorName": "", // 예금주명
                            "paymentExpirationYmdt": "2021-10-25 13:54:38" // 입금 마감일
                    },
                    "cashAuthNo": "", // 현금영수증 승인번호
                    "cashNo": "", // 현금영수증 거래번호
                    "tradeNo": "3000000", // 거래번호
                    "escrowYn": "N", // 에스크로 결제 여부
                    "payAmt": 185000, // PG결제 금액
                    "sellerCouponAmt": 0, // 가맹점 발행쿠폰
                    "pgCouponAmt": 0, // PG 쿠폰 금액
                    "cardCouponAmt": 0, // 카드사 쿠폰 금액
                    "pointAmt": 0, // PG 포인트
                    "paymentKey": {
                            "pgType": "KCP", // PG 유형
                            "key": "key", // PG Key
                            "etcInfos": {} // 기타 결제 키 관련 정보
                    },
                    "taxType": "DUTY", // 과세유형 (과세,면세,영세)
                    "mobileInfo": { // 핸드폰 결제 정보
                    "mobileNo": "010-1234-5678", // 결제 핸드폰 번호
                    "mobileCompany": "" // 통신사
                    },
                    "naverPayInfo": { // 네이버 페이 결제 정보
                            "paymentMeans": "", // 네이버 페이 결제 수단
                            "paymentDueDate": "", // 입금 기한
                            "paymentNumber":"", // PG승인번호
                            "orderDiscountAmount": 1000, // 주문 할인액
                            "generalPaymentAmount": 1000, // 일반결제수단최종결제금액
                            "naverMileagePaymentAmount": 1000, // 네이버페이 포인트 최종 결제 금액
                            "chargeAmountPaymentAmount": 1000, // 충전금최종결제금액
                            "checkoutAccumulationPaymentAmount": 1000, // 네이버페이 적립금 최종 결제 금액
                            "orderType": "", // 주문 유형 구분(네이버페이/통합장바구니)
                            "payLocationType": "", // 결제 위치 구분(PC/MOBILE)
                            "paymentCoreType": "", // 결제 구분(네이버결제/PG 결제)
                            "payLaterPaymentAmount": 1000 // 후불결제 금액(네이버결제/PG 결제)
                    },
                    "recurringPaymentCycleDate": 15, // 정기결제 주기 일자
                    "rentalInfo": { // 렌탈 정보
                            "rentalPeriod": 1, // 렌탈 기간
                            "monthlyRentalAmount": 0.00, //월 렌탈료
                    },
                    "complexPayInfo": { // 복합결제 정보
                            "complexPayId": null, // 복합결제 키
                            "extraPayAmt": 0.00, // 추가 결제 금액
                            "mainPayAmt": 0.00, // 메인 결제 금액
                    }
            }
    }
}
```

{% endcode %}

### 2.2 주문상태변경 <a href="#id-2.2-ec-a3-bc-eb-ac-b8-ec-83-81-ed-83-9c-eb-b3-80-ea-b2-bd" id="id-2.2-ec-a3-bc-eb-ac-b8-ec-83-81-ed-83-9c-eb-b3-80-ea-b2-bd"></a>

* 발행 시점\
  주문상태 변경이나 클레임 상태 변경 시
* '(2-1) 주문생성 웹훅'과 차이점
  * 주문상태 변경 웹훅은 주문단위가 아닌 주문상품 옵션단위로 처리됩니다.

#### Request Body <a href="#request-body" id="request-body"></a>

{% code overflow="wrap" %}

```
[{
    "eventType": "CHANGE_ORDER_STATUS", //이벤트명
    "orderProductOptionNo": 12345, // 주문상품 옵션번호
    "orderNo": "202110110111111", // 주문번호
    "memberNo": 12345, // 회원번호
    "userInputs": [  // 구매자 입력형 옵션
      {
        "inputLabel":"색깔", //구매자 작성형 옵션 이름
        "inputValue":"검정색", //구매자 입력형 옵션 값
      }
    ],
    "serviceNo": 12345, // 서비스번호
    "mallNo": 12345, // 몰번호
    "deliveryNo": 12345, // 배송번호
    "deliveryTemplateNo": 50000, // 배송 템플릿 번호
    "deliveryInternationalYn":false, // 해외배송여부
    "mallProductNo": 100000000, // 상품번호
    "productName": "상품명",
    "mallOptionNo": 6000000, // 상품옵션번호
    "optionUseYn": "Y", // 옵션 사용 여부
    "optionName": "옵션명",
    "optionValue": "옵션값",
    "imageUrl": "//rlyfaazj0.toastcdn.net/...", // 상품 이미지 url
    "orderCnt": 1, // 주문건수
    "originalOrderCnt": 1, // 최초 주문 수량
    "salePrice": 329000.00, // 판매 가격
    "immediateDiscountAmt": 144000.00, // 즉시 할인 가격
    "addPrice": 0.00, // 추가 금액
    "additionalDiscountAmt": 0.00, // 추가 할인 금액
    "partnerChargeAmt": 0.00, // 파트너 부담액
    "adjustedAmt": 185000.00, // 조정된 상품 금액
    "orderStatusType": "PAY_DONE", // 주문옵션상태
    "claimStatusType": null, // 클레임 상태
    "claimNo" : 12345, // 클레임 번호
    "orderYmdt": "2021-10-25 13:53:18", // 주문일시
    "payYmdt": "2021-10-25 13:54:38", // 결제일시
    "orderAcceptYmdt": null, // 주문접수일시
    "releaseReadyYmdt": null, // 배송준비일시
    "releaseYmdt": null, // 배송일시
    "deliveryCompleteYmdt": null, // 배송완료일시
    "buyConfirmYmdt": null, // 구매확정일시
    "registerYmdt": "2021-10-25 13:53:18", // 주문옵션 생성일시
    "trackingKey": "platform=MO&rid=851184319&aid=641_1_3_1025&mid=TMS", // 주문추적키 (쇼핑몰에서 생성되어 주문번호를 특정하는 구분값)
    "deliveryCompanyType": "CJ", // 배송 업체
    "invoiceNo": : "1212", // 송장번호
    "receiverName": "홍길동", // 받는 사람 이름
    "zipCd": 12345, // 배송지 우편 번호
    "address": "경기도 성남시 분당구 대왕판교로645번길 12", // 배송지 주소
    "detailAddress": "16 NHN 플레이뮤지엄", // 배송지 상세 주소
    "jibunAddress": "경기도 성남시 분당구 대왕판교로645번길", // 배송지 지번 주소
    "receiverCity": "", // 배송지 해외(도시)
    "receiverState": "", // 배송지 해외(주)
    "contact1": "010-0000-0000", // 수령자 연락처1
    "contact2": "", // 수령자 연락처2
    "productManagementCd": "", // 상품관리 코드
    "optionManagementCd": "", // 옵션관리 코드
    "usesShippingInfoLaterInput": false, // 나중배송지 입력 여부
    "shippingInfoLaterInputContact": null, // 나중배송지 입력 전화 번호
    "encryptedShippingNo": null, // 나중배송지 입력 시 사용하는 암호화된 배송번호
    "retrieveInvoiceUrl": null, // 배송조회 할 수 있는 url
    "isFreeGift": false, // 사은품 여부
    "updateAdminNo":0, // 수정한 어드민 번호
    "extraManagementCd":null, // 추가 관리 코드
    "order": {
        "extraData": null // 추가 정보
    }
}]
```

{% endcode %}

<br>

### 3. 어떻게 웹훅 사용요청 하나요? <a href="#id-3.-ec-96-b4-eb-96-bb-ea-b2-8c-ec-9b-b9-ed-9b-85-ec-82-ac-ec-9a-a9-ec-9a-94-ec-b2-a-d-ed-95-98-eb-82" id="id-3.-ec-96-b4-eb-96-bb-ea-b2-8c-ec-9b-b9-ed-9b-85-ec-82-ac-ec-9a-a9-ec-9a-94-ec-b2-a-d-ed-95-98-eb-82"></a>

1\. 웹훅 사용정보 전달<br>

워크스페이스> 셀러어드민 내  앱(APP) 등록을 통해 웹훅을 사용등록할 수 있습니다.

보다 자세한 내용은 [앱등록 가이드](https://workspace.godo.co.kr/guide/app/dev/registration?lv=28)를 참고하시길 바랍니다.

&#x20;

2\. 웹훅 주의사항

샵바이 서버 또는 웹훅을 받는 서버의 문제로 일정 시간 웹훅이 통신되지 않을 경우

이미 발생했던 이벤트는 다시 전송되지 않습니다. 따라서 주문상태 조회 API와 함께 사용하시는 것을 권장합니다.<br>

\
\
그 외 궁금하신 사항/어려움이 있다면 아래 코멘트를 남겨주세요\~ \
포럼 운영자가 아니더라도 누구나 서로에게 답변할 수 있습니다.\
shopby에서 제공하는 웹훅에 대해 추가적인 문의 또는 제안사항을 코멘트로 남겨주시면\
워크스페이스 운영에 더욱 도움이 될 거예요!

<br>


# \[웹훅 추가] 회원정보 변경 및 회원탈퇴

### 업데이트 일자: 2022. 10. 14

```
[웹훅 추가] 새롭게 추가개발된 웹훅(Webhook)에 대해 안내드리는 콘텐츠입니다.
```

셀러어드민 > 앱 등록 시 제공하는 웹훅 기능 안내드립니다.<br>

회원정보 변경, 회원탈퇴 웹훅 설정으로 앱이 설치된 쇼핑몰의 회원정보가 변경되거나, 회원탈퇴 발생 시 웹훅을 수신할 수 있습니다.

<br>

■ 적용 위치 : 워크스페이스 GNB > 셀러어드민 > 설치 > 앱 > 앱 등록/수정\
\
■ 추가된 기능 : (1) 회원정보 변경 웹훅 설정\
&#x20;                     (2) 회원탈퇴 웹훅 설정

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

■ 기능 상세

* 쇼핑몰에서 (1) 회원정보 변경이 발생하거나, (2) 회원탈퇴 발생 시 변경된 내용을 웹훅을 통해 등록된 외부 URI로 알려줍니다.
* server API 'member' 권한을 추가하셔야 회원정보 변경, 회원탈퇴 웹훅 설정이 가능합니다.
* 웹훅 발행 시점
  * 회원정보 변경
    * 고객이 회원정보를 수정했을 때 해당 고객 정보를 전달합니다.
  * 회원탈퇴
    * 탈퇴 요청이 발생한 시점에 탈퇴 요청한 고객 정보를 전달합니다.
* Request Body

{% code overflow="wrap" %}

```
{
  mallNo: 쇼핑몰 번호
  memberNo: 회원번호
  memberId: 회원아이디(외부연동 ID로 가입 시 null)
  memberName: 회원이름
  email: 회원이메일
  providerType: 외부연동 ID로 가입 시 외부연동 값 노출(KAKAO, PAYCO 등)
  eventType: "MEMBER_WITHDRAW" 이벤트 구분(MEMBER_WITHDRAW (회원탈퇴)/ MEMBER_INFO_CHANGED(회원정보수정))
}
```

{% endcode %}


# \[웹훅 추가] 앱 설치 및 삭제

### 업데이트 일자: 2022.10.28

```
[웹훅 추가] 새롭게 추가개발된 웹훅(Webhook)에 대해 안내드리는 콘텐츠입니다.
```

<br>

## **앱 설치/삭제 웹훅이란?**

shopby 솔루션 어드민에 1) 앱이 설치되거나 2) 설치된 앱이 삭제됐을 때

앱이 설치되거나, 설치된 앱이 삭제된 경우 웹훅을 통해 등록된 고객사의 외부 URI로 알려주는 REST API call입니다.

<figure><img src="https://rlyfaazj0.toastcdn.net/20221027/171416.20169000/%EC%9B%B9%ED%9B%85.png" alt=""><figcaption></figcaption></figure>

* <mark style="color:blue;">**지원 가능한 method**</mark>: POST / PUT
* <mark style="color:blue;">**웹훅 발행시점**</mark>
  1. 앱 설치(ACTIVE)\
     → 앱이 설치됐을 때 웹훅 전달
  2. 앱 삭제(DELETED)\
     → 설치된 앱이 삭제됐을 때 웹훅 전달
* <mark style="color:blue;">**Request Body**</mark>

  ```
  {
    mallNo: 쇼핑몰 번호
    curretStatus: ACTIVE(설치)/DELETED(삭제)
    appNo: 앱일련번호
    appInstalledNo: 앱설치번호
  }
  ```

***

## **웹훅 사용설정 방법**

1. <mark style="color:blue;">**웹훅 설정 경로**</mark>
   * 워크스페이스> 셀러어드민 내  앱(APP) 등록/수정 시 설정할 수 있습니다.
2. <mark style="color:blue;">**웹훅 주의사항**</mark>
   * shopby 서버 또는 웹훅을 받는 서버의 문제로 일정 시간 웹훅이 통신되지 않을 경우 이미 발생했던 이벤트는 다시 전송되지 않습니다.


# shop by API, POSTMAN에 추가하기

업데이트 일자: 2022. 04. 11<br>

shop by API의 yml 경로를 활용하여 postman에 shop by API를 추가 할 수 있습니다.

postman에서 import 시 link로 선택하여 shop by의 API yml 경로를 추가 합니다.

필요하신 API 도메인에 따라 yml을 추가해서 사용할 수 있습니다.

각자 필요한 API의 yml 경로를 확인하여 추가 하셔서 사용해보세요.<br>

▶ shop by shop API

| 도메인       | yml                                                        |
| --------- | ---------------------------------------------------------- |
| admin     | <https://docs.shopby.co.kr/spec/admin-shop-public.yml>     |
| auth      | <https://docs.shopby.co.kr/spec/auth-shop-public.yml>      |
| claim     | <https://docs.shopby.co.kr/spec/claim-shop-public.yml>     |
| display   | <https://docs.shopby.co.kr/spec/display-shop-public.yml>   |
| marketing | <https://docs.shopby.co.kr/spec/marketing-shop-public.yml> |
| member    | <https://docs.shopby.co.kr/spec/member-shop-public.yml>    |
| manage    | <https://docs.shopby.co.kr/spec/manage-shop-public.yml>    |
| order     | <https://docs.shopby.co.kr/spec/order-shop-public.yml>     |
| product   | <https://docs.shopby.co.kr/spec/product-shop-public.yml>   |
| promotion | <https://docs.shopby.co.kr/spec/promotion-shop-public.yml> |

\
▶ shop by server API

| 도메인           | yml                                                                                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| admin         | <https://server-docs.shopby.co.kr/spec/admin-server-public.yml>                                                                                                |
| claim         | <https://server-docs.shopby.co.kr/spec/claim-server-public.yml>                                                                                                |
| delivery      | <https://server-docs.shopby.co.kr/spec/delivery-server-public.yml>                                                                                             |
| display       | <https://server-docs.shopby.co.kr/spec/display-server-public.yml>                                                                                              |
| manage        | <https://server-docs.shopby.co.kr/spec/manage-server-public.yml>                                                                                               |
| member        | <https://server-docs.shopby.co.kr/spec/member-server-public.yml>                                                                                               |
| order         | <https://server-docs.shopby.co.kr/spec/order-server-public.yml>                                                                                                |
| order-friends | <https://server-docs.shopby.co.kr/spec/order-friends-server-public.yml>                                                                                        |
| product       | <https://server-docs.shopby.co.kr/spec/product-server-public.yml>                                                                                              |
| promotion     | <p><a href="https://server-docs.shopby.co.kr/spec/promotion-server-public.yml"><https://server-docs.shopby.co.kr/spec/promotion-server-public.yml></a><br></p> |


# \[글로벌] 글로벌 기능 가이드

{% hint style="info" %}
샵바이 엔터프라이즈 글로벌 기능은 2가지 방식으로 구현이 가능합니다.

글로벌 기능 구현방식 확인하신 후, 쇼핑몰 운영에 맞는 방식을 선택하여 운영해주시기 바랍니다.
{% endhint %}

## 1. 국내+국외 쇼핑몰을 1개로 운영 <a href="#id-1.-ea-b5-a-d-eb-82-b4-ea-b5-ad-ec-99-b8-ec-87-bc-ed-95-91-eb-aa-b0-ec-9d-84-1-ea-b0-9c-eb-a1-9c-ec" id="id-1.-ea-b5-a-d-eb-82-b4-ea-b5-ad-ec-99-b8-ec-87-bc-ed-95-91-eb-aa-b0-ec-9d-84-1-ea-b0-9c-eb-a1-9c-ec"></a>

* 국내 + 국외 쇼핑몰을 1개로 운영하는 경우, 상품/주문/회원/프로모션/게시판/쇼핑몰 운영방식 등을 <mark style="color:orange;">**1개의 쇼핑몰로 한 번에 운영이 가능**</mark>합니다.
* 단, 상품/프로모션/전시/메일 등에 기입하는 콘텐츠를 언어별로 관리할 수 있는 필드 값을 제공하고 있지 않습니다.
  * 현재 상품의 '영문 상품명' 만 등록 및 관리가 가능합니다.
* 따라서, <mark style="color:orange;">**콘텐츠는 하나의 언어로만 제공**</mark>해야 합니다.
  * 언어별 콘텐츠 필드 추가 기능은 제공 예정입니다. (일정 미정)
  * 언어는 공용 언어 또는 쇼핑몰 회원의 주사용 언어(ex. 영어) 등으로 설정하여 사용하실 수 있습니다.
  * 모든 콘텐츠의 언어를 '영어' 로 설정한 후 쇼핑몰 프론트에서 '실시간 번역/브라우저 번역 기능' 등을 통해 사용하도록 제공이 가능합니다.

***

## 2. 언어 기준으로 쇼핑몰을 여러 개로 운영 <a href="#id-2.-ec-96-b8-ec-96-b4-ea-b8-b0-ec-a4-80-ec-9c-bc-eb-a1-9c-ec-87-bc-ed-95-91-eb-aa-b0-ec-9d-84-ec-97-a" id="id-2.-ec-96-b8-ec-96-b4-ea-b8-b0-ec-a4-80-ec-9c-bc-eb-a1-9c-ec-87-bc-ed-95-91-eb-aa-b0-ec-9d-84-ec-97-a"></a>

* 언어권을 기준으로 쇼핑몰을 구분하여 <mark style="color:orange;">**여러 개의 쇼핑몰로 각각 운영이 가능**</mark>합니다.\
  (ex. 국문몰, 영문몰, 일문몰, 중문몰로 구분)
* 각 언어권 또는 국가 별로 로컬라이징하여 쇼핑몰을 운영하실 수 있습니다.
* 상품/주문/회원/프로모션/게시판/쇼핑몰 운영방식 등을 쇼핑몰 별로 각각 설정이 가능합니다.
* 단, 현재 글로벌 기능은 상품금액을 원화(KRW)단위로만 설정할 수 있어 <mark style="color:orange;">**원화 이외의 다른 해외 통화로 가격 설정 및 운영이 불가**</mark>합니다.
  * 해외 통화로 가격을 설정하는 기능은 제공 예정입니다. (일정 미정)
* 쇼핑몰을 여러 개로 운영하는 경우 다른 쇼핑몰의 <mark style="color:red;">**상품 재고연동 기능**</mark>을 활용하여 연동이 가능합니다.
  * ex) 국문몰과 영문몰의 상품 재고를 연동하고 싶은 경우, 영문몰 상품 등록 시 국문몰의 상품을 복사하여 재고 수량 연동을 할 수 있습니다.

<mark style="color:red;">☑️</mark> <mark style="color:red;"></mark><mark style="color:red;">**상품 재고연동 기능이란?**</mark>\
\- 상품의 재고를 연동해서 사용할 수 있는 기능으로 다른 쇼핑몰의 상품도 재고 연동이 가능합니다.  \
\- 상품의 재고수량을 연동하여 상품을 복사한 경우, 기존 상품을 'Master(M)' 상품, 복사된 상품을 'Slave(S)' 상품으로 구분됩니다.\
\- 상품의 재고수량 연동 시 복사된 상품(Slave) 판매가 발생하면 발생하면 복사한 상품(Master)의 재고수량이 차감됩니다.

▼ shop by enterprise 서비스어드민 > 상품관리 > 상품정보 조회/수정 '상품 복사'

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


# 사용 프로세스

## 이해하기

> shop by 글로벌 기능을 사용하고 싶은 경우, 아래 프로세스를 따라 적용해주시기 바랍니다.

* step 1) [엑심베이 PG 계약](/contents/recommended/global/use_process/step_01)
* step 2) [개발 환경 세팅](/contents/recommended/global/use_process/step_02)
* step 3) [shop by 어드민 세팅](/contents/recommended/global/use_process/step_03)
* step 4) [쇼핑몰 스킨 개발](/contents/recommended/global/use_process/step_04)

shop by 글로벌 기능은 기본스킨에 반영되지 않으며, [쇼핑몰 스킨 개발](/contents/recommended/global/use_process/step_04) 가이드를 참고하여 쇼핑몰 스킨을 개발해주시기 바랍니다.\
만약, 어나더(Another) 스킨 기반으로 쇼핑몰 스킨을 개발하는 경우 [v1.22.17 이상의 버전](https://skins.shopby.co.kr/shopby/another-skin/-/commit/2687acb5b1a1d72ed7951f39458f43990d40e81e)을 패치받아서 적용해주시기 바랍니다.


# 엑심베이 PG 계약

샵바이는 엑심베이 해외 PG 서비스를 제공 중이며, 하기 링크를 통해 엑심베이 접수 및 계약을 하실 수 있습니다.

* 샵바이 전용 신청 링크 : <https://www.eximbay.com/homepage/new/kr/dist/join-online-1.do?partnerCode=NHNSHOPBY>

{% hint style="info" %}
엑심베이 PG 계약이 선행으로 진행되어 있어야 이후 프로세스를 진행하실 수 있습니다. \
PG 수수료는 4.5%(vat 별도)이며, 해외 결제 승인기간이 4주 이상 소요될 수 있습니다.
{% endhint %}


# 개발 환경 세팅

엑심베이 PG 결제창 테스트를 진행하기 위해서는 개발 환경 세팅이 필요합니다.\
개발 환경 세팅을 위해 엑심베이와 계약 완료 후, 하기 정보를 [NHN커머스 고객센터 1:1문의](https://support.nhn-commerce.com/inquiry/list?_gl=1*v6ipfk*_ga*MTgxNTIzMDA4MC4xNzA4Njc2MjY5*_ga_Z1WW9QB68M*MTcxMjAxNjEwMy44OS4xLjE3MTIwMTY1ODkuNTcuMC4w)를 통해 전달 부탁드립니다.

* MID
* SecretKey
* 사용 결제 수단

개발 환경 세팅이 완료되면 [NHN커머스 고객센터 1:1문의](https://support.nhn-commerce.com/inquiry/list?_gl=1*v6ipfk*_ga*MTgxNTIzMDA4MC4xNzA4Njc2MjY5*_ga_Z1WW9QB68M*MTcxMjAxNjEwMy44OS4xLjE3MTIwMTY1ODkuNTcuMC4w) 답변을 통해 안내 드리겠습니다.


# shop by 어드민 세팅

shop by 글로벌 기능은 shop by enterprise 에서만 사용 가능합니다.

글로벌 쇼핑 운영에 필요한 환율, 언어, 배송 국가 정보 등을 shop by 어드민에서 설정할 수 있습니다. \
설정한 정보를 기반으로 쇼핑몰에서 shop api를 이용하여 쇼핑몰 프런트 화면 구현이 가능합니다.

***

**▼ shop by enterprise 서비스어드민 > 서비스관리 > 쇼핑몰 관리 > 쇼핑몰 수정 화면**

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

### ⓐ 쇼핑몰 언어 설정 <a href="#e2-93-90-ec-87-bc-ed-95-91-eb-aa-b0-ec-82-ac-ec-9a-a9-ed-99-94-ed-8f-90-ed-99-98-ec-9c-a8-ec-84-a4-e" id="e2-93-90-ec-87-bc-ed-95-91-eb-aa-b0-ec-82-ac-ec-9a-a9-ed-99-94-ed-8f-90-ed-99-98-ec-9c-a8-ec-84-a4-e"></a>

쇼핑몰에서 사용하는 언어 정보를 설정할 수 있습니다.\
현재 언어는 <mark style="color:orange;">**KO(한국어), EN(영어), JA(일본어), ZH(중국어)**</mark>를 지원합니다.

### ⓑ 쇼핑몰 사용 화폐/환율 설정

쇼핑몰에서 사용하는 화폐와 환율 정보를 설정할 수 있습니다.\
현재 화폐는 <mark style="color:orange;">**KRW(원화) USD(미국 달러), JPY(엔화), CNY(위안화)**</mark>를 지원하며, 환율은 화폐 당 KRW 금액을 수동으로 입력합니다.

### ⓒ 국가별 최대 주문금액 설정

주문 1건 당 최대로 주문할 수 있는 금액을 국가 별로 설정할 수 있습니다.\
주문금액은 KRW(원화) 기준으로 설정 가능하며, 쇼핑몰에서 주문 시 설정한 배송지 주소의 국가 기준으로 최대 주문금액이 제한됩니다.\
ex) 주소지가 중국인 경우 주문 시 최대 500,000원까지 구매 가능하도록 설정 가능

***

**▼ shop by enterprise 서비스어드민 > 상품관리 > 배송비 관리 > 배송비 템플릿관리(탭) 화면**

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

### **ⓓ** 배송불가 국가 설정

주문 및 배송이 불가한 국가 정보를 설정할 수 있습니다.\
배송비 템플릿 그룹별로 배송불가 국가 설정이 가능하며, 상품 별로 특정 국가에 배송이 불가하도록 설정할 수 있습니다.\
배송불가 국가 설정은 상품 배송구분이 '쇼핑몰배송' 인 배송 템플릿에만 적용됩니다. (파트너배송인 경우 배송불가 국가 설정 불가)\
ex) 배송불가 국가를 '대만, 중국' 으로 설정하는 경우, 쇼핑몰에서 주문 시 설정한 배송지 주소의 국가가 대만 or 중국인 경우 주문이 불가합니다.


# 쇼핑몰 스킨 개발

## 이해하기 <a href="#ec-9d-b4-ed-95-b4-ed-95-98-ea-b8-b0" id="ec-9d-b4-ed-95-b4-ed-95-98-ea-b8-b0"></a>

shop by 글로벌 기능 사용을 위한 <mark style="color:red;background-color:yellow;">**쇼핑몰 스킨 개발 가이드**</mark> 입니다.\
shop by 어드민에서 글로벌 기능 설정 시 기본스킨에 반영되지 않으며, 하기 가이드를 참고하여 쇼핑몰 스킨을 개발해주시기 바랍니다.

> 쇼핑몰 개발을 위해 각 화면별 가이드 문서를 확인해주세요.

* [언어/통화 설정](/contents/recommended/global/use_process/step_04/languages)
* [상품/전시 설정](/contents/recommended/global/use_process/step_04/currencies)
* [주문서 조회](/contents/recommended/global/use_process/step_04/order_sheets)
* [주문 예약하기](/contents/recommended/global/use_process/step_04/reserve)
* [회원 등록](/contents/recommended/global/use_process/step_04/profile)

\
만약, 어나더(Another) 스킨 기반으로 쇼핑몰 스킨을 개발하는 경우 [v1.22.17 이상의 버전](https://skins.shopby.co.kr/shopby/another-skin/-/commit/2687acb5b1a1d72ed7951f39458f43990d40e81e)을 패치받아서 적용해주시기 바랍니다.


# 언어/통화 설정

쇼핑몰에서 지원 가능한 언어 및 통화를 조회할 수 있습니다. \
쇼핑몰 운영정책에 따라 쇼핑몰 별로 이용자가 언어/통화를 직접 선택할 수 있는 UI를 제공하거나 쇼핑몰 별로 언어/통화를 직접 선택하지 않고 고정하여 제공할 수 있습니다.

> [GET/malls/internationalization ](https://docs.shopby.co.kr/#/Mall/get-malls-i18n)

```
▶ 몰의 다국어, 환율 설정 조회
현재 몰의 다국어, 환율 설정 조회을 조회하는 API 입니다.
```

**ex 1) 쇼핑몰 언어/통화 고정하여 제공**

\- [sample.com/us](http://sample.com/us) : 언어(영어), 통화(달러) \
\- [sample.com/jp](http://sample.com/jp) : 언어(일본), 통화(엔화)

**ex 2) 쇼핑몰 언어/통화 직접 선택**

\- 대한한공 홈페이지 \[<https://www.koreanair.com/?hl=ko>]


# 상품/전시 설정

쇼핑몰의 상품 및 전시 영역에 노출되는 모든 상품금액 정보는 KRW(원화) 기준으로 응답값을 내려줍니다.\
쇼핑몰 상품 및 전시영역에 해외 통화로 상품금액 표기가 필요한 경우, 아래 API를 활용하여 화면을 구현할 수 있습니다.

> [GET/malls/internationalization ](https://docs.shopby.co.kr/#/Mall/get-malls-i18n)

```
▶ 몰의 다국어, 환율 설정 조회 
현재 몰의 다국어, 환율 설정 조회을 조회하는 API 입니다.
```

`currencies`의 `exchangeRate`를 조회하여 **'KRW(원화) \* 환율'** 을 계산하여 상품금액 정보를 출력 해주셔야 합니다.


# 주문서 조회

쇼핑몰 주문서 페이지에 노출할 해외 통화 결제금액, 엑심베이 해외 PG 결제수단을 설정하는 화면입니다.

> [GET/order-sheets/{orderSheetNo}](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet)

```
▶︎ 주문서 조회하기 API
주문서 번호를 이용하여 주문상품정보를 조회하는 API 입니다.
```

## 결제금액 <a href="#ea-b2-b0-ec-a0-9c-ea-b8-88-ec-95-a1" id="ea-b2-b0-ec-a0-9c-ea-b8-88-ec-95-a1"></a>

하기 정보로 해외 통화 결제금액을 노출할 수 있습니다. \
currency 헤더를 이용하여 currency에 해당 하는 정보를 내려 받을 수 있습니다.

* `internationalPaymentInfo.exchangeRate` : 환율
* `internationalPaymentInfo.exchangedAmt` : 환율 적용된 결제 예정 금액
* `internationalPaymentInfo.currencyCode` : 통화 코드
* `undeliverableCountries` : 배송 불가능한 국가 목록

***

## 결제수단 설정 <a href="#ea-b2-b0-ec-a0-9c-ec-88-98-eb-8b-a8-ec-84-a4-ec-a0-95" id="ea-b2-b0-ec-a0-9c-ec-88-98-eb-8b-a8-ec-84-a4-ec-a0-95"></a>

엑심베이 결제수단을 주문서 페이지 내에 노출할 수 있습니다.\
단, 적립금 전액 결제 또는 최종 결제 금액이 0원일 경우 해당 영역은 노출되지 않으며, 엑심베이와 계약한 결제 수단만 노출할 수 있습니다.\
현재 결제 수단은 신용카드만 사용할 수 있습니다.

`availablePayTypes` 의 `payType`은 `CREDIT_CARD`, `pgType`은 `EXIMBAY_GLOBAL` 로 보내주세요.\
비회원 주문인 경우 `shopbyAuthorization`은 빈 값('')으로 전달해 주세요.

엑심베이 결제를 사용하기 위해서는 엑심베이 SDK 라이브러리가 필요하기 때문에 하기 스크립트를 주문서 페이지에 추가해주세요.

```
<script type="text/javascript" src="https://api.eximbay.com/v1/javascriptSDK.js"></script>
```

스킨의 결제수단 선택 화면을 아래와 같이 구현할 수 있습니다.

> 화면 개발 형태 및 엑심베이와 계약한 결제 수단에 따라 화면은 상이할 수 있습니다.

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


# 주문 예약하기

주문 예약 시 필요한 언어, 통화, 배송지 정보를 설정하고 실제 결제 API 호출하는 화면입니다.

* 🅐 결제언어
* 🅑 결제통화
* 🅒 배송지
* 🅓 결제하기 버튼

> [POST /payments/reserve](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve)

```
▶︎ 주문 예약하기 API
주문을 예약하는 API 입니다.
```

***

## 🅐 결제언어 <a href="#id-3cspan-style-22color-rgb-34-34-34-22-3e-f0-9f-85-90-3c-span-3e-ea-b2-b0-ec-a0-9c-ec-96-b8-ec-96-b4" id="id-3cspan-style-22color-rgb-34-34-34-22-3e-f0-9f-85-90-3c-span-3e-ea-b2-b0-ec-a0-9c-ec-96-b8-ec-96-b4"></a>

language 헤더를 이용하여 결제창의 언어를 선택할 수 있습니다.

## 🅑 결제통화

currency 헤더를 이용하여 결제 시의 언어/통화 수단을 선택할 수 있습니다.\
입력되는 모든 결제 금액은 원화(KRW) 기준이며, currency 입력 값에 따라 몰에 설정된 환율로 자동 계산되어 엑심베이 PG에 요청됩니다.

## 🅒 `배송지`

해외 배송지의 아래 값을 입력해야 합니다.

* `receiverZipCd` : zipCode
* `receiverAddress` : 주소 (도시, 주 정보는 제외)
* `receiverDetailAddress` : 상세 주소
* `receiverCity` : 도시
* `receiverState` : 주
* `receiverFirstName` : 이름
* `receiverLastName` : 성
* `countryCd` : 국가
* `orderAdditionalInfo` : 추가 정보 (대만인 경우 여권번호)

`countryCd`, `receiverState` 기준으로 지역별 배송비가 계산됩니다.

설정한 배송지 정보에 따라 결제 시도 시, 하기 케이스에 대해 400에러가 발생됩니다.\
\- 설정한 `countryCd`(국가)에 최대 주문금액이 설정되어 있고 해당 주문 금액을 초과한 경우\
\- 설정한 `countryCd`(국가)가 배송불가 국가로 설정된 경우

## 🅓 `결제하기 버튼`

실제 결제 API를 호출하는 화면입니다.\
\[결제하기] 버튼 클릭 시, 아래와 같은 엑심베이 결제 모듈이 레이어 팝업 형태로 출력됩니다.

<figure><img src="/files/DjpHzCLEOkSeTP4o1B1E" alt="" width="196"><figcaption></figcaption></figure>

### **ⓐ 결제 편의 모듈**

결제하기 버튼 클릭 시, 결제에 필요한 데이터 유효성 체크 후 실제 결제를 위한 샵바이 API를 호출합니다.

샵바이 서버에서는 Client에서 결제 API를 호출할 수 있는 간단한 javascript 코드를 제공하고 있습니다.\
쇼핑몰에서 javascript를 로드해주세요.

```
<script src="https://shop-api.e-ncp.com/payments/ncp_pay.js"></script>
```

### **ⓑ 결제 모듈 javascript**

추가로 PG 사에서 제공하는 결제 모듈 javascript 를 로드해야 합니다.\
기본 스킨에서는 주문서 화면에서 실행환경에 따라 아래와 같은 결제 모듈 javascript를 로드하고 있습니다.

```
 const payScripts = {
      [
        'https://nsp.pay.naver.com/sdk/js/naverpay.min.js',
        'https://shop-api.e-ncp.com/payments/ncp_pay.js',
        'https://spay.kcp.co.kr/plugin/kcp_spay_hub.js',
        'https://xpayvvip.uplus.co.kr/xpay/js/xpay_crossplatform.js',
      ],
  };
```

Configuration 값 입력 후 revervation 값을 호출해주세요.\
엑심베이를 결제 수단으로 사용할 경우 `NCPPay.setConfiguration` 메소드를 호출하실 때 파라미터에 `currency(통화단위)`와 `language(언어)`를 추가로 입력하여야 합니다.\ <mark style="color:orange;">현재 통화는 KRW(원화) USD(미국 달러), JPY(엔화), CNY(위안화)를 지원하며, 언어는 KO(한국어), EN(영어), JA(일본어), ZH(중국어)를 지원합니다.</mark>

```
NCPPay.setConfiguration({
    'clientId': ncp.clientId, // shopby에서 발급받은 clientId
    'confirmUrl': 'payment-confirm.html', // 결과를 리턴받을 url
    'platform': 'PC', // 'PC or MOBILE_WEB or AOS or IOS'
    'shopbyAuthorization' : accessToken ? `Bearer ${accessToken}` : '', // Oauth2 인증 방식을 사용시 인증 헤더 구분 값
    'accessToken': '', // Oauth 인증 방식을 사용시 인증 헤더 구분 값
    'currency': 'KRW', //'KRW' or 'USD' or 'JPY' or 'CNY'
    'language': 'KO' //'KO' or 'EN' or 'JA' or 'ZH'
  });

NCPPay.reservation(data, function (response) {
    alert("결제완료 되었습니다.");
  });
```

참고로 `clientId`는 쇼핑몰 사이트를 출력하기 위해 할당된 각 상점의 쇼핑몰 구분 값입니다.\
(프론트에서 API호출 시 해당하는 쇼핑몰을 판단할 수 있는 key값)

* 샵바이프로: `environment.json` 내 `clientId` 값으로 확인 가능합니다.
* 샵바이프리미엄: 서비스어드민 > 서비스관리 > 쇼핑몰관리 > (쇼핑몰 선택) > 개발연동정보 > 클라이언트 아이디에서 확인 가능합니다.

단, 엑심베이가 제공하는 아래 코드를 javascript코드로 입력해야합니다.

```
<script type="text/javascript" src="https://api.eximbay.com/v1/javascriptSDK.js"></script>
```

### **ⓒ 결제하기 API**

reservation에 필요한 request 값은 아래 API 데이터 양식을 참고하시길 바랍니다.\
[주문 예약하기 API](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve) 를 사용하면 결제가 진행됩니다.

Request Body 내 `payType`결제수단과 `PgTypes`외부 PG사에 대해 안내드립니다.\
해당 값들은 `GET /order-sheets/{orderSheetNo}` 주문서 조회하기 API에서, 해당 쇼핑몰/상품이 설정한 결제수단에 따라 `availablePayTypes` 사용가능한 결제정보를 응답 값으로 내려줍니다.\
쇼핑몰에서 다양한 PG사와 계약해서 결제수단을 제공할 수 있기 때문에, `payType`을 기준으로 `pgTypes`를 내려주고 있으니 프론트에서 구현 시 내려온 `pgTypes`에 따라 결제모듈을 제공할 수 있습니다.

<mark style="color:orange;">PayPal의 경우 해외 배송지 정보를 필수로 요청해야 합니다.</mark>\ <mark style="color:orange;">또한 2017.02.20 기준으로 지정된 10개 국가(Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand, USA)에 대해서는</mark> `shippingAddress.receiverState` <mark style="color:orange;">값이 필수이며, State Code 값은 아래 URL을 통하여 확인해 주시기 바랍니다.</mark>\
<https://developer.paypal.com/docs/api/reference/state-codes/>

`ShippingAdrdress.countryCd` <mark style="color:orange;">값은 ISO-3166 두 자리 국가코드로 요청하셔야 합니다.</mark>

```
{
  "orderSheetNo": "202007230001814989",
  "shippingAddress": {
    "receiverAddress": "132, My Street", // Address 1
    "receiverDetailAddress": "PO BOX 123", // Address 2
    "receiverFirstName": "John", // First Name
    "receiverLastName": "Smith", // Last name
    "countryCd": "US", // Country/Region
    "receiverCity": "Kingston", // City
    "receiverState": "NY", // State/Province
    "receiverZipCd": "12401", // Zip/Postal Code
    "receiverContact1": "010-7770-7777", // Contact 1
    "receiverContact2": "031-8038-0000", // Contact 2(nullable)

    "usesShippingInfoLaterInput": false,
    "shippingInfoLaterInputContact": null,
    "requestShippingDate": null,
  },
```

### **ⓓ 결제 결과**

`NCPPay.setConfiguration`에 설정한 confirmUrl로 성공 또는 실패 결과를 리턴합니다.\
이후 결제 성공 여부에 따라 '주문완료' 또는 '주문 실패' 화면을 출력합니다.

엑심베이에서 결제 승인이 된 후, 샵바이에 재고가 없는 등의 문제가 발생할 경우 바로 취소 처리되며 실패 응답 값을 내려줍니다.

* 성공 시

  * request parameter 로 결과 값을 `SUCCESS` 로 전달합니다.
  * 주문이 성공한 주문 번호를 함께 전달합니다.

  ex)result=SUCCESS\&orderNo=123
* 실패 시

  * request parameter 로 결과 값을 `FAIL`로 전달합니다.
  * message에 실패 사유를 함께 전달합니다.

  ex) result=FAIL\&message=잔액부족


# 회원 등록

쇼핑몰의 국외 회원 등록 시 이름, 주소, 국가코드를 정보를 입력받을 수 있습니다. &#x20;

> [POST /profile](https://docs.shopby.co.kr/?url.primaryName=member/#/Profile/post-profile)

```
프로필 생성하기 API
회원 프로필 등록 시 사용하는 API 입니다.
```

## 회원명

* 국외 회원의 경우 회원명을 성(lastName)과 이름(firstName)으로 구분하여 등록할 수 있습니다.
* firstName, lastName 을 각각 저장할 경우 memberName 에 ${firstName lastName} 으로 스페이스를 포함하여 저장됩니다.

## 주소

* 주소 우편번호 검색 기능은 제공하지 않습니다.
* zipCode, state, city, address, detailAddress를 직접 입력할 수 있습니다.

## 국가코드

* `countryCd`는 해당 국가의 국가코드 2자리를 입력합니다.
* [국가코드 확인하기 >](https://ko.wikipedia.org/wiki/%EA%B5%AD%EA%B0%80%EB%B3%84_%EA%B5%AD%EA%B0%80_%EC%BD%94%EB%93%9C_%EB%AA%A9%EB%A1%9D)

<br>


# 글로벌 주문/환불 프로세스

## 주문

쇼핑몰에서 주문 시 실제 엑심베이에서 진행되는 승인/정산 통화는 상점-엑심베이 간 계약 시 설정한 통화 기준을 따릅니다.

단, 해외신용카드의 경우 위안화(CNY)는 중국 외환법상 승인 자체가 불가하여 기본적으로 제공하지 않는 통화로 상점- 엑심베이 간 별도 계약이 필요합니다.\
ex) 1 USD=1,300 KRW 로 설정, 상품 가격이 2,600 KRW 일 경우 2,300\*1/1,300=2 USD로 결제 요청

***

## 클레임(취소/교환/반품) <a href="#id-3cspan-style-22color-rgb-18-18-18-22-3e-e2-98-91-ef-b8-8f-3c-span-3e-ed-81-b4-eb-a0-88-ec-9e-84-ec-b" id="id-3cspan-style-22color-rgb-18-18-18-22-3e-e2-98-91-ef-b8-8f-3c-span-3e-ed-81-b4-eb-a0-88-ec-9e-84-ec-b"></a>

글로벌 주문의 경우에도 전체/부분 환불이 가능합니다. (기존 프로세스와 동일)\
클레임 시점에 설정된 환율 정보가 아닌 결제 시점에 저장된 환율정보, 배송지 정보 기준으로 클레임 처리를 하실 수 있습니다.

단, 실제결제금액과 최종환불금액은 환율 소수점 처리에 의해 상이할 수 있습니다. \
샵바이 어드민 환불금액과 엑심베이 PG 어드민의 환불가능금액이 상이하더라도 PG 환불처리 된다면 샵바이 어드민에서 클레임 처리가 완료됩니다.\
ex) 1 USD=1,300 KRW 로 설정하여 1,000원 상품 3개 결제(3,000 KRW=2.30 USD)\
&#x20;         ① 2개 환불: 2,000 KRW=1.53 USD\
&#x20;         ② 1개 환불: 1,000 KRW=0.76 USD\
&#x20;         → 총 환불 금액 2.29 USD로 0.01 USD 차이 발생하나, 클레임 완료 처리 가능

***

## 주문내역 조회 <a href="#id-3cspan-style-22color-rgb-18-18-18-22-3e-e2-98-91-ef-b8-8f-3c-span-3e-ec-a3-bc-eb-ac-b8-eb-82-b4-ec-9" id="id-3cspan-style-22color-rgb-18-18-18-22-3e-e2-98-91-ef-b8-8f-3c-span-3e-ec-a3-bc-eb-ac-b8-eb-82-b4-ec-9"></a>

KRW(원화) 외 다른 통화로 결제 시, 어드민 주문상세 페이지에 결제 시점의 결제환율 정보와 주문금액(원화 기준)을 확인하실 수 있습니다.\
주문 시 입력한 추가정보 데이터는 수령자 정보 > '추가정보' 항목에서 확인하실 수 있습니다.\
엑심베이로 신용카드 결제 시 결제수단은 신용카드로 분류되며, 결제수단에 따라 아래와 같이 노출됩니다.

* 신용카드(Visa, Master, AMEX, JCB), 유니온페이, 알리페이 플러스, 위챗, 페이팔


# Npay 주문형 연동하기

본 가이드는 스킨을 자체 제작하는 헤드리스를 위한 가이드 입니다.

### Npay 구매 버튼 스크립트

플랫폼 유형에 알맞은 스크립트를 선택해 헤더 영역에 추가하세요

{% code overflow="wrap" %}

```javascript
<!-- mobile -->
<script type="text/javascript" src="https://pay.naver.com/customer/js/mobile/naverPayButton.js"></script>

<!-- pc -->
<script type="text/javascript" src="https://pay.naver.com/customer/js/naverPayButton.js"></script>
```

{% endcode %}

### Npay 구매 버튼 옵션 설정

옵션의 종류를 확인하고 알맞은 값을 추가하세요

> 네이버에서제공하는 스크립트를 분석해 작성한 내용입니다.
>
> 업데이트 시점에 따라 내용이 달라질 수 있으니 정확한 옵션에 대한 정보는 하기 스크립트를 확인하세요
>
> * PC : <https://pay.naver.com/customer/js/innerNaverPayButton.js?site_preference=normal&478465>\
>   문서 작성 시점 버전 : 1.3
> * MOBILE : <https://pay.naver.com/customer/js/mobile/innerNaverPayButton.js?site_preference=normal&478465>\
>   문서 작성 시점 버전 : 1.1

```javascript
// mobile
window.naver.NaverPayButton.apply({
    EMBED_ID: 'naver-pay',
    BUTTON_KEY: `${buttonKey}`,
    TYPE: 'MA',
    COLOR: 1,
    COUNT: 2,
    ENABLE: 'Y',
    BUY_BUTTON_HANDLER: {handleBuyButtonClick},
    WISHLIST_BUTTON_HANDLER: {handleWishListButtonClick},
  });
  
// pc
window.naver.NaverPayButton.apply({
    EMBED_ID: 'naver-pay',
    BUTTON_KEY: `${buttonKey}`,
    TYPE: 'A',
    COLOR: 1,
    COUNT: 1,
    ENABLE: 'Y',
    BUY_BUTTON_HANDLER: {handleBuyButtonClick},
    WISHLIST_BUTTON_HANDLER: {handleWishListButtonClick},
  });
  
```

* EMBED\_ID : `Npay 구매` 버튼 노출 할 영역의 `id` 값을 입력하세요.\
  예시)

{% code overflow="wrap" %}

```javascript
<!-- EMBED_ID: 'naver-pay' -->
<div id="naver-pay"></div>
```

{% endcode %}

* BUTTON\_KEY : 네이버에서 전달받은 버튼 생성키
  * `관리자 > 설정 > 네이버페이 설정 > 네이버페이 주문형 > 버튼 인증키` 에 입력한 값을 [GET /order-configs 주문 설정 값 가져오기](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderConfiguration/get-order-configuration) API로 확인할 수 있습니다.\
    응답 값 중 `naverPay.buttonKey`를 사용하시면 됩니다.
* TYPE : 플랫폼 유형에 따라 다르게 설
  * PC : A \~ G
    * F와 G를 설정하는 경우 스크립트 옵션을 확인하세요\ <mark style="background-color:yellow;">F를 설정하는 경우 COLOR: 1, COUNT: 2 만 유효</mark>\ <mark style="background-color:yellow;">G를 설정하는 경우 COLOR: 1, COUNT: 1 만 유효</mark>
    * **샵바이 기본 스킨**에서는 `A`를 기본으로 사용합니다.<br>

      <div align="left"><figure><img src="/files/jmTy4slDOVzfhZysLmtE" alt="" width="563"><figcaption></figcaption></figure></div>
  * MOBILE : MA, MB
    * **샵바이 기본 스킨**에서는 `MA`를 기본으로 사용합니다.<br>

      <div align="left"><figure><img src="/files/2HwTxMNyhoDKL54UWvuG" alt="" width="562"><figcaption></figcaption></figure></div>

    * COLOR : 버튼 모음의 색 설정. 1 혹은 2 설정 가능
      * **샵바이 기본 스킨**에서는 `1`를 기본으로 사용합니다.<br>

    * COUNT : 버튼 개수 설정. 구매하기 버튼만 있으면 1, 찜하기 버튼도 있으면 2를 입력
      * **샵바이 기본 스킨**에서는 `2`를 기본으로 사용합니다.
        * 단, **장바구니 페이지**에서는 **1**로 고정해서 사용합니다. 찜하기 기능을 사용하지 않습니다.<br>

    * ENABLE : 버튼 활성화 여부를 `Y` 혹은 `N` 으로 설정. 품절 등의 이유로 버튼 모음을 비활성화할 때에는 "N" 입력<br>

    * BUY\_BUTTON\_HANDLER : `NPay 구매` 버튼 클릭 시 호출하는 핸들러
      * 핸들러 안에서 2가지 API 를 호출해야 합니다.
        1. [PUT /payments/naver/validate 네이버페이 상품구매 검증하기](https://docs.shopby.co.kr/?url.primaryName=order/#/NaverPay/put-payments-naver-validate) API 로 Npay로 구매가능한 상품인지 확인합니다.
        2. [POST /payments/naver/ordersheet 네이버페이 주문서 생성하기](https://docs.shopby.co.kr/?url.primaryName=order/#/NaverPay/post-payments-naver-ordersheet)\
           1번에서 호출한 `검증 API` 응답 값이 `true` 인 경우에만 Npay 주문서를 생성하시면 됩니다.
           * `clientReturnUrl` 은 주문 실패 혹은 뒤로가기 시 리다이렉트 되는 주소로 `Npay`의 `backUrl`로 설정됩니다. 샵바이 기본 스킨에서는 `location.href` 로 설정합니다.<br>

    * WISHLIST\_BUTTON\_HANDLER: `찜` 하기 버튼 클릭 시 호출하는 핸들러
      * [POST /payments/naver/wish-list 네이버페이 찜 등록하기](https://docs.shopby.co.kr/?url.primaryName=order/#/NaverPay/post-payments-naver-wish-list) API 를 호출해 `찜` 기능을 구현할 수 있습니다.


# 결제 모듈 스크립트 가이드

## 결제 모듈 스크립트(ncp\_pay.js) 에 대하여

### 목적

샵바이에서 kcp, inicis, (구)LG-uPlus, naverpay(결제형/주문형), payco, kakaopay 등 다양한 pg를 이용한 결제를 할 때 프런트에서 간단한 코드 호출만으로 결제를 붙일 수 있도록 통일된 인터페이스를 만들어 주기 위해 제공하는 자바스크립트입니다.

### 사용법

* 결제 모듈 스크립트 import

```
<script src="https://shop-api.e-ncp.com/payments/ncp_pay.js"></script>
```

* `setConfiguration`을 통해 공통 설정을 사전에 지정해두면, 이후 `reservation` 호출 시 모든 PG사에서 동일한 동작을 보장합니다.

```
1.결제 모듈 기본 설정 적용 (NCPPay.setConfiguration)
 1-1. Oauth2 인증 방식을 사용하는 경우
  NCPPay.setConfiguration({
      'clientId': clientId, // shopby에서 발급받은 clientId
      'confirmUrl': 'http://쇼핑몰의URL/쇼핑몰에서_결제결과를_리턴받을_페이지.html', // 결제 완료후 리턴을 받을 업체의 URL
      'platform': 'PC', //  'PC or MOBILE_WEB or AOS OR IOS'
      'shopbyAuthorization': accessToken ? `Bearer ${accessToken}` : '', // oauth2 토큰을 발급 받아 로그인한 사람의 토큰 값
      'accessToken': ''
  });

  1-2. AccessToken 인증 방식을 사용하는 경우
  NCPPay.setConfiguration({
      'clientId': clientId, // shopby에서 발급받은 clientId
      'confirmUrl': 'http://쇼핑몰의URL/쇼핑몰에서_결제결과를_리턴받을_페이지.html', // 결제 완료후 리턴을 받을 업체의 URL
      'platform': 'PC', //  'PC or MOBILE_WEB or AOS OR IOS'
      'accessToken': accessToken ? ${accessToken} : ''  // accessToken 토큰을 발급 받아 로그인한 사람의 토큰 값 
  });

2.주문하기
  NCPPay.reservation(
    orderInfo,                     // 주문 정보 데이터 
    (result) => {                  // 주문 예약하기 api 성공시 콜백함수
      console.log('주문 성공');
    },
    (result) => {                  // 주문 예약하기 api 에러 발생시 콜백함수
      console.log('주문 실패');      // 아래 4번째 인자 값과 무관하게 항상 호출됨
    },
    false,                         // 주문 예약하기 api 에러 발생시, 기본 얼럿 노출 비활성화 여부(true: 안 띄움 / false: 띄움) 
                                   //   - 기본값 false
                                   //   - false: 얼럿 띄움
                                   //   - true : 얼럿을 띄우지 않음. 에러 UI를 직접 제어할 때 사용
                                   //            (true로 두면 사용자에게 보일 에러 UI는 3번째 인자(failCallback)에서 직접 처리)
    {}                             // pg에 전달할 추가 파라미터
  );
```

#### reservation 에 필요한 data

* 아래 문서에 전달되어야 하는 reqeust 값을 json 형태로 data 파라메터로 전달합니다.
* [결제 예약 데이터 양식](https://docs.shopby.co.kr/?url.primaryName=order/#/Purchase/post-payments-reserve)

#### 결제 결과

* 성공인 경우 NCPPay.setConfiguration 에 설정한 confirmUrl 로 성공, 실패인 경우 결과를 리턴합니다.
* 성공인 경우
  * request parameter 로 결과 값을 SUCCESS 로 전달합니다.
  * 주문이 성공한 주문번호를 같이 전달해 줍니다.
  * ex)result=SUCCESS\&orderNo=123
* 실패힌 경우
  * request parameter 로 결과 값을 FAIL로 전달합니다.
  * message 에 실패한 이유를 같이 전달해 줍니다.
  * ex)result=FAIL\&message=잔액부족

#### 글로벌 쇼핑몰

* 글로벌 쇼핑몰의 경우, 결제 모듈 기본 설정 시 **언어(language)** 및 **통화 코드(currency code)** 정보를 함께 전달받습니다.

  이를 통해 각 국가별 결제 환경에 맞는 결제수단 및 표시 정보를 세팅할 수 있습니다.

```
1.결제 모듈 기본 설정 적용 (NCPPay.setConfiguration)
  NCPPay.setConfiguration({
      'clientId': clientId, // shopby에서 발급받은 clientId
      'confirmUrl': 'http://쇼핑몰의URL/쇼핑몰에서_결제결과를_리턴받을_페이지.html', // 결제 완료후 리턴을 받을 업체의 URL
      'platform': 'PC', //  'PC or MOBILE_WEB or AOS OR IOS'
      'shopbyAuthorization': accessToken ? `Bearer ${accessToken}` : '', // oauth2 토큰을 발급 받아 로그인한 사람의 토큰 값
      'accessToken': '',
      'language': 'ko', // 언어
      'currency': 'KRW' // 통화 코드
  });
```

### 제약조건

* 추가로 각 PG 사에서 제공하는 결제 모듈 javascript 를 로드해야 합니다.

  기본 스킨에서는 주문서 화면에서 실행환경에 따라 아래와 같은 결제 모듈 javascript 를 로드하고 있습니다.

```
// 모바일 환경 체크는 프로젝트에 맞는 방식으로 추가 부탁드립니다.
const ksnetScriptUrl = isMobile ? 'https://kspay.ksnet.to/KSPayMobileV1.4/mall/js/kspay_api_ssl.js' : 'https://kspay.ksnet.to/KSPayWebV1.4/mall/js/kspay_api_ssl.js';

const payScripts = {
  [
    'https://shop-api.e-ncp.com/payments/ncp_pay.js',              // 결제모듈 스크립트 (필수)
    'https://nsp.pay.naver.com/sdk/js/naverpay.min.js',            // 네이버페이 
    'https://spay.kcp.co.kr/plugin/kcp_spay_hub.js',               // kcp
    'https://xpay.tosspayments.com/xpay/js/xpay_crossplatform.js', // 토스페이먼츠
    'https://pay.smartropay.co.kr/asset/js/SmartroPAY-1.0.min.js', // 스마트로
    'https://chai.finance/js/v1/payment.min.js',                   // 차이페이
    'https://web.nicepay.co.kr/v3/webstd/js/nicepay-3.0.js',       // 나이스페이
    'https://api.eximbay.com/v1/javascriptSDK.js',                 // 엑심베이
    'https://pay.billgate.net/paygate/plugin/gx_web_client.js',    // 갤럭시아머니트리
    ksnetScriptUrl                                                 // KSNET 
  ],
};
```

### payType 과 pgType 에 대하여

* 해당 쇼핑몰에서 사용설정한 PG와 결제 수단과 상품에 따라 해당 주문에서 사용 가능한 결제 수단을 [주문서 조회하기 api](https://docs.shopby.co.kr/?url.primaryName=order/#/OrderSheet/get-order-sheet) 에서 내려줍니다.
* 사용가능한 결제 수단에 따라 pgType 이 결정됩니다.

#### 제공 중인 payType과 pgType

* **payType**: 사용 가능한 결제수단
* **pgType**: 실제 결제를 발생시키는 외부 PG

| PayType 코드                          | 결제 수단                | PgType 코드            | 결제사         |
| ----------------------------------- | -------------------- | -------------------- | ----------- |
| CREDIT\_CARD                        | 신용카드                 | PAYCO                | PAYCO       |
| ACCOUNT                             | 무통장입금                | PAYPAL               | Paypal      |
| MOBILE                              | 휴대폰결제                | STRIPE               | 스트라이프       |
| REALTIME\_ACCOUNT\_TRANSFER         | 실시간계좌이체              | KCP                  | kcp         |
| VIRTUAL\_ACCOUNT                    | 가상계좌                 | INICIS               | 이니시스        |
| GIFT                                | 상품권                  | NONE                 | 무통장입금       |
| ATM                                 | ATM                  | KCP\_MOBILE          | kcp(모바일)    |
| PAYCO                               | PAYCO                | KCP\_APP             | kcp(앱)      |
| ZERO\_PAY                           | 0원결제                 | NAVER\_PAY           | 네이버페이       |
| ACCUMULATION                        | 적립금 전액 사용            | LIIVMATE             | 리브메이트       |
| PHONE\_BILL                         | 전화결제                 | PAYPALPRO            | Paypal pro  |
| POINT                               | 포인트결제                | ATHOR\_NET           | AthorizeNet |
| YPAY                                | 옐로페이                 | KAKAO\_PAY           | 카카오페이       |
| KPAY                                | 케이페이                 | NAVER\_EASY\_PAY     | 네이버페이(결제형)  |
| PAYPIN                              | 페이핀                  | LG\_U\_PLUS          | 토스페이먼츠      |
| INIPAY                              | INIPay 간편결제          | TOSS\_PAYMENTS       | 토스페이먼츠      |
| PAYPAL                              | PayPal               | CHAI                 | 차이          |
| STRIPE                              | 스트라이프                | SMARTRO\_PAY         | 스마트로        |
| NAVER\_PAY                          | 네이버페이 주문형            | NICEPAY              | 나이스페이       |
| KAKAO\_PAY                          | 카카오페이                | MY\_PAY              | 마이페이        |
| NAVER\_EASY\_PAY                    | 네이버페이 결제형            | EXIMBAY\_GLOBAL      | 엑심베이(글로벌)   |
| NAVERPAY\_SIMPLE                    | 네이버페이                | EASY\_PAY            | 이지페이        |
| SAMSUNG\_PAY                        | 삼성페이                 | GALAXIA\_MONEY\_TREE | 갤럭시아머니트리    |
| CHAI                                | 차이                   | KSNET                | KSNET       |
| TOSS\_PAY                           | 토스페이                 | EASY\_PAY\_OVERSEAS  | 이지페이(해외 전용) |
| SK\_PAY                             | SK페이                 | BLUE\_WALNUT         | 블루월넛        |
| APPLE\_PAY                          | 애플페이                 | HMG\_PAY\_H          | 현대페이        |
| LPAY                                | 엘페이                  | HMG\_PAY\_K          | 기아페이        |
| ESCROW\_REALTIME\_ACCOUNT\_TRANSFER | 실시간계좌이체-에스크로         | APP\_CARD            | 앱카드         |
| ESCROW\_VIRTUAL\_ACCOUNT            | 가상계좌-에스크로            | TOSS\_EASY\_PAY      | 토스 간편결제     |
| VERITRANS\_CARD                     | Veritrans CreditCard | VERITRANS            | Veritrans   |
| TOASTCAM                            | 토스트캠                 | <p><br></p>          | <p><br></p> |
| UNION\_PAY                          | UnionPay             | <p><br></p>          | <p><br></p> |
| ALIPAY                              | Alipay Plus          | <p><br></p>          | <p><br></p> |
| WECHAT\_PAY                         | WeChat Pay           | <p><br></p>          | <p><br></p> |
| EXTERNAL\_PAY                       | 외부 결제 전액 사용          | <p><br></p>          | <p><br></p> |
| RENTAL                              | 렌탈결제                 | <p><br></p>          | <p><br></p> |
| PINPAY                              | 핀페이                  | <p><br></p>          | <p><br></p> |
| HMG\_PAY                            | HMG pay              | <p><br></p>          | <p><br></p> |
| APP\_CARD                           | 앱카드                  | <p><br></p>          | <p><br></p> |
| PAY\_PAY                            | 페이페이                 | <p><br></p>          | <p><br></p> |
| E\_CONTEXT                          | 일본 편의점결제             | <p><br></p>          | <p><br></p> |
| HAPPY\_VOUCHER                      | 국민행복바우처              | <p><br></p>          | <p><br></p> |
| ETC                                 | 기타결제수단               | <p><br></p>          | <p><br></p> |


# FAQ


# 에러코드\_ (1) 주문

업데이트 일자: 2025. 3. 4

```
[FAQ] 주문 API 관련 에러코드 및 에러메시지를 모두 모아서 안내드리는 가이드입니다 .
```

* NCPE0001, 오류가 발생하였습니다. 잠시 후 다시 시도해 주세요.
* NCPE0002, 잘못된 요청입니다.
* NCPE0003, 인증 정보가 필요합니다.
* NCPE0004, 접근 권한이 없습니다.
* NCPE0005, 대상이 존재하지 않습니다
* NCPE0006, 허용되지 않는 처리(Method) 요청 입니다.
* NCPE0007, 제공할 수 없는 컨텐츠 타입니다.
* NCPE0008, 처리할 수 없는 컨텐츠 타입입니다.
* NCPE0009, 올바르지 않은 금액 타입입니다.
* **NCPE0020**, 설정값이 올바르지 않습니다.{0}
* NCPE0010, 파라미터 값이 올바르지 않습니다. {0}
* NCPE0011, 파트너어드민만 사용 가능합니다.
* NCPE0012, 서비스어드민만 사용 가능합니다.
* NCPE0013, 플랫폼 타입을 정확히 입력해 주세요!
* NCPE0014, 다른 작업을 처리중입니다. 잠시 후 다시 시도해 주세요.
* NCPE0015, **{0}은(는) {1}자를 초과할 수 없습니다.**
* O3040, 배송지 우편번호가 올바르지 않습니다.
* O3041, 배송지 주소가 올바르지 않습니다.
* **O3049**, 배송지가 존재하지 않습니다
* **O30500**, 비회원은 사용이 불가능한 기능입니다.
* **O30510**, 기본배송지는 삭제할 수 없습니다. 변경 후 삭제해주세요.
* O3003, 주문서번호가 올바르지 않습니다.
* O3004, PG사 결제 예약에 실패하였습니다.
* O3005, PG사 결제 완료에 실패하였습니다.
* O3006, \[{ 0 }] PG사 결제 실패하였습니다: { 1 }
* O3010, 결제 데이터를 찾을 수 없습니다.
* O3015, 결제예약에 실패하였습니다.
* O3017, 주문예약 정보가 올바르지 않습니다.
* O3019, 상품정보가 올바르지 않습니다.
* O3026, 비회원 주문은 주문임시암호가 필수 입니다.
* O3028, 해외 직배송 상품 구매 시 개인통관고유부호는 필수로 입력해야 합니다.
* O3032, 비회원은 쿠폰을 사용 할 수 없습니다.
* O3035, 쿠폰정보가 올바르지 않습니다.
* O3036, 비회원은 적립금을 사용 할 수 없습니다.
* O3038, 상품 가격 또는 할인금액이 변경되었습니다. 다시 확인하시고 구매해 주세요.
* O3039, 중복된 결제 요청입니다.
* O3050, 비회원 주문은 주문자 이름이 필수 입니다.
* O3051, 비회원 주문은 핸드폰 번호가 필수 입니다.
* O3052, 비회원 주문은 이메일 주소가 필수 입니다.
* **O30520, 배송 불가능한 국가가 포함되어있습니다.**
* O3061, 가상계좌는 수동 입금확인이 불가합니다. PG를 통해 처리해 주세요.
* **O3062**, 사용 적립금이 사용가능한 적립금보다 큽니다.
* O3064, **적립금 {0}원 이상 사용 가능합니다.**
* O3065, orderNos가 한개 이상 포함되어야 합니다.
* O3066, 주소지를 찾지 못했습니다.
* O3067, 적립금 사용이 가능한 상품이 없습니다.
* O3068, 결제 완료에 실패하였습니다.
* **O3069**, 무통장 입금 시 거래할 계좌의 정보(은행코드, 계좌번호, 예금주명)가 필요합니다.
* 10001, **회원이 존재하지 않습니다.**
* 10002, 본인인증이 필요합니다.
* 10003, { 0 } 결제키 정보가 필요합니다.
* 10004, 에스크로 결제는 배송 그룹이 여러 개일 경우 사용할 수 없습니다.
* 10005, 현금영수증 발급이 가능한 PG사 설정이 없습니다.
* 10006, 현금영수증 재발급에 필요한 기존 현금영수증 정보가 없습니다.
* 10007, 현금영수증 재발급에 필요한 기존 현금영수증 증빙타입이 없습니다.
* 10008, 현금영수증 재발급에 필요한 기존 현금영수증 발급값이 없습니다.
* 10009, 현금영수증 취소 금액이 유효하지 않습니다.
* 10010, 이용불가 상태의 회원입니다.
* 10011, 배송안함 주문은 에스크로 결제가 불가능 합니다.
* **O3361**, 사용자 결제 취소에 실패하였습니다.
* O3384, 입금 완료 후 처리에 실패하였습니다.
* 1001, 이미 가입한 회원입니다.
* 1002, 등록된 회원 정보가 없습니다.
* 9002, 입력정보에 오류가 있습니다. (HASH)
* 9003, 입력정보 오류입니다.
* 9999, 처리중 오류가 발생하였습니다. 관리자에게 문의하세요.
* O4001, 결제를 취소하셨습니다. 주문 내용 확인 후 다시 결제해주세요.
* O4002, 결제 가능 시간을 초과하였습니다. 주문 내용 확인 후 다시 결제해주세요.
* O4003, 본인 명의의 카드를 설정 후 다시 결제해주세요.
* O4005, 결제 가능 시간을 초과하였습니다. 주문 내용 확인 후 다시 결제해주세요.
* O4006, 이미 처리중인 주문입니다.
* O4007, 포인트 지급에 실패했습니다.
* O4008, PG, 은행 및 기타 오류 \[{0}]
* OR0001, 정기결제 요청 아이디가 존재하지 않습니다.
* OR0002, 정기결제가 설정되어 있지 않습니다.
* OR0003, 해당 회원의 정기결제 카드가 이미 설정되어 있습니다.
* OR0004, platformType 값이 없습니다.
* OR0005, recurringPaymentCardNo\[{0}] 에 해당하는 값이 없습니다.
* OR0006, 회원에게 활성화된 정기결제 카드가 없습니다.
* OR0007, 상품을 선택해주세요
* OR0008, 올바르지 않은 검색어 구분값입니다.
* **OR0060**, 정기결제 정보를 입력해주세요.
* OR0010, 월주기 정기결제에 배송일 값이 없습니다.
* OR0011, orderNo\[{0}] 정기주문 결제 후 처리에 실패했습니다.
* OR0012, addressNo\[{0}] 값이 존재하지 않습니다.
* OR0013, 동일한 상품(옵션) 은 중복 등록할 수 없습니다.
* OR0014, 주문당 배송지가 2개 이상입니다.
* OR0015, memberNo\[{0}] 는 존재하지 않습니다.
* OR0016, memberNo\[{0}] 의 상태\[{1}] 는 정기결제가 불가능합니다.
* OR0017, 한명의 회원만 전달되어야 합니다.
* OR0018, 없는 정기결제 아이디입니다.
* OR0019, 잘못된 정기결제 주기입니다.
* OR0020, 잘못된 정기결제 일 입니다.
* OR0021, 잘못된 정기결제 상품입니다.
* OR0022, 취소 사유 값이 없습니다.
* OR0023, confirmRedirectUrl 값이 없습니다.
* OR0024, 해당 배송 주소로 신청된 정기배송 건이 있어 수정 불가합니다. 정기배송 해지 후 수정 해주시기 바랍니다.
* OR0025, 해당 배송 주소로 신청된 정기배송 건이 있어 삭제 불가합니다. 정기배송 해지 후 삭제 해주시기 바랍니다.
* OR0026, 정기결제 배송주소만 등록 가능합니다.
* OR0027, 정기결제 상품의 배송주기를 다시 선택해주세요.
* OR0028, 정기결제 상품이 아닙니다.
* OR0029, 카드정보를 삭제하시려면 정기배송 상품을 먼저 해지해 주세요.
* OR0030, 상품가격 또는 할인금액 등 상품정보가 변경되었습니다. 다시 확인하시고 구매해 주세요.
* OR0031, 같은 상품이 정기배송중 입니다.
* OR0031, 변경하고자 하는 배송주기 타입은 이전과 동일해야합니다.
* ODSH0001, 주문서 {0} 가 존재하지 않습니다.
* ODSH0002, 주문서에 담긴 상품 정보가 올바르지 않습니다.
* ODSH0003, 쿠폰정보가 올바르지 않습니다.
* O3336, 인증이 먼저 진행되어야 합니다
* O3338, 인증이 먼저 진행되어야 합니다
* O3336, 인증이 먼저 진행되어야 합니다
* ODSH0005, 주문서의 유효기간이 만료하여 결제를 진행할 수 없습니다. 다시 주문해 주세요.
* ODSH0006, 브랜드{0} 정보를 찾을 수 없습니다.
* ODSH0007, 배송그룹 정보에서 상품{0}을 찾을 수 없습니다.
* ODSH0008, 상품{0} 재고 정보를 찾을 수 없습니다.
* ODSH0009, 잘못된 주문서 아이디 {0} 입니다.
* ODSH0010, 사용 가능한 적립금{0}을 초과 하였습니다.
* ODSH0011, 최소 사용 가능 적립금은 {0} 입니다.
* ODSH0012, 주문서 {0} 의 주문번호를 찾을 수 없습니다.
* ODSH0013, 비회원 주문서 쿠폰을 사용할 수 없습니다.
* ODSH0014, PG사 또는 결제수단이 올바르지 않습니다.
* W0001, 등록할 수 있는 최대 상품수를 초과하였습니다.
* OD0001, 주문상태가 동일하지 않습니다.
* OD0002, 주문상태 변경이 불가 합니다.
* OD0003, { 0 }은(는) 필수입니다.
* OD0004, 재고가 부족합니다.
* OD0005, 존재하지 않는 주문입니다.
* OD0006, 존재하지 않는 주문상품입니다. \[{ 0 }]
* OD0007, 존재하지 않는 주문옵션입니다. \[{ 0 }]
* OD0008, 존재하지 않는 배송입니다. \[{ 0 }]
* OD0009, 검색시 몰 번호는 필수입니다.
* OD0010, 주문 상태변경 실패입니다.
* OD0011, 존재하지 않는 현금영수증입니다.
* OD0012, 존재하지 않는 주문서입니다.
* OD0013, 잘못된 현금영수증 값 입니다. { 0 }
* OD0014, 존재하지 않는 장바구니입니다.
* OD0015, 발급되지 않은 현금영수증 입니다.
* O0016, 당신의 주문이 아닙니다.
* O0007, 구매확정 가능한 상태가 아닙니다.
* O0008, 이미 구매확정된 주문입니다.
* D0002, 배송지 변경이 불가능한 주문상태입니다.
* D0003, 지역별 추가 배송비 발생 지역으로 변경이 불가합니다. 취소 후 재주문 해주시기 바랍니다.
* O7001, 로그인 세션이 만료되었습니다. 로그인 후 이용해 주세요.
* O7002, 동일 주문번호로 중복조회가 불가합니다. 열려있는 주문조회를 종료하시고 다시 진행해 주시기 바랍니다.
* O7003, 비회원 주문이 아닙니다. 로그인 후 확인 해주시기 바랍니다.
* O8001, 회원만 구매 가능한 상품입니다. 로그인해 주세요.
* O8002, ''{0}'' 상품은 최대 {1}개 까지 구매 가능한 상품입니다. 수량을 다시 확인해 주세요.
* O8003, ''{0}'' 상품은 최대 {1}개 까지 구매 가능한 상품입니다. 수량을 다시 확인해 주세요.
* O8004, ''{0}'' 상품은 최대 {1}개 까지 구매 가능한 상품입니다. 수량을 다시 확인해 주세요.
* O0009, 주문번호 또는 비밀번호가 일치하지 않습니다.
* O0010, 주문번호 또는 이메일이 일치하지 않습니다.
* O0018, 비회원 주문의 이름이 맞지 않습니다.
* O0019, 비회원 주문의 연락처가 맞지 않습니다.
* O0020, 비회원 장바구니 정보가 올바르지 않습니다.
* O0022, 장바구니 정보가 올바르지 않습니다.
* O9001, 잘못된 요청입니다.
* O9002, 조회기간은 최대 {0}개월까지 가능합니다.
* O9003, {0} 파라미터 값이 잘못되었습니다.
* E0003, 송장번호 혹은 택배사가 지정되지 않았습니다.
* O0021, 주문옵션번호 {0}의 주문상태가 잘못되었습니다.
* O0023, 클레임 환불 조정 금액과 과세 금액의 합이 0보다 적습니다.
* O0024, 사용 요청 적립금이 결제 금액보다 많습니다.
* O0027, {0} 에는 이모티콘을 입력할 수 없습니다.
* O0028, 주문에 포함된 전체 상품이 취소완료 상태인 경우에만 주문삭제가 가능합니다.
* O0029, 네이버페이 발송지연 처리된 주문 건이 포함되어 있습니다. 발송지연 처리된 주문건을 제외하고 처리해 주세요.
* O0030, 네이버페이 주문형 주문만 처리 가능합니다.
* O0033, 이메일 주소가 확인되지 않아 임시 비밀번호 발급이 불가합니다.
* O0034, 선택하신 상품에 필수 텍스트옵션 미입력 상품이 있습니다. 필수 텍스트옵션을 선택해주세요.
* O0037, 성인 인증된 회원만 구매 가능합니다.
* O0038, 비밀번호 재발급을 위한 인증에 실패하였습니다.
* O0039, 입력하신 정보와 일치하는 주문이 존재하지 않습니다. 다시 입력해 주세요. 주문번호와 비밀번호를 잊으신 경우, 고객센터로 문의하여 주시기 바랍니다.
* O0045, 해당 몰에 이전주문 설정이 존재하지 않습니다.
* O0046, 현재 무통장입금 결제가 불가합니다. 관리자에게 문의하세요.
* O0047, 무통장입금을 사용할 수 없습니다. 관리자에게 문의하세요.
* PPVE0001, 구매불가한 옵션이 포함되어 있습니다.
* PPVE0002, 장바구니 담기 불가능한 상품입니다.
* PPVE0003, 미성년자 구매불가 상품입니다.
* PPVE0004, 비회원 구매불가 상품입니다.
* PPVE0005, 구매불가한 상품입니다.
* PPVE0006, 해당 결제수단으로 결제가 불가능한 상품이 포함되어 있습니다.
* PPVE0007, 구매가능한 회원등급이 아닙니다.
* PPVE0008, 구매가능한 회원그룹이 아닙니다.
* PPVE0009, ''{0}'' 상품은 최소 {1}개 이상 구매 가능한 상품입니다. 수량을 다시 확인해 주세요.
* PPVE0010, 본인인증된 회원만 구매 가능한 상품입니다. 로그인해 주세요.
* PPVE0011, 구매불가한 옵션이 포함되어 있습니다.
* PPVE0020, 구매불가한 상품입니다.
* PPVE0012, 삭제된 상품입니다.
* PPVE0013, 판매중지된 상품입니다.
* PPVE0014, 판매대기중인 상품입니다.
* PPVE0015, 판매종료된 상품입니다.
* PPVE0016, 판매금지된 상품입니다.
* PPVE0017, 예약판매대기중인 상품입니다.
* PPVE0018, 예약판매종료된 상품입니다.
* PPVE0019, 구매불가한 상품입니다.
* PPVE0021, 배송지정일이 등록된 상품은 정기 배송이 불가합니다.
* PPVE0022, 유효하지 않은 정기결제 할인가가 적용되었습니다.

<br>




---

[Next Page](/llms-full.txt/1)