[엔터프라이즈] 정기결제(배송) 선물하기 API 화면가이드

샵바이 엔터프라이즈의 정기결제(배송) 기능과 선물하기(배송지 나중입력) 기능을 결합하여 활용할 수 있도록 기능 설명 및 활용 가능한 shop API를 안내하는 콘텐츠입니다.

해당 기능을 사용하시려면 아래 소개해드리는 API를 활용하여 별도 스킨 개발이 필요합니다.

01. 간단소개

샵바이 엔터프라이즈 전용
기능 요약
- 정기배송 장바구니에서 선물하기가 가능합니다.
  - 종료회차를 설정한 정기배송 상품은 선물하기가 가능합니다.
  - 선물하기를 선택한 경우 선물받는 사람의 이름, 휴대폰번호만 입력합니다.
- 선물하기 신청 완료 시 선물받는 사람의 휴대폰번호로 배송지를 입력할 수 있는 URL이 전송되어, 선물받는 사람이 직접 배송지를 등록하고 사은품을 선택할 수 있습니다. 정기결제(배송) 신청은 이용대기 상태로 생성됩니다.
- 선물받는 사람이 배송지 입력(선물 수락) 완료 시 이용중 상태로 업데이트되며, 배송주기에 맞춰 종료 회차까지 자동으로 정기주문이 생성됩니다.
- 선물받는 사람이 선물 정보와 정기배송 주문을 조회할 수 있도록 제공하며 정기주문 상태가 배송중, 배송완료인 경우 배송 조회도 가능합니다.
- 선물하기 정기주
- 문의 클레임은 주문자가 신청할 수 있습니다. 단 배송중, 배송완료인 주문의 배송 조회는 불가합니다.
- 선물하기 정기주문도 정기배송 신청관리에서 조회 및 관리가 가능합니다. 단 배송지 정보와 사은품 정보는 수정 불가합니다.

02. 프로세스

03. 선물하기(배송지 나중입력) 설정

선물하기(배송지 나중입력) 기능을 사용하기 위해서는 서비스어드민에서 설정이 필요합니다.

1) 정기결제(배송) 배송지 입력 URL 설정

경로
- 서비스어드민 > 서비스관리 > 쇼핑몰관리 > 쇼핑몰 수정
[배송 설정] 영역에서 '정기결제(배송) 배송지 입력 URL'을 설정할 수 있습니다.
'정기결제(배송) 배송지 입력 URL'은 선물받는 사람이 신청 정보(배송지 정보, 사은품 정보)를 입력할 수 있는 페이지 URL로써 '정기배송 배송지 입력 안내' 알림에 해당 URL이 포함되어 선물받는 사람에게 발송됩니다.

2) 정기배송 배송지 입력 안내 자동 알림(SMS/알림톡) 설정

경로
- 서비스어드민 > 운영관리 > SMS관리 > 자동 SMS설정
- 서비스어드민 > 운영관리 > 카카오알림톡 > 알림톡 사용설정
[주문배송 관련] 메세지 중 '정기배송 배송지 입력 안내' 템플릿을 '사용함'으로 설정하시면 정기결제(배송) 선물하기 신청 완료 시점에 선물받는 사람에게 배송지 주소 입력 링크가 발송됩니다.
gift.address(배송지 주소 입력 url)는 '정기결제(배송) 배송지 입력 URL'에 설정한 값으로 치환됩니다.

<참고>

신청내역은 [서비스어드민 > 주문관리 > 정기결제(배송) 신청 관리]에서 조회가 가능합니다.
배송지가 입력되지 않은 정기결제(배송) 신청 건의 이용상태는 '이용대기'로 유지됩니다.
'배송지 미입력 주문 자동취소' 기능을 설정한 경우 설정 일자 도래 시점까지 배송지가 입력되지 않은 경우 시스템 해지 처리됩니다.

3) 정기배송 선물수락 완료 안내 자동 알림(SMS/알림톡) 설정

경로
- 서비스어드민 > 운영관리 > SMS관리 > 자동 SMS설정
- 서비스어드민 > 운영관리 > 카카오알림톡 > 알림톡 사용설정
[주문배송 관련] 메세지 중 '정기배송 선물수락 완료 안내' 템플릿을 '사용함'으로 설정하시면 정기결제(배송) 선물수락 완료 시점에 주문자와 선물받는 사람에게 알림이 발송됩니다.

