개발 FAQ·변경 이력

조회

한 주문에 다른 셀러의 상품이 섞여 있으면 어떻게 보이나요?

응답에는 요청한 키의 셀러 상품만 담겨요. 주문 헤더의 금액 필드(seller_로 시작하는 값)도 그 셀러 상품만 합산한 값이에요. 다만 order_status(주문 전체 진행 상태)는 다른 셀러 상품의 상태까지 반영해 계산되니, 처리 판단에는 각 상품의 item_status를 써 주세요.

결제 전 주문도 조회되나요?

조회되지 않아요. 결제가 완료된 주문만 노출돼요.

주문자·수취인 정보가 null로 와요.

회원이 탈퇴해 개인정보가 파기된 주문이에요. 주문번호·상품·금액·상태는 그대로 조회되지만 이름·연락처·주소는 복원되지 않아요. 배송이 필요한 시점의 주문에서는 발생하지 않아요.

비밀글로 등록된 문의도 볼 수 있나요?

자기 상품에 달린 문의라면 원문을 볼 수 있어요(파트너센터와 같은 기준). 다만 반출 기록이 문의 단위로 남으니 필요 이상으로 반복 수집하지 말아 주세요.

클레임·환불

환불 요청은 어디서 조회하나요?

주문 API가 아니라 클레임 API예요. 취소(cancel)·반품(return)·교환(exchange)이 모두 클레임 축에 있고, 신청 시각 기준 조회는 requested_at_gte/requested_at_lte를 써요.

환불은 어떻게 실행되나요?

별도의 환불 실행 호출은 없어요. 다만 환불이 시작되는 시점이 클레임 종류마다 달라요 — "승인하면 자동"은 취소에만 해당해요. 진행은 클레임 상세의 status로 확인하면 돼요.

타입	환불이 시작되는 시점	비고
취소 (cancel)	approve 승인 시	승인 즉시 refund_processing → completed
반품 (return)	inspect 검수 통과 시(result=pass)	승인(approve)은 approved까지만 옮겨요 — 수거는 pickup(수거 송장 등록)을 따로 호출해야 시작돼요(승인 뒤 반드시 pickup). 수거완료 후 일정 기간 검수가 없으면 검수 통과로 간주해 환불되기도 해요
교환 (exchange)	검수 통과 시 재출고(reshipping)로 가고, 돌려줄 차액이 있을 때만 그 시점에 차액 환불	refund_processing을 거치지 않아요. 차액은 price_difference로 확인해요

자세한 내용은 클레임·문의 처리하기의 환불 진행 절에 있어요.

refund_processing이 오래 머물러 있어요.

가상계좌·무통장 결제 건은 고객이 환불받을 계좌를 앱에서 입력해야 이체가 진행돼요. PG 환불이 실패한 건은 뷰리티가 확인해 수동으로 처리해요. 두 경우 모두 연동사가 따로 할 일은 없어요.

지금 이 클레임에 무엇을 할 수 있는지 어떻게 아나요?

클레임 조회 응답의 available_actions 배열이 알려줘요. 상태 문자열을 보고 직접 추론하지 마세요 — 정책이 바뀌면 그 추론이 조용히 틀려요.

파트너센터에서 이미 처리한 클레임에 API를 호출하면요?

같은 처리를 같은 값으로 보냈다면 200으로 응답해요 — 클레임이 이미 다음 단계로 갔거나 종결됐어도 그 처리가 실제로 수행된 건이면 200이에요. 다른 값으로 보냈거나 수행된 적 없는 처리를 보냈다면 409 IDEMPOTENCY_UNRESOLVED예요. 처리 직전에 상세를 다시 조회해 available_actions를 확인하는 방식을 권해요.

종결된 클레임에 처리를 호출하면 무조건 409인가요?

아니에요. 판정 기준은 상태가 아니라 "그 처리가 실제로 수행됐는가"예요. 예를 들어 환불까지 끝난(completed) 반품에 approve를 다시 보내면 200이고, 검수 불합격으로 rejected가 된 건에 reject를 보내면 409예요(그 건은 reject 처리를 거친 적이 없어요). 세 갈래 판정은 클레임·문의 처리하기에 정리돼 있어요.

주문 처리

이미 발송 처리한 주문에 다른 송장번호를 등록하려면요?

API로는 되지 않아요(409 SHIPMENT_STATE_CONFLICT). 송장 정정은 셀러가 파트너센터에서 처리해요. 같은 송장 판정은 carrier_name·tracking_no·logistics_company 세 값 전부가 기준이라, 선택 항목인 logistics_company를 재전송 때 빠뜨려도 409가 나요.

발주확인을 건너뛰고 바로 송장을 등록해도 되나요?

돼요. paid 상태에서 바로 송장을 등록하면 발주확인 단계는 건너뛴 것으로 처리돼요. 그래서 라인이 preparing을 거치지 않고 paid → shipping으로 넘어갈 수 있으니, preparing 전환을 기다리는 로직을 두지 마세요.

택배사명은 어떻게 보내나요?

아래 5종의 표기를 그대로 보내요. 목록 밖 값은 422 SHIPMENT_CARRIER_NOT_ALLOWED예요.
CJ대한통운 · 우체국택배 · 한진택배 · 롯데택배 · 로젠택배

일괄 송장 등록에서 일부만 실패하면요?

HTTP는 200이고 본문 data.failed[]에 실패한 주문과 error_code가 담겨요. 성공분은 data.succeeded[]예요. 전건 실패도 200이니 HTTP 상태가 아니라 본문으로 판정해 주세요.

구매확정도 API로 할 수 있나요?

할 수 없어요. 고객이 직접 확정하거나 배송완료 14일 후 자동 확정돼요. 확정 여부는 상품의 item_status가 confirmed인지로 확인해요.

문의 답변

답변을 등록했는데 수정하고 싶어요.

API로는 덮어쓸 수 없어요(409 QNA_ALREADY_ANSWERED). 같은 내용을 다시 보내는 건 성공으로 처리되고, 내용 수정은 파트너센터에서만 할 수 있어요.

변경 이력

버전	날짜	내용
v1.0	2026-08-27	오픈 API 1차 공개 — 주문·클레임·문의 조회, 주문 처리(발주확인·송장 등록·배송완료), 클레임 처리(승인·거부·수거·검수·재출고), 문의 답변

더 궁금한 점이 있다면

연동 중 막히는 부분은 판매자 고객센터로 문의해 주세요. 문의 시 사용한 엔드포인트·요청 시각·응답의 error_code를 함께 남겨 주시면 확인이 훨씬 빨라요.