자주 묻는 질문

Q. API마다 인증 방식이 다른가요? 토큰을 발급받아야 하나요?

A. 계정 등록/해제 API만 OAuth2 Access Token + API Key가 필요하고, 그 외 모든 API는 고정 API Key + IP ACL만 사용해요

Q. 운영 API Key는 언제 받나요?

A. 개발 Key와 운영 Key는 별도로 발급돼요. 운영 Key는 토스쇼핑 API가 운영 배포된 뒤 담당자가 전달해요. 배포 직전에 급하게 요청하지 않도록, 운영 Key 교환 시점을 연동 일정에 미리 넣어 담당자와 협의해주세요.

Q. IP 화이트리스트는 어떻게 등록하나요? 403이 계속 떨어져요.

A. 풀필먼트가 토스쇼핑을 호출할 때 쓰는 공인 outbound IP를 담당자에게 전달해 등록해야 해요. 개발용·운영용 IP를 따로 등록하고, 통신은 HTTPS(443) 기준이에요. 등록되지 않은 IP에서의 호출은 403 FORBIDDEN을 받아요. 인프라 IP가 바뀌면 즉시 통보해주세요.

Q. 취소 완료 API에 반품 건이 같이 나와요. 어떻게 구분하나요?

A. 반품이 완료되면 주문상품 상태가 취소와 같은 결제취소(CANCELED_PAYMENT)로 기록돼서, cancel-completed 응답에 반품 건이 함께 잡혀요. 출고 전에 취소된 건은 순수 취소, 출고/배송(DELIVERING·DELIVERED)까지 진행됐다가 되돌아온 건은 반품으로 구분해주세요. 전용 구분 필드 제공 여부는 담당자 확인이 필요해요.

Q. SKU 등록 전에 재고 동기화가 먼저 도착하면 어떻게 처리하나요?

A. 호출 순서를 ① PUT /skus(SKU) → ② PUT /skus/quantity(재고) 로 보장해주세요. 재고가 먼저 도착하는 구조가 불가피하면, SKU 등록 직후 같은 skuKey로 재고를 한 번 더 보내 정합성을 맞추면 돼요. 일단위 SFTP 전체 FEED가 추가로 정합성을 보정해줘요. 매핑 상태는 POST /skus/mappings로 확인할 수 있어요.

Q. 재고는 증분(delta)으로 보내나요, 절대값으로 보내나요?

A. 항상 현재 재고 절대값을 보내요. 증감분이 아니에요. 100개 중 2개가 팔렸으면 98을 보내요. 계약 초기 등록도, 운영 중 변경도 모두 같은 방식(현재 절대값)이에요.

Q. Boolean 필드는 어떤 형식으로 오나요?

A. JSON true/false(불리언 타입)로 내려와요. 문자열 "true"가 아니에요. 파싱 시 불리언으로 처리해주세요.

Q. fulfillmentCenterKey에는 어떤 값을 넣나요?

A. 풀필먼트 WMS의 물류센터 코드를 넣고, fulfillmentCenterName에는 그 코드의 WMS 명칭을 넣어주세요. 한 SKU가 여러 센터에 있으면 skuKey + fulfillmentAccountKey + fulfillmentCenterKey 조합으로 센터별 재고를 각각 보내요.

이 문서로 해결되지 않는 부분은 토스쇼핑 파트너 담당자에게 문의해주세요. 문의 시 **요청 URL, 요청/응답 원문, X-Toss-Shopping-Connect-Tx-Id**를 함께 전달하면 빠르게 확인할 수 있어요.