반품조회 API

Description

[POST] https://sa2.esmplus.com/claim/v1/sa/Returns

고객이 반품신청한 주문을 조회합니다. 반품요청 / 반품수거완료 / 반품환불보류 / 반품환불완료 / 반품철회 / 직권환불완료 반품 상태별로 조회할 수 있습니다. 직권환불(CS고객센터)을 통한 반품환불건은 주기적으로 호출하여 내부 상태값과 Sync 관리할 수 있습니다.

Request Description

항목	항목명	필수여부	Type	Description
SiteType	사이트 구분	Y	int	1 : 옥션 2 : G마켓
ReturnStatus	반품상태	Y	int	1 : 반품요청 2 : 반품수거완료 3 : 반품환불보류 4 : 반품환불완료 5 : 반품철회 6 : 사이트 직권 환불건(반품완료건 중, 고객센터에서 환불처리한 Case)
Type	조회기준 구분	Y	int	0 : 주문번호 1 : 장바구니 번호 2 : 반품신청일(RequestDate) 3 : 반품완료일(반품 상태가 완료- ApproveDate/철회인 주문건 조회 시-WithdrawDate) 4 : 결제완료일(PayDate)
StartDate	조회기준 시작일	Y	DateTime	7일 이하 범위만 조회 가능
EndDate	조회기준 종료일	Y	DateTime	7일 이하 범위만 조회 가능
PayNo	장바구니 번호(결제번호)		long
OrderNo	주문번호		long
IsGiftOrder	선물하기 주문 구분		string	Y : 선물하기 주문 N : 일반 주문 null : 모든 주문 * 미입력 / skip 시 전체 취소 모두 조회 * G마켓만 구분 조회 가능

JSON
{
  "SiteType": int,
  "ReturnStatus": int,
  "Type": int,
  "StartDate": "2023-10-01",
  "EndDate": "2023-10-02",
  "PayNo": long,
  "OrderNo": long,
  "IsGiftOrder": "string"
}

 

Response Description