4) 선물 수락 개인정보 수집/이용 약관

경로
- 서비스어드민 > 서비스관리 > 약관/개인정보처리방침 관리 > 개인정보 수집/동의 항목
[필수] 선물수락 개인정보 수집/이용 항목을 활용하여 배송지 나중 입력(선물 수락) 시 선물받는 사람에게 개인정보 수집 및 이용 동의를 수집 받을 수 있습니다.

04. API 소개 및 화면 가이드

정기결제(배송) 기본 기능 적용 방법은 정기결제(배송) API 화면가이드를 참고하세요.

1) 장바구니 화면

■ 정기결제 주문서 작성하기 API 확인하기

POST /recurring-payments/order-sheets
정기결제 주문을 진행할 상품정보를 전달하는 API입니다.

예시 장바구니 화면 내에서 하단의 [선물하기] 버튼 클릭 시 호출하는 API로, 장바구니 목록에서 체크박스 선택된 상품을 기준으로 정기결제 주문서를 생성합니다.

예시 화면 내 각 상품 당 [선물하기] 버튼을 클릭할 때도, 해당 상품만을 기준으로 정기결제 주문서를 생성합니다.

API 호출 시 정기결제 선물하기 여부를 true로 전달하여야 정기결제 선물하기 주문서로 생성됩니다. 또한, 정기결제 선물하기의 경우 주문서 등록 시 종료 회차를 필수로 전달해 주셔야 합니다. 자세한 내용은 API 문서에서 확인하실 수 있습니다.

isPresent: boolean // 정기결제 선물하기 여부. true로 전달하여야 정기결제 선물하기로 주문서 등록 가능.
products[].recurringPaymentLastRound: number // 정기결제 종료 회차.

2) 주문서 화면

(2-1) 주문서 작성/결제 화면

■ 정기결제 주문서 가져오기 API 확인하기

GET /recurring-payments/order-sheet/{orderSheetNo}
정기결제 주문서를 조회하는 API입니다.

장바구니 화면에서 등록한 배송 주기, 배송일, 배송 요일, 정기결제 사은품을 출력합니다.

정기결제 선물하기 주문서의 경우, API 호출 시 정기결제 선물하기 여부를 true로 전달하여야 합니다.

isPresent: boolean // 정기결제 선물하기 여부. true로 보내야 선물하기 주문서 조회 가능.

■ 정기결제 신청하기 API 확인하기

POST /recurring-payments
정기결제를 신청하는 API입니다.

주문서 화면에서 최종적으로 [정기배송 신청] 버튼 클릭 시 호출되는 API입니다.

정기결제 선물하기의 경우 선물받는 사람 정보, 정기 결제 카드 등록 여부 및 약관 동의 여부 유효성 검사 후 정기결제를 신청합니다.

정기결제 선물하기의 선물받는 사람 정보를 넘기기 위해 다음 값을 API로 보내야 합니다. 자세한 내용은 API 문서에서 확인하실 수 있습니다.

receiverInfoForPresent: {
    receiverContact: string // 선물받는 사람 연락처. ex) '01012341234'
    receiverName: string // 선물받는 사람 이름. ex) '홍길동'
}

배송지 주소는 선물받는 사람이 입력할 정보이기 때문에 기존 배송지 정보를 보내던 주소 번호(addressNo)는 정기결제 선물하기일 때 값을 보내지 않도록 처리해 주시면 됩니다.

정기결제 선물하기 신청 시, 정기결제 일반 신청과 동일하게 서비스어드민 > 주문관리 > 정기결제(배송)신청 내역 관리 및 고객 마이페이지 > 정기배송관리 > 정기배송 신청관리에 등록됩니다.

(2-2) 주문완료 화면

정기결제 신청 완료 시 신청 정보를 확인하는 주문 완료 화면입니다.

정기결제 선물하기의 경우 배송지 정보에 받는사람(이름)과 휴대폰번호에 마스킹이 적용됩니다.

예시 화면에서는 받는사람(이름)과 휴대폰번호만 노출하도록 처리하였습니다.

3) 마이페이지 화면

