Storefront API 개요

온라인쇼핑몰 구매자용(Storefront) API입니다. 관리(Seller) API와 분리 운영되며, 멀티테넌트입니다.

베이스 URL과 테넌트 지정

https://shop.api.avarlabs.com/storefront/v1

스토어(테넌트)는 X-Store-Code 헤더로 지정합니다. 헤더가 없으면 mystore 스토어로 처리됩니다.

curl https://shop.api.avarlabs.com/storefront/v1/products -H "X-Store-Code: mystore"

• 회원/장바구니/주문/리뷰는 모두 스토어 단위로 격리 — A 스토어 계정으로 B 스토어 로그인 불가
• 회원 토큰은 발급한 스토어에서만 유효, 타 스토어 API에 사용 시 401
• 폐쇄(CLOSED)/정지(SUSPENDED) 스토어는 모든 요청에 410 / 503 반환

인증 체계

• 회원: 로그인 후 Access Token(30분) + Refresh Token(14일), Authorization: Bearer. refresh는 rotation 방식 (데모 계정: buyer@example.com / buyer1234!)
• 비회원: 상품 탐색은 인증 불필요. 장바구니는 X-Cart-Token 헤더로 익명 카트 유지
• 자체 로그인(위임): 자체 회원 시스템을 쓰는 경우, 서버에서 회원 토큰을 위임 발급받아 이 API에 사용할 수 있습니다 — Store API의 구매자 위임 참조
• 본인 리소스(주문/클레임/리뷰 등)는 /me 네임스페이스로만 접근

TypeScript에서는 @shop24/storefront-sdk가 토큰/카트 토큰 처리를 캡슐화합니다.

공통 규칙

• 모든 응답은 표준 엔벨로프 — $.meta(status/code/message/isSuccess) + 성공 $.data / 실패 $.error
• 목록 조회: page/size 페이지네이션
• 일시는 ISO 8601 (KST 오프셋 포함)
• 가격은 원 단위 정수
• 개인정보 응답은 본인 인증된 요청에만 제공, 타인 노출 필드는 마스킹