Mall StoryDevelopers
Mall Story
시작하기

Postman 으로 시험하기

코드 없이 Postman 에서 동의 · 토큰 · API 호출까지 따라 합니다. 컬렉션 파일을 받아 바로 씁니다.

업데이트됨 10.13 — Postman 컬렉션에 수정 · 삭제 요청을 채웠습니다

준비

  1. 1
    앱 등록
    쇼핑몰 관리자 > 설정 > 외부연동 설정 > 앱 관리 에서 앱을 등록합니다. Redirect URI 에 https://oauth.pstmn.io/v1/callback 를 넣습니다 — Postman 이 브라우저로 동의 화면을 열고 이 주소로 code 를 받습니다. 권한은 시험할 만큼만 고릅니다(예: 쇼핑몰 정보 조회 · 수정).
  2. 2
    Client ID · 비밀 키 보관
    발급 창에서 바로 복사해 둡니다. 비밀 키는 다시 볼 수 없습니다.
  3. 3
    shop_unique · shop_id 확인
    shop_id 는 쇼핑몰 기본 주소의 앞부분입니다. shop_unique 는 토큰을 받으면 응답에 함께 옵니다 — 처음에는 비워 두고 토큰을 받은 뒤 채웁니다.

컬렉션 받기

폴더가 다섯이고, 관리자 API 폴더 안은 이 문서 왼쪽 메뉴와 같은 하위 폴더(쇼핑몰 정보 · 이미지 업로드 · 상품 관리 · 템플릿 관리 · 회원 관리 · 쿠폰 · MCP)로 나뉩니다 — 관리자 API 소유자 토큰 · 회원 API(회원 동의) 회원 토큰 · 회원 로그인(아이디 · 비밀번호) 회원 토큰 · 쇼핑몰 상품 조회(비회원) · 메타데이터. 폴더마다 OAuth 설정이 미리 들어 있고, 이 문서가 열린 환경의 API 주소가 들어 있습니다.

파일은 둘입니다 — 요청이 든 컬렉션과 변수(Client ID · 비밀 키 등)가 든 환경. 나눠 받는 까닭은 컬렉션을 새로 받아 다시 가져와도 채워 둔 변수가 남게 하려는 것입니다.

Postman 컬렉션 받기 (.json)Postman 환경 받기 (.json)
  1. 1
    가져오기
    Postman > Import 에 받은 두 파일을 함께 끌어 놓습니다.
  2. 2
    환경 고르기
    오른쪽 위 환경 고르기에서 Mall Story · api.mallstory.kr 를 고릅니다. 고르지 않으면 변수가 비어 요청이 실패합니다.
  3. 3
    변수 채우기
    Environments > 그 환경에서 client_id · client_secret · shop_id 를 넣고, shop_url 의 {shop_id} 를 실제 쇼핑몰 아이디로 바꿉니다. Current value 칸에 넣고 Ctrl+S 로 저장해야 요청에 실립니다. api_base 는 들어 있습니다.
컬렉션을 새로 받았을 때
새 컬렉션만 다시 가져옵니다(같은 이름이면 Replace). 환경은 다시 가져오지 않습니다 — 다시 가져오면 빈 값의 환경이 하나 더 생깁니다. 새 버전에 변수가 늘었을 때만 그 칸을 환경에 직접 더합니다(늘어난 변수는 변경 이력에 적습니다).
템플릿 생성 요청
관리자 API > 템플릿 관리 폴더에는 종류마다(공통정보 · 택배 · 직접 · 퀵 · 방문수령 · 색상 · 사이즈 · 맞춤형 리뷰) 목록 · 생성 · 상세 · 수정 · 삭제가 있고, 배송 할증지역 폴더에는 도로 찾기 · 지역 더하기 · 수정 · 삭제 · 기본 지역 빼기 · 되돌리기가 있습니다. 본문은 각 문서의 예시이고, 이름 끝에 {{$timestamp}} 를 붙여 여러 번 보내도 이름이 겹치지 않습니다. 생성하면 새 키가 환경 변수({종류}_template_id 등)에 담겨 이어지는 상세 · 수정 · 삭제가 방금 만든 것을 가리킵니다 — 색상은 생성이 개수만 돌려줘, 바로 뒤의 [만든 색상 찾기]가 그 이름의 색을 color_unique 에 담습니다. 카테고리 · 회원 등급 · 배지 · 쿠폰도 같은 차례(만들기 → 고치기 → 지우기)입니다.
상품 등록 요청
관리자 API > 상품 관리 > 상품 등록 폴더에 상품 등록 요청이 여섯 있습니다(옵션 없음 · 1개 · 2개 · 3개 · 추가상품 · 주문 요청사항). 본문은 그 문서의 예시와 같고, 카테고리와 배송 템플릿은 몰마다 키가 달라 변수로 넣습니다 — category_id 는 '카테고리 목록' 응답의 키(비워 두면 카테고리 없이 등록), parcel_template_id 는 '템플릿 관리 > 택배배송 목록' 응답의 키입니다 — '택배배송 생성' 을 보내면 새 템플릿 키가 이 변수에 저절로 담깁니다(비우면 키가 틀려 400 — 배송없음으로 시험하려면 본문에서 delivery 를 지웁니다). 등록이 되면 새 상품 키가 product_unique 변수에 담겨, 이어서 '상품 상세' · '상품 수정' · '상품 삭제' 를 그대로 보낼 수 있습니다. 보낼 때마다 시험 상품이 하나씩 생기니 '상품 삭제' 로 지웁니다.

토큰 받기 — 관리자 API

소유자 토큰 '관리자 API' 폴더 > Authorization 탭을 열면 아래처럼 채워져 있습니다. 직접 새 요청에 설정할 때도 같은 값을 넣습니다.

