TikTok Shop¶
Đang chạy production
Kết nối qua nút Cấp quyền trong portal, rồi gọi ngay — có sẵn từ gói Growth trở lên và trong bản dùng thử. Chính hạ tầng này cũng đang kéo dữ liệu TikTok Shop hằng ngày cho pipeline nội bộ của Logidata.
Base URL:
Đường dẫn, tham số và response giống hệt TikTok Shop Partner API
v2. Gốc là
https://open-api.tiktokglobalshop.com.
Điều Logidata làm hộ bạn¶
TikTok Shop không chỉ cần gắn header như TikTok Ads. Mỗi request phải kèm một chữ ký HMAC-SHA256 tính trên đường dẫn, timestamp và toàn bộ tham số — sai một ký tự là hỏng cả request, và chữ ký chỉ sống vài phút.
| Việc | Gọi thẳng TikTok Shop | Qua Logidata |
|---|---|---|
| Đăng ký app partner + chờ duyệt | Bạn làm | Đã có |
| Luồng authorize theo từng shop | Bạn dựng | Bấm một nút trên portal |
Tính sign HMAC-SHA256 mỗi request |
Bạn viết và tự debug | Tự động |
app_key, app_secret, access_token |
Bạn giữ | Logidata giữ, bạn không thấy |
cipher riêng theo từng shop |
Bạn tra và gắn | Tự động theo X-Account-Id |
timestamp lệch giờ → chữ ký sai |
Bạn xử lý | Tự động |
Bạn gửi một request bình thường với hai header quen thuộc. Phần còn lại được điền vào giữa đường.
Nhóm dữ liệu¶
Allowlist chỉ đọc, tập trung vào các nhóm Logidata đã dùng thật trong pipeline production:
| Nhóm | Method | Đường dẫn gốc | Dùng để |
|---|---|---|---|
| Shop của kết nối | GET |
/authorization/202309/shops |
Kết nối này đang trỏ tới shop nào. Không cần tham số |
| Đơn hàng | POST |
/order/202309/orders/search |
Tìm đơn theo khoảng thời gian và trạng thái |
| Chi tiết đơn | GET |
/order/202309/orders |
Chi tiết nhiều đơn theo danh sách ID |
| Đối soát | GET |
/finance/202309/statements |
Danh sách statement (kỳ thanh toán) |
| Giao dịch đối soát | GET |
/finance/202501/statements/{statement_id}/statement_transactions |
Từng dòng phí, hoa hồng, khấu trừ trong một statement |
| Đơn Affiliate | POST |
/affiliate_seller/202410/orders/search |
Đơn phát sinh qua affiliate và hoa hồng tương ứng |
Hai endpoint tìm kiếm là POST, dù chúng thuần đọc
TikTok Shop nhận bộ lọc trong JSON body chứ không phải query string, nên
/orders/search và /affiliate_seller/.../orders/search phải gọi bằng
POST kèm Content-Type: application/json. Gọi chúng bằng GET sẽ nhận
403 path_not_allowed. Allowlist vẫn chỉ đọc: PUT, PATCH, DELETE
bị chặn ở mọi đường dẫn, và POST chỉ mở cho đúng hai endpoint trong bảng.
Sản phẩm, kho vận và hoàn/trả đang được rà soát trước khi đưa vào allowlist.
TikTok Shop đánh phiên bản endpoint theo tháng
202309, 202410, 202501 trong đường dẫn là phiên bản endpoint do TikTok
đặt, không phải tham số ngày. TikTok cho hai phiên bản chạy song song một
thời gian rồi khai tử bản cũ. Logidata theo dõi việc này và báo trước qua
Lịch sử thay đổi khi allowlist phải đổi — đây là loại
bảo trì mà tích hợp tự viết thường bỏ quên cho tới lúc pipeline chết.
Khác biệt cần biết trước khi thiết kế pipeline¶
Đối soát là hai tầng. Doanh thu thực nhận không nằm trong đơn hàng. Bạn phải lấy danh sách statement, rồi với mỗi statement lấy tiếp các dòng giao dịch. Một kỳ đối soát sinh ra nhiều request — hãy tính vào hạn mức.
Số liệu đơn thay đổi sau khi tạo. Trạng thái, phí và hoàn trả cập nhật nhiều ngày sau ngày đặt hàng. Kéo lại cửa sổ 2–3 ngày gần nhất mỗi lần chạy thay vì chỉ kéo ngày hôm nay — đây là nhịp mà pipeline nội bộ của Logidata đang dùng.
Ghép dữ liệu với TikTok Ads là việc thủ công. Đơn hàng ở TikTok Shop và chi phí quảng cáo ở TikTok Ads là hai hệ thống ID khác nhau. Nếu bạn cần lãi lỗ theo đơn, xem Chuẩn hoá dữ liệu — Logidata đã có sẵn lược đồ ghép hai nguồn này.
Xác thực và mã lỗi¶
Giống hệt mọi nền tảng khác: X-API-Key + X-Account-Id (xem Xác
thực), và cùng bộ mã lỗi. X-Account-Id
ở đây là giá trị portal hiển thị cho kết nối TikTok Shop của bạn — dán nguyên
văn, không phải shop ID và không phải Business Center ID. Logidata dùng nó để tra
ra shop, cipher và token tương ứng.
Hai mã lỗi chỉ TikTok Shop mới có:
| Mã | Nghĩa |
|---|---|
shop_not_authorized |
Kết nối không còn shop nào đang uỷ quyền. Cấp quyền lại trên portal. |
ambiguous_shop |
Một tài khoản uỷ quyền cho nhiều shop. Thêm tham số shop_id (danh sách shop nằm trong thông báo lỗi, hoặc gọi /authorization/202309/shops). |