# \[엔터프라이즈] 외부 적립금 연동가이드
## 외부 적립금이란?
#### 샵바이에 입점하고자하는 고객사에서 별도의 적립금(마일리지) 혜택을 이미 가지고 있는 경우,
고객사에서 진행할 수 있는 2가지 외부 적립금 호환 방식이 있습니다.
### (방법1) 외부 적립금 전환
#### 개념
고객사 시스템의 적립금을 샵바이 시스템의 적립금으로 '전환'하여, 샵바이 내부 프로세스에 따라 쇼핑몰 고객의 적립금을 지급/차감/조회할 수 있는 개념입니다.\
#### 상세설명
샵바이에서는 이와 관련된 server API를 제공하고 있으며, 해당 API의 호출 주체는 고객사입니다.\
쇼핑몰 고객들이 기존의 적립금을 샵바이의 적립금으로 전환할 수 있는 프론트 구현이 필요합니다.\
자세한 API 내용은 [외부 적립금 전환 가이드](https://workspace.nhn-commerce.com/support/recommendedContents/23047)를 참고하시길 바랍니다.
***
### (방법2) 외부 적립금 연동
본 문서에서 아래 소개 드릴 방식입니다.
#### 개념
고객사에서 기존에 사용하던 적립금(마일리지)를 전환 절차 없이 그대로 사용할 수 있고, 샵바이에서 고객사의 외부적립금을 연동하는 개념입니다.
#### 상세설명
고객사에서 아래에서 안내드릴 스펙에 따라 API를 개발하여 저희 측으로 uri 등을 전달주시면, 해당 API의 호출 주체는 저희 샵바이입니다.\
(ex) 적립금 조회 시, 샵바이에서 고객사에서 개발한 API를 호출하여 고객사의 DB를 조회합니다.\
#### 주의사항
※ 단, 샵바이에서 API 호출 시, 고객사 서버에서 바로 응답되지 않는 성능 이슈가 발생하지 않도록 신경 써주시길 바랍니다.\
※ 적립금이 중복으로 지급될 수 있는 케이스에 대해 확인하시길 바랍니다. (아래 적립금 지급API '제약조건' 문단 확인)\
#### 연동 프로세스
* step 1. 아래 안내드릴 API 스펙에 따라 고객사에서 API 개발
* step 2. \[NHN커머스> 고객센터> 1:1문의]를 통해 아래 정보들을 세팅요청 해주시길 바랍니다. [1:1문의 바로가기>](https://support.nhn-commerce.com/inquiry/list)
| 항목 | 샘플 (예시) | 설명 |
| ---------------------------------- | ------------------------------------------------- | ------------------------------------------------------ |
| 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의 값 |
|
(추가)
memberMappingKey
| MEMBER\_ID(default), MEMBER\_NO, CI | 맴버 맵핑 키 |
* step 3. 아래 NHN커머스 샵바이 ACL 추가바랍니다.
* 리얼 환경: 103.194.111.5, 115.89.203.145
* 2024-08-26 memberMappingKey 항목 추가되었습니다.
* 샘플(예시)
```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"
}
}
```
***
## 적립금 적립/차감/롤백 다이어그램
### 적립금 적립 프로세스
***
### 적립금 차감/ 롤백 프로세스
***
## 1. 적립금 지급 (필수)
### 적립금 지급 API (개발 스펙 안내)
{% hint style="info" %}
* request 는 request body 로 전달
* 형태는 json
{% endhint %}
#### ■ method
* POST
#### ■ request
| attribute | name | required | description | type |
| --------------------------------------------- | -------------------------- | -------- | --------------------------------------------------------------------- | ------------------------------------- |
| memberKey | 회원 연계 키 | 필수 |
| 선택 | 추가 연동키 | Int(nullable) |
| (추가) additionalMappingKey.orderOptionNo |
추가정보 (연관 주문옵션번호)
| 선택 | 추가 연동키 | Int(nullable) |
* 2023-07-24 reasonType 항목 추가되었습니다.
* 2024-01-24 additionalMappingKey.orderNo, additionalMappingKey.reviewNo,additionalMappingKey.orderOptionNo 항목 추가됩니다. (2/20 배포완료)
#### ※ reasonType 코드 값 설명
* 적립 - 적립 - 상품 주문 적립 (구매확정)\
ADD\_AFTER\_PAYMENT
* 적립 - 적립 - 교환/추가결제 적립 (교환대상 가격 > 원주문 상품가격)\
ADD\_AFTER\_REPLACE\_PAYMENT
* 적립 - 사이트 활동 적립 - 상품평 작성 완료\
ADD\_POSTING
* 적립 - 수동적립\
ADD\_MANUAL
* 적립 - 회원가입시 자동 적립\
ADD\_SIGNUP
* 적립 - 생일축하 적립\
ADD\_BIRTHDAY
* 적립 - 회원등급 적립\
ADD\_GRADE
* 적립 - 등급 혜택 즉시 지급\
ADD\_GRADE\_BENEFIT
***
#### ■ response
#### 성공인 경우
| attribute | name | required | description | type |
| --------- | ------ | -------- | ----------- | ------ |
| no | 지급 key | 필수 | 적립 연계키 | String |
#### 실패인 경우
* http code 400 으로 전달
* 보통의 경우 errorMessage로 전달된 실패사유를 사용자에게 노출하거나 로그로 남깁니다.
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달
```json
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}
```
### 제약조건
※ `생일자 적립금 지급`, `등급 적립금 지급` 정기 지급 시, 일 배치(daily batch)로 적립금을 지급합니다.\
단, 해당 정기지급은 `mappingKey`가 0으로 등록되어 있어 외부적립금 사용 시 중복 지급될 수 있습니다.
만약 '[적립금 전환 방식](https://shopby.works/support/recommendedContents/23047)'으로 NHN커머스 샵바이의 적립금을 사용할 경우, 적립금 지급 번호와 사유를 내부 코드로 관리하여 중복지급을 제외할 수 있으나\
본 문서에서 안내드리는 '외부 적립금 연동 방식' 을 사용할 경우, 지급코드를 별도로 관리하지 않기 때문에 중복 지급 될 수 있습니다.
(예시) 중복지급 될 수 있는 케이스\
: \[고객이 1/1을 생일로 등록]-> \[1/1 일 배치를 통해 생일 적립금 지급]-> \[1/2에 고객이 생일을 1/3으로 변경]-> \[1/3 일 배치에서 생일 적립금 중복 지급]\
### 참고사항
`적립금 차감 API` 및 `적립금 차감 롤백 API`는 존재하나,\
`적립금 적립 API`에 대한 `적립금 적립 롤백 API` 는 제공하지 않는 점 참고부탁드립니다.
따라서 이미 적립된 적립금을 차감하기 위해서는, 아래 문서에서 소개 드릴 `적립금 차감 API`를 개발하시길 바랍니다.
***
## 2. 적립금 차감 (필수)
### 적립금 차감 API (개발 스펙 안내)
{% hint style="info" %}
* request 는 request body 로 전달
* 형태는 json
{% endhint %}
#### ■ method
* POST
#### ■ request
| attribute | name | required | description | type |
| ---------------------------------- | -------------------------- | -------- | ----------------------------------------------------------------- | ---------------- |
| memberKey | 회원 연계 키 | 필수 |
| 선택 | 롤백용\* | Int(nullable) |
| additionalMappingKey.reviewNo |
추가정보 (연관 상품리뷰번호)
| 선택 | 롤백용\* | Int(nullable) |
| additionalMappingKey.orderOptionNo |
추가정보 (연관 주문옵션번호)
| 선택 | 롤백용\* | Int(nullable) |
| (추가) orderExtraData | 주문추가정보(JsonString) | 선택 | 주문 예약단계에서 shop api(url링크)에서 입력한 ExtraData를 그대로 바이패스 | String(nullable) |
* 2024-02-20 request > orderExtraData 항목이 신규 추가됩니다.
* 참고사항 (\*)\
구매확정 후 반품 시, 이미 지급된 적립금 정보 확인을 위해 `적립금 차감 API`의 request 항목이 위와 같이 추가되었습니다.\
외부적립금 연동 방식을 사용 중인 고객사의 경우, 새로 추가된 데이터에 대응 가능한 구조로 변경하시길 바랍니다.
* 2023-08-10 reasonType 항목 업데이트 되었습니다.
#### ※ reasonType 코드 값 설명
* 차감 - 사용 - 상품 주문 시 적립금 사용 (결제완료)\
SUB\_PAYMENT\_USED
* 차감 - 사용 - 교환상품 추가 결제 시 적립금 사용 (추가결제 완료)\
SUB\_EXTRA\_PAYMENT\_USED
* 차감 - 적립취소 - 상품평 삭제\
SUB\_DELETE\_POSTING
* 차감 - 수동차감\
SUB\_MANUAL\
\
* 샘플 (예시)
| 선택 | | Int |
| contents | no | 적립금 번호 | 필수 | PK | Int |
| contents | memberKey | 회원 연계 키 | 필수 | 연계키 | String |
| contents | type |
지급/차감/ 지급롤백/ 차감롤백
| 필수 | 적립금 | 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\ (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 %}
#### 실패인 경우
* http code 400
* 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달
{% code overflow="wrap" %}
```json
{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}
```
{% endcode %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://workspace-help.nhn-commerce.com/contents/recommended/prm_mileage_guide.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.