(3-1) 마이페이지 > 정기배송관리 > 정기배송 신청관리

정기결제 선물하기 신청 후 선물받는 사람이 배송지 입력을 하지 않은 경우, 이용대기 상태로 정기결제 신청 건이 추가됩니다. 선물받는 사람이 배송지를 입력하여 선물 수락이 완료된 경우, 이용중 상태로 변경되며 배송 예정일에 맞춰 주문/배송이 진행됩니다.

■ 정기결제 조회하기 API 확인하기

GET /recurring-payments
정기결제를 조회하는 API입니다.

주문자는 마이페이지 내 정기배송관리 메뉴에서, 정기결제 신청 내역을 확인할 수 있습니다.

<참고>

statusType (정기결제 상태 타입)
- 정기결제 선물하는 다음의 상태 중 1가지의 상태만 갖습니다.
  - WAITING -> 이용대기 (선물받는 사람이 아직 정기결제 선물하기 배송지 입력을 하지 않은 경우)
  - ACTIVE -> 이용중
  - SYSTEM_CLOSED -> 정기결제가 불가능한 상품 등의 이유로 시스템상에서 정기결제가 해지된 경우
  - ADMIN_CLOSED -> 관리자가 정기결제를 해지한 경우
  - USER_CLOSED -> 주문자가 직접 정기결제를 해지한 경우
  - ROUND_FINISHED -> 정기결제 종료 회차가 도래하여 해지된 경우
  - SYSTEM_PAUSED -> 결제실패 등의 이유로 시스템상에서 정기결제가 일시정지된 경우
  - ADMIN_PAUSED -> 관리자가 정기결제를 일시정지한 경우
  - USER_PAUSED -> 주문자가 직접 정기결제를 일시정지한 경우
- 이용대기 상태는 정기결제 선물하기에서만 사용되는 정기결제 상태입니다. 선물받는 사람이 배송지 입력을 완료한 경우 다음과 같이 변경됩니다.
  - WAITING(이용대기) -> ACTIVE(이용중)
- 그 외의 정기결제 상태는 일반 정기결제와 동일하게 적용됩니다.
nextActions (다음에 할 수 있는 작업)
- 정기결제 선물하기는 다음 값에 해당하는 작업을 할 수 있습니다.
  - PAUSE -> 일시정지
  - RESUME -> 일시정지 해제
  - SKIP -> 회차 건너뛰기
  - CHANGE_DELIVERY_INFO -> 배송정보 변경
  - CLOSE -> 해지하기
gifts (선택된 사은품)
- 정기결제 선물하기인 경우 사은품은 선물받는 사람이 선택할 수 있으며, 사은품 정보 변경 기능이 제공되지 않습니다.
- 선물받는 사람이 배송지 입력을 하면서 선택한 사은품 혹은 서비스 어드민에서 선택한 사은품을 보여줍니다. 예시 화면에서는 사은품 조회 버튼 클릭 시 노출됩니다.

■ 정기 결제 상세 조회 API 확인하기

GET /recurring-payments/{recurringPaymentId}
정기 결제 상세 조회 API 입니다.

배송정보 변경 레이어를 띄우기 위한 값을 내려받을 수 있습니다.

■ 정기 결제 배송 정보 변경 API 확인하기

PUT /recurring-payments/{recurringPaymentId}/info
정기 결제 정보를 수정하는 API 입니다.

예시 화면 내 [배송정보 변경] 버튼 클릭 시 위와 같은 레이어를 통해 정기결제의 배송정보를 변경할 수 있습니다. 변경을 원치 않는 정보는 null 로 요청해 주시면 됩니다.

정기결제 선물하기 이용대기 상태인 경우 결제 정보와 종료 회차만 변경 가능합니다.

정기결제 선물하기인 경우 종료 회차가 필수값이기 때문에 미설정하거나, 현재 회차보다 작은 회차로 설정할 경우 API에서 예외 처리됩니다.

배송지는 선물받는 사람이 입력한 주소로 정해지며, 주문자는 이를 변경할 수 없으므로 정기결제 선물하기인 경우 주소 번호(addressNo)를 null로 요청해 주세요.

다른 부분들은 모두 기존 정기결제 일반 신청과 동일합니다.

