# Shopee 배송 채널 (Logistics Channel) 한글 가이드

> Shopee 셀러센터 / Shopee OpenAPI v2 기준 배송 채널(=배송 프로그램)을 마켓별로 정리한 문서입니다.  
> 작성일: 2026-05-04

---

## 0. 공식 API 규칙 요약 (반드시 지켜야 함)

### 0-1. 채널 조회 — `v2.logistics.get_channel_list`
- 문서: <https://open.shopee.com/documents/v2/v2.logistics.get_channel_list?module=95&type=1>
- 응답의 `logistics_channel_list[]` 항목별 핵심 필드

| 필드 | 한글 의미 | 비고 |
|---|---|---|
| `logistics_channel_id` | 채널 고유 ID | int64 |
| `logistics_channel_name` | 채널 이름 | "Standard Delivery (5DD)" 등 |
| `enabled` | **샵 레벨 활성화 여부** | false면 셀러센터 배송 탭에서 OFF |
| `force_enable` | 강제 활성 채널 | true면 셀러가 끌 수 없음 |
| `fee_type` | 운임 산정 방식 | `SIZE_SELECTION` / `SIZE_INPUT` / `FIXED_DEFAULT_PRICE` / `CUSTOM_PRICE` |
| `cod_enabled` | COD 지원 여부 | bool |
| `weight_limit.item_max_weight` / `item_min_weight` | 무게 한도 (kg) | 0=무제한 |
| `item_max_dimension.length / width / height / dimension_sum` | 치수 한도 (cm) | |
| `volume_limit.item_max_volume` / `item_min_volume` | 부피 한도 | |
| `support_cross_border` | 크로스보더(SLS) 지원 | bool |
| `mask_channel_id` | 0이면 결제 채널, 0이 아니면 풀필먼트 채널 | |
| `support_pause` | 일시정지 가능 채널 | `get_pause_status`로 현재 상태 확인 |

### 0-2. 상품 등록/수정 시 적용 — `v2.product.add_item` / `update_item`
- 문서: <https://open.shopee.com/documents/v2/v2.product.add_item?module=89&type=1>
- 문서: <https://open.shopee.com/documents/v2/v2.product.update_item?module=89&type=1>

`logistic_info` 배열 규칙:
- `logistic_id` (필수) — `get_channel_list`에서 받은 `logistics_channel_id`
- `enabled` (필수) — true면 해당 상품에서 채널 ON
- `size_id` — `fee_type=SIZE_SELECTION`인 경우 **필수**
- `shipping_fee` — `fee_type=CUSTOM_PRICE`인 경우 **필수**
- `is_free` — 셀러가 운임 부담할 때 true (`block_seller_cover_shipping_fee=true`인 채널은 사용 불가)

### 0-3. 자주 발생하는 채널 비활성 사유
| 에러 | 의미 | 해결 |
|---|---|---|
| `error_invalid_logistic_info` | logistic_info 구조 오류 | logistic_id/size_id/shipping_fee 필수값 확인 |
| `error_invalid_price_for_logistic` | 가격이 채널 한도 초과 | 가격 인하 또는 다른 채널 사용 |
| `error_invalid_days_to_ship` | DTS 범위 위반 | `get_dts_limit`로 허용 범위 조회 |
| `error_param_dts_exceeds_max_limit` | DTS 카테고리 max 초과 | 카테고리 정책 따라 DTS 축소 |
| `error_category_dts` | 카테고리 max DTS 초과 | 동일 |
| 채널 자동 OFF | weight/dimension/volume 한도 초과 | 다른 채널 또는 포장 변경 |

> **상품 등록 직후 특정 채널이 OFF로 들어가는 현상**(예: SG 5DD)은 거의 다음 중 하나입니다.  
> ① 샵 레벨에서 이미 비활성(`enabled=false`)  
> ② 가격/무게/치수가 채널 한도 초과 → Shopee가 자동 OFF  
> ③ `fee_type`이 `SIZE_SELECTION`/`CUSTOM_PRICE`인데 필수값 누락  
> ④ `support_cross_border=false`인데 CB 샵으로 업로드

---

## 1. 마켓별 주요 배송 채널

> 채널 ID는 샵별로 다를 수 있으므로 **반드시 `get_channel_list`로 동적 조회**해서 사용합니다.  
> 아래는 Seller Centre / SEH 기준 자주 노출되는 채널 이름과 한글 해설입니다.

### 1-1. 🇸🇬 싱가포르 (SG)

