tiktok.return_refund.202309.returns.return_id.approve
POST/return_refund/202309/returns/{return_id}/approveGọi qua 360: POST https://partner.quantri360.com/v1/tiktok/return_refund/202309/returns/{return_id}/approve
Endpoint ghi — thay đổi dữ liệu trên TikTok Shop. Key phải được tạo với tick "Cho phép gọi API ghi", nếu không sẽ nhận 403 write_not_allowed. Mỗi lần gọi được ghi nhật ký.
Mô tả API
Duyệt yêu cầu trả hàng.
- Gọi qua /v1/tiktok/return_refund/202309/returns/{return_id}/approve với Authorization: Bearer <key>; dùng platform_shop_id khi có nhiều shop. 360 tự gắn app_key, shop_cipher, sign và access_token.
- API GHI: thay đổi dữ liệu thật trên TikTok Shop; cần key có quyền ghi (can_write) và gói mở module Đơn hàng. Duyệt yêu cầu trả hàng.
- HTTP 200 vẫn có thể có lỗi nghiệp vụ; kiểm code trước khi dùng kết quả.
- Chỉ duyệt khi yêu cầu còn chờ đúng thao tác của người bán. buyer_keep_item chỉ dùng với APPROVE_RETURN; true nghĩa là hoàn toàn bộ tiền và người mua giữ hàng. partial_refund bắt buộc với OFFER_PARTIAL_REFUND, gồm amount và currency; bỏ khi dùng quyết định khác.
Request
Địa chỉ
POST https://partner.quantri360.com/v1/tiktok/return_refund/202309/returns/{return_id}/approve
Xác thực & gian hàng
| Tên | Vị trí | Kiểu | Mẫu | Mô tả |
|---|---|---|---|---|
| Authorization | header | header | Bearer q360_live_ab12cd34_… | Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand. |
| platform_shop_id | query | string | 100001 | Gian hàng (lấy ở GET /v1/platforms → shops[].platform_shop_id). BẮT BUỘC khi brand có > 1 gian hàng trên nền tảng; 360 bỏ tham số này trước khi chuyển tiếp. |
Tham số request
| Tên | Vị trí | Kiểu | Bắt buộc | Mẫu | Mô tả |
|---|---|---|---|---|---|
| return_id | path | string | Có | 100000000000000001 | Mã yêu cầu trả hàng. |
| idempotency_key | query | string | Không | demo-yeu-cau-0001 | Khóa chống xử lý lặp do bên gọi tạo; dùng lại cùng khóa khi thử lại cùng yêu cầu. Tối đa 255 ký tự. Tối đa 255. |
| decision | body | string | Có | APPROVE_REFUND | Quyết định. Giá trị / trường liên quan: APPROVE_REFUND, APPROVE_RETURN, APPROVE_RECEIVED_PACKAGE, APPROVE_REPLACEMENT, ISSUE_REPLACEMENT_REFUND, OFFER_PARTIAL_REFUND, DIRECT_REFUND. |
| buyer_keep_item | body | bool | Không | false | Người mua giữ mặt hàng. Giá trị / trường liên quan: APPROVE_RETURN, true, false. Có thể không xuất hiện khi không có dữ liệu phù hợp. |
| partial_refund | body | object | Không | Một phần hoàn tiền. Giá trị / trường liên quan: decision, OFFER_PARTIAL_REFUND, partial_refund, amount, currency. Bắt buộc khi áp dụng quyết định tương ứng nêu trên. | |
| partial_refund.currency | body | string | Không | VND | Mã tiền tệ. |
| partial_refund.amount | body | string | Không | 10000 | Số tiền. |
Ví dụ request
curl -s -X POST "https://partner.quantri360.com/v1/tiktok/return_refund/202309/returns/100000000000000001/approve" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"decision":"APPROVE_REFUND"}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok/return_refund/202309/returns/100000000000000001/approve",
params={},
json={
"decision": "APPROVE_REFUND"
},
headers={"Authorization": f"Bearer {KEY}"},
timeout=60,
)
print(r.status_code)
print(r.json())Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok/return_refund/202309/returns/100000000000000001/approve');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({"decision":"APPROVE_REFUND"}),
});
console.log(r.status, await r.json());PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok/return_refund/202309/returns/100000000000000001/approve' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"decision":"APPROVE_REFUND"}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;Response
Tham số phản hồi (nguyên của TikTok Shop)
| Tên | Kiểu | Mẫu | Mô tả |
|---|---|---|---|
| code | int | 0 | Mã kết quả; 0 là thành công. |
| message | string | Success | Thông báo kết quả; khi lỗi, đọc nội dung để xử lý. |
| request_id | string | DEMO_REQUEST_0001 | Mã truy vết yêu cầu. |
| data | object | Dữ liệu. |
Mẫu phản hồi
{
"code": 0,
"message": "Success",
"request_id": "DEMO_REQUEST_0001",
"data": {}
}
Mã lỗi của TikTok Shop (2)
Bấm để xem
| Mã | Ý nghĩa |
|---|---|
| ReverseOrderExistNegotiate | 25011010 request has been transferred to platform operator 25011012 reverse status cannot approve application 25011013 reverse status cannot approve receive 25011023 forbid process authentic guarantee order 25011026 forbid process receive for FBT order 25011032 |
| ReverseInvalidStatusPartialRefund | 25020004 decision not match reverse type 25020005 No permission to process this order 25020008 Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support. 25020009 reverse already cancelled |
Bắt đầu dùng
- Đăng ký tài khoản Partner
- Mở loại dữ liệu thuộc nhóm Đơn hàng ở trang nền tảng
- Tạo API key (tick kênh TikTok Shop)
- Gọi theo ví dụ ở trên