정기결제 배송 정보 변경 시 서비스 어드민에서 변경 히스토리를 조회할 수 있습니다.

(3-2) 마이페이지 > 주문목록/배송조회

■ 주문 리스트 조회하기 API 확인하기

GET /profile/orders
시작일 종료일 사이의 주문리스트를 조회하는 API 입니다.

정기결제 선물하기일 때 배송중/배송완료인 경우, 주문자는 배송조회가 불가능합니다. 그 외 기본적인 내용은 정기결제 API 화면 가이드의 내용과 동일합니다.

(3-3) 마이페이지 > 주문목록/배송조회 > 주문/배송상세

■ 주문 상세 조회하기 API 확인하기

GET /profile/orders/{orderNo}
주문번호로 상세 데이터를 조회하는 API 입니다.

주문목록/배송조회와 동일하게 정기결제 선물하기의 배송중/배송완료인 경우, 배송조회가 불가능하며

배송지 정보에 받는사람(이름)과 휴대폰번호에 마스킹이 적용됩니다.

예시 화면에서는 배송지 정보에 받는사람(이름)과 휴대폰번호만 노출하도록 처리하였습니다.

4) 선물수락(배송지 나중입력) 화면

정기결제 선물하기 배송지 입력 화면 예시입니다. SMS 혹은 카카오 알림톡으로 전달받은 링크 클릭 시 이동하는 화면입니다.

■ 정기 결제 선물하기 나중 입력 배송지 정보 조회하기 API 확인하기

GET /recurring-payments/later-input/shippings
정기 결제 선물하기에서 나중 입력 배송지 정보를 조회하는 API 입니다.

정기결제 선물하기 배송지 입력 화면에서 선물정보(주문자 정보, 정기결제 정보(상품 정보, 배송 정보, 사은품 정보, 종료회차 정보))와 배송지 정보(받는사람, 주소, 휴대폰번호, 전화번호, 배송메모), 약관 정보를 출력합니다.

<참고>

정기 결제 그룹번호(recurringPaymentGroupNo)는 SMS 혹은 카카오 알림톡 발송 시 정기결제 선물하기 배송지 입력 URL 파라미터에 포함되므로 쉽게 확인할 수 있습니다.
이용대기 상태에서만 나중 입력 배송지 정보 조회가 가능합니다.
사은품 지급조건(recurringPayments[].giftCondition)은 서비스어드민 > 상품관리 > 정기결제(배송) 상품 관리 > 사은품 설정의 지급 옵션 수량에 따라 달라지며, 정기결제 사은품 리스트(recurringPayments[].freeGifts) 의 사은품 선택 여부(selected)로 선택된 사은품 여부를 알 수 있습니다.
선물수락 개인정보 수집/이용 동의(PI_GIFT_ACCEPT_COLLECTION_AND_USE)를 활용하여 서비스어드민 > 서비스관리 > 약관/개인정보처리방침 관리 > 개인정보 수집/동의 항목 - 선물수락 개인정보 수집/이용 항목 내용을 출력합니다.
지역별 추가 배송비가 발생하여 선물하기 불가한 지역인 경우, 유효성 체크하여 알럿 메시지를 출력해야합니다.

■ 정기 결제 선물하기 나중 입력 배송지 정보 수정하기 API 확인하기

PUT /recurring-payments/later-input/shippings
정기 결제 선물하기에서 나중 입력 배송지 정보를 수정하는 API 입니다.

사은품 정보, 비밀번호, 배송지 정보, 약관 동의 여부 유효성 검사 후 정기배송 선물 수락이 완료됩니다.

<참고>

정기 결제 그룹번호(recurringPaymentGroupNo)는 SMS 혹은 카카오 알림톡 발송 시 정기결제 선물하기 배송지 입력 URL 파라미터에 포함되므로 쉽게 확인할 수 있습니다.

5) 선물받은 정기배송 관리 화면

선물받는 사람이 배송지를 입력하여 선물 수락이 완료된 경우, 카카오 알림톡 혹은 SMS로 선물 보낸 분/받는 분에게 정기결제 신청그룹번호가 담긴 정기배송 선물수락 완료 안내가 발송됩니다.

(5-1) 로그인 화면

■ 정기결제 선물하기 수령자 주문 토큰 발급하기 API 확인하기

