관리자 API템플릿 관리소유자 토큰

배송 할증지역

기본 할증지역에서 빼거나 이 쇼핑몰만의 할증지역을 더하고, 주소 검색 · 좌표 · 지도로 확인합니다.

무엇인가요

쇼핑몰 관리자 > 상품 > 템플릿 관리 > 배송 할증지역과 같은 작업입니다. 제주 · 도서산간처럼 배송비가 더 붙는 지역을 정합니다. 배송 템플릿의 extra_fee(제주 · 도서산간 추가 배송비)가 이 판정으로 붙습니다.

기본 할증지역 — 모든 쇼핑몰이 같이 쓰는 공용 목록입니다. 읽고, 이 쇼핑몰에서만 빼거나 되돌릴 수 있습니다(자료 자체는 운영자가 고칩니다).
이 쇼핑몰의 할증지역 — 더한 지역(INCLUDE)과 기본에서 뺀 지역(EXCLUDE)입니다.
찾기 · 좌표 · 지도는 등록할 도로 · 건물을 찾고 결과를 확인하는 도우미입니다. 관리자 화면의 검색 · 지도와 같은 값입니다.

요청	경로	바로가기	권한
GET	`/surcharges`	목록	`products:read`
POST	`/surcharges`	등록	`products:write`
PATCH	`/surcharges/{surcharge_unique}`	수정	`products:write`
DELETE	`/surcharges/{surcharge_unique}`	삭제	`products:write`
POST	`/surcharges/bulk`	일괄 등록	`products:write`
GET	`/surcharges/base`	기본 지역 검색	`products:read`
PATCH	`/surcharges/base`	기본 지역 빼기	`products:write`
GET	`/surcharges/base/{area_unique}/coord`	기본 지역 좌표	`products:read`
GET	`/surcharges/juso`	도로 검색	`products:read`
GET	`/surcharges/address`	주소 검색	`products:read`
GET	`/surcharges/locate`	건물 좌표	`products:read`
GET	`/surcharges/preview`	미리보기	`products:read`
GET	`/surcharges/reverse`	좌표 → 주소	`products:read`
GET	`/surcharges/map`	전체 지도	`products:read`

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

권한 products:read

쿼리	형식	설명
`type`	string	더한 지역 · 뺀 지역 가운데 하나로 거름. 없으면 둘 다 코드값

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "items": [
    {
      "surcharge_unique": "6abb41e66574bd83dff3405c",
      "type": "INCLUDE",
      "kind": "ISLAND",
      "scope": "",
      "road_code": "418203216019",
      "zipcode": "12429",
      "address": "경기 가평군 가평읍 북한강변로",
      "road_addr": "경기 가평군 가평읍 북한강변로 4 (산유리)",
      "adm_cd": "4182025032",
      "buld_mnnm": [],
      "memo": "",
      "lat": 37.7490013621251,
      "lng": 127.5141202528282,
      "created": "2026-09-29T04:43:18.930Z"
    }
  ]
}

응답 필드

필드	형식	설명
`surcharge_unique`	string	할증지역 키. 수정 · 삭제 경로에 넣습니다
`type`	string	더한 지역인가 · 기본에서 뺀 지역인가 코드값
`kind`	string	할증 종류(배송 템플릿의 어느 추가 배송비를 받나) 코드값
`scope`	string	범위 — 빈 글자면 도로 코드값
`road_code`	string	도로명 코드(12자리)
`adm_cd`	string	법정동 코드(10자리)
`address`	string	주소(도로 · 리 · 읍면동까지)
`road_addr`	string	대표 건물의 도로명주소
`zipcode`	string	우편번호
`buld_mnnm`	number[]	건물 본번 — 비면 도로 전체, 있으면 그 번호만
`memo`	string	메모(손님에게 보이지 않음)
`lat`	number	위도(서버가 채움)
`lng`	number	경도(서버가 채움)
`created`	ISO	등록 시각

오류

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

등록

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

권한 products:write

이 쇼핑몰만의 할증지역을 더합니다. 좌표는 서버가 주소로 찾아 채웁니다. 등록할 도로 · 건물은 도로 검색 · 주소 검색으로 찾습니다.

요청 본문

