Chuyển tới nội dung chính

Hướng dẫn ủy quyền creator

Hướng dẫn này dành cho​

  • các app cần gọi Affiliate Creator APIs
  • các tích hợp cần dữ liệu hoặc khả năng affiliate phía creator

Ủy quyền creator để làm gì?​

Sau khi creator ủy quyền, app có thể gọi các API Affiliate Creator.

Khái niệm cốt lõi​

Ủy quyền creator nghĩa là:một creator cấp cho app TikTok Shop của bạn quyền truy cập dữ liệu và khả năng phía creator, để app của bạn có thể gọi các Creator Open API liên quan.

Về bản chất, luồng này vẫn dựa trên OAuth:

  1. Xây dựng liên kết ủy quyền
  2. Cho người dùng đăng nhập và chấp thuận ủy quyền
  3. Nhận callback kèm code
  4. Đổi code lấy token
  5. Dùng token để gọi Creator APIs

Ủy quyền creator khác với ủy quyền seller. Token của creator và token của seller là hai loại thông tin xác thực khác nhau và không được dùng thay thế lẫn nhau.

Điều kiện tiên quyết​

Trước khi bắt đầu ủy quyền creator, hãy đảm bảo các mục sau đã sẵn sàng:

Điều kiện tiên quyết phía app​

  • app đã được tạo
  • API access đã được bật
  • một Redirect URL hợp lệ đã được cấu hình
  • các creator scope cần thiết đã được bật hoặc phê duyệt
  • nếu khả năng creator vẫn đang ở giai đoạn beta / dựa trên danh sách cho phép (allowlist), app phải được phê duyệt cho đợt triển khai đó

Điều kiện tiên quyết phía creator​

người dùng là một creator TikTok Shop thực sự, không chỉ là một tài khoản TikTok thông thường. Creator có thể đăng ký làm creator TikTok Shop bằng cách làm theo hướng dẫn của từng quốc gia tương ứng:

Khu vực mà creator chọn phải là một trong các thị trường mục tiêu của app:

Nếu app của bạn đang trong giai đoạn phát triển, vui lòng liên hệ App Store Manager để được cấp tài khoản test creator. Tài khoản test creator hiện chỉ khả dụng cho các thành viên trong giai đoạn beta của chúng tôi.

Luồng ủy quyền đầu cuối (end-to-end)​

Một luồng ủy quyền creator thực tế có thể hiểu qua 7 bước:

  1. chuẩn bị app
  2. bật các creator scope
  3. xây dựng liên kết ủy quyền creator
  4. cho creator đăng nhập và ủy quyền
  5. nhận code và state tại Redirect URL
  6. đổi auth_code lấy access_token / refresh_token
  7. gọi Creator Open APIs và xác thực granted_scopes

Bước 1: Chuẩn bị app​

Trong Partner Center, hãy đảm bảo bạn đã:

  • tạo app / service
  • bật API access
  • cấu hình Redirect URL
  • lấy app_key / app_secret
  • bật các creator scope cần thiết trong Manage API

Redirect URL là điểm đến callback sau khi ủy quyền thành công. Ở môi trường production, nó nên là một endpoint thực sự phía server, có khả năng xác thực các tham số callback, đặc biệt là state.

Bước 2: Bật các creator scope​

Đây là các creator scope được bật hoặc phê duyệt trong Partner Center.

APP & Service -> Manage API，tìm các scope key bắt đầu bằng creator. Ví dụ：

Bước 3: Xây dựng liên kết ủy quyền​

Liên kết ủy quyền cơ bản có thể lấy được từ nút Copy authorization link.

Đối với liên kết ủy quyền creator, bạn bắt buộc phải thêm thủ công một tham số state để tăng tính bảo mật. state là một chuỗi ngẫu nhiên không thể đoán trước, giúp chống lại các tấn công giả mạo yêu cầu liên trang (cross-site request forgery), và không được tự động thêm vào liên kết ủy quyền cơ bản.

Vui lòng xem tài liệu OpenID Connect để biết ví dụ về cách tạo và xác nhận state. Khi mã hóa state, hãy loại bỏ khoảng trắng ở đầu và cuối.

Ngoài ra, bạn có thể tự ghép thủ công toàn bộ liên kết ủy quyền bằng cách dùng app_key và state của mình.

Liên kết ủy quyền cuối cùng sẽ có dạng:

PLAINWord Wrap

https://shop.tiktok.com/alliance/creator/auth?app_key={your_app_key}&state={your_state}

Tham số：

  • app_key: định danh ứng dụng của bạn
  • state: tham số bảo mật, nên được tạo phía server

Thực hành tốt nhất cho state：

  • tạo nó ở phía server
  • làm cho nó ngẫu nhiên và không thể đoán trước
  • gắn nó với phiên ủy quyền hiện tại
  • xác thực nó nghiêm ngặt khi callback
  • coi nó là chỉ dùng một lần để giảm rủi ro replay

