Mall StoryDevelopers
Mall Story
관리자 API소유자 토큰

쇼핑몰 정보

쇼핑몰 이름과 판매자(사업자 · 고객센터 · 주소 · 개인정보 보호책임자) 정보를 조회하고 고칩니다.

무엇인가요

쇼핑몰 이름과 판매자 정보입니다. 판매자 정보는 전자상거래법이 손님에게 보이라고 정한 사업자 정보로, 쇼핑몰 하단에 그대로 실립니다. 쇼핑몰 관리자 > 기본 정보와 같은 검사 · 같은 저장입니다.

요청경로바로가기권한
GET/v1/shop/{shop_unique}조회shop:read
PATCH/v1/shop/{shop_unique}수정shop:write
MCP 로도 같습니다
AI 에이전트는 get_shop · update_shop 도구로 같은 일을 합니다. → MCP 도구

조회

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}

권한 shop:read

bash요청
curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "shop_unique": "6a9515bdcb3ab5179ba767ad",
  "shop_id": "test2",
  "shop_name": "테스트몰",
  "shop_url": "https://test2.story.store",
  "seller_type": "INDIVIDUAL",
  "company_name": "마이샵",
  "ceo_name": "홍길동",
  "business_number": "1234567890",
  "mail_order_number": "제 2026-서울강남-01234호",
  "business_type": "",
  "business_item": "",
  "tel": "",
  "email": "",
  "fax": "",
  "work_time": "평일 10:00 ~ 19:00",
  "privacy_officer": "",
  "privacy_email": "",
  "address": {
    "zipcode": "06236",
    "address1": "서울 강남구 테헤란로 152",
    "address2": "10층"
  }
}

응답 필드

필드형식설명
shop_uniquestring쇼핑몰 키. 경로에 넣는 값(읽기 전용)
shop_idstring쇼핑몰 아이디 — 기본 주소 {shop_id}.mallstory.kr 의 앞부분(읽기 전용)
shop_urlstring기본 주소(읽기 전용)
shop_namestring쇼핑몰 이름. 2~30자
seller_typestring판매자 유형 코드값
company_namestring상호(법인명). 개인판매자는 판매자 이름
ceo_namestring대표자명
business_numberstring사업자등록번호 10자리. 줄표를 보내도 숫자만 저장하고, 검증번호가 맞아야 합니다
mail_order_numberstring통신판매업 신고번호
business_typestring업태
business_itemstring종목
address.zipcodestring사업장 우편번호
address.address1string사업장 기본주소
address.address2string사업장 상세주소. 주소를 바꿀 때는 세 칸을 함께 보냅니다
telstring대표전화. 숫자와 줄표, 8~12자리
emailstring대표메일
faxstring팩스번호
work_timestring고객센터 업무시간 안내(여러 줄)
privacy_officerstring개인정보 보호책임자 이름
privacy_emailstring개인정보 보호책임자 메일

오류

상태code언제
403Forbidden토큰이 묶인 쇼핑몰과 경로의 shop_unique 가 다름
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 shop:read 가 없음

수정

PATCHhttps://api.mallstory.kr/v1/shop/{shop_unique}

권한 shop:write

보낸 필드만 바뀌고 나머지는 그대로입니다. 읽기 전용 필드(shop_unique · shop_id · shop_url)는 보낼 수 없습니다.

요청 본문

필드형식설명
shop_namestring쇼핑몰 이름. 2~30자
seller_typestring판매자 유형 코드값
company_namestring상호(법인명). 개인판매자는 판매자 이름
ceo_namestring대표자명
business_numberstring사업자등록번호 10자리. 줄표를 보내도 숫자만 저장하고, 검증번호가 맞아야 합니다
mail_order_numberstring통신판매업 신고번호
business_typestring업태
business_itemstring종목
address.zipcodestring사업장 우편번호
address.address1string사업장 기본주소
address.address2string사업장 상세주소. 주소를 바꿀 때는 세 칸을 함께 보냅니다
telstring대표전화. 숫자와 줄표, 8~12자리
emailstring대표메일
faxstring팩스번호
work_timestring고객센터 업무시간 안내(여러 줄)
privacy_officerstring개인정보 보호책임자 이름
privacy_emailstring개인정보 보호책임자 메일
bash요청
curl -X PATCH 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"work_time":"평일 10:00 ~ 19:00"}'
json200 OK
{
  "shop": {
    "shop_unique": "6a9515bdcb3ab5179ba767ad",
    "work_time": "평일 10:00 ~ 19:00",
    "…": "조회와 같은 필드"
  },
  "changed": []
}

응답은 {shop, changed} 입니다. changed 는 실제로 값이 바뀐 필드이고, 위 예시처럼 같은 값을 보내면 빈 배열입니다(다시 불러도 안전합니다).

json400 — 쇼핑몰명을 1자로 보냄
{
  "code": "InvalidParameterValue",
  "message": "쇼핑몰명은 2~30자로 입력하세요."
}
  • 저장 규칙은 관리자 화면과 같습니다. 하나만 보내도 저장된 나머지 칸이 규칙(필수 칸 · 전화 모양)을 지켜야 저장됩니다.
  • seller_type 을 PERSONAL 로 바꾸면 사업자등록번호 · 통신판매업 신고번호 · 업태 · 종목이 비워집니다.
  • 주소가 바뀌면 할증지역 판단에 쓰는 법정동 코드가 비워집니다. 쇼핑몰 관리자에서 우편번호를 다시 고르면 채워집니다.

오류

상태code언제
400InvalidParameterValue모르는 필드 · 형식이 틀린 값 · 저장 규칙 위반(message 에 고칠 칸이 적힘)
400InvalidRequestBody본문이 JSON 이 아님
403Forbidden토큰이 묶인 쇼핑몰과 경로의 shop_unique 가 다름
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 shop:write 가 없음