항목	항목명	Type	Description
ResultCode	결과코드	int	0 : Success 1: Fail(Error Message참고)
Message	메시지	string
ReturnStatus	반품상태	int	1 : 반품요청 2 : 반품수거완료 3 : 반품환불보류 4 : 반품환불완료 5 : 반품철회 6 : 사이트 직권환불 ※ 반품 수거중일 경우, 반품요청(1번)에 포함 ※ 반품수거중이면서 보류중일 경우, 반품환불보류(3번)에 포함
IsFastRefund	빠른환불여부	boolean	true : 빠른 환불 대상 false : 빠른 환불 대상 아님 * 빠른 환불 주문 대상건인지 여부 * 빠른 환불 주문 대상건이면, 송장 Tracking 또는 수거여부에 따라 바로 환불완료 가능
FastRefundRewardStatus	빠른환불보상상태	int	0 : 상태없음 1 : 보상요청 2 : 보상검토중 3 : 보상완료 4 : 보상불가 5 : 보상요청취소
GoodsStatus	상품상태	int	0 : 알수없음 1 : 포장 개봉미사용 2 : 포장개방사용 3 : 미개봉 * 구매자가 표시한 상품상태 * 현재는 반품 신청 시 선택하는 부분은 없으나 반품 사유 or CS와 협의된 상품 상태 값 내려감
AddReturnShippingFee	추가반품배송비	number	판매자가 반품 보류시 추가 청구한 금액
WhoAddReturnShippingFee	추가반품배송비 지불주체	int	1 : 사이트 부담 2 : 구매자 부담 3 : 판매자 부담
AddReturnShippingFeeWay	추가반품배송비 결제수단	int	1 : 지금결제함(카드결제, 핸드폰결제등) 2 : 환불금 차감 대기 3 : 판매자 직접 결제 4 : 상품에 동봉함 5 : 스마일캐시 결제 6 : 기타
ReturnShippingFee	반품배송비	number	반품신청 시 구매자에게 부과된 금액
ReturnShippingFeeWay	반품배송비 결제수단	int	1 : 지금결제함(카드결제, 핸드폰결제등) 2 : 환불금 차감 대기 3 : 판매자 직접 결제 4 : 상품에 동봉함 5 : 스마일캐시 결제 6 : 기타
WhoReturnShippingFee	반품배송비 지불주체	int	1 : 사이트 부담 2 : 구매자 부담 3 : 판매자 부담 4 : 구매자 부분 부담(G마켓 또는 옥션 지원 쿠폰 사용하고 남은차액 고객이 결제할 경우)
HoldInfo > HoldDate	보류일자	string
HoldInfo > IsHold	보류 여부	boolean	true : 보류설정된 상태 false : 보류설정되지 않은 상태 * 보류 설정된 상태인지 여부
HoldInfo > Reason	보류사유	int	0 : 기타유보사유 2 : 추가반품비청구 (기타반품비) 4 : 반품미입고
HoldInfo > FeeDate	보류 해제일자	date
ShippingInfo > CompleteDate	원배송완료일자	date
ShippingInfo > ShippingFee	최초배송비금액	date
ShippingInfo > WhoShippingFee	최초배송비 지불주체	int	1 : 사이트 부담 2 : 구매자 부담 3 : 판매자 부담
ShippingInfo > DeliveryCompCode	원배송 택배사코드	G마켓: string 옥션: int	택배사코드는 5자리 숫자 (택배사 코드 참고)
ShippingInfo > InvoiceNo	원배송 송장번호	string
PickupInfo > Status	반품수거상태	string	(G마켓 지정 택배)사이트 에서 직접 택배사에 수거지시를 내리는 주문건인지, (판매자 자체배송)판매자가 직접 택배사에 수거지시를 내렸는 지 여부 0 : 없음 1 : 사이트 수거지시 2 : 사이트 수거지시 아님
PickupInfo > CompleteDate	반품수거완료일자	string
PickupInfo > DeliveryCompName	반품수거택배사명	string
PickupInfo > InvoiceNo	반품송장번호	string
PickupInfo > SenderInfo > Name	수령인명/발송인명	string
PickupInfo > SenderInfo > HpNo	수령인/발송인휴대폰번호	string	일반전화번호 고객이 입력했을 경우 일반전화번호도 내려갈 수 있음
PickupInfo > SenderInfo > TelNo	수령인/발송인일반전화번호	string	휴대폰 번호 고객이 입력했을 경우 휴대폰번호도 내려갈 수 있음
PickupInfo > SenderInfo > ZipCode	수거지우편번호	string	5자리/6자리 모두 내려갈 수 있음
PickupInfo > SenderInfo > AddressFront	수거지주소1	string
PickupInfo > SenderInfo > AddressBack	수거지주소2	string	고객이 직접 입력한 수거지주소 고객이 작성하지 않을 경우 안내려갈 수 있음
PickupInfo > SenderInfo > Address	수거지주소1+2	string
PickupInfo > ReceiverInfo > Name	회수인명(판매자정보)	string	판매자가 해당 상품의 반품배송지로 등록한 정보 내려감
PickupInfo > ReceiverInfo > HpNo	회수인휴대폰(판매자정보)	string	판매자가 해당 상품의 반품배송지로 등록한 정보 내려감
PickupInfo > ReceiverInfo > TelNo	회수인전화번호(판매자정보)	string	판매자가 해당 상품의 반품배송지로 등록한 정보 내려감
PickupInfo > ReceiverInfo > ZipCode	회수지우편번호(판매자정보)	string	판매자가 해당 상품의 반품배송지로 등록한 정보 내려감
PickupInfo > ReceiverInfo > AddressFront	회수지주소1(판매자정보)	string	판매자가 해당 상품의 반품배송지로 등록한 정보 내려감
PickupInfo > ReceiverInfo > AddressBack	회수지주소2(판매자정보)	string	판매자가 해당 상품의 반품배송지로 등록한 정보 내려감
PickupInfo > ReceiverInfo > Address	회수지주소1+2(판매자정보)	string	판매자가 해당 상품의 반품배송지로 등록한 정보 내려감
SiteType	사이트구분	string	조회한 조건에 따라 조회한 주문건의 사이트가 내려감 1 : 옥션 2,3 : G마켓
SellerId	판매자ID	string	해당주문건의 판매자ID
PayNo	장바구니번호	int	장바구니번호(결제번호)
GroupNo	묶음배송비정책번호	bigint	묶음배송비정책번호(배송번호)
OrderNo	주문번호	int
GoodsNo	ESM상품번호	string
SiteGoodsNo	사이트상품번호	string	현재 주문 건의 G마켓 or 옥션 상품번호
data > isGiftOrder	선물하기 주문 구분	string	Y : 선물하기 주문 N : 일반 주문
RequestUser	반품신청자	string	반품신청한 주체 0 : 없음 1 : 구매자 2 : 판매자 3 : 고객센터 4 : 기타 5 : 선물수령인 (G마켓 주문만)
ApproveUser	반품처리자	string	반품처리 주체 0 : 없음 1 : 구매자 2 : 판매자 3 : 고객센터 4 : 기타 ※ 옥션의 경우, 교환에서 반품전환 시 환불승인까지 진행되므로 처리자가 판매자로 내려감
Reason	반품사유	string	0 : 판매자 귀책 1 : 구매자 귀책 2 : 기타 (고객센터, CS 에서만 해당 사유 처리 가능)
ReasonCode	반품요청사유코드	int	12월 23일부터 제공 반품/교환요청 시, 고객이 선택한 클레임요청 사유코드 추가 [구매자귀책] 1 : 단순변심 2 : 사이즈/색상 등 옵션 변경 [판매자귀책] 3 : 오배송 4 : 상품미도착 5 : 상품불량 6 : 판매자요청 [기타] 0 : 선택없음
ResonDetail	반품사유직접입력	string	고객이 직접입력한 사유 텍스트로 내려감
OrderDate	주문일자	string
PayDate	결제일자	string
RequestDate	반품신청일자	string
WithdrawDate	반품철회일자	string
ApproveDate	반품승인일자	string
CompleteDate	반품처리일자	string	내부 시스템 처리 Update 일자
SlotInfo > BranchCode	당일배송 지점코드	int	일반 배송 주문은 데이터 없음
SlotInfo > DeliverySlotId	당일배송 배송슬롯번호	int	일반 배송 주문은 데이터 없음
SlotInfo > AllocationStartDate	당일배송 배송시작시간	datetime	일반 배송 주문은 데이터 없음
SlotInfo > AllocationEndDate	당일배송 배송종료시간	datetime	일반 배송 주문은 데이터 없음

 JSON_Success

