개요
Mall Story Open API 로 무엇을 할 수 있는지, 어떤 방식으로 연결하는지 알아봅니다.
Mall Story Open API
Mall Story Open API 는 주문관리 솔루션 · 물류 · 마케팅 도구 같은 외부 서비스와 AI 에이전트가 쇼핑몰의 상품 · 주문 · 회원 데이터를 다룰 수 있게 여는 API 입니다. 판매자가 직접 승인한 범위 안에서만 동작합니다.
베타 — 바뀔 수 있습니다
정식 공개 전이라 필드 · 규칙이 예고 없이 바뀔 수 있습니다. 바뀐 것은 모두 변경 이력에 적고(피드
/changelog.xml), 호환을 깨는 변경은 따로 표시합니다. 정식 공개 뒤에는 폐기 · 호환 깨짐을 매달 1일(휴일이면 다음 영업일)에만, 3개월 전에 예고하고 바꿉니다.지금 열린 것
앱 등록 · OAuth 인가와 토큰 · 회원 로그인, 관리자 API(쇼핑몰 정보 · 이미지 업로드 · 상품 · 상품 카테고리 · 상품 배지 · 상품 아이콘 · 템플릿 관리 · 회원 · 회원 등급 · 회원 적립금 · 쿠폰), 회원 API(회원 본인 · 쇼핑몰 화면 조회), MCP 가 열려 있습니다. 주문 · 클레임 · 리뷰 · 문의 등은 쇼핑몰 관리자에 그 메뉴가 생기는 차례로 열립니다. 아직 열리지 않은 부분에는 준비 중 표시가 붙어 있습니다.
연결하는 방법
| 방식 | 토큰 | 누가 쓰나 | 주소 |
|---|---|---|---|
| 관리자 API | 소유자 토큰 | 주문관리 · 물류 등 외부 서비스(서버)가 쇼핑몰을 관리할 때 | https://api.mallstory.kr/v1/shop/{shop_unique} |
| 회원 API | 회원 토큰 | 외부에서 만든 쇼핑몰 화면 · 회원용 앱이 로그인한 회원 자신의 정보를 다룰 때 | https://api.mallstory.kr/v1/me |
| MCP 서버 | 소유자 토큰 | AI 에이전트가 대화로 쇼핑몰을 다룰 때 | https://api.mallstory.kr/mcp |
모두 같은 OAuth 2.0 인가를 거치고 같은 권한(스코프) 규칙을 따릅니다. 다른 것은 누가 승인하느냐입니다 — 소유자 토큰은 쇼핑몰 소유자가, 회원 토큰은 회원이 승인합니다. 한 토큰으로 다른 쪽 API 는 부를 수 없습니다(403).
꼭 알아 둘 원칙
- 토큰은 쇼핑몰 하나에 묶입니다. 판매자가 쇼핑몰을 여러 개 운영해도, 동의 화면에서 고른 한 곳만 다룰 수 있습니다.
- 권한은 두 겹입니다. 앱 등록 때 정한 상한 안에서 요청하고, 판매자가 동의 화면에서 승인한 것만 생깁니다.
- PKCE 가 필수입니다. 모든 인가 요청에
code_challenge를 붙입니다. - 토큰은 언제든 폐기될 수 있습니다. 판매자가 연결을 끊으면 즉시 무효가 됩니다. 401 을 받으면 다시 인가를 받으세요.