필드	형식	설명
`type`필수	string	이 쇼핑몰이 더하는 지역이면 INCLUDE 코드값
`kind`필수	string	할증 종류 코드값
`scope`	string	범위 — 비우면 도로 코드값
`road_code`필수	string	도로명 코드(검색 결과의 road_code)
`adm_cd`필수	string	법정동 코드(검색 결과의 adm_cd)
`address`필수	string	주소
`buld_mnnm`	number[]	건물 본번(그 번호만 할증)
`memo`	string	메모

bash요청

curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"type":"INCLUDE","kind":"ISLAND","road_code":"111402005001","adm_cd":"1114010300","address":"서울특별시 중구 세종대로","memo":"API 시험"}'

json201 Created

{
  "surcharge_unique": "6accb197c2ca90eedea6211e",
  "type": "INCLUDE",
  "kind": "ISLAND",
  "scope": "",
  "road_code": "111402005001",
  "zipcode": "",
  "address": "서울특별시 중구 세종대로",
  "road_addr": "",
  "adm_cd": "1114010300",
  "buld_mnnm": [],
  "memo": "API 시험",
  "lat": 37.56620502202934,
  "lng": 126.97770627907742,
  "created": "2026-10-12T10:08:23.543Z"
}

오류

상태	code	언제
400	`InvalidParameterValue`	필수 값이 없거나 이미 더한 도로
400	`SurchargeCoordNotFound`	주소 · 코드 · 건물번호로 좌표를 찾지 못함
401	`MissingLoginSession`	Authorization 헤더에 Bearer 토큰이 없음
401	`InvalidAccessToken`	토큰이 틀리거나 만료 · 폐기됨
403	`InsufficientScope`	토큰에 products:write 가 없음

수정

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

권한 products:write

보낸 필드만 바뀝니다. 필드는 등록과 같습니다.

bash요청

curl -X PATCH 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/6accb197c2ca90eedea6211e' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"memo":"API 시험 (수정)"}'

json200 OK

{
  "surcharge_unique": "6accb197c2ca90eedea6211e",
  "type": "INCLUDE",
  "kind": "ISLAND",
  "scope": "",
  "road_code": "111402005001",
  "zipcode": "",
  "address": "서울특별시 중구 세종대로",
  "road_addr": "",
  "adm_cd": "1114010300",
  "buld_mnnm": [],
  "memo": "API 시험 (수정)",
  "lat": 37.56620502202934,
  "lng": 126.97770627907742,
  "created": "2026-10-12T10:08:23.543Z"
}

오류

상태	code	언제
404	`SurchargeNotExist`	없는 키
401	`MissingLoginSession`	Authorization 헤더에 Bearer 토큰이 없음
401	`InvalidAccessToken`	토큰이 틀리거나 만료 · 폐기됨
403	`InsufficientScope`	토큰에 products:write 가 없음

삭제

DELETEhttps://api.mallstory.kr/v1/shop/{shop_unique}/surcharges/{surcharge_unique}

권한 products:write

bash요청

curl -X DELETE 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/6accb197c2ca90eedea6211e' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "deleted": true,
  "surcharge_unique": "6accb197c2ca90eedea6211e"
}

오류

상태	code	언제
404	`SurchargeNotExist`	없는 키
401	`MissingLoginSession`	Authorization 헤더에 Bearer 토큰이 없음
401	`InvalidAccessToken`	토큰이 틀리거나 만료 · 폐기됨
403	`InsufficientScope`	토큰에 products:write 가 없음

일괄 등록

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

권한 products:write

고른 도로(와 건물번호)를 한 번에 더합니다. 줄의 모양은 등록과 같고, 이미 더한 도로는 건너뜁니다. 줄은 도로 검색 결과로 만듭니다.

요청 본문

필드	형식	설명
`kind`	string	모든 줄에 붙일 할증 종류. 없으면 도서산간 코드값
`items`필수	array	도로 줄(최대 500) — `road_code` · `adm_cd` · `address` · `buld_mnnm`. 범위는 모두 도로입니다

bash요청

curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/bulk' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"ISLAND","items":[{"road_code":"111402005001","adm_cd":"1114010300","address":"서울특별시 중구 세종대로","buld_mnnm":[]}]}'

json200 OK

{
  "created": 1,
  "skipped": 0,
  "no_coord": 0
}

응답 예시는 모양을 보여 주는 값입니다(일괄 등록은 시험 데이터를 남기지 않으려 부르지 않았습니다).

응답 필드

