Mall StoryDevelopers
Mall Story
관리자 API템플릿 관리소유자 토큰

공통정보

상품 상세 위 · 아래에 붙는 공통 안내(공통정보 템플릿)를 관리합니다.

업데이트됨 10.13 — 이미지 칸은 어디서 저장하든 파일 키만 믿습니다

무엇인가요

상품 상세 위 · 아래에 공통으로 붙는 안내(교환 · 반품 안내, 브랜드 소개 등)입니다.

항목내용
권한읽기 products:read · 쓰기 products:write (소유자 토큰)
상품에서 쓰는 곳상품의 top_template_ids · bottom_template_ids
관리자 화면상품 > 템플릿 관리 — 같은 검증 · 같은 저장
요청경로바로가기
GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/common목록
GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/common/{template_unique}상세
POSThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/common생성
PATCHhttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/common/{template_unique}수정
DELETEhttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/common/{template_unique}삭제

목록

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

이 쇼핑몰의 템플릿 전부입니다(쪽 나눔 없음). 줄마다 이 템플릿을 쓰는 상품 수 used_count 가 붙습니다 — 관리자 목록의 "적용상품" 칸과 같습니다.

쿼리형식설명
sortstring정렬 키. 빼면 등록일시 최신순(관리자 목록의 기본과 같음) 코드값
orderstring정렬 방향. 빼면 name 는 오름차순, 시각은 최신순. sort 와 함께 보냅니다 코드값
bash요청
curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/common' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "items": [
    {
      "template_unique": "6acca48ec2ca90eedea620f5",
      "name": "교환 · 반품 안내",
      "title": "교환 · 반품 안내",
      "mode": "EDITOR",
      "content": "<p>상품 수령 후 7일 이내 교환 · 반품할 수 있습니다.</p>",
      "editor_content": "<p>상품 수령 후 7일 이내 교환 · 반품할 수 있습니다.</p>",
      "image": null,
      "created": "2026-10-12T09:12:46.681Z",
      "updated": "2026-10-12T09:12:46.681Z",
      "used_count": 0
    }
  ]
}

상세

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/common/{template_unique}
bash요청
curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/common/6acca48ec2ca90eedea620f5' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "template_unique": "6acca48ec2ca90eedea620f5",
  "name": "교환 · 반품 안내",
  "title": "교환 · 반품 안내",
  "mode": "EDITOR",
  "content": "<p>상품 수령 후 7일 이내 교환 · 반품할 수 있습니다.</p>",
  "editor_content": "<p>상품 수령 후 7일 이내 교환 · 반품할 수 있습니다.</p>",
  "image": null,
  "created": "2026-10-12T09:12:46.681Z",
  "updated": "2026-10-12T09:12:46.681Z"
}

응답 필드

필드형식설명
template_uniquestring키. 상세 · 수정 · 삭제 경로에 넣습니다
namestring템플릿명(관리자 목록에 보이는 이름)
titlestring안내 제목(상품 상세에 보임)
modestring안내를 본문(content)으로 쓰는가, 이미지(image) 한 장으로 넣는가 코드값
editor_contentstring본문 HTML — EDITOR 면 필수
imageobject | null이미지 한 장 — IMAGE 면 필수. 키 문자열 "…" 또는 {"file_id": "…"} 만 보냅니다(이미지 업로드에서 받은 값)
contentstring상품 상세에 실리는 HTML. 서버가 만듭니다 — EDITOR 면 editor_content, IMAGE 면 그 이미지 태그
image.urlstring이미지 주소(IMAGE). 서버가 저장소 · 경로로 만듭니다
createdISO생성 시각
updatedISO마지막 수정 시각
used_countnumber이 템플릿을 쓰는 상품 수(목록에만)

생성

POSThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/common

이미지 방식은 image 에 이미지 업로드(?usage=product.template)로 받은 키만 넣습니다. 제목만 고치는 수정은 이미지를 그대로 두고, 이미지를 바꾸려면 새로 올린 키를 보냅니다.

요청 본문

필드형식설명
name필수string템플릿명(관리자 목록에 보이는 이름)
title필수string안내 제목(상품 상세에 보임)
mode필수string안내를 본문(content)으로 쓰는가, 이미지(image) 한 장으로 넣는가 코드값
editor_contentstring본문 HTML — EDITOR 면 필수
imageobject | null이미지 한 장 — IMAGE 면 필수. 키 문자열 "…" 또는 {"file_id": "…"} 만 보냅니다(이미지 업로드에서 받은 값)
bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/common' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"교환 · 반품 안내","title":"교환 · 반품 안내","mode":"EDITOR","content":"<p>상품 수령 후 7일 이내 교환 · 반품할 수 있습니다.</p>","editor_content":"<p>상품 수령 후 7일 이내 교환 · 반품할 수 있습니다.</p>"}'
json201 Created
{
  "template_unique": "6acca48ec2ca90eedea620f5"
}

새 템플릿의 키를 돌려줍니다.

수정

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

보낸 필드만 바뀝니다. 나머지는 지금 값 그대로입니다. 필드는 생성과 같습니다.

bash요청
curl -X PATCH 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/common/6acca48ec2ca90eedea620f5' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"교환 · 반품 · 환불 안내"}'
json200 OK
{
  "template_unique": "6acca48ec2ca90eedea620f5"
}
json수정 뒤 상세
{
  "template_unique": "6acca48ec2ca90eedea620f5",
  "name": "교환 · 반품 안내",
  "title": "교환 · 반품 · 환불 안내",
  "mode": "EDITOR",
  "content": "<p>상품 수령 후 7일 이내 교환 · 반품할 수 있습니다.</p>",
  "editor_content": "<p>상품 수령 후 7일 이내 교환 · 반품할 수 있습니다.</p>",
  "image": null,
  "created": "2026-10-12T09:12:46.681Z",
  "updated": "2026-10-12T09:12:46.806Z"
}

삭제

DELETEhttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/common/{template_unique}
bash요청
curl -X DELETE 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/common/6acca48ec2ca90eedea620f5' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "affected": 0
}

지운 템플릿을 상단 · 하단에 걸어 둔 상품에서는 떼어집니다. affected 는 바뀐 상품 수입니다. 이미지 방식이면 그 이미지 파일도 함께 지웁니다.

오류

상태code언제
400InvalidParameterValue템플릿명 · 제목 · 작성 방식이 없거나 올바르지 않음 · EDITOR 인데 본문이 없음 · IMAGE 인데 이미지가 없음(이미지를 업로드하세요)
400InvalidParameterValueimage.file_id 가 이 쇼핑몰에 올린 이미지가 아니거나 지워진 이미지(공통정보 템플릿 이미지: …)
404NoticeTemplateNotExist없는 키이거나 지운 템플릿
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:read · products:write 가 없음

오류 본문은 {code, message, request_id} 이고, message 는 관리자 화면과 같은 문구라 사용자에게 그대로 보여 줄 수 있습니다.