[엔터프라이즈] 외부 적립금 연동가이드

외부 적립금이란?

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

고객사에서 진행할 수 있는 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

지급 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" : "[email protected]",
"mappingKey" : "2022080117000000001",
"additionalMappingKey" : {
    "orderNo" : "2022080117000000001",
    "reviewNo" : "3",
    "orderOptionNo" : "2"
    }
}

■ response

성공인 경우

attribute

name

required

description

type

차감롤백을 위한 key

필수

연계키

String

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

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

request 는 request body 로 전달
형태는 json
불가능한 경우 적립으로 처리 ( ※ 이 경우 적립금 유효기간은 유지되지 않음 )

■ method

POST

■ request

attribute

name

required

description

type

차감 롤백을 위한 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

■ 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

■ 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

적립금 번호

필수

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" : "실패사유"
}

Previous[엔터프라이즈] 외부 적립금 전환 가이드 Next[엔터프라이즈] 사은품 API 화면가이드

Last updated 10 months ago

hashtag외부 적립금이란?

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

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

hashtag개념

hashtag상세설명

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

hashtag개념

hashtag상세설명

hashtag주의사항

hashtag연동 프로세스

hashtag적립금 적립/차감/롤백 다이어그램

hashtag적립금 적립 프로세스

hashtag적립금 차감/ 롤백 프로세스

hashtag1. 적립금 지급 (필수)

hashtag적립금 지급 API (개발 스펙 안내)

hashtag■ method

hashtag■ request

hashtag※ reasonType 코드 값 설명

hashtag■ response

hashtag성공인 경우

hashtag실패인 경우

hashtag제약조건

hashtag참고사항

hashtag2. 적립금 차감 (필수)

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

hashtag■ method

hashtag■ request

hashtag※ reasonType 코드 값 설명

hashtag■ response

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

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

hashtag■ method

hashtag■ request

hashtag■ response

hashtag성공인 경우

hashtag실패인 경우

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

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

hashtag■ method

hashtag■ request (parameter)

hashtag■ response

hashtag성공인 경우

hashtag실패인 경우

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

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

hashtag■ method

hashtag■ request (parameter)

hashtag■ response

hashtag성공인 경우

hashtag실패인 경우

외부 적립금이란?

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

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

개념

상세설명

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

개념

상세설명

주의사항

연동 프로세스

적립금 적립/차감/롤백 다이어그램

적립금 적립 프로세스

적립금 차감/ 롤백 프로세스

1. 적립금 지급 (필수)

적립금 지급 API (개발 스펙 안내)

■ method

■ request

※ reasonType 코드 값 설명

■ response

성공인 경우

실패인 경우

제약조건

참고사항

2. 적립금 차감 (필수)

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

■ method

■ request

※ reasonType 코드 값 설명

■ response

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

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

■ method

■ request

■ response

성공인 경우

실패인 경우

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

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

■ method

■ request (parameter)

■ response

성공인 경우

실패인 경우

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

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

■ method

■ request (parameter)

■ response

성공인 경우

실패인 경우