[프리미엄] 외부 적립금 연동가이드

외부 적립금이란?

샵바이에 입점하고자하는 고객사에서 별도의 적립금(마일리지) 혜택을 이미 가지고 있는 경우,

고객사에서 진행할 수 있는 2가지 외부 적립금 호환 방식이 있습니다.

(방법1) 외부 적립금 전환

개념

고객사 시스템의 적립금을 샵바이 시스템의 적립금으로 '전환'하여, 샵바이 내부 프로세스에 따라 쇼핑몰 고객의 적립금을 지급/차감/조회할 수 있는 개념입니다.

상세설명

샵바이에서는 이와 관련된 server API를 제공하고 있으며, 해당 API의 호출 주체는 고객사입니다. 쇼핑몰 고객들이 기존의 적립금을 샵바이의 적립금으로 전환할 수 있는 프론트 구현이 필요합니다. 자세한 API 내용은 외부 적립금 전환 가이드를 참고하시길 바랍니다.

---

(방법2) 외부 적립금 연동

본 문서에서 아래 소개 드릴 방식입니다.

개념

고객사에서 기존에 사용하던 적립금(마일리지)를 전환 절차 없이 그대로 사용할 수 있고, 샵바이에서 고객사의 외부적립금을 연동하는 개념입니다.

상세설명

고객사에서 아래에서 안내드릴 스펙에 따라 API를 개발하여 저희 측으로 uri 등을 전달주시면, 해당 API의 호출 주체는 저희 샵바이입니다. (ex) 적립금 조회 시, 샵바이에서 고객사에서 개발한 API를 호출하여 고객사의 DB를 조회합니다.

주의사항

※ 단, 샵바이에서 API 호출 시, 고객사 서버에서 바로 응답되지 않는 성능 이슈가 발생하지 않도록 신경 써주시길 바랍니다. ※ 적립금이 중복으로 지급될 수 있는 케이스에 대해 확인하시길 바랍니다. (아래 적립금 지급API '제약조건' 문단 확인)

연동 프로세스

• step 1. 아래 안내드릴 API 스펙에 따라 고객사에서 API 개발

• step 2. [NHN커머스> 고객센터> 1:1문의]를 통해 아래 정보들을 세팅요청 해주시길 바랍니다. 1:1문의 바로가기>

항목	샘플 (예시)	설명
domain	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 항목 추가되었습니다.

• 샘플(예시)

{
    "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 (개발 스펙 안내)

• request 는 request body 로 전달

• 형태는 json

■ 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)

• 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 로 에러 코드와 메시지를 전달

{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}

제약조건

※ 생일자 적립금 지급, 등급 적립금 지급 정기 지급 시, 일 배치(daily batch)로 적립금을 지급합니다. 단, 해당 정기지급은 mappingKey가 0으로 등록되어 있어 외부적립금 사용 시 중복 지급될 수 있습니다.

만약 '적립금 전환 방식'으로 NHN커머스 샵바이의 적립금을 사용할 경우, 적립금 지급 번호와 사유를 내부 코드로 관리하여 중복지급을 제외할 수 있으나 본 문서에서 안내드리는 '외부 적립금 연동 방식' 을 사용할 경우, 지급코드를 별도로 관리하지 않기 때문에 중복 지급 될 수 있습니다.

(예시) 중복지급 될 수 있는 케이스 : [고객이 1/1을 생일로 등록]-> [1/1 일 배치를 통해 생일 적립금 지급]-> [1/2에 고객이 생일을 1/3으로 변경]-> [1/3 일 배치에서 생일 적립금 중복 지급]

참고사항

적립금 차감 API 및 적립금 차감 롤백 API는 존재하나, 적립금 적립 API에 대한 적립금 적립 롤백 API 는 제공하지 않는 점 참고부탁드립니다.

따라서 이미 적립된 적립금을 차감하기 위해서는, 아래 문서에서 소개 드릴 적립금 차감 API를 개발하시길 바랍니다.

---

2. 적립금 차감 (필수)

적립금 차감 API (개발 스펙 안내)

• request 는 request body 로 전달

• 형태는 json

■ method

• POST

■ request

