스토어프론트 API 개요

스토어프론트 API는 외부 정적 프론트엔드에서 사용하는 브라우저용 API입니다.

Base URL: https://{site_host}/api/storefront/v1
Site key: X-Runmoa-Site-Key: moa_pub_xxxxxxxxx

공통 헤더

X-Runmoa-Site-Key: moa_pub_xxxxxxxxx
Accept: application/json

사용자 인증이 필요한 API에는 아래 헤더를 추가합니다.

Authorization: Bearer USER_LOGIN_TOKEN

브라우저 요청 옵션

정적 프론트엔드에서 fetch를 사용할 때는 아래처럼 credentials: 'include'를 함께 설정합니다.

await fetch(`${API_BASE}/site`, {
  credentials: 'include',
  headers: {
    'X-Runmoa-Site-Key': STOREFRONT_KEY,
    Accept: 'application/json',
  },
});

게스트 장바구니는 브라우저의 device cookie로 식별되므로, 외부 도메인에서 장바구니를 유지하려면 credentials: 'include'가 필요합니다. 로그인 사용자 API도 같은 fetch helper를 재사용하면 됩니다.

기능 범위

범위	설명
사이트/페이지	사이트 기본 정보, 메타, 페이지, 메뉴, 팝업
상품/콘텐츠 조회	상품/콘텐츠 목록과 상세, 카테고리, 태그, 콘텐츠 요약/설명
로그인	Schoolmoa client id 조회, callback 처리, 로그아웃
장바구니	게스트 장바구니, 로그인 장바구니, 게스트 장바구니 병합
주문/결제	주문 생성, 결제 초기화, 내 주문 조회
마이페이지	내 정보, 주문, 보유 콘텐츠
게시판	게시판, 게시글, 댓글

스토어프론트 API에서 제외되는 기능

아래 작업은 브라우저용 키로 제공하지 않습니다.

• 상품 생성, 수정, 삭제
• 콘텐츠 생성, 수정, 삭제
• 관리자 설정 변경
• 판매자 정산, 매출, 리포트, 운영 데이터 조회
• 프로필 수정, 환불 요청처럼 별도 사용자 확인이 필요한 기능

상품/콘텐츠 생성과 수정은 서버용 비공개 API에서 처리합니다. 관리자 설정, 정산, 리포트는 런모아 관리자 기능에서 처리합니다.

결제 경로 원칙

외부 사이트의 결제는 POST /payments/initialize 응답의 form payload를 submit하는 방식으로 구현합니다.

외부 정적 프론트엔드는 항상 아래 경로로 결제를 시작합니다.

POST /api/storefront/v1/payments/initialize

결제는 표준 NicePay 카드결제만 사용합니다. 정적 프론트엔드는 POST /payments/initialize 응답의 form payload만 submit하면 됩니다.