| 채널 영문명 | 한글 해설 | fee_type | 비고 |
|---|---|---|---|
| **Standard Delivery (3DD)** | 표준 배송 (3일 내 배송) | SIZE_SELECTION | 가장 일반적, 무게 30kg / 100×100×100cm 한도 |
| **Standard Delivery (5DD)** | 표준 배송 (5일 내 배송) | SIZE_SELECTION | 일반 셀러 기본값. 가격 한도/카테고리 제약 시 자동 OFF |
| **Bulky Delivery (3DD)** | 대형 화물 배송 (3일) | SIZE_SELECTION | 대형 가구/가전 (>30kg) |
| **Bulky Delivery (5DD)** | 대형 화물 배송 (5일) | SIZE_SELECTION | |
| **Self Collect** | 셀프 픽업 (Shopee 픽업지점) | FIXED_DEFAULT_PRICE | 셀러가 픽업 박스에 입고 |
| **J&T Express** | J&T 익스프레스 | SIZE_INPUT | |
| **Ninja Van** | 닌자밴 | SIZE_INPUT | |
| **Pre-Order** | 프리오더 (DTS 7~30일) | SIZE_SELECTION | `is_pre_order=true` + `days_to_ship` |
| **SLS Cross-Border (CB)** | Shopee Logistics Service - 해외 셀러용 | FIXED_DEFAULT_PRICE | `support_cross_border=true` 채널 |

### 1-2. 🇲🇾 말레이시아 (MY)

| 채널 영문명 | 한글 해설 | 비고 |
|---|---|---|
| **Standard Delivery** | 표준 배송 (Pos Laju + Shopee Express) | 기본 채널 |
| **Bulky Delivery** | 대형 화물 (가구/가전) | |
| **Pos Laju** | 포스라주 (말레이시아 우편) | |
| **J&T Express** | J&T 익스프레스 | |
| **Ninja Van** | 닌자밴 | |
| **Self Collect** | 셀프 픽업 | |
| **Cash on Delivery (COD)** | 착불 결제 (CB는 미지원) | |
| **SLS-MY (CB)** | 해외 셀러 통합 배송 | |

### 1-3. 🇹🇭 태국 (TH)

| 채널 영문명 | 한글 해설 | 비고 |
|---|---|---|
| **Shopee Express Standard** | Shopee 익스프레스 표준 | 기본 채널 (비용 최적) |
| **Shopee Express Saver** | Shopee 익스프레스 알뜰 | 저단가 |
| **Shopee Express Instant** | Shopee 익스프레스 당일/즉시 (방콕권) | `service_type_identifier=instant` |
| **Kerry Express** | 케리 익스프레스 | |
| **Flash Express** | 플래시 익스프레스 | |
| **J&T Express** | J&T 익스프레스 | |
| **Thailand Post EMS** | 태국우체국 EMS | |
| **Self Collect (Pickup)** | 셀프 픽업 | |
| **SLS-TH (CB)** | 크로스보더 통합 배송 | |

### 1-4. 🇻🇳 베트남 (VN)

| 채널 영문명 | 한글 해설 | 비고 |
|---|---|---|
| **Shopee Express Standard** | Shopee 익스프레스 표준 | |
| **Shopee Express Instant** | 당일배송 (호치민/하노이) | |
| **Shopee Express Saver** | 알뜰 배송 | |
| **Giao Hàng Nhanh (GHN)** | GHN (속달) | |
| **Giao Hàng Tiết Kiệm (GHTK)** | GHTK (절약 배송) | |
| **Vietnam Post (VNPost)** | 베트남 우체국 | EMS / Tiet Kiem 두 종류 |
| **J&T Express VN** | J&T 익스프레스 | |
| **Ninja Van VN** | 닌자밴 | |
| **SLS-VN (CB)** | 크로스보더 통합 | |

### 1-5. 🇵🇭 필리핀 (PH)

| 채널 영문명 | 한글 해설 | 비고 |
|---|---|---|
| **Standard Local** | 표준 로컬 배송 (마스크 채널) | mask_channel |
| **Standard Local - J&T Express** | J&T 풀필먼트 | mask_channel_id=4000 |
| **Standard Local - Flash Express** | Flash 풀필먼트 | |
| **Standard Local - Ninja Van** | 닌자밴 풀필먼트 | |
| **Sulit Local** | 절약형 로컬 (저단가) | |
| **Bulky Cargo - J&T Cargo** | 대형 화물 (J&T Cargo) | |
| **Bulky Cargo - Flash Cargo** | 대형 화물 (Flash) | |
| **Shopee Self Pick-up** | Shopee 셀프 픽업 | |
| **YTO Express** | YTO 익스프레스 (Sulit 산하) | |
| **SLS-PH (CB)** | 크로스보더 통합 | |

