본 가이드는 앱 개발 시 숙지해야 할 내용에 대해 안내합니다.
server API를 통해 쇼핑몰 프런트에서 호출할 스크립트를 저장하거나,
주문이나 상품에 대한 정보를 조회/등록하거나, 쇼핑몰 관리자 정보를 조회할 수 있습니다.
제공 중인 각 솔루션별 API 목록은 워크스페이스 > GNB > API에서 확인할 수 있으며,
server API 호출 전에 API 문서 상단에 기재된 server API 호출 시 주의사항을 반드시 확인해 주시기 바랍니다.

[목차]

• 만료일 연장 (결제유형이 인앱결제인 상품은 필수적으로 개발 필요)
• 사용 상태 조회
• 스크립트 설치
• 쇼핑몰 관리자 정보 조회

스토어 출시를 목적으로 앱 '판매정보'를 입력할 경우 결제유형을 선택할 수 있습니다.
이때 결제유형을 인앱결제인 경우 앱의 서비스 만료일을 아래 API를 통해 전달해야 합니다.

put설치 앱 만료일 연장하기

/app-installed/extend

인앱 결제 완료 시 설치한 앱 만료일을 '최초 세팅' 또는 '연장'합니다

api 확인하기

[만료일 연장]

인앱결제 앱은 설치 시 만료일이 설치일로 저장되기 때문에 만료일 연장 이후 server API를 호출할 수 있습니다.
즉, 만료일을 연장하기 이전에는 server API 호출이 불가하며, workspace 도메인에 포함된 server API만 호출할 수 있습니다.

만료일 연장하기API는 원주문의 잔여 기간과 무관하게 덮어씌우는 개념입니다.
(ex)현재 10/12이고, 기존 만료일이 10/14였을 경우, 기존 만료일과 상관없이 새로운 만료일을 10/17으로 연장할 수 있습니다.

[파라미터]

• requestDateTime: 사용 만료일
  • 판매자가 만료일을 일자/시/분/초 단위로 지정해야 합니다. (YYYY-MM-DD hh:mm:ss 외 포맷은 에러)
  • 만료일은 API 호출 시점 보다 과거 시간대를 지정할 수 없습니다.
• paymentType: 결제타입
  • ENUM: TRIAL무료체험 , CHARGE 인앱결제
  • 무료체험: 앱 구매자가 특정 기간 동안 무료 체험으로 해당 앱 서비스를 쇼핑몰에서 실행하는 경우
  • 인앱결제: 앱 구매자가 별도의 판매 페이지에서 해당 앱 서비스를 결제하여, 쇼핑몰에서 실행하는 경우
• price: 결제금액
  • 쇼핑몰 관리자가 지불한 금액
  • 무료체험인 경우 0, 인앱결제인 경우 결제금액
• orderNo: 주문번호
  • 결제된 시스템에서 생성된 주문번호
    • 만료일을 연장할 경우 새로 생성된 주문번호
    • 주문번호가 생성되지 않는 경우에도 유니크한 번호 생성하여 전달 필요
  • 환불 및 주문취소 등의 사유로 만료일 초기화 시 orderNO로 매핑

[후불결제 형태의 앱]

1. step 1) 결제 전, 앱 사용을 허용하기 위해 API 호출
   • requestDateTime: 2099-12-31 00:00:00
   • paymentType: TRIAL
   • price: 0
   • orderNo: 유니크한 번호 생성하여 전달
2. step 2) 결제 이후, 앱 사용에 대한 보다 정확한 정보를 워크스페이스로 전달하기 위한 API 호출
   • requestDateTime: 2099-12-31 00:00:00
   • paymentType: CHARGE
   • price: 결제금액
   • orderNo: 결제 전에 보냈던 값과 상이한 신규 주문번호 전달

앱의 사용 상태는 결제대기/사용중/삭제 3가지로 구분됩니다.

get앱 사용 상태 조회하기

/app-installed/status

앱 사용상태를 조회 할 수 있는 API입니다

api 확인하기

• 결제대기 EXPIRED
  • 만료일(requestDateTime)이 연장되지 않아 사용할 수 없는 상태로, 결제 등의 액션에 따른 만료일 연장이 필요합니다.
    • case1. 앱이 초기 설치 되어, 앱 만료일API을 호출하지 않아 앱을 실행할 수 없는 상태
    • case2. 만료일을 연장하지 않았거나, 환불 등으로 판매사가 앱의 만료일을 초기화한 상태
• 사용 중ACTIVE
  • 앱 사용 중인 상태로, 정상적으로 앱 기능을 사용할 수 있습니다.
  • 무료앱의 경우, 앱을 설치하자마자 active 상태가 됩니다.
• 삭제 DELETED
  • 쇼핑몰 운영자가 설치한 앱을 삭제한 상태를 의미합니다. 앱을 다시 사용하려면 쇼핑몰 운영자의 재설치가 필요합니다.

[스크립트 동작 프로세스]

1. step1. 스크립트 저장

   서비스 이용에 필요한 스크립트를 외부 스크립트 등록하기 API를 통해 저장합니다.
   해당 외부 스크립트 등록 API에 대해서는 아래 [스크립트 저장]내용을 참고해 주시기 바랍니다.

2. step2. 쇼핑몰에 고객이 접근 시, 화면별 스크립트 실행

   쇼핑몰 프런트에 고객이 접근했을 때, 외부스크립트 조회 API를 통해 해당 쇼핑몰 페이지에 등록된 스크립트를 불러와 동작하게 합니다.

