LogoLogo
  • 샵바이 스킨 알아보기
    • 샵바이 스킨 설명서
    • 오로라 리액트(통합형) 스킨 개발 가이드
    • 오로라 리액트(통합형) 릴리즈 노트
    • 오로라 바닐라(개별형) 릴리즈 노트
    • 1:1 문의하기
  • 오로라 개별형 스킨 개발 가이드
    • 개발 프로세스
      • 등록
      • 개발
        • 개발 환경 구성하기
        • 스킨 디렉토리 구조
      • 설치
    • 기본 API 이해하기
      • 샵바이 API 호출 가이드
        • OAuth 2.0 적용 가이드
      • 외부 스크립트 호출 가이드
    • 화면별 API 활용 가이드
      • 공통 영역
        • 공통 상단
        • 공통 하단
        • 디자인 팝업
        • 슬라이드 메뉴 (모바일 전용)
        • 최근 본 상품
      • 메인 화면
        • 배너 영역
        • 상품진열 영역
        • 인스타그램 연동
      • 회원가입
      • 로그인
      • 간편 로그인
      • 휴대폰 본인인증
      • 상품 리스트
      • 상품 상세
        • 상품 기본 정보
        • 상품 상세 배너 (모바일 전용)
        • 상품 상세정보 (탭)
        • 배송/반품/교환 안내 (탭)
        • 상품후기 (탭)
        • 상품문의 (탭)
        • 관련상품
      • 장바구니
      • 주문서
      • 마이페이지 > 쇼핑정보
        • 주문목록/배송조회
        • 취소/반품/교환 내역
        • 주문 상세
        • 좋아요
      • 마이페이지 > 혜택관리
        • 쿠폰
        • 적립금
      • 마이페이지 > 회원정보
        • 회원정보 수정
        • 회원탈퇴
        • 배송지 관리
      • 마이페이지 > 나의 게시글
        • 1:1 문의
        • 상품문의
        • 상품후기
      • 상품후기 게시판
      • 일반 게시판
      • 기획전
    • KCP 휴대폰 본인인증 연동 (iOS/AOS)
  • 앱 개발 가이드
    • [샵바이] 웹훅(webhook) 가이드
    • [고도몰] 웹훅(webhook) 가이드
  • 추천 콘텐츠
    • 추천 콘텐츠
      • [간편 로그인] SNS 연동 기능 개발 가이드
      • [공통] 마이페이 API 화면가이드
      • [엔터프라이즈] 선물하기 기능 (배송지 나중입력)
      • [엔터프라이즈] 카카오 싱크 신청 가이드
      • [엔터프라이즈] 카카오 싱크 회원가입 API 화면가이드
      • [엔터프라이즈] 이니렌탈(렌탈결제) API 화면가이드
      • [엔터프라이즈] 외부 회원 연동 가이드
      • [엔터프라이즈] 외부 적립금 전환 가이드
      • [엔터프라이즈] 외부 적립금 연동가이드
      • [엔터프라이즈] 사은품 API 화면가이드
      • [엔터프라이즈] PG신청 가이드 (2024/4/1 업데이트)
      • [엔터프라이즈] 카카오 픽셀 설치 가이드
      • [엔터프라이즈]정기결제(배송) API 화면가이드
      • [프로/엔터프라이즈] 쇼핑몰에 인스타그램 위젯을 적용해보세요!
      • [베이직/프로] 카카오싱크 신청 가이드
      • [웹훅 추가] 주문정보 웹훅(Webhook)이란?
      • [웹훅 추가] 회원정보 변경 및 회원탈퇴
      • [웹훅 추가] 앱 설치 및 삭제
      • shop by API, POSTMAN에 추가하기
      • [글로벌] 글로벌 기능 가이드
        • 사용 프로세스
          • 엑심베이 PG 계약
          • 개발 환경 세팅
          • shop by 어드민 세팅
          • 쇼핑몰 스킨 개발
            • 언어/통화 설정
            • 상품/전시 설정
            • 주문서 조회
            • 주문 예약하기
            • 회원 등록
        • 글로벌 주문/환불 프로세스
    • FAQ
      • 에러코드_ (1) 주문
      • 에러코드_ (2) 프로모션
      • 에러코드_ (3) 클레임
      • 쿠폰 코드 API 에러메시지 안내
      • 장바구니/주문결제 에러코드 안내
      • 배송타입 및 택배사코드 안내
      • 파트너어드민 매출내역 조회기준
      • shop api error response 안내
      • server API로 주문의 외부 유입경로 집계 방법
      • 은행코드 안내
      • 7/15 스킨 에디터 업데이트 주의사항
        • 모바일_업데이트 전 템플릿 코드
        • PC_업데이트 전 템플릿 코드
        • 업데이트 후/전 템플릿 코드 비교
      • [샵바이 엔터프라이즈] server API 호출방법
      • [샵바이 엔터프라이즈] 파트너 어드민에서 상품 노출은 미리 해두고, 판매 기간은 미래시점으로 설정할 수 있는 기능이 있을까요?
      • [샵바이 엔터프라이즈] 파트너사 담당MD 일괄변경 어떻게하나요?
Powered by GitBook
On this page
  • 외부 적립금이란?
  • (방법1) 외부 적립금 전환
  • (방법2) 외부 적립금 연동
  • 적립금 적립/차감/롤백 다이어그램
  • 적립금 적립 프로세스
  • 적립금 차감/ 롤백 프로세스
  • 1. 적립금 지급 (필수)
  • 적립금 지급 API (개발 스펙 안내)
  • 제약조건
  • 참고사항
  • 2. 적립금 차감 (필수)
  • 적립금 차감 API (개발 스펙 안내)
  • 3. 적립금 차감 롤백 (필수)
  • 적립금 차감 롤백 API (개발 스펙 안내)
  • 4. 사용가능 적립금 조회 (필수)
  • 사용가능 적립금 조회 API (개발 스펙 안내)
  • 5. 적립금 내역 조회 (선택)
  • 적립금 내역 조회 API (개발 스펙 안내)

Was this helpful?

  1. 추천 콘텐츠
  2. 추천 콘텐츠

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

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

Last updated 1 month ago

Was this helpful?

외부 적립금이란?

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

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

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

개념

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

상세설명

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


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

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

개념

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

상세설명

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

주의사항

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

연동 프로세스

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

항목
샘플 (예시)
설명

domain

외부 개발사는 개발된 도메인 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으로 등록되어 있어 외부적립금 사용 시 중복 지급될 수 있습니다.

(예시) 중복지급 될 수 있는 케이스 : [고객이 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" : "test@abc.com",
"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" : "실패사유"
}

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

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

외부 적립금 전환 가이드
1:1문의 바로가기>
적립금 전환 방식
https://sample-dev.com