tiktok.fbt.202602.inbound_orders.tracking_update
POST/fbt/202602/inbound_orders/tracking_updateGọi qua 360: POST https://partner.quantri360.com/v1/tiktok/fbt/202602/inbound_orders/tracking_update
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
KHO TIKTOK (FBT): Thay thế danh sách vận đơn theo thùng của đơn nhập kho đã gửi, trước khi Delivered hoặc Received.
- HIỆN CHƯA GỌI ĐƯỢC QUA 360: ứng dụng 360 chưa được cấp quyền cho nhóm API kho TikTok (FBT). Cần dùng → liên hệ 360.
- 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. Thay danh sách vận đơn đã lưu theo thùng.
- HTTP 200 vẫn có thể có lỗi nghiệp vụ; kiểm code trước khi dùng kết quả.
- Dùng mã số order_id không có IBR. Gửi đủ parcel_tracking_info cần giữ: phần tử bỏ sót trong danh sách gửi không rỗng sẽ không được giữ. Mỗi thùng được đổi vận đơn tối đa 5 lần; giá trị đầu tiên hoặc gửi lại cùng giá trị đã chuẩn hóa không tính lượt đổi. Lần đổi thứ 6 bị từ chối.
- Thay thế danh sách lưu trữ theo nguyên tắc toàn bộ hoặc không cập nhật; đồng bộ kho nằm ngoài thao tác đó và lỗi đồng bộ kho không được trả về. Đăng ký theo dõi vận chuyển chạy bất đồng bộ.
Request
Địa chỉ
POST https://partner.quantri360.com/v1/tiktok/fbt/202602/inbound_orders/tracking_update
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ó | 100000000000000101 | Mã đơn. |
| parcel_tracking_info | body | object[] | Không | Toàn bộ danh sách vận đơn theo thùng, không phải cập nhật từng phần. | |
| parcel_tracking_info[].provider_name | body | string | Có | OTHER | Tên đơn vị vận chuyển, phải đúng chuỗi viết hoa. |
| parcel_tracking_info[].tracking_number | body | string | Có | DEMO12345678 | Mã vận đơn không rỗng; chỉ chữ ASCII, số, khoảng trắng và dấu gạch ngang; sau khi bỏ khoảng trắng và gạch ngang còn 8–40 ký tự chữ hoặc số. |
| parcel_tracking_info[].carton_number | body | string | Có | C0001 | Mã thùng đã tồn tại trong đơn nhập kho; bỏ khoảng trắng đầu cuối khi đối chiếu. |
Ví dụ request
curl -s -X POST "https://partner.quantri360.com/v1/tiktok/fbt/202602/inbound_orders/tracking_update" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"order_id":"100000000000000101","parcel_tracking_info":[{"provider_name":"OTHER","tracking_number":"DEMO12345678","carton_number":"C0001"}]}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok/fbt/202602/inbound_orders/tracking_update",
params={},
json={
"order_id": "100000000000000101",
"parcel_tracking_info": [
{
"provider_name": "OTHER",
"tracking_number": "DEMO12345678",
"carton_number": "C0001"
}
]
},
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/fbt/202602/inbound_orders/tracking_update');
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":"100000000000000101","parcel_tracking_info":[{"provider_name":"OTHER","tracking_number":"DEMO12345678","carton_number":"C0001"}]}),
});
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/fbt/202602/inbound_orders/tracking_update' . '?' . 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":"100000000000000101","parcel_tracking_info":[{"provider_name":"OTHER","tracking_number":"DEMO12345678","carton_number":"C0001"}]}');
$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ả. |
| request_id | string | DEMO_REQUEST_FBT_01 | Mã truy vết yêu cầu. |
| data | object | Minh họa | Dữ liệu phản hồi. |
Mẫu phản hồi
{
"code": 0,
"message": "Success",
"request_id": "DEMO_REQUEST_FBT_01",
"data": "Minh họa"
}
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