Hướng dẫn tích hợp TikTok Shop API: OAuth, chữ ký và webhook
Hướng dẫn tích hợp TikTok Shop API với OAuth, ký HMAC, xác thực webhook, giới hạn tốc độ và cách xử lý các lỗi thường gặp.
Long Nguyen
Lập trình viên Fullstack · Kỹ sư AI · Nhà nghiên cứu
Tích hợp TikTok Shop API hoạt động như thế nào?
Một tích hợp TikTok Shop API gồm bốn thành phần trải trên ba host khác nhau: người bán cấp quyền, trao đổi token, gọi Business API có chữ ký và nhận webhook. Phần lớn lần triển khai đầu tiên thất bại do gọi sai host hoặc ký sai dữ liệu, chứ không phải vì bản thân endpoint.
| Bước | Host hoặc cơ chế | Chức năng |
|---|---|---|
| 1. Người bán cấp quyền cho ứng dụng | services.tiktokshop.com (toàn cầu) hoặc services.us.tiktokshop.com (Mỹ), đường dẫn /open/authorize?service_id=... |
Trả về auth_code tạm thời đến URL chuyển hướng của bạn |
| 2. Trao đổi token | auth.tiktok-shops.com, /api/v2/token/get và /api/v2/token/refresh |
Đổi mã lấy access token và refresh token |
| 3. Gọi Business API | open-api.tiktokglobalshop.com, /{category}/{version}/{resource} |
Sản phẩm, đơn hàng, hoàn tất đơn, trả hàng, tài chính và cấu hình webhook |
| 4. Webhook | Một endpoint HTTPS do bạn cung cấp | Đẩy các sự kiện về đơn hàng, kiện hàng, sản phẩm và cấp quyền đến hệ thống của bạn |
Host token và host Business API là hai hệ thống khác nhau. Ngoài ra, trao đổi token là một yêu cầu GET chứa app secret trong query string. Điều này khá khác thường với các lập trình viên quen với OAuth 2.0 POST tiêu chuẩn, nên nội dung này được tách thành một phần riêng bên dưới.
Cấp quyền TikTok Shop API: Partner Center, ứng dụng và scope
Mọi thứ bắt đầu tại TikTok Shop Partner Center. Trong mục App & Service, bạn tạo ứng dụng; trang chi tiết ứng dụng hiển thị ba giá trị sẽ được sử dụng thường xuyên: app_key, app_secret và service_id. service_id dùng để tạo liên kết cấp quyền cho người bán; key và secret dùng để nhận diện ứng dụng, còn secret được dùng để ký mọi yêu cầu, vì vậy chỉ được lưu trên server.
Scope cần được cân nhắc kỹ hơn mức thông thường:
- Bạn bật scope cho ứng dụng trong Partner Center. Hướng dẫn cấp quyền của TikTok cảnh báo rằng việc bật những scope không cần thiết có thể khiến quá trình xét duyệt ứng dụng kéo dài hơn và làm giảm tỷ lệ người bán chấp thuận cấp quyền.
- Các scope thực tế được người bán chấp thuận sẽ trả về trong trường
granted_scopescủa phản hồi token. Lỗi105005(bị từ chối quyền truy cập) có nghĩa là ứng dụng hoặc token đó không có scope mà endpoint yêu cầu. Nếu vấn đề nằm ở token, người bán phải cấp quyền lại để nhận token có scope tương ứng. - Nếu ứng dụng đã cấu hình danh sách IP được phép, các yêu cầu xuất phát từ địa chỉ không nằm trong danh sách sẽ thất bại với lỗi
36009033.
Khuyến nghị của tôi là chỉ yêu cầu các scope cần cho những tính năng bạn phát hành trước, sau đó bổ sung scope theo từng tính năng. Màn hình cấp quyền gọn gàng thường có tỷ lệ chuyển đổi tốt hơn. Hơn nữa, mỗi thay đổi scope về sau đều yêu cầu tất cả người bán đã kết nối cấp quyền lại, vì vậy lập kế hoạch nhóm scope ngay từ đầu sẽ tiết kiệm hơn việc bổ sung từng scope một cách bị động.
Để thử nghiệm, Partner Center cung cấp Seller Center development shops và công cụ kiểm thử API. Trong mục Development Kits còn có Webhook Log, nơi hiển thị dữ liệu TikTok Shop đã gửi và phản hồi từ server của bạn. Đây là cách nhanh nhất để gỡ lỗi endpoint webhook.
TikTok Shop OAuth: liên kết cấp quyền, auth_code và trao đổi token
- Đưa người bán đến liên kết cấp quyền của bạn. Thêm một giá trị
statekhó đoán, lưu giá trị này ở phía server và kiểm tra khi người bán quay lại (bảo vệ CSRF). - TikTok chuyển hướng người bán đến Redirect URL của bạn với
?code=...&state=.... Nếu người bán từ chối, họ vẫn được chuyển hướng nhưng vớicode=null&error=auth_denied. - Trao đổi
code(được gọi làauth_codetrong Token API) ngay lập tức. Mã hết hạn sau 30 phút và chỉ sử dụng được một lần. Dùng lại hoặc trì hoãn việc trao đổi sẽ tạo ra lỗi36004004. - Lưu các token trả về, thông tin nhận diện shop và các scope đã được cấp.
Các endpoint token có ba điểm đặc biệt cần biết trước khi viết client:
- Cả trao đổi token lẫn làm mới token đều là yêu cầu
GET, trong đóapp_key,app_secretvà code hoặc refresh token được truyền trong query string. grant_typephải chính xác làauthorized_codekhi trao đổi token (không phảiauthorization_codetheo chuẩn thông thường) và làrefresh_tokenkhi làm mới token.- Phản hồi thành công có dạng
code: 0trong thân JSON, vì vậy cần kiểm tra thân phản hồi chứ không chỉ dựa vào HTTP status.
import requests
AUTH_HOST = "https://auth.tiktok-shops.com"
def _token_call(path, params):
resp = requests.get(f"{AUTH_HOST}{path}", params=params, timeout=15)
payload = resp.json()
if payload.get("code") != 0: # success is code 0 in the body
raise RuntimeError(f"token call failed: code={payload.get('code')} "
f"message={payload.get('message')} "
f"request_id={payload.get('request_id')}")
return payload["data"]
def exchange_auth_code(app_key, app_secret, auth_code):
return _token_call("/api/v2/token/get", {
"app_key": app_key,
"app_secret": app_secret,
"auth_code": auth_code,
"grant_type": "authorized_code", # not "authorization_code"
})
def refresh_tokens(app_key, app_secret, refresh_token):
return _token_call("/api/v2/token/refresh", {
"app_key": app_key,
"app_secret": app_secret,
"refresh_token": refresh_token,
"grant_type": "refresh_token",
})
Phản hồi chứa access_token, access_token_expire_in và refresh_token_expire_in dưới dạng Unix timestamp, cùng với open_id, seller_name, seller_base_region, user_type và granted_scopes. Theo mặc định, access token có hiệu lực trong 7 ngày. Refresh token hết hạn khi thời hạn cấp quyền mà người bán chấp thuận kết thúc, vì vậy đây không phải là thông tin xác thực vĩnh viễn.
Một số hệ quả thực tế đối với thiết kế hệ thống:
- Lưu cả hai timestamp hết hạn theo từng shop và chủ động làm mới token trước khi access token hết hạn, thay vì chờ phản hồi
105002(thông tin xác thực hết hạn) xuất hiện giữa lúc đồng bộ đơn hàng. - Coi mọi phản hồi làm mới token là thông tin chính thức và thay thế cả hai token bằng các giá trị mới được trả về.
- Vì app secret được truyền trong query string, hãy loại trừ hai URL này khỏi access log, APM trace và báo cáo lỗi.
- Dùng
user_typeđể xác nhận loại người dùng đã cấp quyền cho bạn (seller, creator hoặc partner) trước khi chuyển token đến các endpoint giới hạn theo seller.
Cách ký yêu cầu TikTok Shop API bằng HMAC-SHA256
Mọi yêu cầu đến Business API đều cần tham số query sign. Yêu cầu không có chữ ký hợp lệ sẽ bị từ chối. Hướng dẫn ký của TikTok định nghĩa thuật toán; về cơ bản, bạn cần xây dựng chuỗi qua sáu bước:
- Lấy tất cả query parameter ngoại trừ
signvàaccess_token, sau đó sắp xếp key theo thứ tự alphabet. - Nối chúng theo dạng
{key}{value}, không có dấu phân cách. - Đặt request path ở đầu chuỗi, bao gồm category, version và resource (ví dụ
/authorization/202309/shops). - Trừ khi content type là
multipart/form-data, nối thêm request body. - Bọc toàn bộ chuỗi bằng app secret ở cả hai đầu:
secret + string + secret. - Tính HMAC-SHA256 của chuỗi đó, sử dụng app secret làm key, rồi mã hóa kết quả dưới dạng hex.
import hashlib, hmac
from urllib.parse import urlsplit, parse_qsl
def sign_request(url, body, app_secret, content_type="application/json"):
parts = urlsplit(url)
params = {k: v for k, v in parse_qsl(parts.query, keep_blank_values=True)
if k not in ("sign", "access_token")}
base = parts.path + "".join(f"{k}{params[k]}" for k in sorted(params))
if not content_type.startswith("multipart/form-data"):
base += body.decode("utf-8") # the exact bytes you will send
wrapped = app_secret + base + app_secret
return hmac.new(app_secret.encode(), wrapped.encode(),
hashlib.sha256).hexdigest()
Để kiểm tra một cách triển khai, hãy dùng ví dụ hoàn chỉnh trong hướng dẫn: app secret e59af819cc, path /authorization/202309/shops, app_key=29a39d và timestamp=1623812664. Chuỗi được ký cuối cùng là e59af819cc/authorization/202309/shopsapp_key29a39dtimestamp1623812664e59af819cc và chữ ký là b596b73e0cc6de07ac26f036364178ab16b0a907af13d43f0a0cd2345f582dc8. Hàm trên tạo ra chính xác kết quả này.
Khi TikTok trả về lỗi chữ ký, nguyên nhân gần như luôn nằm ở một trong các điểm sau:
| Lỗi thường gặp | Vì sao làm hỏng chữ ký |
|---|---|
| Tuần tự hóa lại JSON body sau khi ký | Hướng dẫn yêu cầu ký đúng các byte sẽ được gửi đi. Thay đổi thứ tự key, khoảng trắng hoặc cách escape sẽ tạo ra hash khác. Hãy tuần tự hóa một lần, ký các byte đó và gửi chính các byte đó. |
| Đưa access token vào chữ ký | Từ API version 202309 trở đi, token được truyền trong header x-tts-access-token và không nằm trong chuỗi được ký. Các query parameter access_token của API cũ cũng bị loại trừ. |
| Dùng SHA-256 thông thường | Bắt buộc phải dùng HMAC-SHA256 với app secret làm key. |
| Bỏ quên path hoặc đoạn version | Hãy ký path chính xác như phần xuất hiện sau host. |
| Timestamp không đúng | Timestamp phải là Unix timestamp 10 chữ số tính theo giây, nằm trong khoảng từ 5 phút trước đến 30 giây sau đồng hồ của nền tảng. Dùng mili giây sẽ thất bại. |
| Sai app key hoặc secret | Đây là nguyên nhân phổ biến nhất: dùng key của ứng dụng này cùng secret của ứng dụng khác. |
Lưu ý rằng shop_cipher, nếu endpoint yêu cầu, là query parameter thông thường và phải được đưa vào chuỗi được ký.
Lệnh gọi đầu tiên: Get Authorized Shops và shop_cipher
Lệnh gọi đầu tiên được khuyến nghị là Get Authorized Shops, GET /authorization/202309/shops. Endpoint này cho biết những shop nào đã cấp quyền cho ứng dụng của bạn và trả về các định danh cần dùng cho những thao tác tiếp theo, bao gồm shop_cipher được mã hóa.
import json, time, requests
from urllib.parse import urlencode
API_HOST = "https://open-api.tiktokglobalshop.com"
def call_api(method, path, app_key, app_secret, access_token,
query=None, body=None):
query = {"app_key": app_key, "timestamp": str(int(time.time())),
**(query or {})}
raw = b"" if body is None else json.dumps(body, separators=(",", ":")).encode()
url = f"{API_HOST}{path}?{urlencode(query)}"
query["sign"] = sign_request(url, raw, app_secret)
resp = requests.request(
method, f"{API_HOST}{path}", params=query, data=raw, timeout=20,
headers={"x-tts-access-token": access_token,
"content-type": "application/json"})
return resp.status_code, resp.json()
# First call: which shops did this seller authorize?
status, data = call_api("GET", "/authorization/202309/shops",
APP_KEY, APP_SECRET, access_token)
Các lệnh gọi Business API sử dụng app_key, sign và timestamp trong query, cùng với header x-tts-access-token và content-type. Đoạn category trong path dùng để nhóm API theo lĩnh vực kinh doanh:
| Lĩnh vực | Đoạn category | Resource ví dụ |
|---|---|---|
| Cấp quyền | authorization |
shops |
| Sản phẩm | product |
products, categories, inventory |
| Đơn hàng | order |
orders |
| Hoàn tất đơn | fulfillment |
packages, shipping_documents |
| Trả hàng và hoàn tiền | return_refund |
returns, refunds, cancellations |
| Logistics | logistics |
warehouses, delivery_options, shipping_providers |
| Tài chính | finance |
payments, settlements |
| Sự kiện (webhook) | event |
webhooks |
Điểm dễ nhầm ở đây là shop_cipher phụ thuộc vào từng endpoint. Một số endpoint bắt buộc tham số này (bỏ qua sẽ trả về 106013), trong khi endpoint khác lại từ chối vì không cần tham số (phản hồi 36009004 với thông báo cho biết tham số này không được yêu cầu). Đừng phỏng đoán: hãy kiểm tra yêu cầu trên trang tài liệu của từng endpoint và lưu cờ cấu hình riêng cho từng endpoint trong lớp wrapper của client.
Webhook TikTok Shop: thiết lập, xác thực và thử lại
Webhook đẩy sự kiện đến một URL HTTPS mà bạn đăng ký. Bạn có thể cấu hình trong Partner Center (App & Service, sau đó chọn ứng dụng, Basic Information, Developing) hoặc theo từng shop thông qua Events API với PUT /event/202309/webhooks và body chứa address cùng event_type. Cả hai cách đều ghi vào cùng một cấu hình bên dưới, vì vậy hãy chọn một nguồn dữ liệu chính. Hướng dẫn cấu hình webhook của TikTok quy định các nguyên tắc gửi như sau:
| Yêu cầu | Quy tắc |
|---|---|
| URL | HTTPS, TLS 1.2 trở lên, dùng tên miền (không dùng địa chỉ IP), không có port tùy chỉnh |
| Xác nhận đã nhận | Trả về HTTP 200 với body rỗng trong vòng 3 giây |
| Từ chối chữ ký không hợp lệ | Trả về 401. Đây được tính là lần gửi thất bại, không phải xác nhận đã nhận |
| Đảm bảo gửi | Ít nhất một lần, vì vậy sẽ có sự kiện trùng lặp |
| Thử lại | 2 phút sau lần thất bại đầu tiên, sau đó là 30 phút, 3 giờ và 12 giờ kể từ lần thất bại trước đó. Việc thử lại dừng sau khi lần thử thứ tư thất bại |
Xác thực chữ ký
Chữ ký webhook không giống chữ ký của API request. TikTok đặt chữ ký trong header Authorization (không có tiền tố Bearer) dưới dạng HMAC-SHA256 hex viết thường. Chữ ký được tạo từ app_key nối với raw request body, sử dụng app secret làm key. Hãy xác thực trên raw byte trước khi phân tích cú pháp và so sánh bằng phép so sánh constant-time.
import hashlib, hmac
def verify_webhook(app_key, app_secret, raw_body, authorization):
expected = hmac.new(app_secret.encode(), app_key.encode() + raw_body,
hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, (authorization or "").strip().lower())
Ví dụ chính thức có thể tái hiện: app key abcdef, app secret 123 và payload đơn hàng mẫu trong phần tổng quan webhook tạo ra 5dec0f11ec2f6783b8deee53c9ffbf8d024302f7c7e7fa55a35d17629031ac05. Hàm trên cho kết quả khớp chính xác và sẽ thất bại nếu chỉ một byte trong body thay đổi.
Các sự kiện đáng đăng ký
Danh sách sự kiện khá dài, vì vậy hãy chọn theo chức năng ứng dụng của bạn:
| event_type | Dùng để |
|---|---|
ORDER_STATUS_CHANGE |
Đồng bộ đơn hàng mới và thay đổi trạng thái |
RECIPIENT_ADDRESS_UPDATE, PACKAGE_UPDATE |
Cập nhật thông tin giao hàng và hoàn tất đơn |
CANCELLATION_STATUS_CHANGE, RETURN_STATUS_CHANGE, REVERSE_STATUS_UPDATE |
Xử lý hủy đơn, trả hàng và yêu cầu hoàn tiền của người mua |
PRODUCT_STATUS_CHANGE, PRODUCT_AUDIT_STATUS_CHANGE, PRODUCT_CREATION, PRODUCT_INFORMATION_CHANGE, PRODUCT_CATEGORY_CHANGE |
Theo dõi trạng thái listing và kết quả kiểm duyệt |
SELLER_DEAUTHORIZATION |
Dừng gọi API cho shop đó và đánh dấu kết nối là không hoạt động |
UPCOMING_AUTHORIZATION_EXPIRATION |
Cảnh báo người bán và đưa họ qua quy trình cấp quyền lại. Sự kiện được gửi 30 ngày trước khi hết hạn, sau đó gửi hằng ngày cho đến khi cấp quyền lại |
Hãy thiết kế listener theo trình tự xác thực, lưu dữ liệu, xác nhận đã nhận rồi xử lý bất đồng bộ. Loại bỏ sự kiện trùng lặp dựa trên tts_notification_id và không chỉ phân nhánh theo trường số type, vì tài liệu chưa công bố ánh xạ số đầy đủ cho mọi chủ đề. Thay vào đó, hãy dùng event_type đã đăng ký và schema payload của chủ đề tương ứng. Quan trọng nhất, TikTok khuyến nghị không coi webhook là nguồn dữ liệu duy nhất: hãy duy trì tác vụ polling theo lịch để đối soát đơn hàng, kiện hàng, sản phẩm, hàng trả lại và đơn hủy, nhằm tránh một lần giao thất bại sau chuỗi thử lại 12 giờ biến thành đơn hàng bị bỏ sót.
Giới hạn tốc độ TikTok Shop API và cách xử lý lỗi 429
Bạn sẽ thấy các con số cố định về giới hạn TikTok Shop trong những bài viết của bên thứ ba. Đừng mặc định sử dụng chúng. Trang giới hạn tốc độ của TikTok cho biết nền tảng dùng cơ chế phân bổ QPS động, dựa trên các yếu tố như số shop đã cấp quyền, loại endpoint và tải thực tế của nền tảng; TikTok không công bố một mức QPS cố định duy nhất. Nếu tài liệu của một endpoint công bố giới hạn riêng, giới hạn đó được ưu tiên.
Tài liệu chính thức cung cấp mô hình phân lập và mức khởi đầu như sau:
- Đơn vị phân lập nhỏ nhất là app ID kết hợp với shop đã cấp quyền. Cùng một ứng dụng có dung lượng riêng cho từng shop, và cùng một shop có dung lượng riêng cho từng ứng dụng, vì vậy một shop bận rộn sẽ không làm nghẽn hàng đợi của shop khác. Tuy nhiên, một số endpoint được giới hạn theo app.
- Nhiều shop đã cấp quyền thường đồng nghĩa với tổng dung lượng lớn hơn, nhưng mức tăng không tuyến tính và cũng không diễn ra ngay lập tức.
- Lỗi 429 không phải lúc nào cũng do bạn: cơ chế giới hạn bảo vệ ở cấp endpoint hoặc cấp nền tảng có thể kích hoạt ngay cả khi lưu lượng thấp.
| Loại endpoint | Mức khởi đầu đề xuất theo app và shop |
|---|---|
| Ghi dữ liệu nặng hoặc phân tích phức tạp | 0,2 đến 1 yêu cầu/giây |
| Ghi dữ liệu tiêu chuẩn | 1 đến 3 yêu cầu/giây (dùng idempotency trước khi bật retry) |
| Đọc hoặc đồng bộ tiêu chuẩn | 3 đến 10 yêu cầu/giây |
| Đọc nhẹ hoặc xử lý theo batch | 5 đến 20 yêu cầu/giây |
TikTok xem đây là mức khởi đầu thận trọng cho việc điều tiết ở phía client, không phải quota được đảm bảo. Hãy tăng 20 đến 30% sau mỗi 10 đến 15 phút và dừng lại khi bắt đầu xuất hiện giới hạn tốc độ.
Coi cả HTTP 429 và mã nghiệp vụ 36009002 là dấu hiệu bị giới hạn tốc độ, đồng thời ghi log cả hai. Mã 503 là trường hợp khác (dịch vụ không khả dụng), vì vậy hãy chờ trong thời gian ngắn thay vì áp dụng hình phạt rate limit. Mẫu retry được tài liệu hóa là exponential backoff kèm jitter và không được thử lại sớm hơn giá trị trong header Retry-After. Tài liệu đưa ra độ trễ cơ sở 1 giây, giới hạn cục bộ 60 giây và khoảng 5 lần retry làm ví dụ; bạn nên điều chỉnh theo khối lượng công việc.
import random
def backoff_seconds(retry, retry_after=None, base=1.0, cap=60.0):
wait = min(base * (2 ** retry) + random.uniform(0, 0.5), cap)
return max(wait, retry_after) if retry_after is not None else wait
Hai thói quen giúp giảm việc bị giới hạn tốc độ hiệu quả hơn bất kỳ đoạn mã backoff nào: ưu tiên endpoint batch (thông thường được tính một lần cho mỗi HTTP request, không phải mỗi item, trừ khi endpoint quy định khác) và ưu tiên đồng bộ tăng dần với bộ lọc theo thời gian thay đổi thay vì tải toàn bộ dữ liệu. Nếu sản phẩm của bạn kết nối nhiều người bán, hãy xây dựng một bộ giới hạn cho từng cặp app-shop và đưa yêu cầu của mỗi shop vào hàng đợi riêng. Cách lập lịch đa người bán này là bước biến phần lớn tích hợp TikTok Shop từ một script viết cuối tuần thành hệ thống thực thụ; đây cũng là loại công việc được cung cấp qua dịch vụ tích hợp TikTok Shop API cho người bán social commerce.
API version: Vì sao 202309 quan trọng?
TikTok quản lý version riêng cho từng API; tên version thể hiện năm và tháng phát hành. Version mới thường được phát hành hằng tháng, nhưng không phải API nào cũng thay đổi mỗi tháng, vì vậy các endpoint khác nhau trong cùng một tích hợp có thể hợp lệ khi sử dụng các version khác nhau.
- Từ kiểu version 202309, version trở thành một đoạn trong path:
https://open-api.tiktokglobalshop.com/{category}/{version}/{resource}. API cũ truyềnversiondưới dạng query parameter. - Ở version 202309, access token được chuyển từ query string sang header
x-tts-access-token. - Sau khi version mới được phát hành, version trước đó vẫn khả dụng ít nhất 2 tháng. Việc ngừng vĩnh viễn sẽ được thông báo trong changelog trước ít nhất 2 tháng.
- Version không hợp lệ hoặc đã ngừng hoạt động trả về
36009014, dù một số phản hồi từ gateway vẫn hiển thị36009004kèm thông báo version không hợp lệ. Hãy kiểm tra cả nội dung thông báo bên cạnh mã lỗi.
Version cũng có hệ quả về nghiệp vụ. TikTok Shop đã bổ sung trạng thái đơn hàng On Hold: trong một giờ sau khi thanh toán, người mua có thể hủy mà không cần người bán phê duyệt, người bán không thể thao tác trên đơn và các trường địa chỉ sẽ được trả về rỗng. Chỉ phản hồi đơn hàng v202309 mới có trường is_on_hold_order; ứng dụng dùng version cũ không thể nhận diện đáng tin cậy các đơn này. Nếu đồng bộ đơn hàng vẫn chạy trên version cũ, đây là phần cần được nâng cấp trước tiên.
Hãy cố định version rõ ràng trong client, kiểm tra changelog theo lịch và đọc tài liệu của version mục tiêu (path, header, field và scope) trước khi nâng cấp từng endpoint.
Các lỗi TikTok Shop API thường gặp và ý nghĩa
| Mã | Ý nghĩa | Điểm đầu tiên cần kiểm tra |
|---|---|---|
106001 |
sign không hợp lệ |
Path đã ký, đúng byte của body, timestamp và app secret |
105002 |
Access token hết hạn | Thực hiện quy trình refresh rồi thử lại một lần |
105005 |
Bị từ chối truy cập vì thiếu scope | Scope của ứng dụng trong Manage API, sau đó kiểm tra granted_scopes của token |
101000 |
Query hoặc header không hợp lệ (token hoặc cipher) | user_type của token có phù hợp với endpoint không và token có thuộc shop trong shop_cipher không |
106013 |
Thiếu shop_cipher |
Lấy giá trị này từ Get Authorized Shops |
36009004 |
Được dùng cho nhiều lỗi xác thực request | Đọc thông báo: thiếu chữ ký, header token sai, app key sai, timestamp nằm ngoài khoảng cho phép hoặc có shop_cipher không cần thiết |
36009002 |
Bị giới hạn tốc độ | Giảm tốc độ và tuân thủ Retry-After |
36009010 |
HTTP method không hợp lệ | Dùng chính xác method trong tài liệu endpoint |
36009014 |
API version không hợp lệ | Đoạn version trong path |
36009033 |
IP không nằm trong danh sách được phép | Cài đặt App and Service trong Partner Center |
36004004 |
Auth code không hợp lệ | Code đã được dùng, cũ hơn 30 phút hoặc không đúng |
Hai nguyên tắc giúp rút ngắn thời gian gỡ lỗi. Không bao giờ chỉ phân nhánh logic theo 36009004; hãy kết hợp mã này với từ khóa trong message. Đồng thời, luôn ghi lại toàn bộ phản hồi cùng request_id, vì đây là mã TikTok Support cần để tra soát.
Checklist đưa tích hợp TikTok Shop vào production
- Lưu trữ mã hóa
app_secret, access token và refresh token; loại bỏ URL của token endpoint khỏi log. - Làm mới token theo lịch bằng timestamp hết hạn đã lưu; theo dõi riêng ngày kết thúc cấp quyền của từng shop.
- Tuần tự hóa request body một lần và ký đúng những byte sẽ gửi.
- Duy trì cấu hình riêng theo từng endpoint cho
shop_cipher, HTTP method và API version. - Dùng một rate limiter và một hàng đợi cho mỗi cặp app-shop, ưu tiên endpoint batch và backoff khi gặp cả 429 lẫn
36009002. - Xác thực chữ ký webhook trên raw body, phản hồi 200 nhanh, lưu dữ liệu trước rồi xử lý sau và loại bỏ trùng lặp dựa trên
tts_notification_id. - Đăng ký
SELLER_DEAUTHORIZATIONvàUPCOMING_AUTHORIZATION_EXPIRATIONđể quyền truy cập shop không bị mất mà không có cảnh báo. - Đối soát đơn hàng, kiện hàng, sản phẩm và hàng trả lại bằng polling theo lịch, để webhook không trở thành nguồn dữ liệu duy nhất.
- Theo dõi changelog để biết version sắp ngừng hoạt động và các field bắt buộc mới.
Nếu bạn muốn có đội ngũ xây dựng và duy trì hệ thống thay vì tự triển khai, hãy yêu cầu báo giá miễn phí và mô tả quy trình TikTok Shop bạn cần.
CÂU HỎI THƯỜNG GẶP
Câu hỏi thường gặp
Làm thế nào để được cấp quyền truy cập TikTok Shop API?
Đăng ký trong TikTok Shop Partner Center, tạo ứng dụng trong mục App & Service và bật các API scope cần cho tính năng của bạn. Trang chi tiết ứng dụng cung cấp app_key, app_secret và service_id. Sau đó, từng người bán sẽ cấp quyền cho ứng dụng thông qua liên kết cấp quyền; bạn trao đổi auth_code nhận được để lấy access token và refresh token.
Access token của TikTok Shop có hiệu lực trong bao lâu?
Theo mặc định, access token có hiệu lực trong 7 ngày và phản hồi chứa access_token_expire_in dưới dạng Unix timestamp. Refresh token hết hạn khi thời hạn cấp quyền mà người bán chấp thuận kết thúc. Hãy chủ động làm mới token trước khi hết hạn bằng refresh endpoint tại auth.tiktok-shops.com.
Vì sao TikTok Shop API báo chữ ký của tôi không hợp lệ?
Các nguyên nhân thường gặp là dùng sai app key hoặc secret, đưa access token vào chuỗi được ký, tuần tự hóa lại JSON body sau khi ký, bỏ sót request path, dùng SHA-256 thông thường thay vì HMAC-SHA256 hoặc sử dụng timestamp nằm ngoài khoảng từ 5 phút trước đến 30 giây sau đồng hồ của nền tảng. Hãy ký đúng các byte bạn gửi đi.
Giới hạn tốc độ của TikTok Shop API là bao nhiêu?
Không có một giới hạn cố định duy nhất. TikTok phân bổ QPS động dựa trên các yếu tố như số shop đã cấp quyền, loại endpoint và tải của nền tảng; nếu tài liệu endpoint công bố giới hạn riêng thì giới hạn đó được ưu tiên. Giới hạn tốc độ thể hiện qua HTTP 429 hoặc mã nghiệp vụ 36009002. Hãy dùng hàng đợi theo từng cặp app-shop, endpoint batch và exponential backoff kèm jitter, đồng thời tuân thủ Retry-After.
Nên dùng webhook TikTok Shop hay polling?
Nên dùng cả hai. Webhook cung cấp sự kiện gần như theo thời gian thực, nhưng cơ chế gửi là ít nhất một lần, yêu cầu xác nhận bằng phản hồi 200 body rỗng trong vòng 3 giây và dừng thử lại sau khi lần thử thứ tư thất bại. TikTok khuyến nghị đối soát dữ liệu quan trọng như đơn hàng, kiện hàng, sản phẩm và hàng trả lại bằng polling API theo lịch.