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

색상

옵션 색 칩에 쓰는 색상 목록을 관리합니다.

업데이트됨 10.13 — 목록 정렬 sort · order 를 받습니다

무엇인가요

옵션의 색 칩에 쓰는 색상 목록입니다.

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

목록

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

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

쿼리형식설명
sortstring정렬 키 — 색상은 sort_order(노출순서)도 받습니다. 빼면 노출순서 → 이름순(관리자 목록의 기본과 같음) 코드값
orderstring정렬 방향. 빼면 name · sort_order 는 오름차순, 시각은 최신순. sort 와 함께 보냅니다 코드값
bash요청
curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/colors' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "items": [
    {
      "color_unique": "6acca48fc2ca90eedea620fa",
      "name": "샌드베이지",
      "hex": "#D8C3A5",
      "keywords": [],
      "sort_order": 0,
      "created": "2026-10-12T09:12:47.441Z",
      "updated": "2026-10-12T09:12:47.441Z",
      "used_count": 0
    }
  ]
}

상세

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/colors/{color_unique}
bash요청
curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/colors/6acca48fc2ca90eedea620fa' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "color_unique": "6acca48fc2ca90eedea620fa",
  "name": "샌드베이지",
  "hex": "#D8C3A5",
  "keywords": [],
  "sort_order": 0,
  "created": "2026-10-12T09:12:47.441Z",
  "updated": "2026-10-12T09:12:47.441Z"
}

응답 필드

필드형식설명
color_uniquestring키. 상세 · 수정 · 삭제 경로에 넣습니다
itemsarray생성할 때만 — 한 번에 여러 개. 한 개는 {name, hex}
namestring색 이름(같은 이름은 안 됨)
hexstring색 값 #RRGGBB
keywordsstring[]함께 찾히는 말(검정색 · Black …) — 수정으로만 넣습니다
sort_ordernumber차례 — 수정으로만
createdISO생성 시각
updatedISO마지막 수정 시각
used_countnumber이 템플릿을 쓰는 상품 수(목록에만)

생성

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

생성은 items 로 여러 개를 한 번에 받습니다. 생성 때는 이름과 색 값만 쓰고, 키워드 · 차례는 수정으로 넣습니다.

요청 본문

필드형식설명
items필수array생성할 때만 — 한 번에 여러 개. 한 개는 {name, hex}
name필수string색 이름(같은 이름은 안 됨)
hex필수string색 값 #RRGGBB
keywordsstring[]함께 찾히는 말(검정색 · Black …) — 수정으로만 넣습니다
sort_ordernumber차례 — 수정으로만
bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/colors' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"name":"샌드베이지","hex":"#D8C3A5"}]}'
json201 Created
{
  "count": 1
}

생성한 개수를 돌려줍니다. 새 키는 목록에서 이름으로 찾습니다.

수정

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

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

bash요청
curl -X PATCH 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/colors/6acca48fc2ca90eedea620fa' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"hex":"#D2B48C","keywords":["베이지","모래색"]}'
json200 OK
{
  "ok": true
}
json수정 뒤 상세
{
  "color_unique": "6acca48fc2ca90eedea620fa",
  "name": "샌드베이지",
  "hex": "#D2B48C",
  "keywords": [
    "베이지",
    "모래색"
  ],
  "sort_order": 0,
  "created": "2026-10-12T09:12:47.441Z",
  "updated": "2026-10-12T09:12:47.499Z"
}

삭제

DELETEhttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/colors/{color_unique}
bash요청
curl -X DELETE 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/colors/6acca48fc2ca90eedea620fa' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "ok": true
}

지운 색을 쓰던 상품 옵션에서는 색 표시가 빠집니다. 응답은 {ok: true} 입니다.

오류

상태code언제
409ProductColorNameDuplicate같은 이름의 색이 이미 있음
400InvalidParameterValue이름 · 색 값이 없거나 올바르지 않음
404ProductColorNotExist없는 키이거나 지운 색
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:read · products:write 가 없음

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