항목값
Auth TypeOAuth 2.0
Add auth data toRequest Headers (Header Prefix: Bearer)
Grant typeAuthorization Code (With PKCE)
Callback URLAuthorize using browser 체크 → https://oauth.pstmn.io/v1/callback
Auth URLhttps://api.mallstory.kr/oauth/authorize
Access Token URLhttps://api.mallstory.kr/api/oauth/token
Client ID · Client Secret앱 등록 때 받은 값
Code Challenge MethodSHA-256
Code Verifier비워 둡니다 — Postman 이 만듭니다
Scopeshop:read shop:write (공백으로 구분, 앱 권한 안에서)
State아무 값 — 비우면 400 입니다
Client AuthenticationSend client credentials in body (Basic Auth header 도 됩니다)
  1. 1
    Get New Access Token
    누르면 브라우저에 Mall Story 동의 화면이 열립니다.
  2. 2
    승인
    쇼핑몰 소유자 아이디 · 비밀번호로 확인하고 [승인] 을 누릅니다. Postman 으로 돌아옵니다.
  3. 3
    Use Token
    토큰 창에서 shop_unique 를 복사해 환경 변수에 넣고 [Use Token] 을 누릅니다. 이후 요청에 Bearer 토큰이 붙습니다.
2시간이 지나면
access token 이 만료되면 401 이 옵니다. 토큰 창의 Refresh 를 누르거나 Auto-refresh 를 켭니다(refresh token 은 14일, 갱신할 때마다 바뀝니다).

토큰 받기 — 회원 API

회원 토큰 회원 API 는 동의 주소(쇼핑몰 주소)와 동의하는 사람(회원)이 다릅니다. '회원 API' 폴더 > Authorization 탭에 채워져 있습니다.

  1. 1
    앱 권한 확인
    관리자 API 와 같은 앱(같은 client_id · client_secret)을 씁니다. 앱 권한에 me:read · me:write 가 들어 있어야 합니다.
  2. 2
    설정 확인
    Auth URL 은 {{shop_url}}/oauth/authorize(쇼핑몰 주소), Scope 는 me:read me:write 입니다.
  3. 3
    Get New Access Token
    브라우저에 쇼핑몰 동의 화면이 열립니다. 쇼핑몰 회원 아이디 · 비밀번호를 넣고 [동의하고 계속] 을 누릅니다(관리자 계정이 아니라 그 쇼핑몰의 회원 계정).
  4. 4
    Use Token
    토큰 창에 subject: member 와 member_unique 가 보입니다. '내 정보' 요청을 보냅니다.
회원용 앱을 따로 쓸 때
브라우저 · 모바일 앱(비밀 키 없음)으로 시험하려면 이 폴더의 Authorization 탭에서 Client ID 를 그 앱 것으로 바꾸고 Client Secret 을 비웁니다. 그 앱에도 Redirect URI https://oauth.pstmn.io/v1/callback 를 등록합니다.
회원 토큰으로 관리자 API 를 부르면 403
폴더가 토큰을 가른다 — 관리자 API 폴더 요청에 회원 토큰을 붙이면 403 입니다. 반대도 같습니다.

토큰 받기 — 회원 로그인

회원 토큰 동의 화면 없이 아이디 · 비밀번호로 받습니다. 쇼핑몰 자신의 화면이 쓰는 길입니다. → 회원 로그인

  1. 1
    변수 채우기
    member_login_id · member_password 에 그 쇼핑몰 회원의 아이디 · 비밀번호를 넣고 저장합니다. 앱은 같은 client_id · client_secret 입니다(서버 앱 · 권한에 me:read).
  2. 2
    '회원 로그인' 보내기
    200 이면 토큰이 member_access_token 변수에 저장됩니다(요청의 Tests 스크립트).
  3. 3
    '내 정보' 보내기
    폴더가 그 토큰을 Bearer 로 붙입니다. Get New Access Token 은 누르지 않습니다.

호출해 보기

요청기대 결과
GET 관리자 API › 쇼핑몰 정보 · 조회200 — 쇼핑몰 이름과 판매자 정보
PATCH 관리자 API › 쇼핑몰 정보 · 수정200 — changed 에 바뀐 필드. 같은 값이면 빈 배열
GET 관리자 API › 회원 목록200 — {items, page, size, total, has_more}
POST 관리자 API › MCP · tools/list200 — 토큰 권한에 맞는 도구 목록
GET 회원 API › 내 정보200 — 로그인한 회원 자신의 정보
GET 메타데이터 › 인가 서버200 — 인증 없이 열립니다
수정 요청은 실제 쇼핑몰을 바꿉니다
판매자 정보는 쇼핑몰 하단에 바로 실립니다. 시험은 지금 값과 같은 값으로 보내거나, 시험용 쇼핑몰에서 하세요.

막힐 때

보이는 것까닭 · 할 일
동의 화면에 "앱에 등록된 Redirect URI 와 다릅니다"앱의 Redirect URI 에 https://oauth.pstmn.io/v1/callback 가 없습니다. 추가하고 다시 시도합니다
invalid_scope앱에 고르지 않은 권한을 Scope 에 넣었습니다
invalid_request · stateState 칸이 비어 있습니다
토큰 단계 invalid_clientClient ID · 비밀 키가 틀렸거나 앱이 중지됐습니다
invalid_grantcode 가 만료(10분)되었거나 이미 쓰였습니다. Get New Access Token 을 다시 누릅니다
403 Forbiddenshop_unique 가 토큰의 쇼핑몰과 다릅니다. 토큰 창의 shop_unique 를 쓰세요