Mall StoryDevelopers
Mall Story
시작하기

빠른 시작

관리자 API · 회원 API 각각, 앱 등록부터 첫 호출까지 따라 합니다.

관리자 API 로 시작

소유자 토큰 주문관리 솔루션 · AI 에이전트처럼 서버에서 쇼핑몰을 관리하는 경우입니다.

  1. 1
    앱 등록
    쇼핑몰 관리자 > 설정 > 외부연동 설정 > 앱 관리 에서 [앱 등록] 을 누릅니다. Redirect URI 와 권한 상한을 정하면 Client ID · 비밀 키가 나옵니다. → 앱 등록하기
  2. 2
    판매자를 동의 화면으로 보내기
    GET /oauth/authorize 로 보냅니다. 판매자가 로그인하고 쇼핑몰 · 권한을 승인하면 Redirect URI 로 code 가 돌아옵니다. → 인가 요청과 동의
  3. 3
    토큰으로 바꾸기
    서버에서 POST /api/oauth/token 으로 code 를 access token · refresh token 으로 바꿉니다. → 토큰
  4. 4
    API 호출
    Authorization: Bearer {access_token} 헤더를 붙여 /v1/shop/{shop_unique}/{resource} 를 부릅니다. → API 호출하기
  5. 5
    만료되면 갱신
    access token 은 2시간 뒤 만료됩니다. refresh token 으로 새 토큰을 받습니다(14일).
코드 없이 먼저 해 보려면
Postman 으로 시험하기 — 컬렉션을 받아 변수만 채우면 동의 · 토큰 · 호출까지 됩니다.

한눈에 보는 요청

text1) 브라우저를 이 주소로 보냅니다
https://api.mallstory.kr/oauth/authorize?response_type=code
  &client_id=ms_xxxxxxxxxxxx
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &scope=shop%3Aread%20orders%3Aread
  &state=8f3c2a91
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
bash2) 돌아온 code 를 토큰으로
curl -X POST 'https://api.mallstory.kr/api/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=authorization_code \
  -d code=SplxlOBeZQQYbYS6WxSbIA \
  -d redirect_uri=https://app.example.com/oauth/callback \
  -d client_id=ms_xxxxxxxxxxxx \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
bash3) API 호출
curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/orders' \
  -H 'Authorization: Bearer {access_token}'

회원 API 로 시작

회원 토큰 쇼핑몰 화면 · 회원용 앱이 로그인한 회원의 정보를 다루는 경우입니다. 회원 토큰을 받는 길이 둘입니다.

누가받는 법회원이 보는 것
쇼핑몰 자신의 화면 · 앱회원 로그인그 화면의 로그인 폼 — 아이디 · 비밀번호만
남의 서비스회원 동의쇼핑몰 주소의 동의 화면 — 로그인 · [동의하고 계속]

쇼핑몰 자신의 화면 — 회원 로그인

  1. 1
    앱 등록 — 서버 앱
    앱 종류 서버 앱, 회원 본인 권한(me:read · me:write)을 켭니다. 관리 권한과 함께 켜도 됩니다.
  2. 2
    로그인 폼 → 서버
    회원이 넣은 아이디 · 비밀번호를 서버에서 POST /v1/member/login 에 비밀 키와 함께 보냅니다. → 회원 로그인
  3. 3
    내 정보 호출
    받은 토큰으로 GET /v1/me. → 회원 본인

남의 서비스 — 회원 동의

  1. 1
    앱 등록 — 브라우저 · 모바일 앱
    앱 종류를 브라우저 · 모바일 앱으로 고르고 회원 본인 권한(me:read · me:write)을 켭니다. 비밀 키가 없습니다. → 앱 등록하기
  2. 2
    회원을 쇼핑몰 주소의 동의 화면으로
    https://{shop_id}.mallstory.kr/oauth/authorize 로 보냅니다. 회원은 로그인한 뒤 다음 화면에서 동의합니다. → 회원 동의
  3. 3
    토큰으로 바꾸기 — 비밀 키 없이
    POST /api/oauth/token 에 client_id · code · code_verifier 만 보냅니다. 응답에 "subject": "member" 가 옵니다.
  4. 4
    내 정보 호출
    GET /v1/me — 경로에 회원 번호가 없습니다. 토큰이 정합니다. → 회원 본인