v2.returns.get_return_list
GET /api/v2/returns/get_return_list
Sử dụng API này để lấy thông tin chi tiết của nhiều yêu cầu hoàn trả theo ID cửa hàng.
Đường dẫn Endpoint
URL: https://partner.shopeemobile.com/api/v2/returns/get_return_list
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 |
|---|---|---|---|---|
| page_no | int64 | True | 1 | Chỉ định mục bắt đầu của dữ liệu cần trả về. Mặc định là 0. Nếu dữ liệu nhiều hơn một trang, offset có thể là mục bắt đầu cho lần gọi tiếp theo. |
| page_size | int64 | True | 10 | Nếu có nhiều mục cần lấy, bạn có thể cần gọi GetReturnList nhiều lần. Mỗi kết quả được trả về dưới dạng một trang. Mặc định là 40. Dùng bộ lọc phân trang để kiểm soát số mục tối đa (<= 100) trả về mỗi trang, cùng với số offset để bắt đầu lần gọi tiếp theo. |
| create_time_from | timestamp | False | 1655392442 | Các trường create_time_from và create_time_to xác định khoảng thời gian truy vấn đơn hàng (dựa trên thời gian tạo đơn). Trường create_time_from là ngày bắt đầu. Khoảng thời gian tối đa có thể chỉ định là 15 ngày. |
| create_time_to | timestamp | False | 1655392542 | Các trường create_time_from và create_time_to xác định khoảng thời gian truy vấn đơn hàng (dựa trên thời gian tạo đơn). Trường create_time_from là ngày bắt đầu. Khoảng thời gian tối đa có thể chỉ định là 15 ngày. |
| update_time_from | timestamp | False | 1655392442 | Các trường update_time_from và update_time_to xác định khoảng thời gian truy vấn dựa trên lần cập nhật hoàn trả gần nhất. Trường update_time_from là ngày bắt đầu. Khoảng thời gian tối đa là 15 ngày. update_time_from phải >= create_time_from. |
| update_time_to | timestamp | False | 1655392542 | Các trường update_time_from và update_time_to xác định khoảng thời gian truy vấn dựa trên lần cập nhật hoàn trả gần nhất. Trường update_time_from là ngày bắt đầu. Khoảng thời gian tối đa là 15 ngày. update_time_from phải >= create_time_from. |
| status | string | False | REQUESTED | Dùng để lọc yêu cầu hoàn trả theo trạng thái hoàn trả. Xem "Định nghĩa Dữ liệu - ReturnStatus". |
| negotiation_status | string | False | TERMINATED | Dùng để lọc yêu cầu hoàn trả theo trạng thái thương lượng. Xem "Định nghĩa Dữ liệu - NegotiationStatus". |
| seller_proof_status | string | False | PENDING | Dùng để lọc yêu cầu hoàn trả theo trạng thái bằng chứng. Xem "Định nghĩa Dữ liệu - SellerProofStatus". |
| seller_compensation_status | string | False | NOT_REQUIRED | Dùng để lọc yêu cầu hoàn trả theo trạng thái bồi thường. Xem "Định nghĩa Dữ liệu - SellerCompensationStatus". |
Tham số Response
| Name | Type | Sample | Description |
|---|---|---|---|
| request_id | string | 33e099960cdf420393ca5d5c35016f6d | 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ả. | |
| more | boolean | true | Cho biết có trang tiếp theo hay không. |
| return | object[] | ||
| image | string[] | ["https://cf.shopee.sg/file/166f23cbfb31bd882f51cfe7f90d3826"] | URL hình ảnh của yêu cầu hoàn trả. |
| reason | string | PHYSICAL_DMG | 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 | return reason | 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 | 200203171852695 | Mã số của yêu cầu hoàn trả. |
| refund_amount | float | 1409.0 | 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 | 1580721513 | Thời gian tạo yêu cầu hoàn trả. |
| update_time | timestamp | 1580729377 | Thời gian chỉnh sửa yêu cầu hoàn trả. |
| status | string | CANCELLED | 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 | 1580721513 | 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 | string[] | ["UNKNOWN"] | 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 | true | 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 | 1409.0 | Giá đơn hàng trước chiết khấu. |
| user | object | ||
| username | string | abcdefg | 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 | ***********r1@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 | 0 | Mã định danh duy nhất của Shopee cho một biến thể sản phẩm. |
| name | string | agsabdmnambd | Tên sản phẩm bằng ngôn ngữ địa phương. |
| images | string[] | ["https://cf.shopee.sg/file/166f23cbfb31bd882f51cfe7f90d3826"] | URL hình ảnh của sản phẩm. |
| amount | int64 | 1 | Số lượng sản phẩm này. |
| item_price | float | 1409.9 | 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 | 2147533133 | 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. |
| order_sn | string | 200203C6W0AR27 | Mã định danh duy nhất của Shopee cho một đơn hàng. |
| return_ship_due_date | timestamp | 1655438336 | Thời hạn người mua gửi hàng. |
| return_seller_due_date | timestamp | 1655438336 | 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. |
| negotiation_status | string | PENDING_RESPOND | Trạng thái thương lượng. Xem "Định nghĩa Dữ liệu - NegotiationStatus". |
| seller_proof_status | string | PENDING | Trạng thái bằng chứng. Xem "Định nghĩa Dữ liệu - SellerProofStatus". |
| seller_compensation_status | string | PENDING_REQUEST | Trạng thái bồi thường. Xem "Định nghĩa Dữ liệu - SellerCompensationStatus". |
| 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 | false | 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 | false | 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. |
| 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. |
| 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. |