attribute	name	required	description	type
memberKey	회원 연계 키	필수	연동시 사용한 유형의 값 (MEMBER_ID,MEMBER_NO,CI)	String
amount	차감금액	필수	적립금	Long ( 양수 )
reason	차감 사유	필수		String
reasonType	직립금 차감 사유	필수	enum 형식	String
mappingKey	차감키	필수	롤백용으로 사용하는 값 주문번호, 리뷰번호, 주문옵션 번호 또는 "0" 으로 전달	String
additionalMappingKey.orderNo	추가정보 (연관 주문번호)	선택	롤백용*	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

• 샘플 (예시)

{"amount" : 100,
"reason" : "테스트 차감",
"memberKey" : "[e-mail]",
"mappingKey" : "2022080117000000001",
"additionalMappingKey" : {
    "orderNo" : "2022080117000000001",
    "reviewNo" : "3",
    "orderOptionNo" : "2"
    }
}

■ response

성공인 경우

attribute	name	required	description	type
no	차감롤백을 위한 key	필수	연계키	String

---

3. 적립금 차감 롤백 (필수)

적립금 차감 롤백 API (개발 스펙 안내)

• request 는 request body 로 전달

• 형태는 json

• 불가능한 경우 적립으로 처리 ( ※ 이 경우 적립금 유효기간은 유지되지 않음 )

■ method

• POST

■ request

attribute	name	required	description	type
no	차감 롤백을 위한 key	필수	차감 시, 받은 response.no 값 전달 없는경우 주문번호 전달	String
mappingKey	차감롤백을 위한 mapping key	필수	취소된 주문번호 전달	String
amount	취소금액 (롤백금액)	필수		Int
reason	롤백 사유	필수		String
lastSubPayAmt	남은 적립금	선택	부분 취소 시, 남은 적립금액	Int(nullable)
memberKey	연동시 사용한 유형의 값(MEMBER_ID,MEMBER_NO,CI)			String

• 2024-08-26 lastSubPayAmt 항목 추가되었습니다.

롤백 케이스 별 amount, lastSubPayAmt 예시

• case1. 전체 취소 시

  • amount: 1,000

  • lastSubPayAmt: 1,000

• case2. 100 point 부분 취소 시

  • amount: 100

  • lastSubPayAmt: 1,000

■ response

성공인 경우

• http code 200

실패인 경우

• http code 400

• 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}

---

4. 사용가능 적립금 조회 (필수)

사용가능 적립금 조회 API (개발 스펙 안내)

• request 는 request param으로 전달

• response 형태는 json

■ method

• GET

■ request (parameter)

attribute	name	required	description	type
memberKey	회원 연계 키	필수	연동시 사용한 유형의 값 (MEMBER_ID,MEMBER_NO,CI)	String
expireStartYmdt	만료조회 시작일(디폴트 : 오늘 - 30일)	선택		LocalDateTime(format : 'yyyy-MM-dd HH:mm:ss')
expireEndYmdt	만료조회 종료일 (디폴트 : 오늘)	선택		LocalDateTime(format : 'yyyy-MM-dd HH:mm:ss')

■ response

성공인 경우

attribute	name	required	description	type
amount	사용 가능한 총 적립금	필수		Long
expiresAmount	만료예정 적립금	선택	조회기간(expireStartYmdt ~ expireEndYmdt) 동안 만료될 금액 (만료일이 expireStartYmdt보다 크고, expireEndYmdt보다 작음)	Long(nullable)

실패인 경우

• http code 400

• 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}

---

5. 적립금 내역 조회 (선택)

적립금 내역 조회 API (개발 스펙 안내)

• request 는 request param으로 전달

• response 형태는 json

■ method

• GET

■ request (parameter)

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	검색 조건(지급/차감)	선택	전체("null") - default, 지급("ADD"), 차감("SUBTRACT")	String
memberKey	회원 연계 키	선택	null 이면 전체	String(nullable)
page	페이지 번호	필수	조회할 페이징 번호 (default 0)
size	페이지 사이즈	필수	페이지당 조회할 content 개수 ( default 100 )

■ response

성공인 경우

attribute-level1	attribute-level2	name	required	description	type
totalCount	-	전체 데이터 건수	선택		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<String,Object> (nullable)

• 샘플(예시)

{
  "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"
         }
     }
  ]
}

실패인 경우

• http code 400

• 아래와 같은 형태의 response body 로 에러 코드와 메시지를 전달

{
"errorCode" : "실패코드",
"errorMessage" : "실패사유"
}