tiktok.fulfillment.202309.packages.search
POST/fulfillment/202309/packages/searchGọi qua 360: POST https://partner.quantri360.com/v1/tiktok/fulfillment/202309/packages/search
Mô tả API
Tìm gói hàng theo thời gian tạo / cập nhật và trạng thái gói — mỗi gói kèm mã vận đơn, đơn vị vận chuyển và các đơn trong gói.
- Gọi qua /v1/tiktok/fulfillment/202309/packages/search 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 chỉ đọc; code = 0 mới là thành công.
- Body rỗng
{}= mọi gói, mới nhất trước.
Request
Địa chỉ
POST https://partner.quantri360.com/v1/tiktok/fulfillment/202309/packages/search
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ả |
|---|---|---|---|---|---|
| page_size | query | int | Có | 50 | Số gói mỗi trang: 1–50. |
| page_token | query | string | Không | next_page_token của trang trước. | |
| sort_field | query | string | Không | update_time | create_time (mặc định) · update_time · order_pay_time. |
| sort_order | query | string | Không | DESC | ASC · DESC (mặc định). |
| create_time_ge | body | int | Không | Tạo từ (Unix giây, ≥). | |
| create_time_lt | body | int | Không | Tạo trước (Unix giây, <). | |
| update_time_ge | body | int | Không | 1792650000 | Cập nhật từ (Unix giây, ≥). |
| update_time_lt | body | int | Không | 1792736400 | Cập nhật trước (Unix giây, <). |
| package_status | body | string | Không | Lọc một trạng thái: TO_FULFILL (chờ gửi) · PROCESSING (đã sắp xếp, chờ ĐVVC lấy) · FULFILLING (ĐVVC đã lấy, đang giao) · COMPLETED (đã giao) · CANCELLED (đã hủy — thường do thất lạc / hỏng). |
Phân trang
Lặp khi data.next_page_token khác rỗng: gửi lại đúng body, thêm query page_token = data.next_page_token.
Ví dụ request
curl -s -X POST "https://partner.quantri360.com/v1/tiktok/fulfillment/202309/packages/search?platform_shop_id=7494000000000000000&page_size=50&sort_field=update_time" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"update_time_ge":1792650000,"update_time_lt":1792736400}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok/fulfillment/202309/packages/search",
params={
"platform_shop_id": "7494000000000000000",
"page_size": 50,
"sort_field": "update_time"
},
json={
"update_time_ge": 1792650000,
"update_time_lt": 1792736400
},
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/fulfillment/202309/packages/search');
for (const [k, v] of Object.entries({"platform_shop_id":"7494000000000000000","page_size":50,"sort_field":"update_time"})) 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({"update_time_ge":1792650000,"update_time_lt":1792736400}),
});
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/fulfillment/202309/packages/search' . '?' . http_build_query(['platform_shop_id' => '7494000000000000000', 'page_size' => 50, 'sort_field' => 'update_time']);
$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, '{"update_time_ge":1792650000,"update_time_lt":1792736400}');
$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 | 0 = thành công; khác 0 xem message (105001–105003 = token, 360 đã tự làm mới một lần). |
| message | string | Success | Thông điệp của TikTok. |
| request_id | string | DEMO_REQUEST_0001 | Mã request TikTok. |
| data | object | Dữ liệu. | |
| total_count | number | 1 | Tổng số gói khớp bộ lọc. |
| next_page_token | string | Rỗng = hết. | |
| packages | object[] | Gói hàng. | |
| id | string | 100000000000000001 | Mã gói — xem chi tiết: GET /fulfillment/202309/packages/{package_id}. |
| status | string | FULFILLING | `TO_FULFILL` (chờ gửi) · `PROCESSING` (đã sắp xếp, chờ ĐVVC lấy) · `FULFILLING` (ĐVVC đã lấy, đang giao) · `COMPLETED` (đã giao) · `CANCELLED` (đã hủy — thường do thất lạc / hỏng). |
| tracking_number | string | VNDEMO0001 | Mã vận đơn. |
| shipping_provider_id | string | 100000000000000001 | |
| shipping_provider_name | string | Mẫu minh họa | |
| orders | object[] | Đơn trong gói. | |
| id | string | 100000000000000001 | |
| skus | object[] | {id, name, image_url, quantity}. | |
| id | … | 100000000000000001 | Mã. Trường cũ, nên hạn chế dùng. |
| name | … | Mẫu minh họa | Tên. Trường cũ, nên hạn chế dùng. |
| image_url | … | https://example.com/tep-minh-hoa.pdf | Ảnh url. Trường cũ, nên hạn chế dùng. |
| quantity | … | Số lượng. Trường cũ, nên hạn chế dùng. | |
| order_line_item_ids | string[] | ||
| create_time | number | 1792650000 | Unix giây. |
| update_time | number | 1792650000 | Unix giây. |
Mẫu phản hồi
{
"code": 0,
"message": "Success",
"request_id": "DEMO_REQUEST_0001",
"data": {
"total_count": 1,
"next_page_token": "",
"packages": [
{
"id": "100000000000000001",
"status": "FULFILLING",
"tracking_number": "VNDEMO0001",
"shipping_provider_id": "100000000000000001",
"shipping_provider_name": "Mẫu minh họa",
"orders": [
{
"id": "100000000000000001",
"skus": [
{
"id": "100000000000000001",
"name": "Mẫu minh họa",
"image_url": "https://example.com/tep-minh-hoa.pdf",
"quantity": ""
}
]
}
],
"order_line_item_ids": [
"100000000000000001"
],
"create_time": 1792650000,
"update_time": 1792650000
}
]
}
}
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