[카카오쇼핑] 교환요청, 주문정보조회 시 클레임 요청고객 추가 안내 (교환요청 API 버전 변경 포함) – Kakao Shopping Open API

안녕하세요.
카카오 쇼핑입니다.

선물하기 수신자(선물받은 고객)가 직접 교환요청이 가능하도록 서비스가 개선될 예정입니다.
이에 따라, 선물하기/톡스토어 교환 관련 API 가 변경될 예정으로 안내드립니다.

■ 적용일자
2024년 6월 10일(월) ← 일자변경 (기존. 6월3일(월) )

■ 변경사항

1. 교환요청 API
1) API Path가 vi -> v2로 변경됩니다.
- 현재 : POST /v1/shopping/claims/exchange/request
- 변경: POST /v2/shopping/claims/exchange/request
*교환요청 API 외 [교환수거완료],[교환보류],[교환재발송],[교환철회],[교환회수송장입력/수정] API는 변경사항 없이 API Path가 v1으로 그대로 유지됩니다.

2) ExchangeClaimRequest > claimRequestUser 값이 추가됩니다.

<requestBody 예시> 교환요청 API - 신규추가는 bold 표시

{
  "orderIds": [
    0
  ],
  "collectType": "AUTO",
  "reasonCode": "CANCELED_BY_BUYER_CHANGE_OF_MIND",
  "reasonComment": "string",
  "deliveryCompanyCode": "CJGLS",
  "invoiceNumber": "string",
  "claimRequestUser": "BUYER"
}

2. 주문정보조회 API
- OrderClaimExchange > claimRequestUser 값이 추가됩니다.

[관련 API]
-교환요청 API: /v2/claims/exchange/request
- 주문정보 조회 API: /v1/shopping/order?order_id={order_id}
- 주문정보 복수 조회 API: /v1/shopping/orders/bulk?order_ids={order_ids}

<requestBody 예시> 주문정보조회 API - 신규 추가는 bold 표시

{
  "id": 3000765409,
  "orderBase": {
    "id": 3000765409,
    "paymentId": 3000714802,
    "channelType": "GIFT",
    "status": "ExchangeRequest",
    "createdAt": "20240416150816",
    "paidAt": "20240416150835",
    "modifiedAt": "20240513113702"
  },
  "orderer": {
    "phoneNumber": "+82 10-0000-0000"
  },
  "orderProduct": {
    "id": 1015351,
    "name": "[알리샤][선물] 묶음가_반품(1천)_교환(2천)_출수거지동일",
    "sellerItemNo": "",
    "optionContent": "옵션: 샤인머스캣",
    "quantity": 2,
    "productPrice": 2400,
    "optionPrice": 0,
    "sellerDiscountPrice": 0,
    "sellerCouponDiscountPrice": 0,
    "adminDiscountPrice": 0,
    "settlementBasicPrice": 2400,
    "refererCode": "",
    "brandName": "알리샤넬_브랜드",
    "deliveryAmountOriginId": 1452126,
    "deliveryAmountPayPointTime": "PayedToOrder",
    "deliveryAmountType": "FREE",
    "deliveryAmount": 0,
    "areaAdditionalDeliveryAmount": 0
  },
  "orderDeliveryRequest": {
    "receiverName": "알리샤수신자",
    "receiverAddress": "경기 성남시 분당구 판교역로 166 (카카오 판교 아지트) 11",
    "receiverAddress1": "경기 성남시 분당구 판교역로 166 (카카오 판교 아지트)",
    "receiverAddress2": "11",
    "receiverPhoneNumber": "",
    "receiverMobileNumber": "010-3068-0804",
    "zipcode": "13529",
    "roadZipCode": "13529"
  },
  "orderDelivery": {
    "deliveryRequestAt": "20240416151002",
    "confirmedAt": "20240416151051",
    "invoiceRegisteredAt": "20240416151141",
    "shippingMethod": "SHIPPING",
    "deliveryCompanyCode": "CJGLS",
    "invoiceNumber": "1231231231"
  },
  "orderClaimExchange": {
    "claimId": 67360,
    "claimItemId": 88222,
    "claimItemStatus": "REQUEST",
    "claimRequestUser": "수신자",
    "reasonCodeId": 17,
    "reasonCodeName": "변심에 의한 상품 교환",
    "reasonComment": "",
    "referType": "FRONT",
    "createdAt": "20240513113701",
    "modifiedAt": "20240513113702",
    "returnAddressId": 1743,
    "returnMethod": "반송예정",
    "collectType": "LATER",
    "pickupName": "알리샤수신자",
    "pickupZipCode": "13529",
    "pickupRoadZipCode": "13529",
    "pickupAddress1": "경기 성남시 분당구 판교역로 166 (카카오 판교 아지트)",
    "pickupAddress2": "11",
    "pickupMobileNumber": "010-3068-0804",
    "pickupPhoneNumber": "",
    "exchangeName": "알리샤수신자",
    "exchangeZipCode": "13529",
    "exchangeRoadZipCode": "13529",
    "exchangeAddress1": "경기 성남시 분당구 판교역로 166 (카카오 판교 아지트)",
    "exchangeAddress2": "11",
    "exchangeMobileNumber": "010-3068-0804",
    "exchangePhoneNumber": "",
    "exchangeShippingFee": 2000,
    "exchangeShippingFeeMethod": "DirectAmount",
    "exchangeShippingFeeMethodLabel": "판매자에게 직접 송금"
  }
}

■ 참고사항
- 교환요청 API는 선물하기/톡스토어 공통 사용 API로, 톡스토어 주문의 교환요청 API 호출 시에도 API path를 v2로 변경하여 호출해주셔야 합니다.
- "claimRequestUser"는 필수값으로 선물하기/톡스토어 주문의 교환요청API 호출 시 필수로 입력해주셔야 하며, 선물하기 자기구매 주문과 톡스토어 주문은 "claimRequestUser" = "BUYER"만 입력이 가능합니다. ("RECEIVER" 입력 시 에러 발생)

관련하여 문의사항 있으실경우 http://kko.to/G5xpSFS4j 으로 전달부탁드립니다.
감사합니다.

이 섹션의 문서

관련 문서