필드	형식	설명
`created`	number	더한 줄 수
`skipped`	number	이미 더해 건너뛴 줄 수
`no_coord`	number	좌표를 못 구해 넣지 않은 줄 수

오류

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

기본 지역 검색

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

권한 products:read

쿼리	형식	설명
`keyword`	string	검색어(주소)
`field`	string	검색할 칸
`kind`	string	할증 종류로 거름 코드값
`scope`	string	범위로 거름 코드값
`page`	number	쪽 번호(기본 1)
`size`	number	쪽당 건수(기본 10)

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/base?size=2' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "items": [
    {
      "area_unique": "6aba268aecfe255d509df8b5",
      "kind": "ISLAND",
      "scope": "EMD",
      "address": "경기도 안산시 단원구 육도안길 9 (육도 복지회관)",
      "road_code": "412734373327",
      "adm_cd": "4127311400",
      "buld_mnnm": [],
      "excluded": false
    }
  ],
  "total": 252,
  "page": 1,
  "total_pages": 26
}

응답 필드

필드	형식	설명
`items[].area_unique`	string	기본 지역 키. 빼기 · 좌표에 씁니다
`items[].kind`	string	할증 종류 코드값
`items[].scope`	string	범위 코드값
`items[].address`	string	주소
`items[].road_code`	string	도로명 코드
`items[].adm_cd`	string	법정동 코드
`items[].buld_mnnm`	number[]	건물 본번
`items[].excluded`	boolean	이 쇼핑몰에서 뺐는가
`total`	number	전체 건수
`page`	number	지금 쪽 번호
`total_pages`	number	전체 쪽 수

오류

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

기본 지역 빼기 · 되돌리기

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

권한 products:write

요청 본문

필드	형식	설명
`area_unique`필수	string	기본 지역 키
`excluded`필수	boolean	true 면 이 쇼핑몰에서 뺌 · false 면 되돌림

bash요청

curl -X PATCH 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/base' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"area_unique":"6aba268aecfe255d509df8b5","excluded":true}'

json200 OK

{
  "excluded": true
}

오류

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

기본 지역 좌표

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/surcharges/base/{area_unique}/coord

권한 products:read

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/base/6aba268aecfe255d509df8b5/coord' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "coord": {
    "lat": 37.09834813185476,
    "lng": 126.45051520956243
  },
  "shape": {
    "type": null,
    "coordinates": "[[[[126.3801, 37.10758], …]]] (줄임)"
  }
}

좌표를 못 구하면 404 가 아니라 {coord: null} 입니다. shape 는 경계 모양(GeoJSON)입니다.

오류

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

도로 검색

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

권한 products:read

일괄 등록용 도로명주소 검색입니다. 도로로 묶고 도로마다 건물을 붙입니다. 이미 더한 도로 · 기본 지역을 함께 표시합니다.

쿼리	형식	설명
`keyword`필수	string	도로명 · 지번 검색어

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/juso?keyword=세종대로' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "items": [
    {
      "road_code": "111104100190",
      "adm_cd": "1111011700",
      "address": "서울특별시 종로구 당주동 세종대로23길",
      "li": "",
      "buildings": [
        {
          "no": "20-2",
          "bd_nm": "가로판매대"
        },
        {
          "no": "21",
          "bd_nm": ""
        }
      ],
      "registered": false,
      "registered_buildings": [],
      "base": null,
      "covered": null
    }
  ],
  "total": 308,
  "truncated": false
}

오류

상태	code	언제
502	`JusoFailed`	도로명주소 서비스가 답하지 않음
401	`MissingLoginSession`	Authorization 헤더에 Bearer 토큰이 없음
401	`InvalidAccessToken`	토큰이 틀리거나 만료 · 폐기됨
403	`InsufficientScope`	토큰에 products:read 가 없음

주소 검색

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

권한 products:read

도로명주소 검색(건물 단위, 첫 쪽)입니다.

쿼리	형식	설명
`keyword`필수	string	검색어

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/address?keyword=세종대로 110' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "items": [
    {
      "address": "서울특별시 중구 세종대로 110",
      "bd_nm": "서울특별시청",
      "jibun": "서울특별시 중구 태평로1가 31 서울특별시청",
      "road_code": "111402005001",
      "adm_cd": "1114010300",
      "li": "",
      "emd": "태평로1가"
    }
  ],
  "total": 2
}

오류

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

건물 좌표

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

