[공통] 반품 내역 · 반품 상세

화면 정보

Screen ID	Screen Title	Screen Path
ORD-RTN-LIST-01	반품 내역	`/mypage/order/return`
ORD-RTN-DETAIL-01	반품 상세	`/mypage/order/return/{orderNumber}`

개요

반품/교환 요청 내역 목록과 반품 상세 화면. 교환(EXCHANGE)은 어드민에서만 처리되므로 목록에서 교환 건 클릭 시 별도 상세 화면 없이 안내 처리한다.

ORD-RTN-LIST-01 — 반품 내역

화면 구성

반품 내역 (ORD-RTN-LIST-01)
├── 헤더                    ← 뒤로가기 / "반품 내역" / 검색 버튼
├── 탭 영역                 ← 전체 / 온라인 매장 / 오프라인 매장 / 라플 매장
├── 반품/교환 내역 카드 목록 ← 무한 스크롤, 최신순
└── 빈 상태 / 오류 상태

탭별 필터 기준

탭	필터 기준
전체 매장	반품/교환 요청 전체 조회
온라인 매장	`isOffline = false`
오프라인 매장	`isOffline = true`
라플 매장	라플 유형 주문

store 코드 값 및 탭 포함 여부는 스토어별 문서에서 정의한다.

반품/교환 상태 표시

requestType	requestStatus	표시 문구
`RETURN`	`PENDING`	반품 신청
`RETURN`	`REFUNDED`	반품 완료
`RETURN`	`CANCELED`	반품 취소
`EXCHANGE`	`PENDING`	교환 신청
`EXCHANGE`	`REFUNDED`	교환 완료
`EXCHANGE`	`CANCELED`	교환 취소

상품 상태(productStatus) 표시

코드	표시 문구
`IN_RETURN`	반품 진행중
`RETURNED`	반품 완료
`CONFIRMED`	구매 확정

매장 정보 표시 기준

조건	표시 기준
`isOffline = false`	스토어별 온라인 매장명
`isOffline = true`	`offlineStoreName`
라플 유형	라플 스토어

온라인 매장 표시 문구는 스토어별 문서에서 정의한다.

배송 정보 표시 구분

구분	필드
원본 배송 정보	`shippingCompany`, `shippingNumber`
반품/교환 배송 정보	`latestRequestShippingCompany`, `latestRequestShippingNumber`

주문번호 클릭 동작

requestType	이동 대상
`RETURN`	반품 상세(ORD-RTN-DETAIL-01)로 이동
`EXCHANGE`	교환은 어드민 처리 전용 — 고객센터 문의 안내

상품 가시성 처리

조건	표시
`visible == false`	상품명 뒤에 “(판매중단)” 표시
상품 클릭 시	“현재 판매하지 않는 상품입니다” 안내

검색

항목	기준
검색 UI	검색 버튼 클릭 → 상단 노출 + 배경 dimmed 처리
검색 대상	주문번호 (`orderNumber`) · 상품명 (`productName`)
검색 방식	부분 일치, `onSearch` 콜백으로 즉시 실행
닫기	배경 터치 또는 X 클릭 (결과 유지)
탭 전환 시	검색어 조건 유지

ORD-RTN-DETAIL-01 — 반품 상세

화면 구성

반품 상세 (ORD-RTN-DETAIL-01)
├── 헤더                    ← 뒤로가기 / "반품 신청 내역"
├── 기본 정보               ← 매장명 / 주문번호 / 반품 요청번호 / 주문일 / 반품 신청일
├── 반품 상품 정보          ← 이미지 / 브랜드 / 상품명 / 사이즈 / 수량 / 반품 사유
│   └── 반품 상태 / 수거 송장 정보
├── 수거지 정보             ← 배송 정보 변경 버튼 (조건부)
├── 환불 정보               ← 반품 배송비 / 환불 예정 금액 / 환불 상태
└── 반품 취소 버튼          ← 하단 고정 (조건부)

반품 상태 표시

상태 코드	표시 문구
`REQUESTED`	반품 신청됨
`PICKUP_READY`	수거 준비중
`PICKUP_COMPLETED`	수거 완료
`REFUNDED`	환불 완료
`CANCELED`	반품 취소

배송 정보 변경 버튼

항목	기준
표시 조건	수거 업체 방문 전 상태 (수거 완료 전)
클릭 동작	확인 팝업 → “배송 정보 변경 시 수거 받는 분도 함께 변경됩니다.”
변경 불가	수거 완료 / 환불 완료 / 주문 확정 → “수거지 변경이 불가능한 상태입니다”

배송지 변경 프로세스