POST /recurring-payments/{recurringPaymentGroupNo}/guest
정기 결제 선물하기 주문 조회용 토큰을 발급하는 API 입니다.

예시 화면에서 [확인] 버튼 클릭 시 요청하는 API입니다.

신청그룹번호, 이름, 비밀번호를 입력하여 토큰을 발급받습니다. 발급받은 토큰과 신청그룹번호를 이용하여 선물받은 정기배송 관리 화면에 접근 가능합니다.

신청그룹번호의 경우, 정기배송 선물수락 완료 안내 카카오 알림톡 혹은 SMS에 포함되어 쉽게 확인하실 수 있습니다.

(5-2) 선물받은 정기배송 관리

■ 정기결제 선물하기 수령자 주문 상세 조회하기 API 확인하기

GET /recurring-payments/{recurringPaymentGroupNo}/guest
정기 결제 선물하기 주문 상세 조회 API 입니다.

guestToken에는 위의 정기결제 선물하기 수령자 주문 토큰 발급하기 API에서 발급받은 토큰을, recurringPaymentGroupNo에는 신청그룹번호를 넘겨주어 선물받은 정기배송 정보를 조회할 수 있습니다.

선물정보, 배송지 정보, 주문목록/배송조회 정보를 출력합니다. 주문목록/배송조회에서 배송중/배송완료 상태의 경우, 배송조회가 가능합니다.

Previous[엔터프라이즈]정기결제(배송) API 화면가이드 Next[프로/엔터프라이즈] 쇼핑몰에 인스타그램 위젯을 적용해보세요!

Last updated 23 hours ago

Was this helpful?

[엔터프라이즈] 정기결제(배송) 선물하기 API 화면가이드

샵바이 엔터프라이즈의 정기결제(배송) 기능과 선물하기(배송지 나중입력) 기능을 결합하여 활용할 수 있도록 기능 설명 및 활용 가능한 shop API를 안내하는 콘텐츠입니다.

해당 기능을 사용하시려면 아래 소개해드리는 API를 활용하여 별도 스킨 개발이 필요합니다.

01. 간단소개

샵바이 엔터프라이즈 전용
기능 요약
- 정기배송 장바구니에서 선물하기가 가능합니다.
  - 종료회차를 설정한 정기배송 상품은 선물하기가 가능합니다.
  - 선물하기를 선택한 경우 선물받는 사람의 이름, 휴대폰번호만 입력합니다.
- 선물하기 신청 완료 시 선물받는 사람의 휴대폰번호로 배송지를 입력할 수 있는 URL이 전송되어, 선물받는 사람이 직접 배송지를 등록하고 사은품을 선택할 수 있습니다. 정기결제(배송) 신청은 이용대기 상태로 생성됩니다.
- 선물받는 사람이 배송지 입력(선물 수락) 완료 시 이용중 상태로 업데이트되며, 배송주기에 맞춰 종료 회차까지 자동으로 정기주문이 생성됩니다.
- 선물받는 사람이 선물 정보와 정기배송 주문을 조회할 수 있도록 제공하며 정기주문 상태가 배송중, 배송완료인 경우 배송 조회도 가능합니다.
- 선물하기 정기주
- 문의 클레임은 주문자가 신청할 수 있습니다. 단 배송중, 배송완료인 주문의 배송 조회는 불가합니다.
- 선물하기 정기주문도 정기배송 신청관리에서 조회 및 관리가 가능합니다. 단 배송지 정보와 사은품 정보는 수정 불가합니다.

02. 프로세스

03. 선물하기(배송지 나중입력) 설정

선물하기(배송지 나중입력) 기능을 사용하기 위해서는 서비스어드민에서 설정이 필요합니다.

1) 정기결제(배송) 배송지 입력 URL 설정

경로
- 서비스어드민 > 서비스관리 > 쇼핑몰관리 > 쇼핑몰 수정
[배송 설정] 영역에서 '정기결제(배송) 배송지 입력 URL'을 설정할 수 있습니다.
'정기결제(배송) 배송지 입력 URL'은 선물받는 사람이 신청 정보(배송지 정보, 사은품 정보)를 입력할 수 있는 페이지 URL로써 '정기배송 배송지 입력 안내' 알림에 해당 URL이 포함되어 선물받는 사람에게 발송됩니다.

