샵바이 API 호출 가이드
이해하기
이 문서는 샵바이 API의 기초 정보와 호출 방법을 소개합니다.
샵바이 API 호출 및 연동 개념
샵바이 API는 RESTful한 아키텍쳐로서 표준 HTTP Request Method, 리소스를 예측할 수 있는 엔드포인트 URL, HTTP 코드 기반의 에러 메시지를 제공합니다.
위 이미지와 같이, shop by pro의 모든 스킨들은 샵바이 솔루션에서 제공하는 샵바이 API를 RESTful한 방식으로 호출하여 어드민과 연동합니다.
- shop by pro(샵바이 프로)
- NHN커머스의 쇼핑몰 솔루션 라인업 중 하나로서, 본 스킨 개발 가이드에서는 shop by pro를 기준으로 합니다.
- shop by premium(샵바이 프리미엄) 역시 본 문서의 API를 참고할 수 있습니다.
- 샵바이 API
- NHN커머스에서 제공하는 오픈소스로서 (1) shop API (2) admin API (3) server API로 분류됩니다.
API 문서에서는 현재 (1) shop API와 (3) server API만 공개하고 있습니다.
- 본 샵바이 API 가이드 문서에서는 고객들이 접근하는 쇼핑몰 사이트 화면을 구성할 수 있는 shop API를 기준으로 합니다.
- 스킨(Skin)
- 쇼핑몰 고객들이 보는 쇼핑몰 프론트 화면 디자인 (템플릿, 레이아웃)을 뜻합니다.
- 어드민(Admin)
- 쇼핑몰 관리자(판매자)가 사용하는 화면으로 상품, 주문, 회원 관리 등 쇼핑몰을 관리하는 화면입니다.
샵바이 API 공통 파라미터(Parameters)
모든 샵바이 API 는 Request header 에 아래 3개의 파라미터(Parameters)를 필수 값(required)으로 넣어야 합니다.
Request 파라미터는 API별로 상이하나, 아래 3가지 항목은 모든 API에서 공통적으로 요구됩니다.
- Version
- API 버전 (샵바이는 1.0 버전으로 API 제공하고 있으며, 버전이 다른 API의 경우 문서 제목의 버전을 참고 바랍니다.)
- clientId
- - 클라이언트 아이디로서, 쇼핑몰 사이트를 출력하기 위해 할당된 각 상점의 쇼핑몰 구분 값
(프론트에서 API호출 시 해당하는 쇼핑몰을 판단할 수 있는 key값)
- - 샵바이프로: enviroment.json 내 clientId 값으로 확인 가능
- - 샵바이프리미엄: 서비스어드민 > 서비스관리 > 쇼핑몰관리 > (쇼핑몰 선택) > 개발연동정보 > 클라이언트 아이디에서 확인 가능
- - 클라이언트 아이디로서, 쇼핑몰 사이트를 출력하기 위해 할당된 각 상점의 쇼핑몰 구분 값
- platform
- 현재 실행 플랫폼으로서, 쇼핑몰 사이트를 출력하는 디바이스 기준 (PC, MOBILE_WEB, AOS, IOS)
아래는 Request header 에 필수 값 3개를 입력하여 호출하는 예제 코드이며, 모든 샵바이 API 를 호출할 때 실행됩니다.
1
2 const requestInit = {
3 methid,
4 headers: {
5 platform: 'PC',
6 clientId: shopby.config.skin.clientId,
7 Version: '1.0',
8 },
9 body: isFormData ? requestBody : JSON.stringify(requestBody),
10 };
11 로그인 상태 구분
쇼핑몰에서는 회원(member)과 비회원(guest)을 판별하기 위해, 로그인 상태 여부를 구분하는 것이 중요합니다.
앞으로 소개 드릴 화면별 설명에서는, 고객이 로그인을 했는지(=회원) 또는 하지 않았는지(=비회원)에 따라 사용되는 API가 다를 수 있으므로,
로그인 상태 여부를 판단하는 로직에 대해 소개하겠습니다.
샵바이에서는 액세스 토큰(accessToken) 기반의 로그인 방식을 사용합니다.
기본적으로 액세스 토큰의 존재 유무에 따라 로그인 상태를 구분할 수 있으며, 그 외 액세스 토큰 의 유효 기간 및 샵바이 API의 에러 응답 값에 따라 로그인 상태가 결정됩니다.
새로고침 혹은 쇼핑몰 내 다른 페이지 접근 시에도 로그인 상태를 유지하기 위해, 액세스 토큰 및 유효 기간 정보를 localStorage 에 저장해서 사용할 것을 권장 드립니다.
액세스 토큰 발급 API 등 보다 자세한 내용은 로그인 화면 문서를 확인하시길 바랍니다.
쇼핑몰 기본 정보 호출
- step1 : CDN에서 몰 정보 조회하기
- step 2-1: CDN에 몰 정보가 존재하는 경우, 해당 정보를 사용
- step 2-2: CDN에 몰 정보가 없는 경우, GET /malls API 호출
- URI : clientId 와 전체 주소를 모두 인코딩을해야 CDN에 저장된 정보에 올바르게 접근할 수 있습니다.
1
2 const uri = encodeURI(`https://shopby-scripts.cdn-nhncommerce.com/mall-configurations/${profile}/${encodeURIComponent(clientId)}/mallInfo.js`)
3 - dataType: jsonp
- jsonpCallback: getMalls (임의 수정 불가)
1
2 const cdnUri = encodeURI(`https://shopby-scripts.cdn-nhncommerce.com/mall-configurations/${상점의 profile 을 입력하세요}/${encodeURIComponent(상점의 clientId 를 입력하세요)}/mallInfo.js`);
3
4 $.ajax({
5 url: cdnUri,
6 jsonpCallback: 'getMalls',
7 dataType: 'jsonp',
8 success: function (malls) }
9 // cdn 에 정보가 있는 경우 여기서 malls 정보를 처리하세요.
10 }, error: function () {
11 // cdn 에 없는 경우 기존에 사용하고 있었던 getMalls api 를 직접 호출하여 malls 정보를 받아 처리하세요. },
12 });
13 ※ 관련 릴리즈노트 확인하기
쇼핑몰 기본 정보를 호출할 수 있는 GET/ malls API을 소개합니다.
해당 API는 쇼핑몰 어느 화면에서든 공통적으로 필요한 기본 API입니다.
- get쇼핑몰 기본 정보 조회
- /malls
쇼핑몰 전반에 대한 기본 정보와 설정 데이터를 조회할 수 있습니다.
해당 API는 쇼핑몰 명, 회원 가입 시 설정 값, 푸터 영역에 명시하는 쇼핑몰 기본 정보, 네이버 웹마스터 설정 값, 구글 에널리틱스 설정 값 등의 데이터를 포함합니다.
'API 확인하기' 버튼을 클릭하면, 우측에서 Responses>Schema 를 통해 상세 리턴 값들의 정의를 확인할 수 있습니다.
기본 스킨에서는 호출된 Responses의 리턴 값을 모두 사용하고 있으며, 각 리턴 값이 어느 화면에서 사용되었는지는 이후 진행될 문서에서 화면별로 다시 소개합니다.
해당 설정 값들은 실시간 변동성이 크지 않은 데이터로, API 호출 횟수를 줄이고자 응답 값을 localStorage 에 캐싱 주기를 5분으로 설정하였습니다.
쇼핑몰 정보, 특정 사용설정 항목 등이 5분 캐싱이 적용되어 API를 호출하지 않고 로컬에 저장된 데이터를 사용하므로,
어드민에서 변경된 사항이 실시간으로 데이터가 변경되지 않을 수 있습니다.