tiktok.return_refund.202602.refunds.calculate
POST/return_refund/202602/refunds/calculateGọi qua 360: POST https://partner.quantri360.com/v1/tiktok/return_refund/202602/refunds/calculate
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
Ước tính tiền có thể hoàn cho yêu cầu hủy, hoàn tiền hoặc trả hàng và hoàn tiền. Nếu bỏ skus, order_line_item_ids và order_line_list thì tính cho tất cả dòng đơn; phương thức gửi trả có thể ảnh hưởng kết quả.
- Gọi qua /v1/tiktok/return_refund/202602/refunds/calculate 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. Ước tính tiền có thể hoàn cho yêu cầu hủy, hoàn tiền hoặc trả hàng và hoàn tiền. Nếu bỏ skus, order_line_item_ids và order_line_list thì tính cho tất cả dòng đơn; phương thức gửi trả có thể ảnh hưởng kết quả.
- HTTP 200 vẫn có thể có lỗi nghiệp vụ; kiểm code trước khi dùng kết quả.
- Chỉ ước tính tiền hoàn; không gửi đồng thời order_line_item_ids và order_line_list có giá trị.
Request
Địa chỉ
POST https://partner.quantri360.com/v1/tiktok/return_refund/202602/refunds/calculate
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ả |
|---|---|---|---|---|---|
| order_id | body | string | Có | 100000000000000001 | Mã đơn hàng. |
| request_type | body | string | Có | REFUND | Yêu cầu loại. |
| shipment_type | body | string | Không | PLATFORM | Vận chuyển loại. Giá trị / trường liên quan: PLATFORM, BUYER_ARRANGE. |
| handover_method | body | string | Không | DROP_OFF | Bàn giao phương thức. Giá trị / trường liên quan: DROP_OFF, PICKUP. |
| reason_name | body | string | Có | ecom_order_delivered_refund_reason_missing_product_seller | Tên lý do dùng cho yêu cầu. |
| order_line_item_ids | body | string[] | Không | ["100000000000000001"] | Các mã đơn dòng mặt hàng. Giá trị / trường liên quan: order_line_item_ids, order_line_list. Không gửi đồng thời order_line_item_ids và order_line_list có giá trị. |
| skus | body | object[] | Không | Các sku. | |
| skus[].sku_id | body | string | Có | 100000000000000001 | Mã SKU. |
| skus[].quantity | body | int | Có | 1 | Số lượng. |
| order_line_list | body | object[] | Không | Đơn dòng danh sách. Giá trị / trường liên quan: order_line_item_ids, order_line_list. Không gửi đồng thời order_line_item_ids và order_line_list có giá trị. | |
| order_line_list[].order_line_item_id | body | string | Không | 100000000000000001 | Mã dòng hàng trong đơn. |
| order_line_list[].sub_order_line_item_id | body | string | Không | 100000000000000001 | Mã con đơn dòng mặt hàng. Bắt buộc với sản phẩm dạng gói; không bắt buộc với sản phẩm thường. |
Ví dụ request
curl -s -X POST "https://partner.quantri360.com/v1/tiktok/return_refund/202602/refunds/calculate" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"order_id":"100000000000000001","request_type":"REFUND","reason_name":"ecom_order_delivered_refund_reason_missing_product_seller"}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok/return_refund/202602/refunds/calculate",
params={},
json={
"order_id": "100000000000000001",
"request_type": "REFUND",
"reason_name": "ecom_order_delivered_refund_reason_missing_product_seller"
},
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/202602/refunds/calculate');
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({"order_id":"100000000000000001","request_type":"REFUND","reason_name":"ecom_order_delivered_refund_reason_missing_product_seller"}),
});
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/202602/refunds/calculate' . '?' . 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, '{"order_id":"100000000000000001","request_type":"REFUND","reason_name":"ecom_order_delivered_refund_reason_missing_product_seller"}');
$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. | |
| order_refund_amount | object | Đơn hoàn tiền số tiền. | |
| currency | string | VND | Mã tiền tệ. |
| refund_total | string | 10000 | Hoàn tiền tổng. |
| refund_subtotal | string | 10000 | Hoàn tiền tạm tính. |
| refund_shipping_fee | string | 10000 | Hoàn tiền vận chuyển phí. |
| refund_tax | string | 10000 | Hoàn tiền thuế. |
| retail_delivery_fee | string | 10000 | Bán lẻ giao hàng phí. |
Mẫu phản hồi
{
"code": 0,
"message": "Success",
"request_id": "DEMO_REQUEST_0001",
"data": {
"order_refund_amount": {
"currency": "VND",
"refund_total": "10000",
"refund_subtotal": "10000",
"refund_shipping_fee": "10000",
"refund_tax": "10000",
"retail_delivery_fee": "10000"
}
}
}
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