2) 정기배송 배송지 입력 안내 자동 알림(SMS/알림톡) 설정

경로
- 서비스어드민 > 운영관리 > SMS관리 > 자동 SMS설정
- 서비스어드민 > 운영관리 > 카카오알림톡 > 알림톡 사용설정
[주문배송 관련] 메세지 중 '정기배송 배송지 입력 안내' 템플릿을 '사용함'으로 설정하시면 정기결제(배송) 선물하기 신청 완료 시점에 선물받는 사람에게 배송지 주소 입력 링크가 발송됩니다.
gift.address(배송지 주소 입력 url)는 '정기결제(배송) 배송지 입력 URL'에 설정한 값으로 치환됩니다.

<참고>

신청내역은 [서비스어드민 > 주문관리 > 정기결제(배송) 신청 관리]에서 조회가 가능합니다.
배송지가 입력되지 않은 정기결제(배송) 신청 건의 이용상태는 '이용대기'로 유지됩니다.
'배송지 미입력 주문 자동취소' 기능을 설정한 경우 설정 일자 도래 시점까지 배송지가 입력되지 않은 경우 시스템 해지 처리됩니다.

3) 정기배송 선물수락 완료 안내 자동 알림(SMS/알림톡) 설정

경로
- 서비스어드민 > 운영관리 > SMS관리 > 자동 SMS설정
- 서비스어드민 > 운영관리 > 카카오알림톡 > 알림톡 사용설정
[주문배송 관련] 메세지 중 '정기배송 선물수락 완료 안내' 템플릿을 '사용함'으로 설정하시면 정기결제(배송) 선물수락 완료 시점에 주문자와 선물받는 사람에게 알림이 발송됩니다.

4) 선물 수락 개인정보 수집/이용 약관

경로
- 서비스어드민 > 서비스관리 > 약관/개인정보처리방침 관리 > 개인정보 수집/동의 항목
[필수] 선물수락 개인정보 수집/이용 항목을 활용하여 배송지 나중 입력(선물 수락) 시 선물받는 사람에게 개인정보 수집 및 이용 동의를 수집 받을 수 있습니다.

04. API 소개 및 화면 가이드

정기결제(배송) 기본 기능 적용 방법은 정기결제(배송) API 화면가이드를 참고하세요.

1) 장바구니 화면

■ 정기결제 주문서 작성하기 API 확인하기

POST /recurring-payments/order-sheets
정기결제 주문을 진행할 상품정보를 전달하는 API입니다.

예시 화면 내 각 상품 당 [선물하기] 버튼을 클릭할 때도, 해당 상품만을 기준으로 정기결제 주문서를 생성합니다.

isPresent: boolean // 정기결제 선물하기 여부. true로 전달하여야 정기결제 선물하기로 주문서 등록 가능.
products[].recurringPaymentLastRound: number // 정기결제 종료 회차.

2) 주문서 화면

(2-1) 주문서 작성/결제 화면

■ 정기결제 주문서 가져오기 API 확인하기

GET /recurring-payments/order-sheet/{orderSheetNo}
정기결제 주문서를 조회하는 API입니다.

장바구니 화면에서 등록한 배송 주기, 배송일, 배송 요일, 정기결제 사은품을 출력합니다.

정기결제 선물하기 주문서의 경우, API 호출 시 정기결제 선물하기 여부를 true로 전달하여야 합니다.

isPresent: boolean // 정기결제 선물하기 여부. true로 보내야 선물하기 주문서 조회 가능.

■ 정기결제 신청하기 API 확인하기

POST /recurring-payments
정기결제를 신청하는 API입니다.

주문서 화면에서 최종적으로 [정기배송 신청] 버튼 클릭 시 호출되는 API입니다.

정기결제 선물하기의 경우 선물받는 사람 정보, 정기 결제 카드 등록 여부 및 약관 동의 여부 유효성 검사 후 정기결제를 신청합니다.

정기결제 선물하기의 선물받는 사람 정보를 넘기기 위해 다음 값을 API로 보내야 합니다. 자세한 내용은 API 문서에서 확인하실 수 있습니다.

receiverInfoForPresent: {
    receiverContact: string // 선물받는 사람 연락처. ex) '01012341234'
    receiverName: string // 선물받는 사람 이름. ex) '홍길동'
}