### 1-6. 🇮🇩 인도네시아 (ID)

| 채널 영문명 | 한글 해설 | 비고 |
|---|---|---|
| **Reguler** | 일반 배송 | |
| **Hemat** | 알뜰 배송 (저단가) | |
| **Kargo** | 대형 화물 | |
| **Sameday** | 당일 배송 (자카르타권) | |
| **Instant** | 즉시 배송 (Grab/Gojek) | |
| **JNE Reguler / JNE OKE / JNE YES** | JNE 표준/저가/익일 | |
| **J&T Express** | J&T | |
| **SiCepat REG / SiCepat BEST** | SiCepat 표준/익일 | |
| **AnterAja** | 안테르아자 | |
| **Pos Indonesia** | 인도네시아 우체국 | |
| **GoSend / GrabExpress** | 고센드/그랩익스프레스 (Instant) | |
| **SLS-ID (CB)** | 크로스보더 통합 | |

### 1-7. 🇧🇷 브라질 (BR)

| 채널 영문명 | 한글 해설 | 비고 |
|---|---|---|
| **Shopee Envios** | Shopee 자체 풀필먼트 | 가장 저렴, **거의 모든 BR 셀러 기본** |
| **Correios PAC** | 브라질 우체국 PAC (저가/느림) | |
| **Correios SEDEX** | 브라질 우체국 SEDEX (속달) | |
| **Loggi** | Loggi 풀필먼트 | |
| **JadLog** | JadLog 풀필먼트 | |
| **Shopee Xpress BR** | Shopee 익스프레스 | |
| **SLS-BR (CB)** | 크로스보더 통합 (CN/KR/SG 셀러용) | |

### 1-8. 🇲🇽 멕시코 (MX)

| 채널 영문명 | 한글 해설 | 비고 |
|---|---|---|
| **Shopee Xpress** | Shopee 자체 풀필먼트 | 기본 |
| **Estafeta** | 에스타페타 | |
| **Paquetexpress** | 파케테익스프레스 | |
| **DHL Mexico** | DHL | |
| **SLS-MX (CB)** | 크로스보더 통합 | |

### 1-9. 🇹🇼 대만 (TW)

| 채널 영문명 | 한글 해설 | 비고 |
|---|---|---|
| **7-11 Pickup** | 세븐일레븐 편의점 픽업 | 가장 일반적 |
| **Family Mart Pickup** | 패밀리마트 편의점 픽업 | |
| **Hsinchu Bus** | 신주(新竹) 버스 (일반택배) | |
| **Hsinchu Express** | 신주 익스프레스 | |
| **Black Cat Express** | 흑묘택배 (Yamato 계열) | |
| **Self Pickup** | 매장 직접 픽업 | |
| **SLS-TW (CB)** | 크로스보더 통합 | |

### 1-10. 🇰🇷 한국 / 🇨🇳 중국 / 🇯🇵 일본 (CB 셀러용)

CB(Cross Border) 셀러는 위 마켓별 채널 중 `support_cross_border=true`인 채널만 사용합니다.  
대표적으로 다음과 같은 SLS 통합 채널을 통해 발송합니다.

| 채널 영문명 | 한글 해설 |
|---|---|
| **SLS Cross-Border Standard** | SLS 표준 (선편/Air 혼합, 대부분의 마켓 지원) |
| **SLS Cross-Border Economy** | SLS 이코노미 (저단가, 느림) |
| **SLS Cross-Border SEDEX (BR)** | BR 전용 빠른 통관 채널 |

---

## 2. fee_type별 운임 처리 규칙

| fee_type | 운임 결정 주체 | 셀러 입력값 | logistic_info 필수 필드 |
|---|---|---|---|
| `SIZE_SELECTION` | 셀러가 사이즈 선택 (S/M/L) | `size_id` | logistic_id, enabled, **size_id** |
| `SIZE_INPUT` | 셀러가 무게/치수 입력하면 자동 계산 | dimension, weight | logistic_id, enabled |
| `FIXED_DEFAULT_PRICE` | Shopee가 고정 운임 설정 | 없음 | logistic_id, enabled |
| `CUSTOM_PRICE` | 셀러가 운임 직접 입력 | `shipping_fee` | logistic_id, enabled, **shipping_fee** |

> 우리 업로더는 현재 `logistic_id + enabled`만 전송하므로 `SIZE_SELECTION` / `CUSTOM_PRICE` 채널은 **자동 OFF로 처리될 수 있음**.  
> 따라서 SG 5DD 같은 SIZE_SELECTION 채널은 size_id 미지정 시 OFF가 정상 동작입니다.

---

