# API TikTok Shop là gì? Các nhóm API và cách ứng dụng cho người bán

API TikTok Shop là cổng để phần mềm đọc và cập nhật dữ liệu gian hàng: đơn hàng, vận chuyển, trả hàng, sản phẩm, tồn kho, quyết toán, affiliate. Thường dùng để kéo đơn về Google Sheets hoặc ERP, đồng bộ tồn kho và đối soát quyết toán. Partner Quantri360 mở các API này, gọi bằng một API key.

| Thông tin | Nội dung |
|---|---|
| Dấu hiệu | Ngày nào cũng xuất đơn TikTok Shop từ Seller Center; Không biết kiện nào đứng yên quá lâu cho tới khi khách hỏi; Trả hàng, hủy đơn tăng mà không rõ lý do nằm ở đâu; Quyết toán từng kỳ phải dò tay với đơn; Tồn kho TikTok Shop lệch với kho tổng |
| Cập nhật | 2026-11-16 |

## API là gì, áp vào TikTok Shop nghĩa là gì?

API là cách hai phần mềm trao đổi dữ liệu theo một quy ước cố định: phần mềm gửi yêu cầu, phía bên kia trả dữ liệu có cấu trúc (JSON). Với TikTok Shop, API thay các thao tác tay trên Seller Center: xuất đơn, theo dõi kiện, xử lý trả hàng, sửa tồn kho, tải quyết toán. Việc lặp lại hằng ngày hoặc nhiều gian hàng thì nên chuyển sang API.

## API TikTok Shop gồm những nhóm nào?

| Nhóm | Dùng để |
|---|---|
| Seller | Đơn hàng, vận chuyển, kiện hàng, FBT, trả hàng, hủy đơn, chăm sóc khách |
| Product | Sản phẩm, danh mục, thuộc tính, tồn kho, khuyến mãi |
| Finance | Quyết toán theo kỳ, giao dịch từng đơn, thanh toán, rút tiền |
| Affiliate | Đơn qua creator, chiến dịch affiliate của người bán |
| Livestream | Chỉ số phiên live bán hàng |
| Video | Chỉ số video bán hàng |