(2-2) 주문완료 화면

정기결제 신청 완료 시 신청 정보를 확인하는 주문 완료 화면입니다.

정기결제 선물하기의 경우 배송지 정보에 받는사람(이름)과 휴대폰번호에 마스킹이 적용됩니다.

예시 화면에서는 받는사람(이름)과 휴대폰번호만 노출하도록 처리하였습니다.

3) 마이페이지 화면

(3-1) 마이페이지 > 정기배송관리 > 정기배송 신청관리

■ 정기결제 조회하기 API 확인하기

GET /recurring-payments
정기결제를 조회하는 API입니다.

주문자는 마이페이지 내 정기배송관리 메뉴에서, 정기결제 신청 내역을 확인할 수 있습니다.

<참고>

statusType (정기결제 상태 타입)
- 정기결제 선물하는 다음의 상태 중 1가지의 상태만 갖습니다.
  - WAITING -> 이용대기 (선물받는 사람이 아직 정기결제 선물하기 배송지 입력을 하지 않은 경우)
  - ACTIVE -> 이용중
  - SYSTEM_CLOSED -> 정기결제가 불가능한 상품 등의 이유로 시스템상에서 정기결제가 해지된 경우
  - ADMIN_CLOSED -> 관리자가 정기결제를 해지한 경우
  - USER_CLOSED -> 주문자가 직접 정기결제를 해지한 경우
  - ROUND_FINISHED -> 정기결제 종료 회차가 도래하여 해지된 경우
  - SYSTEM_PAUSED -> 결제실패 등의 이유로 시스템상에서 정기결제가 일시정지된 경우
  - ADMIN_PAUSED -> 관리자가 정기결제를 일시정지한 경우
  - USER_PAUSED -> 주문자가 직접 정기결제를 일시정지한 경우
- 이용대기 상태는 정기결제 선물하기에서만 사용되는 정기결제 상태입니다. 선물받는 사람이 배송지 입력을 완료한 경우 다음과 같이 변경됩니다.
  - WAITING(이용대기) -> ACTIVE(이용중)
- 그 외의 정기결제 상태는 일반 정기결제와 동일하게 적용됩니다.
nextActions (다음에 할 수 있는 작업)
- 정기결제 선물하기는 다음 값에 해당하는 작업을 할 수 있습니다.
  - PAUSE -> 일시정지
  - RESUME -> 일시정지 해제
  - SKIP -> 회차 건너뛰기
  - CHANGE_DELIVERY_INFO -> 배송정보 변경
  - CLOSE -> 해지하기
gifts (선택된 사은품)
- 정기결제 선물하기인 경우 사은품은 선물받는 사람이 선택할 수 있으며, 사은품 정보 변경 기능이 제공되지 않습니다.
- 선물받는 사람이 배송지 입력을 하면서 선택한 사은품 혹은 서비스 어드민에서 선택한 사은품을 보여줍니다. 예시 화면에서는 사은품 조회 버튼 클릭 시 노출됩니다.

■ 정기 결제 상세 조회 API 확인하기

GET /recurring-payments/{recurringPaymentId}
정기 결제 상세 조회 API 입니다.

배송정보 변경 레이어를 띄우기 위한 값을 내려받을 수 있습니다.

■ 정기 결제 배송 정보 변경 API 확인하기

PUT /recurring-payments/{recurringPaymentId}/info
정기 결제 정보를 수정하는 API 입니다.

정기결제 선물하기 이용대기 상태인 경우 결제 정보와 종료 회차만 변경 가능합니다.

정기결제 선물하기인 경우 종료 회차가 필수값이기 때문에 미설정하거나, 현재 회차보다 작은 회차로 설정할 경우 API에서 예외 처리됩니다.

다른 부분들은 모두 기존 정기결제 일반 신청과 동일합니다.

정기결제 배송 정보 변경 시 서비스 어드민에서 변경 히스토리를 조회할 수 있습니다.

(3-2) 마이페이지 > 주문목록/배송조회

■ 주문 리스트 조회하기 API 확인하기

GET /profile/orders
시작일 종료일 사이의 주문리스트를 조회하는 API 입니다.