Không nhúng mật khẩu, token, hay dữ liệu nhạy cảm khác trực tiếp vào state.

Bước 4: Cho creator đăng nhập và ủy quyền​

Sau khi mở liên kết ủy quyền, creator thường sẽ:

  1. đăng nhập bằng tài khoản TikTok
  2. vào trang ủy quyền creator
  3. xem lại các scope được yêu cầu
  4. nếu trang ủy quyền hỗ trợ ủy quyền một phần, creator có thể bật hoặc tắt một số scope (hành vi UI cụ thể cần được kiểm chứng)
  5. nhấn Authorize

Lưu ý kỹ thuật: creator có thể chỉ ủy quyền một phần các scope được yêu cầu​

Điều này nghĩa là ủy quyền thành công không tự động đồng nghĩa với việc tất cả các scope nghiệp vụ cần thiết đã được cấp.

Bước 5: Xử lý callback và lấy auth code​

Sự thật chính thức / ràng buộc giao diện​

Sau khi creator chấp thuận ủy quyền, nền tảng sẽ chuyển hướng trở lại Redirect URL của bạn kèm theo một code tạm thời. Ở đây code là tên tham số được trả về trong URL callback; khi bạn gọi Get Access Token, hãy truyền chính giá trị đó dưới dạng auth_code (mốc dẫn chứng: ví dụ callback trong phần này + danh sách tham số ở Bước 6).

Một callback điển hình trông như sau:

PLAINWord Wrap

{redirect_url}?code={CODE_FROM_CALLBACK}&state={state}

Triển khai khuyến nghị / thực hành kỹ thuật tốt nhất​

Trình xử lý callback của bạn nên:

  • đọc code
  • đọc và xác thực state
  • phát hiện lỗi callback nếu người dùng từ chối ủy quyền
  • dừng luồng nếu không có code hợp lệ được trả về

auth_code nên được coi là tồn tại trong thời gian ngắn và thường chỉ dùng một lần. Hãy đổi nó lấy token càng sớm càng tốt.

Bước 6: Đổi auth code lấy token​

Sự thật chính thức / ràng buộc giao diện​

Dùng endpoint Get Access Token:

PLAINWord Wrap

GET https://auth.tiktok-shops.com/api/v2/token/get

Tham số bắt buộc​

  • app_key
  • app_secret
  • auth_code (dùng code được trả về bởi URL callback)
  • grant_type=authorized_code

Các trường phản hồi quan trọng​

  • access_token
  • refresh_token
  • open_id
  • user_type
  • granted_scopes

Triển khai khuyến nghị / thực hành kỹ thuật tốt nhất: xác thực ngay sau khi đổi token​

Luôn kiểm tra:

  1. code == 0
  2. user_type == 1
  3. granted_scopes bao phủ các scope tối thiểu mà nghiệp vụ của bạn yêu cầu

Nếu các kiểm tra này thất bại, đừng chuyển thẳng sang các lệnh gọi API nghiệp vụ.

Bước 7: Làm mới token​

Sự thật chính thức / ràng buộc giao diện​

Khi access token hết hạn, hãy làm mới nó bằng:

PLAINWord Wrap

GET https://auth.tiktok-shops.com/api/v2/token/refresh

Tham số bắt buộc​

  • app_key
  • app_secret
  • refresh_token
  • grant_type=refresh_token

Triển khai khuyến nghị / thực hành kỹ thuật tốt nhất: sau khi làm mới, kiểm tra lại các trường quan trọng​

  • user_type
  • open_id
  • granted_scopes

Để an toàn, tốt hơn là không nên giả định token sau khi làm mới hoạt động y hệt token trước đó. Một thực hành kỹ thuật an toàn hơn là xác thực lại các trường quan trọng mỗi khi một token mới được cấp.

Cách sử dụng granted_scopes đúng cách​

granted_scopes là một trong những trường quan trọng nhất trong ủy quyền creator.

Hãy sử dụng nó ở hai cấp độ:

Cấp độ 1: ngay sau khi ủy quyền​

Kiểm tra xem creator đã cấp các scope tối thiểu mà nghiệp vụ của bạn yêu cầu hay chưa.

Cấp độ 2: trước khi thực thi tính năng​

Trước khi gọi một endpoint, hãy xác nhận rằng scope cần thiết đã có trong granted_scopes.

Các cách sử dụng khuyến nghị​

  • nếu ủy quyền thành công nhưng scope chưa đầy đủ, hãy nhắc creator ủy quyền lại
  • nếu API trả về 105005, hãy kiểm tra cả scope của app lẫn granted_scopes của token
  • nếu sản phẩm của bạn có nhiều module, hãy duy trì một ánh xạ scope-to-feature

Ủy quyền một phần​

