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.
Ứ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.
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
- Đăng ký Partner Quantri360, bật xác thực hai lớp.
- Kết nối gian hàng ở trang danh sách API TikTok Shop.
- Tạo API key ở mục Quản lý API, có thể giới hạn theo IP và đặt hạn dùng.
- Gọi API:
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_timechỉ thấy đơn mới tạo. Đồng bộ định kỳ nên lọc theoupdate_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ơnpage_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-Afterrồ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.