[스크립트 저장]

post외부스크립트 등록하기

/external-script

앱 실행 시점에 토큰 권한 체크 후, 외부 스크립트를 mall에 저장합니다.

api 확인하기

스크립트는 쇼핑몰에서 사용 중인 스킨에 따라 PC 또는 모바일 플랫폼에 저장할 수 있습니다.
외부스크립트 등록하기 API를 호출하여 자바스크립트 코드를 한 번에 여러 위치에 스크립트를 저장할 수 있습니다.
단, 동일한 위치에 스크립트를 저장하는 경우 가장 마지막에 저장한 스크립트 기준으로 업데이트 됩니다.

또한 스크립트를 저장하는 시점을 선택하여 개발할 수 있습니다.
별도 관리자 화면에서 회원가입한 시점 또는 회원가입 이후 특정 액션을 취한 시점 등 원하는 시점에 외부스크립트 등록하기 API를 호출해 주시면 됩니다.

[스크립트 추가 가능한 화면 목록]

[변수 조회 가이드]

화면별 사용 가능한 글로벌 변수는 아래표에서 확인 가능합니다.

※ 외부 스크립트를 이용하여 쇼핑몰 이용자의 개인정보를 제3자에게 제공하거나, 개인정보처리업무를 위탁하는 경우 개인정보보호법에 따라 (제3자 제공의 경우) 별도 동의를 받거나, (위탁의 경우) 이를 정보주체가 알기 쉽도록 공개하여야 합니다.
※ 앱 등록 시 개인정보처리방침 및 개인정보 수집 및 이용에 대한 동의 내용을 반드시 입력하시기 바랍니다.

[스크립트 작성가이드]

• 중첩된 객체 내의 특정 값을 조회하고자 하는 경우

  장바구니의 구매금액 합(buyAmt) 을 조회하고자 하는 경우, 마침표 프로퍼티 접근 연산자(.) 를 이용하여 값을 조회할 수 있습니다.

  (예시)

  var buyAmt = sb.cart.price.buyAmt

• 복수 개의 데이터의 값을 조회하고자 하는 경우

  장바구니의 담긴 상품의 옵션 번호(optionNo) 을 모두 조회하고자 하는 경우, Array.prototype.map 메소드를 이용하여 값을 조회할 수 있습니다.

  (예시)

  var optionNos = sb.cart.deliveryGroups.
      map(deliveryGroup => deliveryGroup.orderProducts.
       map(orderProduct => orderProduct.orderProductOptions.
       map(orderProductOption => orderProductOption.optionNo)
     )
   )

API의 스키마 배열을 확인하여 원하는 데이터를 조회할 수 있습니다

[스크립트 삭제]

delete외부스크립트 삭제하기

/external-script

앱 실행 시점에 토큰 권한 체크 후, 외부 스크립트를 mall에서 제거합니다.

api 확인하기

외부스크립트 삭제 API를 호출하여 특정 쇼핑몰에 등록된 스크립트를 삭제할 수 있으며,
쇼핑몰 관리자에서 앱이 삭제된 경우 삭제된 쇼핑몰에서는 더 이상 스크립트가 작동하지 않습니다.

스크립트 삭제 API를 호출할 때 파라미터에 deviceType과 scriptType을 입력하여 보낼 경우, 원하는 위치의 스크립트만 삭제할 수 있습니다.
(ex) PC / MAIN 입력 시, 스크립트 타입이 MAIN이면서 (쇼핑몰 메인화면 위치) 기기타입이 PC인 외부스크립트만 지워집니다.

해당 파라미터를 null로 보낼 경우, 설치된 앱에 등록된 스크립트가 전체삭제됩니다.

[스크립트 조회]

get외부 스크립트 조회하기

/external-script

쇼핑몰에서 사용 중인 외부 스크립트 리스트를 불러옵니다.

api 확인하기

쇼핑몰 스킨에 스크립트 조회 API가 삽입되어 있으면 프런트 화면에 접속 시 쇼핑몰에 저장된 스크립트가 실행됩니다.
쇼핑몰 스킨에 스크립트 조회API가 삽입되어 있지 않은 경우 스크립트를 저장하여도 스크립트가 실행되지 않습니다.

※ 추가된 스크립트가 쇼핑몰에서 정상 실행되고 있는지는 아래와 같은 방법으로 확인 가능합니다.
- 방법: 개발자도구 열기 > 시크릿모드에서 샵바이프로 쇼핑몰 열기 > Elements 탭과 network 탭에서 확인가능
단, 스크립트가 캐싱이 되면 해당 내용이 보이지 않습니다.

▼ (예시1) Elements 탭에 값이 확인됨

▼ (예시2) Network 탭에 external-scripts 를 통해 추가된 스크립트 값이 확인됨

get쇼핑몰 어드민/mall 정보 조회하기

/auth/me

access_token을 발급한 로그인한 어드민의 정보와 몰 정보를 조회합니다.

api 확인하기

액세스토큰(access token)을 발급한 쇼핑몰 관리자의 정보(ex 운영자 이메일, 이름/ 쇼핑몰 이름, 번호 등)를 조회할 수 있으며, 이를 통해 앱 개발사 시스템에 회원가입 및 자동 로그인 처리가 가능합니다.