Danh sách đầy đủ kèm tham số: [API TikTok Shop trên Partner Quantri360](https://partner.quantri360.com/sources/tiktok).

## Ứng dụng API TikTok Shop: 5 bài toán thường gặp

**1. Kéo đơn theo giờ về Sheets / ERP.**
Gọi `orders/search` với `sort_field=update_time` và khoảng `update_time_ge` / `update_time_lt`, lặp `page_token` tới hết. Lọc theo thời gian cập nhật thay vì thời gian tạo để bắt cả đơn đổi trạng thái. Cần thêm chi tiết từng đơn thì gọi `GET /order/202309/orders` với danh sách mã đơn.

**2. Theo dõi vận chuyển và giao hàng.**
`POST /fulfillment/202309/packages/search` liệt kê kiện hàng; `GET /fulfillment/202309/orders/{order_id}/tracking` trả hành trình của một đơn. Dùng để cảnh báo kiện đứng yên quá lâu hoặc giao thất bại.

**3. Xử lý trả hàng và hủy đơn.**
`returns/search` và `cancellations/search` trả danh sách yêu cầu kèm lý do và trạng thái. Gom theo lý do để biết sản phẩm nào bị trả nhiều, khâu nào gây hủy. Xem thêm [tỷ lệ hủy đơn TikTok Shop](/blog/ty-le-huy-don-tiktok-shop).

**4. Đồng bộ sản phẩm, tồn kho.**
`POST /product/202309/products/search` lấy danh sách sản phẩm và SKU; nhóm Product có API cập nhật tồn kho và giá khi kho tổng thay đổi. Một nguồn tồn kho dùng chung cho nhiều kênh giúp tránh bán vượt.

**5. Đối soát quyết toán.**
`GET /finance/202309/statements` trả các kỳ quyết toán; `statement_transactions` theo kỳ hoặc theo đơn trả từng khoản phí và tiền về. `GET /finance/202507/orders/unsettled` cho biết đơn nào chưa được quyết toán.

## Trạng thái đơn TikTok Shop cần biết khi đọc API

Trường `status` của đơn cho biết đơn đang ở khâu nào. Báo cáo doanh thu và cảnh báo vận hành nên đọc theo nhóm trạng thái, không theo từng mã riêng lẻ:

| Trạng thái | Nghĩa | Dùng cho |
|---|---|---|
| `UNPAID`, `ON_HOLD` | Chưa thanh toán / đang giữ để kiểm tra | Chưa tính doanh thu |
| `AWAITING_SHIPMENT` | Chờ người bán đóng gói | Cảnh báo đơn sắp trễ hạn gửi |
| `AWAITING_COLLECTION` | Đã đóng gói, chờ đơn vị vận chuyển lấy | Theo dõi kho |
| `PARTIALLY_SHIPPING`, `IN_TRANSIT` | Đang giao | Theo dõi giao hàng |
| `DELIVERED`, `COMPLETED` | Đã giao / hoàn tất | Doanh thu đã giao |
| `CANCELLED` | Đã hủy | Tỷ lệ hủy, lý do hủy |

Đơn đã hoàn tất vẫn có thể phát sinh yêu cầu trả hàng sau đó, nên doanh thu cuối cùng cần đối chiếu thêm nhóm trả hàng và quyết toán.

**Thiết kế bảng đơn.** Mỗi dòng là một dòng sản phẩm trong đơn, khóa là (mã đơn, mã dòng hàng). Mỗi lần đồng bộ ghi đè theo khóa, để đơn đổi trạng thái nhiều lần vẫn chỉ có bản mới nhất.

## Bắt đầu gọi API TikTok Shop qua Partner Quantri360

1. Đăng ký [Partner Quantri360](https://partner.quantri360.com/register), bật xác thực hai lớp.
2. Kết nối gian hàng ở trang [danh sách API TikTok Shop](https://partner.quantri360.com/sources/tiktok).
3. Tạo API key ở mục **Quản lý API**, có thể giới hạn theo IP và đặt hạn dùng.
4. Gọi API:

```bash
curl -s -X POST "https://partner.quantri360.com/v1/tiktok/order/202309/orders/search?page_size=50&sort_field=update_time" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"update_time_ge":1794502800,"update_time_lt":1794589199}'
```

Brand có nhiều gian hàng TikTok Shop thì thêm `platform_shop_id=<mã gian hàng>` vào query.

## Lỗi hay gặp khi ứng dụng API TikTok Shop

- **Bỏ sót đơn đổi trạng thái**: lọc theo `create_time` chỉ thấy đơn mới tạo. Đồng bộ định kỳ nên lọc theo `update_time`.
- **Dừng phân trang sớm**: lặp tới khi không còn `next_page_token`, không dừng khi một trang trả ít hơn `page_size`.
- **Thời gian sai múi giờ**: tham số thời gian là Unix giây (UTC). Đổi từ giờ Việt Nam trước khi gửi.
- **Brand nhiều gian hàng mà không gửi `platform_shop_id`**: request bị từ chối; lấy mã ở `GET /v1/platforms`.
- **429 / 503**: chờ theo `Retry-After` rồi gọi lại.

## Câu hỏi thường gặp

### API TikTok Shop gồm những nhóm nào?

Seller (đơn hàng, vận chuyển, trả hàng, chăm sóc khách), Product (sản phẩm, tồn kho, khuyến mãi), Finance (quyết toán, giao dịch), Affiliate, Livestream và Video.

### Lấy danh sách đơn TikTok Shop bằng API nào?

`POST /order/202309/orders/search`, lọc theo thời gian tạo hoặc cập nhật, phân trang bằng `page_token`.

### Xem tiền quyết toán bằng API nào?

`GET /finance/202309/statements` cho từng kỳ quyết toán; giao dịch chi tiết của một đơn ở `GET /finance/202501/orders/{order_id}/statement_transactions`.

### Tra cứu đơn trả hàng, đơn hủy bằng API nào?

`POST /return_refund/202309/returns/search` và `POST /return_refund/202309/cancellations/search`.

### Gọi API TikTok Shop qua Quantri360 thế nào?

Gửi request tới `https://partner.quantri360.com/v1/tiktok/<đường dẫn API>` với header `Authorization: Bearer <key>`; brand nhiều gian hàng thì thêm `platform_shop_id`.

## Đọc tiếp

- [Đồng bộ đơn TikTok Shop vào Google Sheets](/giai-phap/tiktok-shop-google-sheets)
- [Đổ đơn sàn vào MySQL / PostgreSQL](/giai-phap/don-san-vao-sql)
- [API Shopee: nhóm API và cách ứng dụng](/giai-phap/api-shopee)

---
Nguồn: https://quantri360.com/giai-phap/api-tiktok-shop · Quantri360
