# API 자주 묻는 질문
### 0. API 공통 / 일반
Q. API 응답값이 None인 경우 성공/실패 확인 방법
A. 문서상 Response Body가 None으로 표기되어 있더라도, 실제 응답에는 `resultType`이 반드시 포함됩니다. 이 값이 `SUCCESS`인지 `FAIL`인지로 성공 여부를 판단하시면 됩니다.
Q. String 파라미터의 최대 길이
**A.** 필드마다 다르지만 대부분 **255자** 이내입니다. 단, 상품 상세설명(`description`)과 같은 필드는 **1500자**까지 가능합니다.
Q. clientId & clientSecret 발급 절차
**A.** 토스쇼핑 파트너 시스템 계정 발급 후, 토스 쇼핑 API 서버 및 테스트앱 접근 가이드를 통해 발급받으실 수 있습니다.
***
### 1. 상품 관리
Q. 상품 등록/수정 방식 (단건 vs 다건)
**A.** **단건 등록 API** 사용을 권장합니다.
* 다건 등록은 추후 지원 중단(Deprecate) 검토 중입니다.
* **검수:** 단건 등록 시에도 자동으로 검수 요청 프로세스가 동작합니다.
Q. 가격(salePrice) 및 재고 설정
**A.**
* **할인 적용:** `salePrice`에는 **할인이 적용된 최종 판매가**를 입력해야 합니다. (예: 정상가 10,000원, 2,000원 할인 → `salePrice`: 8,000원)
* **옵션:** `options`와 `stocks.options`는 동일한 옵션값을 의미합니다.
Q. 상품 식별자 매핑 (stocks.id)
**A.** `stocks.id`는 `stocks.itemId`와 1:1 관계이며, 옵션의 유니크한 키로 사용 가능합니다.
* **주의:** 옵션 ID가 별도로 없는데 기존 옵션을 추가/제거해서 전송하면 **새로운 옵션 ID가 발급**됩니다.
Q. 판매 중지 / 재개 / 숨김 처리 API
**A.** 별도의 상태 변경 API를 사용합니다.
* **판매 중지:** 재고 수정 API를 통해 재고를 0으로 변경.
* **숨김 처리:** `상품 정보 노출 상태 숨기기로 변경` API 사용 (앱 미노출).
* **삭제 확인:** 삭제된 상품의 정보는 조회 불가.
Q. 배송비 템플릿과 정책의 관계 (deliveryPolicy)
**A.** **배송비 묶음 그룹과 배송비 정책은 서로 결합되어 있지 않습니다.**
* **템플릿 역할:** 배송비 템플릿(`isMain=true` 등)은 상품 등록 시 정책을 **Pre-fill(미리 채워주기)** 해주는 역할만 합니다.
* **적용:** 템플릿 유무와 관계없이, 상품 등록 시 입력한 개별 `deliveryPolicy`가 최종적으로 적용됩니다.
Q. 묶음 배송(deliveryLocationId) 및 조건부 무료 로직
**A.**
* **ID Null:** 묶음 배송 불가 (개별 배송).
* **ID 동일:** 동일한 `deliveryLocationId`를 가진 상품끼리 묶음 배송 가능.
* **배송비 부과 기준:** 같은 그룹 내 상품 중 **가장 낮은 배송비**를 보장하는 정책 하나가 적용됩니다.
* **조건부 무료(`minimumPurchasePrice`):** 동일한 묶음 배송 그룹에 속한 상품들의 **판매가 합계**를 기준으로 충족 여부를 판단합니다.
Q. 제주/도서산간 지역 설정
**A.** 제주와 도서산간의 배송 가능 여부를 **각각 분리하여 설정할 수 없습니다.** (통합 설정만 가능)
***
### 2. 주문 및 배송
Q. 주문 식별자 (Unique Key)
**A.**
* **주문:** `orderId`
* **주문 상품:** `orderProductId` (주문상품번호). 각 품목(Item)에 대한 유니크 키입니다.
Q. 주문/배송 정보 상세
**A.**
* **무통장 입금:** 미지원.
* **제주/도서산간 여부:** 제주는 6으로 시작하는 우편번호, 도서산간은 토스쇼핑 자체 우편번호 목록 기준.
* **송장 유효성:** API 단계에서 가송장 여부 등 유효성은 체크하지 않습니다.
* **교환/반품 송장:** 교환/반품 송장 등록 기능은 현재 지원하지 않습니다.
Q. 주문 상태 변경 (취소/거부)
**A.** '판매자 취소', '취소 거부', '취소 승인' 등은 API로 제공되지 않으며 토스 셀러 어드민에서 처리해야 합니다.
Q. 배송비의 유형과 정산
**A.**
1. **배송비 (초도배송비):** 최초 주문 시 부과.
2. **반품/교환 배송비:** 고객 귀책 시 발생.
3. **도서산간 추가 배송비:** 지역 특성에 따라 추가 부과.
***
### 3. 클레임 (취소/교환/반품)
Q. 부분 취소/교환/반품 가능 여부
**A.**
* **가능:** 주문 내 상품 A, B 중 A만 취소.
* **불가능:** 상품 A를 2개 샀을 때, **1개만 부분 취소(수량 분할)** 하는 것은 불가능.
Q. 철회 기능
**A.** 고객은 셀러 승인 전까지 요청을 철회할 수 있습니다.
Q. [상세] 고객 귀책 반품/교환 시 비용 청구 공식
**A.** 제주/도서산간 추가 비용은 아래 공식대로 합산되어 고객에게 결제 요청됩니다.
**1. 반품 시 (`refundOneWayDeliveryFee`)**
* 일반: `반품배송비(편도)`
* 제주: `반품배송비(편도)` + `제주 추가비(편도)`
* 도서산간: `반품배송비(편도)` + `도서산간 추가비(편도)`
**2. 교환 시 (`exchangeRoundTripDeliveryFee`)**
* 일반: `교환배송비(왕복)`
* 제주: `교환배송비(왕복)` + **`제주 추가비(편도) * 2`**
* 도서산간: `교환배송비(왕복)` + **`도서산간 추가비(편도) * 2`**
Q. [상세] 고객 귀책 반품 시 '초도배송비' 차감 로직
**A.** 반품 배송비 외에 **초도배송비**가 환불금에서 차감되는 경우는 다음 두 가지입니다.
1. **조건부 무료 깨짐:** (부분)반품으로 인해 무료배송 조건이 미충족 된 경우.
2. **전체 반품:** 무료배송으로 받은 건을 전체 반품한 경우.
* *참고: 판매자 귀책 시에는 배송비 추가 결제나 차감이 없습니다.*
***
### 4. 정산 및 데이터 대사
Q. 정산 데이터 구조
* **데이터 분리:** 상품 정산 내역과 배송비 정산 내역은 **별도의 Row**로 나뉘어 들어옵니다.
* **배송비 매핑:** 배송비 객체에도 `orderId`가 있어 원주문과 연결 가능합니다.
* **상태값:** `CONFIRMED_ORDER` (구매확정), `CANCELED_PAYMENT` (결제취소/반품).
Q. 정산 지급 일정 (D+2 영업일)
지급일(`payoutDate`) 당일, 배치 작업 완료 후 API 조회가 가능합니다.
| **구매확정 요일** | **정산 지급(조회) 요일** |
| ----------- | ---------------- |
| 월요일 | **수요일** |
| 화요일 | **목요일** |
| 수요일 | **금요일** |
| 목요일 | **월요일** |
| 금/토/일요일 | **화요일** |
Q. 세금계산서 품목 및 결제수단 매핑
API에서 제공하는 정보를 통해 아래와 같이 4개 품목으로 매핑합니다.
| **세금계산서 품목 (Group)** | **매핑할 실제 결제수단 (API 값)** |
| -------------------- | ----------------------- |
| **카드** | 신용카드, 체크카드 |
| **토스머니** | 토스머니, 토스페이머니, 계좌이체 |
***
### 5. 정산 산식 모음
Q. 주요 금액 필드 산식
| **항목** | **API 필드명** | **계산 산식 (Formula)** | **비고** |
| ---------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **정산 기준금** | `orderProductPrice` | **판매가 × 수량** | |
| `stockPrice * quantity` | **\[변경됨]** 쿠폰 차감 전 순수 판매가 총액 | | |
| **수수료 기준금** | `feeBaseAmount` | **정산 기준금 - 셀러쿠폰** | |
| `orderProductPrice - shoppingDiscountMerchant` | **\[신규]** 수수료 부과 기준액 | | |
| **유저 결제액** | `orderProductPaidAmount` | `orderProductPrice` - `TotalDiscount` | 고객 실 결제 금액 |
| **실 지급액** | `settlementAmount` | `feeBaseAmount` - `TotalFees` | 최종 입금액 |
| **상품 수수료율** | **`productFeeRate`** | **`productFee`(상품 수수료) / `amountForFee`** | *(참고: 이 공식으로 수수료율이 역산되어 계산됩니다)* |
| **정산금액** | **`settlementAmount`** | **(주문금액) - (모든 수수료 및 부가세) - (셀러부담쿠폰)** | • 상세: `주문금액(판매가+배송비)` - `결제수수료` - `결제VAT` - `상품수수료` - `상품VAT` - `셀러부담쿠폰할인액` |
| **프로모션 할인 금액** | `shoppingDiscount` | `shoppingDiscountToss`(토스 부담 쿠폰 할인) + `shoppingDiscountMerchant`(셀러 부담 쿠폰 할인) + `extraDiscout`(주문 상품별 안분된 추가 할인 금액) | |
Q. 할인 항목 매핑 (토스쇼핑파트너스 어드민과 비교)
* `shoppingDiscountMerchant` = 어드민 **'쿠폰 할인 부담금'**
* `shoppingDiscountToss` = 토스 부담 쿠폰 + 추가할인(`extraDiscount`)
Q. 결제 상태별 상세 산식
**1. PAY (결제 건)**
* `orderProductPaidAmount` = `orderProductPrice` - `shoppingDiscount` - `tossPayDiscount` - `tossPayPoint`
* `settlementAmount` = `feeBaseAmount` - (`수수료 합계`)
**2. REFUND (환불 건)**
* `orderProductPaidAmount` = `orderProductPrice` + `shoppingDiscount` + `tossPayDiscount` + `tossPayPoint`
* `settlementAmount` = `feeBaseAmount` + (`수수료 환급`)