v2.returns.get_return_detail
GET /api/v2/returns/get_return_detail
Sử dụng API này để lấy thông tin chi tiết của một yêu cầu hoàn trả theo mã số hoàn trả.
Đường dẫn Endpoint
URL: https://partner.shopeemobile.com/api/v2/returns/get_return_detail
Tham số chung
| Name | Type | Sample | Description |
|---|---|---|---|
| partner_id | int | 1 | Partner ID được gán khi đăng ký thành công. Bắt buộc cho tất cả các yêu cầu. |
| timestamp | timestamp | 1610000000 | Dùng để chỉ định thời điểm gửi yêu cầu. Bắt buộc cho tất cả các yêu cầu. Hết hạn sau 5 phút. |
| access_token | string | c09222e3fc40ffb25fc947f738b1abf1 | Token dùng để truy cập API, xác định quyền của bạn. Có thể dùng nhiều lần và hết hạn sau 4 giờ. |
| shop_id | int | 600000 | Mã định danh duy nhất của Shopee cho một cửa hàng. Tham số bắt buộc cho hầu hết các API. |
| sign | string | e318d3e932719916a9f9ebb57e2011961bd47abfa54a36e040d050d8931596e2 | Chữ ký được tạo từ partner_id, đường dẫn api, timestamp, access_token, shop_id và partner_key qua thuật toán HMAC-SHA256. Chi tiết: https://open.shopee.com/documents?module=87&type=2&id=58&version=2 |
Tham số Request
| Name | Type | Required | Sample | Description |
|---|---|---|---|---|
| return_sn | string | True | 2206150VT13E3MQ | Mã số của yêu cầu hoàn trả. |
Tham số Response
| Name | Type | Sample | Description |
|---|---|---|---|
| request_id | string | d52ca43b277a4f9292fb8be658bfd33d | Mã định danh của yêu cầu API dùng để theo dõi lỗi. |
| error | string | Mã lỗi. | |
| message | string | Mô tả lỗi. | |
| response | object | Số tiền hoàn trả. | |
| image | string[] | ["https://cf.shopee.sg/file/166f23cbfb31bd882f51cfe7f90d3826"] | URL hình ảnh của yêu cầu hoàn trả. |
| buyer_videos | object[] | ||
| thumbnail_url | string | https://down-ws-sg.img.susercontent.com/sg-11110158-23040-t1taxpkdkgpvf7 | URL ảnh đại diện của video. |
| video_url | string | https://play-ws.vod.shopee.com/api/v4/11110158/mms/sg-11110158-6jrnk-lf6a3juz7hw96f.ori.mp4 | URL của video. |
| reason | string | NOT_RECEIPT | Cho biết lý do hoàn trả ban đầu do người mua cung cấp khi khởi tạo yêu cầu hoàn trả. Giá trị áp dụng: Xem Định nghĩa Dữ liệu - ReturnReason và Reassessed Request Reason. Lưu ý: Có thể có trường hợp Nhân viên Shopee cập nhật yêu cầu hoàn trả với "Lý do Hoàn trả Đã Đánh giá Lại" sau khi xem xét thêm chi tiết và có thể yêu cầu bằng chứng từ người bán. Kết quả đánh giá lại sẽ được cung cấp riêng trong trường reassessed_request_reason. |
| text_reason | string | not received | Lý do người mua cung cấp. |
| reassessed_request_reason | string | ITEM_MISSING | Cho biết lý do hoàn trả được nền tảng đánh giá lại là phù hợp hơn. Có thể có trường hợp Nhân viên Shopee cập nhật yêu cầu hoàn trả với "Lý do Hoàn trả Đã Đánh giá Lại" sau khi xem xét thêm chi tiết và có thể yêu cầu bằng chứng từ người bán. Giá trị áp dụng: Xem Định nghĩa Dữ liệu - ReturnReason và Reassessed Request Reason. Nếu chưa có đánh giá lại, giá trị sẽ là NONE. |
| return_sn | string | 2206140TA5PM808 | Mã số của yêu cầu hoàn trả. |
| refund_amount | float | 13.97 | Số tiền hoàn trả. |
| currency | string | SGD | Đơn vị tiền tệ của yêu cầu hoàn trả. |
| create_time | timestamp | 1655205084 | Thời gian tạo yêu cầu hoàn trả. |
| update_time | timestamp | 1655219544 | Thời gian chỉnh sửa yêu cầu hoàn trả. |
| status | string | ACCEPTED | Kiểu liệt kê xác định trạng thái hiện tại của yêu cầu hoàn trả. Giá trị áp dụng: Xem Định nghĩa Dữ liệu - ReturnStatus. |
| due_date | timestamp | 1655377883 | Thời hạn cuối cùng người bán xử lý yêu cầu hoàn trả này. |
| tracking_number | string | RNSHS00177569 | Mã vận đơn do đơn vị vận chuyển cấp cho lô hàng. |
| dispute_reason | int32 | 2 | Lý do người bán tranh chấp yêu cầu hoàn trả. Trường này hữu ích khi yêu cầu hoàn trả đang bị tranh chấp. Giá trị áp dụng: Xem Định nghĩa Dữ liệu - ReturnDisputeReason. |
| dispute_text_reason | string | "reason" | Lý do người bán cung cấp. Trường này hữu ích khi yêu cầu hoàn trả đang bị tranh chấp. |
| needs_logistics | boolean | false | Sản phẩm cần gửi lại cho người bán. Có thể là kênh tích hợp hoặc không tích hợp. |
| amount_before_discount | float | 13.99 | Giá đơn hàng trước chiết khấu. |
| user | object | ||
| username | string | gwlsg01 | Biệt danh của người mua, sẽ bị ẩn thành "****" nếu là hoàn trả không tích hợp tại khu vực TW. |
| string | ********oo@shopee.com | Email của người mua, sẽ trống nếu là hoàn trả không tích hợp tại khu vực TW. | |
| portrait | string | https://cf.shopee.sg/file/166f23cbfb31bd882f51cfe7f90d3826 | Ảnh đại diện của người mua, sẽ trống nếu là hoàn trả không tích hợp tại khu vực TW. |
| item | object[] | ||
| model_id | int64 | 2001586745 | Mã định danh duy nhất của Shopee cho một biến thể sản phẩm. |
| name | string | [Self collection point] Orange macaron | Tên sản phẩm bằng ngôn ngữ địa phương. |
| images | string[] | ["https://cf.shopee.sg/file/4ecbb6fa567e42c1b1e02993ad53df12"] | URL hình ảnh của sản phẩm. |
| amount | int32 | 1 | Số lượng sản phẩm này. |
| item_price | float | 10.0 | Giá của sản phẩm. |
| is_add_on_deal | boolean | false | Cho biết sản phẩm này có thuộc add-on deal hay không. |
| is_main_item | boolean | false | Cho biết sản phẩm này là sản phẩm chính hay phụ. True là sản phẩm chính, false là sản phẩm phụ. |
| add_on_deal_id | int64 | 0 | Mã định danh duy nhất của một add-on deal. |
| item_id | int64 | 2700126223 | ID của sản phẩm. |
| item_sku | string | USB | SKU của sản phẩm. |
| variation_sku | string | RED | SKU biến thể của sản phẩm. |
| refund_amount | float | 12.34 | Số tiền hoàn trả của sản phẩm. Chỉ dành cho cửa hàng được phép hoàn trả số lượng một phần. Nếu không có, tham chiếu đến item_price. |
| order_sn | string | 220614T9XV8JTN | Mã định danh duy nhất của Shopee cho một đơn hàng. |
| return_ship_due_date | timestamp | 1655438205 | Thời hạn người mua gửi hàng. |
| return_seller_due_date | timestamp | 1655438205 | Thời hạn người bán xử lý yêu cầu hoàn trả khi người mua đã gửi hàng. |
| activity | object[] | ||
| activity_id | int64 | 123456789 | ID của hoạt động. |
| activity_type | string | BUNDLE | Loại hoạt động. |
| original_price | string | 12.34 | Giá gốc của hoạt động. |
| discounted_price | string | 12.34 | Giá chiết khấu của hoạt động. |
| items | object[] | ||
| item_id | int64 | 12345678 | ID của sản phẩm. |
| variation_id | int64 | 12345678 | Mã định danh duy nhất của Shopee cho một biến thể sản phẩm. |
| quantity_purchased | int64 | 2 | Số lượng sản phẩm đã mua. |
| original_price | string | 12.34 | Giá gốc của sản phẩm. |
| refund_amount | float | 12.34 | Số tiền hoàn trả của sản phẩm trong trường hợp bundle deal, chỉ dành cho cửa hàng được phép hoàn trả số lượng một phần. |
| seller_proof | object | ||
| seller_proof_status | string | PENDING | Cho biết người bán có cần cung cấp bằng chứng khi trạng thái hoàn trả là RETURN_JUDING, RETURN_SELLER_DISPUTE và RETURN_ACCEPTED hay không. Giá trị áp dụng: Xem Định nghĩa Dữ liệu - SellerProofStatus. |
| seller_evidence_deadline | timestamp | 1655438336 | Cho biết thời hạn nộp bằng chứng. |
| seller_compensation | object | ||
| seller_compensation_status | string | PENDING_REQUEST | Cho biết người bán có đủ điều kiện gửi yêu cầu bồi thường hay không. Xem "Định nghĩa Dữ liệu - SellerCompensationStatus". |
| seller_compensation_due_date | timestamp | 1655438336 | Cho biết thời hạn gửi yêu cầu bồi thường. |
| compensation_amount | float | 100.0 | Cho biết số tiền bồi thường mà nhân viên đã quyết định. |
| negotiation | object | ||
| negotiation_status | string | PENDING_RESPOND | Cho biết người bán có thể thương lượng với người mua hay không. Xem "Định nghĩa Dữ liệu - NegotiationStatus". |
| latest_solution | string | RETURN_REFUND | Cho biết giải pháp đề xuất là gì. Xem "Định nghĩa Dữ liệu - ReturnSolution". |
| latest_offer_amount | float | 12.34 | Cho biết số tiền hoàn trả trong giải pháp đề xuất mới nhất. |
| latest_offer_creator | string | username | Cho biết bên nào đã đưa ra đề xuất mới nhất. |
| counter_limit | int32 | 0 | Cho biết giới hạn phản đề xuất còn lại. |
| offer_due_date | timestamp | 1655438336 | Cho biết thời hạn của đề xuất. |
| logistics_status | string | LOGISTICS_REQUEST_CREATED | Cho biết trạng thái logistics ngược. Xem "Định nghĩa Dữ liệu - LogisticsStatus". Lưu ý: - Đây là trường kế thừa chỉ phản ánh trạng thái logistics ngược của RR Thông thường. Để xác định RR có phải là RR Thông thường không, kiểm tra xem return_refund_request_type = 0. - Nếu cần trạng thái logistics ngược cho RR Thông thường, RR Đang vận chuyển hoặc Hoàn trả Tại Chỗ, hãy dùng trường mới reverse_logistic_status. |
| reverse_logistic_status | string | LOGISTICS_REQUEST_CREATED | Cho biết trạng thái logistics ngược mới nhất của một yêu cầu hoàn trả, đề cập đến trạng thái hiện tại của người mua gửi kiện hàng về điểm xác nhận (người bán hoặc kho hàng), bao gồm RR Thông thường, RR Đang vận chuyển và Hoàn trả Tại Chỗ. Xem "Định nghĩa Dữ liệu - ReverseLogisticsStatus" vì trạng thái hiển thị cho RR Thông thường và RR Đang vận chuyển hoặc Hoàn trả Tại Chỗ là khác nhau. |
| return_pickup_address | object | Cho biết địa chỉ lấy hàng của người mua. | |
| address | string | BLOCK 106, HENDERSON CRESCENT | Cho biết địa chỉ người nhận. |
| name | string | name | Cho biết tên người nhận. |
| phone | string | 6512345678 | Cho biết số điện thoại người nhận. [Chỉ dành cho kênh không tích hợp TW] Sẽ trả về "****" khi có "virtual_contact_number". |
| town | string | Batino | Cho biết thị trấn/xã của người nhận. |
| district | string | Calamba City | Cho biết quận/huyện của người nhận. |
| city | string | Laguna | Cho biết thành phố của người nhận. |
| state | string | South Luzon | Cho biết tỉnh/bang của người nhận. |
| region | string | SG | Cho biết khu vực của người nhận. |
| zipcode | string | 150106 | Cho biết mã bưu chính của người nhận. |
| virtual_contact_number | string | 0928000886 | [Chỉ dành cho kênh không tích hợp TW] Số điện thoại ảo để liên lạc với người nhận. |
| package_query_number | string | 66668888 | [Chỉ dành cho kênh không tích hợp TW] Số truy vấn được dùng trong cuộc gọi số điện thoại ảo để liên lạc với người nhận của yêu cầu hoàn trả này. |
| return_address | object | ||
| whs_id | string | SGC | Cho biết ID kho hàng mà sản phẩm sẽ được trả về. Vui lòng gọi v2.shop.get_warehouse_detail để kiểm tra thông tin kho hàng chi tiết, với trường "location_id" của v2.shop.get_warehouse_detail khớp với trường "whs_id" của v2.return.get_return_detail. Đối với người bán dùng dịch vụ Shopee thực hiện đơn hàng (FBS) & nhiều kho hàng, đơn R/R sẽ được trả về kho gần nhất với địa chỉ người mua thay vì chỉ 1 địa chỉ hoàn trả mặc định. Nếu là người bán thông thường, trường này sẽ trả về rỗng. |
| return_refund_type | string | RRAOC | Cho biết yêu cầu hoàn trả là RRBOC (yêu cầu Hoàn trả/Hoàn tiền trước khi hoàn tất đơn hàng) hay RRAOC (yêu cầu Hoàn trả/Hoàn tiền sau khi hoàn tất đơn hàng). |
| return_solution | int32 | 0 | Cho biết giải pháp cập nhật nhất của yêu cầu Hoàn trả/Hoàn tiền (LƯU Ý: đây không phải là giải pháp trong quá trình thương lượng). Giá trị áp dụng: - 0: Hoàn trả và Hoàn tiền - 1: Chỉ Hoàn tiền |
| is_seller_arrange | boolean | true | Cho biết return_sn có đang sử dụng phương thức hoàn trả "Người bán Sắp xếp" hay không. Chỉ True đối với TW và BR. |
| is_shipping_proof_mandatory | boolean | true | Cho biết việc tải lên bằng chứng vận chuyển có bắt buộc với người bán để xác nhận "Sắp xếp Lấy hàng" khi is_seller_arrange = true hay không. |
| has_uploaded_shipping_proof | boolean | false | Cho biết người bán đã tải lên bằng chứng vận chuyển cho yêu cầu hoàn trả này chưa. |
| is_reverse_logistics_channel_integrated | boolean | false | Cho biết loại kênh logistics ngược được chọn là tích hợp hay không tích hợp. |
| reverse_logistic_channel_name | string | test_reverse_logistic_channel_name | Cho biết tên đơn vị vận chuyển logistics ngược. |
| return_refund_request_type | int32 | 0 | Cho biết loại yêu cầu hoàn trả/hoàn tiền, có thể là RR Thông thường, RR Đang vận chuyển hoặc Hoàn trả Tại Chỗ: 0: RR Thông thường (yêu cầu do người mua sau khi giao hàng xong / ngày giao hàng ước tính) 1: RR Đang vận chuyển (yêu cầu do người mua khi hàng đang trên đường giao) 2: Hoàn trả Tại Chỗ (yêu cầu do tài xế sau khi người mua từ chối kiện hàng khi giao). Xem thêm Định nghĩa Dữ liệu - Return Refund Request Type. |
| validation_type | string | seller_validation | Cho biết người bán hay kho hàng sẽ nhận kiện hàng hoàn trả từ người mua và xác nhận tình trạng kiện hàng: - seller_validation - warehouse_validation. Xem thêm Định nghĩa Dữ liệu - ValidationType. |
| is_arrived_at_warehouse | int32 | 3 | [Chỉ dành cho validation_type = warehouse_validation] Cho biết trạng thái nhận hàng tại kho. Trường này giúp người bán nhanh chóng xác định kiện hàng đã đến kho hay bị từ chối. Giá trị áp dụng: 1: Chờ nhập kho 2: Bị từ chối 3: Đã nhập kho 4: Đã hủy |
| follow_up_action_list | object[] | [Chỉ dành cho validation_type = warehouse_validation] Các hành động xử lý kho hàng cho mỗi sản phẩm trong kiện hàng. | |
| item_id | int64 | 2700126223 | Mã định danh duy nhất của sản phẩm. |
| model_id | int64 | 2000458802 | Mã định danh duy nhất của biến thể thuộc sản phẩm. |
| qty | int32 | 2 | Số lượng sản phẩm hoặc biến thể có cùng trạng thái hiện tại. |
| current_status | int32 | 2 | Trạng thái hiện tại của sản phẩm/biến thể tại kho hàng. Giá trị áp dụng: 1: Tiêu hủy 2: Trả lại Người bán 7: Đã nhận và nhập kho 8: Trả lại Người mua 9: Thiếu hàng. Lưu ý: Vì Bán lại hiện chỉ áp dụng cho kiện hàng Giao hàng Thất bại, các giá trị sau sẽ không được trả về hiện tại: 3: Nhập kho để Bán lại 4: Xuất kho Bán lại 5: Bán lại Thất bại 6: Thoát Bán lại |
| related_order_sn_list | string[] | [] | Danh sách order_sn được tạo từ quá trình Bán lại. Chỉ trả về khi current_status = 4 (Xuất kho Bán lại). Lưu ý: Vì Bán lại hiện chỉ áp dụng cho kiện hàng Giao hàng Thất bại, trường này sẽ trống hiện tại và sẽ có giá trị hợp lệ khi Bán lại áp dụng cho kiện hàng Hoàn trả/Hoàn tiền trong tương lai. |
| resell_failed_next_step | string | "" | Bước tiếp theo sau khi Bán lại thất bại. Chỉ trả về khi current_status = 5 (Bán lại Thất bại). Lưu ý: Vì Bán lại hiện chỉ áp dụng cho kiện hàng Giao hàng Thất bại, trường này sẽ trống hiện tại và sẽ có giá trị hợp lệ khi Bán lại áp dụng cho kiện hàng Hoàn trả/Hoàn tiền trong tương lai. |