{
  "ResultCode": 0,
  "Message": "string",
  "Data": [
    {
      "ReturnStatus": 0,
      "IsFastRefund": true,
      "FastRefundRewardStatus": 0,
      "GoodsStatus": 0,
      "AddReturnShippingFee": 0.0,
      "WhoAddReturnShippingFee": 0,
      "AddReturnShippingFeeWay": 0,
      "ReturnShippingFee": 0,
      "WhoReturnShippingFee": 0,
      "ReturnShippingFeeWay": 0,
      "HoldInfo": {
        "HoldDate": "2019-04-19T04:01:30.473Z",
        "IsHold": true,
        "Reason": 0,
        "FreeDate": "2019-04-19T04:01:30.473Z"
      },
      "ShippingInfo": {
        "CompleteDate": "2019-04-19T04:01:30.473Z",
        "ShippingFee": 0,
        "WhoShippingFee": 0,
        "DeliveryCompCode": 0,
        "InvoiceNo": "string"
      },
      "PickupInfo": {
        "Status": 0,
        "CompleteDate": "2019-04-19T04:01:30.473Z",
        "DeliveryCompName": "string",
        "InvoiceNo": "string",
        "SenderInfo": {
          "Name": "string",
          "HpNo": "string",
          "TelNo": "string",
          "ZipCode": "string",
          "AddressFront": "string",
          "AddressBack": "string",
          "Address": "string"
        },
        "ReceiverInfo": {
          "Name": "string",
          "HpNo": "string",
          "TelNo": "string",
          "ZipCode": "string",
          "AddressFront": "string",
          "AddressBack": "string",
          "Address": "string"
        }
      },
      "SlotInfo": {
        "BranchCode": int,
        "DeliverySlotId": int,
        "AllocationStartDate": datetime,
        "AllocationEndDate": datetime
      },
      "SiteType": 0,
      "SellerId": "string",
      "PayNo": 0,
      "GroupNo": 0,
      "OrderNo": 0,
      "GoodsNo": 0,
      "SiteGoodsNo": "string",
      "IsGiftOrder": "string",
      "RequestUser": 0,
      "ApproveUser": 0,
      "Reason": 0,
      "ReasonCode": 0,
      "ReasonDetail": "string",
      "OrderDate": "2019-04-19T04:01:30.474Z",
      "PayDate": "2019-04-19T04:01:30.474Z",
      "RequestDate": "2019-04-19T04:01:30.474Z",
      "WithdrawDate": "2019-04-19T04:01:30.474Z",
      "ApproveDate": "2019-04-19T04:01:30.474Z",
      "CompleteDate": "2019-04-19T04:01:30.474Z"
    }
  ]
}

