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

상품 아이콘

상품 이미지 우측 상단에 얹는 아이콘(이미지 한 장 · SVG 가능)을 만들고 고치고 지웁니다. 상품의 icon_id 에 넣는 키입니다.

업데이트됨 10.14 — 상품 아이콘 API 와 상품의 icon_id 를 열었습니다

무엇인가요

상품 이미지 우측 상단에 얹는 작은 그림입니다 — 목록의 썸네일과 상품 페이지의 대표 이미지에 함께 보입니다. 쇼핑몰 관리자의 상품 등록 · 수정 > 전시 설정 > 아이콘에서 만드는 것과 같습니다. 아이콘을 만들어 두고 상품의 icon_id(상품 등록, 하나)에 키를 넣습니다.

  • 배지는 상품명 앞의 글자 표식이고, 아이콘은 사진 위의 그림 표식입니다. 아이콘은 간편제작이 없고 이미지 한 장뿐입니다.
  • 이미지는 JPG · PNG · GIF 와 SVG 를 받습니다. 올릴 때 ?usage=product.decoration&variant=icon 을 붙입니다 — JPG · PNG 는 가로 · 세로 160 안으로 줄이고(정사각 권장), SVG 는 스크립트 · 이벤트 · 바깥 참조를 걷어 내고 크기 그대로 둡니다.
  • 고치거나 지우면 손님 화면에 바로 반영됩니다.
  • 이미지는 file_id 만 믿습니다 — 경로 · 주소는 이 쇼핑몰의 파일 기록에서 채웁니다. 다른 쇼핑몰 · 지운 파일이면 400.
요청경로바로가기권한
GET/icons목록products:read
GET/icons/{icon_unique}상세products:read
POST/icons생성products:write
PATCH/icons/{icon_unique}수정products:write
DELETE/icons/{icon_unique}삭제products:write

이미지 먼저 올리기

아이콘 이미지는 이미지 업로드에 variant=icon 을 붙여 올립니다. 이때만 SVG 를 받고, 한 번에 한 장입니다.

bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/files/images?usage=product.decoration&variant=icon' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -F 'files=@best.png'
json201 Created
{
  "items": [
    {
      "file_id": "6ace1b0a6ba8ebc3a773ac21",
      "url": "https://cdn.story.store/storages/2026/10/14/9b2f4c1e-5d7a-4e0b-a3f1-2c8d6e4b7a90.png",
      "name": "best.png",
      "size": 6214,
      "width": 160,
      "height": 160
    }
  ]
}

목록

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

권한 products:read

지우지 않은 아이콘을 이름순으로 모두 줍니다(관리자 고르기 목록과 같은 차례).

bash요청
curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/icons' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "items": [
    {
      "icon_unique": "6ace1b0b4555cab633c38e14",
      "name": "BEST",
      "created": "2026-10-14T05:21:47.318Z",
      "updated": "2026-10-14T05:22:20.904Z",
      "image": {
        "file_id": "6ace1b2c6ba8ebc3a773ac3f",
        "url": "https://cdn.story.store/storages/2026/10/14/4e81a7d2-0c3b-4f96-b5e2-7d19a0c6f348.png",
        "width": 160,
        "height": 160
      }
    }
  ]
}

응답 필드

필드형식설명
icon_uniquestring아이콘 키. 상품의 icon_id 에 넣는 값
namestring아이콘명
imageobjectfile_id · url · width · height(SVG 는 크기가 비어 있을 수 있음)
created · updatedISO만든 · 고친 시각

오류

상태code언제
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:read 가 없음

상세

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

권한 products:read

목록 한 줄과 같은 모양입니다.

bash요청
curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/icons/6ace1b0b4555cab633c38e14' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "icon_unique": "6ace1b0b4555cab633c38e14",
  "name": "BEST",
  "created": "2026-10-14T05:21:47.318Z",
  "updated": "2026-10-14T05:21:47.318Z",
  "image": {
    "file_id": "6ace1b0a6ba8ebc3a773ac21",
    "url": "https://cdn.story.store/storages/2026/10/14/9b2f4c1e-5d7a-4e0b-a3f1-2c8d6e4b7a90.png",
    "width": 160,
    "height": 160
  }
}

오류

상태code언제
404IconNotExist없는 키이거나 지운 아이콘
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:read 가 없음

생성

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

권한 products:write

요청 본문

필드형식설명
name필수string아이콘명(20자까지). 관리자가 고를 때 쓰는 이름이고, 손님 화면에서는 그림의 대체 글자(alt)입니다
image필수file_id이미지 업로드(?usage=product.decoration&variant=icon)로 받은 file_id — 문자열 또는 {"file_id": "…"}
bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/icons' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"BEST","image":"6ace1b0a6ba8ebc3a773ac21"}'
json201 Created
{
  "icon_unique": "6ace1b0b4555cab633c38e14",
  "name": "BEST",
  "created": "2026-10-14T05:21:47.318Z",
  "updated": "2026-10-14T05:21:47.318Z",
  "image": {
    "file_id": "6ace1b0a6ba8ebc3a773ac21",
    "url": "https://cdn.story.store/storages/2026/10/14/9b2f4c1e-5d7a-4e0b-a3f1-2c8d6e4b7a90.png",
    "width": 160,
    "height": 160
  }
}
json400 — 이 쇼핑몰에 올린 이미지가 아님
{
  "code": "InvalidParameterValue",
  "message": "아이콘 이미지: 이 쇼핑몰에 올린 이미지가 아니거나 지워진 이미지입니다(6ace1b0a0021241bbb288c07). 이미지를 다시 올려 받은 file_id 를 넣으세요.",
  "request_id": "req_3f0d2a9c7e1b4c58a6d4e2f190b7c3a5"
}

오류

상태code언제
400InvalidParameterValue이름 없음 · 20자 넘음 · 이미지 없음 · 이 쇼핑몰 파일이 아님
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:write 가 없음

수정

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

권한 products:write

보낸 필드만 바뀝니다. 필드는 생성과 같습니다. 이미지를 바꿔 끼우면 옛 이미지 파일은 지워집니다.

bash요청
curl -X PATCH 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/icons/6ace1b0b4555cab633c38e14' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"image":"6ace1b2c6ba8ebc3a773ac3f"}'
json200 OK
{
  "icon_unique": "6ace1b0b4555cab633c38e14",
  "name": "BEST",
  "created": "2026-10-14T05:21:47.318Z",
  "updated": "2026-10-14T05:22:20.904Z",
  "image": {
    "file_id": "6ace1b2c6ba8ebc3a773ac3f",
    "url": "https://cdn.story.store/storages/2026/10/14/4e81a7d2-0c3b-4f96-b5e2-7d19a0c6f348.png",
    "width": 160,
    "height": 160
  }
}

오류

상태code언제
400InvalidParameterValue생성과 같음
404IconNotExist없는 키이거나 지운 아이콘
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:write 가 없음

삭제

DELETEhttps://api.mallstory.kr/v1/shop/{shop_unique}/icons/{icon_unique}

권한 products:write

아이콘을 지우고, 쓰던 상품의 icon_id 를 null 로 비웁니다(상품의 updated 는 그대로). affected 는 비운 상품 수입니다. 이미지 파일도 지워집니다.

bash요청
curl -X DELETE 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/icons/6ace1b0b4555cab633c38e14' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "deleted": true,
  "icon_unique": "6ace1b0b4555cab633c38e14",
  "affected": 0
}

오류

상태code언제
404IconNotExist없는 키이거나 이미 지운 아이콘
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:write 가 없음