“배송 정보 변경” 클릭
확인 팝업 표시
변경 클릭 → 배송지 목록 조회 → 모달 표시
선택/입력 완료 → 저장
성공 → “수거지 정보가 변경되었습니다” 토스트

반품 취소 버튼

항목	기준
표시 조건	수거 전 또는 수거 진행 중 미처리 상태
비표시 조건	수거 완료 / 환불 완료 / 이미 취소 상태
클릭 동작	“반품 요청을 취소하시겠습니까?” 팝업 → 확인 → API 호출
성공 시	화면 상태 “반품 취소”로 업데이트

환불 정보 표시

항목	필드
반품 배송비	`requestDeliveryPrice`
환불 예정 금액	`refundedPrice`
환불 완료일	`refundedAt` (환불 완료 상태일 때만 표시)

수거 송장번호 클릭

택배사 배송조회 페이지 외부 링크로 열기
필드: latestRequestShippingCompany + latestRequestShippingTrackingNumber

API 연동

1. 반품 내역 목록 조회

엔드포인트: GET /v1/orders/histories/return

파라미터	설명
`page`	페이지 번호
`size`	페이지 크기 (기본 20)
`store`	매장 필터 (`WORKSOUT` / `RAFFLE`)
`isOffline`	온라인/오프라인 구분
`keyword`	검색어

응답 필드	활용
`orderNumber`	카드 식별 / 상세 이동 파라미터
`orderedAt`	주문일, `DESC` 정렬 기준
`requestType`	`RETURN` / `EXCHANGE` 구분
`requestStatus`	반품/교환 상태 표시
`products[].productStatus`	상품 상태 표시
`products[].visible`	`false`이면 “(판매중단)”
`products[].latestRequestType`, `latestRequestStatus`	최신 요청 상태

2. 반품 상세 조회

엔드포인트: GET /v1/orders/histories/{orderNumber}

주문 상세와 동일한 엔드포인트. latestRequest == RETURN인 주문 조회.

응답 필드	활용
`products[].latestRequest`	`RETURN` 확인
`products[].latestRequestStatus`	반품 상태 표시
`products[].latestRequestOrderNumber`	반품 요청번호
`products[].latestRequestReason`	반품 사유
`products[].latestRequestShippingCompany`	수거 택배사
`products[].latestRequestShippingTrackingNumber`	수거 송장번호
`orderRequestExtra.requestedAt`	반품 신청일
`orderRequestExtra.refundedPrice`	환불 예정 금액
`orderRequestExtra.requestDeliveryPrice`	반품 배송비
`orderRequestExtra.status`	반품 상태 코드

3. 배송지 변경

목적	엔드포인트
변경 가능 여부 확인	`GET /v1/orders/change/{반품요청번호}/available`
배송지 목록 조회	`GET /v1/users/addresses`
배송지 변경 저장	`POST /v1/orders/requests/{orderNumber}/address`

변경 가능 여부 확인 시 orderNumber는 반품 요청번호(latestRequestOrderNumber) 사용.

{
  "userAddressId": 0,
  "addressName": "집",
  "receiverName": "string",
  "receiverPhone": "string",
  "receiverAddress": "string",
  "receiverDetailAddress": "string",
  "receiverPostcode": "string",
  "shippingRequest": ""
}

4. 아임포트 결제 확인 (반품 배송비 결제 후)

엔드포인트: POST /v1/iamport/payment/confirm

{
  "imp_uid": "imp_123456789",
  "merchant_uid": "20240924180609129_04"
}

모바일 결제 완료 후 /cart/request/success/mobile 경로로 리다이렉트

에러 처리 요약

증상	예상 원인	1차 조치
반품 내역 전체 미로드	API 실패 / 세션 만료	네트워크 → API 응답 → 로그인 상태 확인
특정 탭에서만 미노출	`store` / `isOffline` 필터 불일치	요청 파라미터와 주문 데이터 비교
EXCHANGE 클릭 시 상세 진입	`requestType` 분기 누락	`RETURN`만 상세 이동, `EXCHANGE`는 고객센터 안내
반품 상세 미로드	`orderNumber` 미전달 또는 API 실패	파라미터 및 응답 확인
배송지 변경 버튼 미표시	반품 상태 조건 불충족	수거 완료 전 상태인지 확인
배송지 변경 API 실패	주문번호 대신 반품 요청번호 미사용	`latestRequestOrderNumber` 사용 여부 확인
반품 취소 버튼 미표시	반품 상태 조건 불충족	수거 완료 / 환불 완료 / 취소 상태이면 정상 미표시
아임포트 결제 실패	카드 승인 실패 / 타임아웃	오류 메시지 + 재시도 유도

변경 이력

버전	날짜	변경 내용
v1.0	2026-07-06	최초 작성