JSON_Fail

{
    "ResultCode": int,
    "Message": "string",
    "Data": string
}

Sample Code_Success

G마켓

{
  "ResultCode":0,
  "Message":"Success",
  "Data":[
  {
   ReturnStatus":2,
   "IsFastRefund":false,
   "FastRefundRewardStatus":0,
   "GoodsStatus":1,
   "AddReturnShippingFee":0.0,
   "WhoAddReturnShippingFee":0,
   "AddReturnShippingFeeWay":0,
   "ReturnShippingFee":0.0,
   "WhoReturnShippingFee":0,
   "ReturnShippingFeeWay":0,
   "HoldInfo":{
   "HoldDate":null,
   "IsHold":false,
   "Reason":0,
   "FreeDate":"2019-04-19T15:31:27.297"
  },
   "ShippingInfo":{
      "CompleteDate":"2019-04-09T13:49:43.91",
     "ShippingFee":0.0000,
     "WhoShippingFee":2,
     "DeliveryCompCode":"10013",
     "InvoiceNo":"344755391152"
       },
  "PickupInfo":{
     "Status":2,
     "CompleteDate":"2019-04-19T15:31:25.26",
     "DeliveryCompName":"자체배송",
     "InvoiceNo":"매장확인",
     "SenderInfo":{
        "Name":"수령인명",
        "HpNo":"010-1234-5678",
        "TelNo":"010-1234-5678",
        "ZipCode":"200-933",
        "AddressFront":"강원 춘천시 석사동",
        "AddressBack":"840-3",
        "Address":"강원 춘천시 석사동 840-3"
                  },
     "ReceiverInfo":{
        "Name":"회수인명",
       "HpNo":"010-1234-5678",
       "TelNo":"010-1234-5678",
       "ZipCode":"200933 ",
       "AddressFront":"강원 춘천시 석사동",
       "AddressBack":"840-3 201호",
       "Address":"강원 춘천시 석사동 840-3 201호"
      }
   },
   "SlotInfo": null,
   "SiteType":3,
   "SellerId":"sellerid_test",
   "PayNo":4452790338,
   "GroupNo":19218613,
   "OrderNo":2943112798,
   "GoodsNo":0,
   "SiteGoodsNo":"1535172911",
   "IsGiftOrder": "N",
   "RequestUser":3,
   "ApproveUser":2,
   "Reason":0,
   "ReasonCode": 1,
   "ReasonDetail":"230사이즈로 주문했습니다. 그런데 박스에는 230이라고 써있는데 안에 든 신발은 240입니다. 230으로 보내주세요. 보내시기 전 신발사이즈 꼭 확인 부탁드립니다.",
   "OrderDate":"2019-04-07T19:20:33.64",
   "PayDate":"2019-04-07T19:20:39.317",
   "RequestDate":"2019-04-19T10:53:00",
   "WithdrawDate":null,
   "ApproveDate":"2019-04-19T15:31:00",
   "CompleteDate":null
  }
 ]
}