(3-3) 마이페이지 > 주문목록/배송조회 > 주문/배송상세

■ 주문 상세 조회하기 API 확인하기

GET /profile/orders/{orderNo}
주문번호로 상세 데이터를 조회하는 API 입니다.

주문목록/배송조회와 동일하게 정기결제 선물하기의 배송중/배송완료인 경우, 배송조회가 불가능하며

배송지 정보에 받는사람(이름)과 휴대폰번호에 마스킹이 적용됩니다.

예시 화면에서는 배송지 정보에 받는사람(이름)과 휴대폰번호만 노출하도록 처리하였습니다.

4) 선물수락(배송지 나중입력) 화면

정기결제 선물하기 배송지 입력 화면 예시입니다. SMS 혹은 카카오 알림톡으로 전달받은 링크 클릭 시 이동하는 화면입니다.

■ 정기 결제 선물하기 나중 입력 배송지 정보 조회하기 API 확인하기

GET /recurring-payments/later-input/shippings
정기 결제 선물하기에서 나중 입력 배송지 정보를 조회하는 API 입니다.

<참고>

정기 결제 그룹번호(recurringPaymentGroupNo)는 SMS 혹은 카카오 알림톡 발송 시 정기결제 선물하기 배송지 입력 URL 파라미터에 포함되므로 쉽게 확인할 수 있습니다.
이용대기 상태에서만 나중 입력 배송지 정보 조회가 가능합니다.
사은품 지급조건(recurringPayments[].giftCondition)은 서비스어드민 > 상품관리 > 정기결제(배송) 상품 관리 > 사은품 설정의 지급 옵션 수량에 따라 달라지며, 정기결제 사은품 리스트(recurringPayments[].freeGifts) 의 사은품 선택 여부(selected)로 선택된 사은품 여부를 알 수 있습니다.
선물수락 개인정보 수집/이용 동의(PI_GIFT_ACCEPT_COLLECTION_AND_USE)를 활용하여 서비스어드민 > 서비스관리 > 약관/개인정보처리방침 관리 > 개인정보 수집/동의 항목 - 선물수락 개인정보 수집/이용 항목 내용을 출력합니다.
지역별 추가 배송비가 발생하여 선물하기 불가한 지역인 경우, 유효성 체크하여 알럿 메시지를 출력해야합니다.

■ 정기 결제 선물하기 나중 입력 배송지 정보 수정하기 API 확인하기

PUT /recurring-payments/later-input/shippings
정기 결제 선물하기에서 나중 입력 배송지 정보를 수정하는 API 입니다.

사은품 정보, 비밀번호, 배송지 정보, 약관 동의 여부 유효성 검사 후 정기배송 선물 수락이 완료됩니다.

<참고>

정기 결제 그룹번호(recurringPaymentGroupNo)는 SMS 혹은 카카오 알림톡 발송 시 정기결제 선물하기 배송지 입력 URL 파라미터에 포함되므로 쉽게 확인할 수 있습니다.

5) 선물받은 정기배송 관리 화면

(5-1) 로그인 화면

■ 정기결제 선물하기 수령자 주문 토큰 발급하기 API 확인하기

POST /recurring-payments/{recurringPaymentGroupNo}/guest
정기 결제 선물하기 주문 조회용 토큰을 발급하는 API 입니다.

예시 화면에서 [확인] 버튼 클릭 시 요청하는 API입니다.

신청그룹번호의 경우, 정기배송 선물수락 완료 안내 카카오 알림톡 혹은 SMS에 포함되어 쉽게 확인하실 수 있습니다.

(5-2) 선물받은 정기배송 관리

■ 정기결제 선물하기 수령자 주문 상세 조회하기 API 확인하기

GET /recurring-payments/{recurringPaymentGroupNo}/guest
정기 결제 선물하기 주문 상세 조회 API 입니다.

선물정보, 배송지 정보, 주문목록/배송조회 정보를 출력합니다. 주문목록/배송조회에서 배송중/배송완료 상태의 경우, 배송조회가 가능합니다.

Previous[엔터프라이즈]정기결제(배송) API 화면가이드 Next[프로/엔터프라이즈] 쇼핑몰에 인스타그램 위젯을 적용해보세요!

Last updated 23 hours ago

Was this helpful?