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

상품 배지

상품명 앞에 붙는 배지(NEW · HOT)를 만들고 고치고 지웁니다. 상품의 badge_ids 에 넣는 키입니다.

업데이트됨 10.14 — 배지 이미지는 가로 160 을 넘으면 줄여 저장합니다

무엇인가요

상품명 앞에 붙는 작은 표식("NEW" · "HOT")입니다. 쇼핑몰 관리자의 상품 등록 · 수정 > 전시 설정 > 배지에서 만드는 것과 같습니다. 배지를 만들어 두고 상품의 badge_ids(상품 등록, 5개까지)에 키를 넣습니다.

  • 두 방식의 값을 모두 들고 있습니다 — 이미지 첨부로 바꿔도 색 · 도형이 남고, 어느 쪽이 손님에게 나가는지는 design 이 정합니다.
  • 고치거나 지우면 손님 화면에 바로 반영됩니다.
  • 이미지는 file_id 만 믿습니다 — 경로 · 주소는 이 쇼핑몰의 파일 기록에서 채웁니다. 다른 쇼핑몰 · 지운 파일이면 400.
요청경로바로가기권한
GET/badges목록products:read
GET/badges/{badge_unique}상세products:read
POST/badges생성products:write
PATCH/badges/{badge_unique}수정products:write
DELETE/badges/{badge_unique}삭제products:write

목록

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

권한 products:read

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

bash요청
curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/badges' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "items": [
    {
      "badge_unique": "6acdf41f4555cab633c38cbb",
      "name": "NEW",
      "design": "IMAGE",
      "shape": "TYPE2",
      "text_color": "#FFFFFF",
      "background_color": "#1E88E5",
      "border_color": null,
      "created": "2026-10-13T09:04:31.205Z",
      "updated": "2026-10-13T09:04:33.106Z",
      "image": {
        "file_id": "6acdf4216ba8ebc3a773ab1b",
        "url": "https://cdn.story.store/storages/2026/10/13/3ce010ea-2a44-48fc-80e6-66f20c42d717.png",
        "width": 64,
        "height": 24
      }
    }
  ]
}

응답 필드

필드형식설명
badge_uniquestring배지 키. 상품의 badge_ids 에 넣는 값
namestring배지명(20자까지, 이모지도 한 글자). 손님에게 보이는 글자. 같은 이름도 됨
designstring간편제작 · 이미지 첨부 코드값
shapestring간편제작 도형. 비우면 TYPE1 코드값
text_color · background_colorstring간편제작이면 필수. #RRGGBB
border_colorstring테두리 색. #RRGGBB, 비우면 없음
imageobject | nullfile_id · url · width · height. 이미지를 올린 적이 없으면 null
created · updatedISO만든 · 고친 시각

오류

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

상세

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

권한 products:read

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

bash요청
curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/badges/6acdf41f4555cab633c38cbb' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "badge_unique": "6acdf41f4555cab633c38cbb",
  "name": "NEW",
  "design": "SIMPLE",
  "shape": "TYPE2",
  "text_color": "#FFFFFF",
  "background_color": "#E53935",
  "border_color": null,
  "created": "2026-10-13T09:04:31.205Z",
  "updated": "2026-10-13T09:04:31.205Z",
  "image": null
}

오류

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

생성

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

권한 products:write

요청 본문

필드형식설명
name필수string배지명(20자까지, 이모지도 한 글자). 손님에게 보이는 글자. 같은 이름도 됨
design필수string간편제작 · 이미지 첨부 코드값
shapestring간편제작 도형. 비우면 TYPE1 코드값
text_color · background_colorstring간편제작이면 필수. #RRGGBB
border_colorstring테두리 색. #RRGGBB, 비우면 없음
imagefile_id이미지 첨부면 필수. 이미지 업로드(?usage=product.decoration)로 받은 file_id — 문자열 또는 {"file_id": "…"}
bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/badges' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"NEW","design":"SIMPLE","shape":"TYPE2","text_color":"#FFFFFF","background_color":"#E53935"}'
json201 Created
{
  "badge_unique": "6acdf41f4555cab633c38cbb",
  "name": "NEW",
  "design": "SIMPLE",
  "shape": "TYPE2",
  "text_color": "#FFFFFF",
  "background_color": "#E53935",
  "border_color": null,
  "created": "2026-10-13T09:04:31.205Z",
  "updated": "2026-10-13T09:04:31.205Z",
  "image": null
}
json400 — 색상코드가 아님
{
  "code": "InvalidParameterValue",
  "message": "글자 색상의 색상코드가 잘못되었습니다.",
  "request_id": "req_b7507260cb11462ea513c39f3af140cc"
}

오류

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

수정

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

권한 products:write

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

bash요청
curl -X PATCH 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/badges/6acdf41f4555cab633c38cbb' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"background_color":"#1E88E5"}'
json200 OK
{
  "badge_unique": "6acdf41f4555cab633c38cbb",
  "name": "NEW",
  "design": "SIMPLE",
  "shape": "TYPE2",
  "text_color": "#FFFFFF",
  "background_color": "#1E88E5",
  "border_color": null,
  "created": "2026-10-13T09:04:31.205Z",
  "updated": "2026-10-13T09:04:31.969Z",
  "image": null
}
json요청 — 이미지 첨부로 바꾸기
{
  "design": "IMAGE",
  "image": "6acdf4216ba8ebc3a773ab1b"
}
json200 OK
{
  "badge_unique": "6acdf41f4555cab633c38cbb",
  "name": "NEW",
  "design": "IMAGE",
  "shape": "TYPE2",
  "text_color": "#FFFFFF",
  "background_color": "#1E88E5",
  "border_color": null,
  "created": "2026-10-13T09:04:31.205Z",
  "updated": "2026-10-13T09:04:33.106Z",
  "image": {
    "file_id": "6acdf4216ba8ebc3a773ab1b",
    "url": "https://cdn.story.store/storages/2026/10/13/3ce010ea-2a44-48fc-80e6-66f20c42d717.png",
    "width": 64,
    "height": 24
  }
}
json400 — 이 쇼핑몰에 올린 이미지가 아님(보낸 path 는 버림)
{
  "code": "InvalidParameterValue",
  "message": "배지 이미지: 이 쇼핑몰에 올린 이미지가 아니거나 지워진 이미지입니다(6acdf41f0021241bbb288be9). 이미지를 다시 올려 받은 file_id 를 넣으세요.",
  "request_id": "req_c7a56efa8d384565a0bc9cd25dc077d0"
}

오류

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

삭제

DELETEhttps://api.mallstory.kr/v1/shop/{shop_unique}/badges/{badge_unique}

권한 products:write

배지를 지우고, 쓰던 상품의 badge_ids 에서도 뺍니다(상품의 updated 는 그대로). affected 는 뺀 상품 수입니다. 이미지 파일도 지워집니다.

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

오류

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