옥션

{
  "ResultCode":0,
  "Message":"Success",
  "Data":[
  {
   "ReturnStatus":3,
   "IsFastRefund":false,
   "FastRefundRewardStatus":0,
   "GoodsStatus":3,
   "AddReturnShippingFee":0.0000,
   "WhoAddReturnShippingFee":0,
   "AddReturnShippingFeeWay":0,
   "ReturnShippingFee":0.0000,
   "WhoReturnShippingFee":3,
   "ReturnShippingFeeWay":0,
   "HoldInfo":{
   "HoldDate":"2019-04-19T13:54:00",
   "IsHold":true,
   "Reason":4,
   "FreeDate":null
  },
   "ShippingInfo":{
   "CompleteDate":"2019-04-12T21:28:43.343",
   "ShippingFee":0.0,
   "WhoShippingFee":2,
   "DeliveryCompCode":10008,
   "InvoiceNo":"303961565235"
  },
   "PickupInfo":{
   "Status":2,
   "CompleteDate":null,
   "DeliveryCompName":"기타",
   "InvoiceNo":"",
   "SenderInfo":{
      "Name":"수취인명",
      "HpNo":"010-1234-5678",
      "TelNo":"010-1234-5678",
      "ZipCode":"42952 ",
      "AddressFront":"대구광역시 달성군 화원읍 구라리 1722 대곡역신동아파밀리에아파트",
      "AddressBack":"1111",
      "Address":"대구광역시 달성군 화원읍 구라리 1722 대곡역신동아파밀리에아파트 1111"
   },
      "ReceiverInfo":{
      "Name":"회수인명",
      "HpNo":"1577-1110",
      "TelNo":"010-1234-5678",
      "ZipCode":"135190",
      "AddressFront":"서울특별시 강남구 세곡동 111 - 20",
      "AddressBack":"서울남부지점(동남권 물류센터)",
      "Address":"서울특별시 강남구 세곡동 111 - 20 서울남부지점(동남권 물류센터)"
   }
  },
   "SiteType":1,
   "SellerId":"sellerid_test",
   "PayNo":1193250356,
   "GroupNo":915831153,
   "OrderNo":1590211563,
   "GoodsNo":0,
   "SiteGoodsNo":"B625011788",
   "RequestUser":1,
   "ApproveUser":0,
   "Reason":0,
   "ReasonCode": 1,
   "ReasonDetail":"안감 끝부분 찢어짐 있습니다.",
   "OrderDate":"2019-04-11T17:17:00",
   "PayDate":"2019-04-11T17:17:00",
   "RequestDate":"2019-04-19T13:50:00",
   "WithdrawDate":null,
   "ApproveDate":null,
   "CompleteDate":null
  }
 ]
}

Sample Code_Fail

{
    "ResultCode": 2141,
    "Message": "사이트 타입이 올바르지 않습니다",
    "Data": null
}

 

Error Code

결과코드	메시지	원인
8668	ShowAlertException$조회 기간은 7일 이내로 입력 바랍니다	StartDate ~ EndDate 조회기간 초과
99999	주문정보가 없습니다	주문번호/장바구니번호 조회한 결과 없을 경우
99999	API Error - 문자열이 유효한 DateTime으로 인식되지 않습니다	날짜형식 오류일 경우