Creator có thể chọn bật hoặc tắt scope nào để ủy quyền. Một creator có thể không chấp thuận tất cả các scope trong một lần; callback thành công tự nó không có nghĩa là tất cả các scope nghiệp vụ cần thiết đều khả dụng (mốc dẫn chứng: trường granted_scopes trong phản hồi token).

Sau khi gọi [Get Access Token], vui lòng kiểm tra mảng granted_scopes trong phản hồi, và đảm bảo creator đã ủy quyền tất cả các scope cần thiết.

Định nghĩa các scope key nằm trên trang Manage API:

Nếu các scope đã ủy quyền không đủ cho nghiệp vụ của bạn, vui lòng yêu cầu creator "remove all access" và ủy quyền lại.

Ủy quyền lại và thu hồi ủy quyền​

Sự thật chính thức / ràng buộc giao diện​

Ủy quyền creator có thể được lý giải qua hai thay đổi vòng đời dưới đây. Các điểm vào sản phẩm cụ thể cho "remove all access" hoặc vô hiệu hóa một số scope vẫn cần được kiểm chứng.

Creator gỡ bỏ toàn bộ quyền truy cập​

Kết quả:

  • token cũ trở nên không hợp lệ
  • các lệnh gọi API trong tương lai thất bại với các lỗi kiểu token invalid / deauthorized

Creator vô hiệu hóa một số scope​

Kết quả:

  • các API thuộc các scope đó sẽ bắt đầu thất bại với lỗi quyền (permission errors)
  • một lỗi phổ biến là 105005

Triển khai khuyến nghị / thực hành kỹ thuật tốt nhất​

Do đó, app của bạn nên cung cấp:

  • một cách rõ ràng để quay lại trang ủy quyền
  • một luồng ủy quyền lại dễ hiểu
  • thông báo lỗi rõ ràng cho token không hợp lệ và scope bị thiếu

Lỗi thường gặp và khắc phục sự cố​

Error / scenarioMeaningSuggested action
105005Thiếu scope cần thiết ở cấp app hoặc cấp tokenKiểm tra scope của app, sau đó kiểm tra granted_scopes của token, rồi yêu cầu creator ủy quyền lại nếu cần
105002Access token đã hết hạnLàm mới token
105001 / token invalidToken không hợp lệ, đã bị thu hồi, hoặc người dùng đã gỡ bỏ toàn bộ quyền truy cậpỦy quyền lại nếu cần
101000Sai danh tính token hoặc ghép sai cặp API-tokenĐảm bảo bạn không dùng token của seller cho một API của creator
Một quy tắc kinh nghiệm thực tế:Nếu một scope vừa được bật mà vẫn không hoạt động, điều đầu tiên cần kiểm tra thường là granted_scopes của token từ lần ủy quyền gần nhất của creator, không phải số phiên bản app.

Thực hành tốt nhất​

  1. tạo và xác thực state ở phía server
  2. lưu trữ lâu dài granted_scopes
  3. lưu token của creator tách biệt với token của seller
  4. đổi auth code càng sớm càng tốt sau khi callback
  5. chỉ yêu cầu các scope tối thiểu cần thiết
  6. cung cấp một điểm vào ủy quyền lại rõ ràng trong sản phẩm
  7. kiểm tra khả năng scope trước khi gọi một API

FAQ​

Token của creator và token của seller có thể dùng thay thế lẫn nhau không?​

Không. Chúng đại diện cho các danh tính người dùng khác nhau và không nên trộn lẫn.

Tại sao ủy quyền thành công nhưng API vẫn trả về 105005?​

Thường là vì một trong hai lý do:

  • app chưa bật scope cần thiết, hoặc
  • granted_scopes của token không chứa scope cần thiết

Sau khi làm mới token, có nên tiếp tục kiểm tra granted_scopes không?​

Để an toàn, có. Một thực hành kỹ thuật an toàn hơn là xác thực lại các trường khả năng quan trọng mỗi khi một token mới được cấp.

Tôi nên làm gì nếu creator chỉ cấp một phần các scope được yêu cầu?​

Dùng granted_scopes để kiểm soát khả dụng của tính năng, và ủy quyền lại nếu một scope bị thiếu làm tắc nghẽn các luồng nghiệp vụ quan trọng.

Missing parameter: The URL must include the "state" parameter for creators to authorize this app. Please contact the developer for assistance.​

Đối với liên kết ủy quyền creator, bạn bắt buộc phải thêm thủ công một tham số state để tăng tính bảo mật. state là một chuỗi ngẫu nhiên không thể đoán trước, giúp chống lại các tấn công giả mạo yêu cầu liên trang (cross-site request forgery), và không được tự động thêm vào liên kết ủy quyền cơ bản.

No data retrieved: The requested API list is empty. Please contact the app developer for more information.​

APP phải bật các creator api scope.

APP & Service -> Manage API, tìm các scope key bắt đầu bằng creator.