## 3. 우리 시스템 적용 정책

### 3-1. 채널 ON/OFF 토글 (실시간 샵 설정 변경)
사용자가 `shopee-upload.html` → "업로드 설정" → "배송 채널 ON/OFF" 패널에서 마켓별로 토글합니다.  
**토글 시 동작:** `POST /api/shopee/logistics-channel-toggle` → 백엔드가 `v2.logistics.update_channel` 호출 → **샵의 실제 설정이 즉시 변경**됩니다 (Seller Center와 동기화).

요청 예:
```json
POST /api/shopee/logistics-channel-toggle
{ "shop_id": 1684901122, "market": "SG", "logistics_channel_id": 80012, "enabled": true }
```

### 3-2. 활성화 실패 → Seller Center 자동 안내
일부 채널은 API만으로 활성화 불가하며, 셀러센터 UI에서 사전 등록/검증이 필요합니다. 우리 시스템은 update_channel 응답의 에러를 분류해 사용자에게 Seller Center 링크를 제공합니다.

| 에러 메시지(영문) | 코드 | 우리 시스템 매핑 메시지 | 액션 |
|---|---|---|---|
| `whitelist / exclusive / serviceable validation` | `NEEDS_REGISTRATION` | "Seller Center에서 신청/검증 필요" | 셀러센터로 이동 |
| `address miss long lat` / `require pickup address` | `NEEDS_PICKUP_ADDRESS` | "픽업 주소 등록 먼저" | 셀러센터 주소 페이지로 이동 |
| `masked channel` | `MASKED_CHANNEL` | "마스킹 채널 — 부모 채널을 활성화" | 안내만 |
| `force enabled` | `FORCE_ENABLED` | "강제 활성 — 비활성화 불가" | 토글 비활성 |
| `compulsory_channel_rule` / `minimum_activation_rule` | `COMPULSORY_RULE` | "최소 1개 종속 채널 먼저 활성" | 셀러센터로 이동 |
| `dependent_block_rule` | `DEPENDENT_BLOCK` | "종속 채널 먼저 비활성화 필요" | 셀러센터로 이동 |
| `not allowed to update channel` / `error_permission` | `NO_PERMISSION` | "권한 부족 / Seller Center 잠금" | 셀러센터로 이동 |

마켓별 Seller Center 배송 설정 URL:
```
SG: https://seller.shopee.sg/portal/settings/shop/shipping
MY: https://seller.shopee.com.my/portal/settings/shop/shipping
TH: https://seller.shopee.co.th/portal/settings/shop/shipping
VN: https://banhang.shopee.vn/portal/settings/shop/shipping
ID: https://seller.shopee.co.id/portal/settings/shop/shipping
PH: https://seller.shopee.ph/portal/settings/shop/shipping
BR: https://seller.shopee.com.br/portal/settings/shop/shipping
MX: https://seller.shopee.com.mx/portal/settings/shop/shipping
TW: https://seller.shopee.tw/portal/settings/shop/shipping
CO: https://seller.shopee.com.co/portal/settings/shop/shipping
CL: https://seller.shopee.cl/portal/settings/shop/shipping
```

### 3-3. 업로드 시 적용 규칙 (backend)
1. 마켓별 `get_channel_list`로 채널 동적 조회
2. `enabled=true && !force_disable` 채널만 logistic_info에 포함
3. fee_type별 필수값(size_id / shipping_fee) 자동 보정
4. 채널이 0개면 업로드 실패 처리 (Seller Center 링크 안내)

### 3-4. 향후 확장
- size_id 자동 매핑 (가격/무게 기반 S/M/L 추정) → `SIZE_SELECTION` 채널 강제 활성
- `get_dts_limit` 호출로 카테고리별 days_to_ship 자동 보정
- `get_pause_status`로 일시정지된 채널 자동 제외

---

## 4. 참고 링크

- [v2.logistics.get_channel_list](https://open.shopee.com/documents/v2/v2.logistics.get_channel_list?module=95&type=1)
- [v2.logistics.update_channel](https://open.shopee.com/documents/v2/v2.logistics.update_channel?module=95&type=1)
- [v2.logistics.get_pause_status](https://open.shopee.com/documents/v2/v2.logistics.get_pause_status?module=95&type=1)
- [v2.product.add_item](https://open.shopee.com/documents/v2/v2.product.add_item?module=89&type=1)
- [v2.product.update_item](https://open.shopee.com/documents/v2/v2.product.update_item?module=89&type=1)
- [Seller Education Hub - Singapore](https://seller.shopee.sg/edu)
- [Seller Education Hub - Brazil](https://seller.shopee.com.br/edu)