> For the complete documentation index, see [llms.txt](https://workspace-help.nhn-commerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://workspace-help.nhn-commerce.com/contents/recommended/prm_mileage_guide.md).
# \[엔터프라이즈] 외부 적립금 연동가이드
## 외부 적립금이란?
#### 샵바이에 입점하고자하는 고객사에서 별도의 적립금(마일리지) 혜택을 이미 가지고 있는 경우,
고객사에서 진행할 수 있는 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
회원 연계 키
필수
연동시 사용한 유형의 값
(MEMBER_ID,MEMBER_NO,CI)
String
amount
적립금액
필수
적립금
Long
reason
적립 세부내역 사유
필수
String
reasonType
적립금 지급 사유
필수
enum 형식
String
expiredDateTime
적립금 만료일
필수
LocalDateTime : 'yyyy-MM-dd HH:mm:ss'
mappingKey
적립키
필수
롤백용으로 사용하는 값
주문번호, 리뷰번호, 주문옵션 번호 또는 "0" 으로 전달
String
(추가) additionalMappingKey.orderNo
추가정보 (연관 주문번호)
선택
추가 연동키
Int(nullable)
(추가) additionalMappingKey.reviewNo
추가정보 (연관 상품리뷰번호)
선택
추가 연동키
Int(nullable)
(추가) additionalMappingKey.orderOptionNo
추가정보 (연관 주문옵션번호)
선택
추가 연동키
Int(nullable)
requestId
멱등성 키
필수
동일한 값으로 재요청 시, 중복 처리하지 않고 정상 응답 변환 필요.
String
* 2023-07-24 reasonType 항목 추가되었습니다.
* 2024-01-24 additionalMappingKey.orderNo, additionalMappingKey.reviewNo,additionalMappingKey.orderOptionNo 항목 추가됩니다. (2/20 배포완료)
* 2026-07-01 requestId 항목이 추가되었습니다.
#### ※ 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 | 회원 연계 키 | 필수 |