권한 products:read

쿼리	형식	설명
`road_code`필수	string	도로명 코드
`adm_cd`필수	string	법정동 코드
`address`필수	string	주소

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/locate?road_code=111402005001&adm_cd=1114010300&address=서울특별시 중구 세종대로 110' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "point": {
    "lat": 37.56620502202934,
    "lng": 126.97770627907742
  }
}

오류

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

미리보기

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

권한 products:read

등록 전에 그 범위 · 코드의 좌표와 모양(경계 면 · 도로 선)을 봅니다. 저장하지 않습니다.

쿼리	형식	설명
`scope`	string	범위 코드값
`road_code`	string	도로명 코드
`adm_cd`	string	법정동 코드
`address`	string	주소
`buld_mnnm`	string	건물 본번

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/preview?scope=EMD&adm_cd=1114010300' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "coord": {
    "lat": 37.566,
    "lng": 126.977
  },
  "shape": "{ type, coordinates } (줄임)"
}

응답은 기본 지역 좌표와 같은 모양이고, 못 찾으면 둘 다 null 입니다.

오류

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

좌표 → 주소

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

권한 products:read

지도의 한 점 → 주소 · 코드와 이 쇼핑몰의 지금 판정(covered)입니다.

쿼리	형식	설명
`lat`필수	number	위도
`lng`필수	number	경도

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/reverse?lat=37.5665&lng=126.978' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "place": {
    "address": "서울특별시 중구 태평로1가 31",
    "bd_nm": "",
    "road_code": "",
    "adm_cd": "1114010300",
    "li": "",
    "emd": "태평로1가",
    "covered": null
  }
}

covered 는 이 점이 할증지역에 드는지(null 이면 들지 않음)입니다.

오류

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

전체 지도

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

권한 products:read

기본 지역 전체와 이 쇼핑몰이 더한 지역의 좌표와 모양입니다. 지도에 그릴 때 씁니다.

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/surcharges/map' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "items": [
    {
      "id": "shop:6abb41e66574bd83dff3405c",
      "source": "shop",
      "unique": "6abb41e66574bd83dff3405c",
      "kind": "ISLAND",
      "scope": "",
      "address": "경기 가평군 가평읍 북한강변로",
      "road_code": "418203216019",
      "adm_cd": "4182025032",
      "buld_mnnm": [],
      "excluded": false,
      "lat": 37.7490013621251,
      "lng": 127.5141202528282,
      "shape": "ROAD:418203216019:4182025032",
      "view": {
        "surcharge_unique": "6abb41e66574bd83dff3405c",
        "type": "INCLUDE",
        "kind": "ISLAND",
        "scope": "",
        "road_code": "418203216019",
        "zipcode": "12429",
        "address": "경기 가평군 가평읍 북한강변로",
        "road_addr": "경기 가평군 가평읍 북한강변로 4 (산유리)",
        "adm_cd": "4182025032",
        "buld_mnnm": [],
        "memo": "",
        "lat": 37.7490013621251,
        "lng": 127.5141202528282,
        "created": "2026-09-29T04:43:18.930Z"
      }
    }
  ],
  "shapes": "{ \"…\": { \"type\": \"MultiPolygon\", \"coordinates\": … } } (줄임)",
  "shape_missing": 0
}

응답 필드

필드	형식	설명
`items`	array	지역 한 줄 — `source`(base 기본 · shop 이 쇼핑몰) · `kind` · `scope` · 좌표 등
`shapes`	object	지역 키 → 경계 모양(GeoJSON)
`shape_missing`	number	모양을 못 구한 지역 수

오류

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

무엇인가요#

목록#

응답 필드

오류

등록#

요청 본문

오류

수정#

오류

삭제#

오류

일괄 등록#

요청 본문

응답 필드

오류

기본 지역 검색#

응답 필드

오류

기본 지역 빼기 · 되돌리기#

요청 본문

오류

기본 지역 좌표#

오류

도로 검색#

오류

주소 검색#

오류

건물 좌표#

오류

미리보기#

오류

좌표 → 주소#

오류

전체 지도#

응답 필드

오류

무엇인가요

목록

등록

수정

삭제

일괄 등록

기본 지역 검색

기본 지역 빼기 · 되돌리기

기본 지역 좌표

도로 검색

주소 검색

건물 좌표

미리보기

좌표 → 주소

전체 지도