Hướng dẫn ủy quyền (202309)
Yêu cầu
Trước khi bắt đầu, hãy đảm bảo rằng bạn đã hoàn thành các bước sau:
- Đăng ký làm nhà phát triển trên Partner Center.
- Tạo một app.
- Xác minh rằng các API đã được kích hoạt cho app của bạn.
Ủy quyền Development Shop
Để phục vụ mục đích kiểm thử các yêu cầu API, bạn nên bắt đầu bằng cách sử dụng tài khoản thử nghiệm Seller Center thông qua mục Development Shops của Partner Center. Tài khoản thử nghiệm Seller Center cung cấp đầy đủ chức năng Seller Center, bao gồm cả ủy quyền.
Khi ủy quyền cho một app bằng tài khoản thử nghiệm Seller Center, bạn sẽ được chuyển thẳng đến bước seller authorization approval, cho phép bạn tạo access token mà không cần sử dụng liên kết ủy quyền.
Để biết thêm thông tin về cách tạo tài khoản thử nghiệm Seller Center, vui lòng truy cập Hướng dẫn sử dụng Seller Center Development Shops của chúng tôi.
Bước 1: Lấy authorization code
Tạo liên kết ủy quyền
Sau khi tạo một app, hãy tạo liên kết ủy quyền bằng cách nhấp vào Copy authorization link trong mục Authorization của app.
📌 Lưu ý: Nếu bạn không thấy tùy chọn Copy authorization link, hãy kiểm tra xem bạn có còn đang ở chế độ nháp hay không. Một custom app ở chế độ nháp sẽ cần được phát hành để có thể tạo liên kết ủy quyền.
❗ Quan trọng: Lưu ý rằng liên kết ủy quyền sẽ khác nhau giữa Partner Center của US và Non-US.
Ví dụ liên kết ủy quyền cho US:
PLAINTEXTWord Wrap
https://services.us.tiktokshop.com/open/authorize?service_id=7172**********70150
Ví dụ liên kết ủy quyền cho Non-US:
PLAINTEXTWord Wrap
https://services.tiktokshop.com/open/authorize?service_id=7172*******70150
service_id là định danh duy nhất của ứng dụng trực tuyến (client) đã đăng ký của bạn. Bạn có thể lấy service_id trong phần chi tiết app, như minh họa trong hình sau:
Ngoài ra, một tham số state có thể được thêm vào liên kết ủy quyền của bạn để tăng cường bảo mật. state là một chuỗi ngẫu nhiên không thể đoán trước, giúp bảo vệ chống lại các cuộc tấn công giả mạo yêu cầu liên trang (cross-site request forgery).
Vui lòng xem tài liệu OpenID Connect để biết ví dụ về cách tạo và xác nhận một state. Khi mã hóa một state, hãy loại bỏ các khoảng trắng ở đầu và cuối.
Ví dụ liên kết ủy quyền có tham số state:
PLAINTEXTWord Wrap
https://services.us.tiktokshop.com/open/authorize?service_id=7172**********70150
&state=xaoegsefowuf
Phê duyệt ủy quyền của seller
Sau khi seller mở liên kết ủy quyền của bạn, họ sẽ thấy lời nhắc ủy quyền sau:
Sau khi nhấp vào Next dưới đúng khu vực, seller sẽ được yêu cầu đăng nhập vào tài khoản của họ (hoặc tạo một tài khoản seller nếu họ chưa có). Nếu đã có một tài khoản seller center đang đăng nhập, bước này sẽ được bỏ qua và seller sẽ được chuyển thẳng đến bước tiếp theo:
Sau khi đăng nhập, seller sẽ thấy biểu mẫu sau:
Sau khi nhập và xác nhận thông tin bắt buộc, seller sẽ có thể ủy quyền cho app của bạn:
❗ Quan trọng: Sau khi phê duyệt ủy quyền thành công, seller sẽ được chuyển hướng đến Redirect URL mà bạn đã cung cấp trong app. URL này chứa thông tin quan trọng cho (các) bước tiếp theo.
Nhận authorization code
Sau khi seller phê duyệt ủy quyền cho app trong tài khoản TikTok Seller Center thông qua liên kết ủy quyền dịch vụ, họ sẽ được chuyển hướng đến Redirect URL đã nhập khi tạo app. Redirect URL sẽ chứa một auth_code tạm thời dưới dạng tham số truy vấn.
❗ Quan trọng: auth_code hết hạn sau 30 phút và chỉ có thể sử dụng một lần.
Ví dụ Redirect URL và auth_code:
PLAINTEXTWord Wrap
{redirect_url}?code=FeBoANmHP3yqdoUI9fZOCw&state={state}
Bước 2: Yêu cầu access token và refresh token
Hãy đảm bảo bạn có một auth_code hợp lệ trước khi yêu cầu access token. Vui lòng tham khảo Bước 1: Lấy authorization code để biết cách lấy auth_code.
Để yêu cầu một access_token và refresh_token, hãy gửi một yêu cầu GET đến endpoint sau:
PLAINTEXTWord Wrap
auth.tiktok-shops.com/api/v2/token/get
| Parameter | Type | Required? | Description | Sample |
|---|---|---|---|---|
app_key | string | Yes | App key trong trang app của Partner Center | 123abc |
app_secret | string | Yes | App secret trong trang app của Partner Center | 15abf8a4972afd1f275d5b19bfa9a17e0d142aa7 |
auth_code | string | Yes | Authorization code thu được trong Bước 1: Lấy authorization code | TTP_FeBoANmHP3yqdoUI9fZOCw |
grant_type | string | Yes | Loại grant token. Chỉ chấp nhận giá trị authorized_code | authorized_code |
Yêu cầu của bạn sẽ giống như sau:
PLAINTEXTWord Wrap
auth.tiktok-shops.com/api/v2/token/get?app_key=123abcd
&app_secret=15abf8a4972afd1f275d5b19bfa9a17e0d142aa7
&auth_code=TTP_FeBoANmHP3yqdoUI9fZOCw
&grant_type=authorized_code
Nếu tất cả các tham số được nhập trong yêu cầu GET đều hợp lệ, phản hồi sẽ chứa các tham số sau:
| Parameter | Type | Description | Sample |
|---|---|---|---|
access_token | string | User access token cần thiết để gọi đến các endpoint của TikTok Shop Open API. Truyền giá trị này trong header x-tts-access-token của một yêu cầu API để ủy quyền cho yêu cầu đó. | TTP_RLM6CIADWF606TZGFO5XGA |
access_token_expire_in | Unix timestamp | Mốc thời gian hết hạn của access token, với thời gian hết hạn mặc định được đặt là bảy ngày. Unix timestamp biểu thị ngày và giờ access token sẽ hết hạn. | 1630401330 |
refresh_token | string | Một token để làm mới access token | TTP_C2XWDN63ON-FOHJSMR0WSG |
refresh_token_expire_in | Unix timestamp | Mốc thời gian hết hạn của refresh token. Unix timestamp biểu thị ngày và giờ refresh token sẽ hết hạn. | 1630401510 |
open_id | string | Một ID dùng để xác định người dùng đã ủy quyền cho việc truy xuất dữ liệu của họ trong các lệnh gọi API | ephr6QAAAADhos3OBMztFEwRCWQGzDmfXm_7O2OTJyaYKA15pIaiEg |
seller_name | string | Tên của seller mà bạn đang ủy quyền cho app của mình | Test Name |
seller_base_region | string | Khu vực nơi seller đặt trụ sở | US |
user_type | int | Loại người dùng, với các giá trị có thể có: |
- 0: Seller
- 1: Creator
- 3: Partner | 1 |
|
request_id| string | ID để theo dõi yêu cầu API | 2022080809462301024509910319695C45 |
PLAINTEXTWord Wrap
{
"code":0,
"message":"success",
"data":{
"access_token":"TTP_Fw8rBwAAAAAkW03FYd09DG-9INtpw361hWthei8S3fHX8iPJ5AUv99fLSCYD9-UucaqxTgNRzKZxi5-tfFMtdWqglEt5_iCk",
"access_token_expire_in":1660556783,
"refresh_token":"TTP_NTUxZTNhYTQ2ZDk2YmRmZWNmYWY2YWY2YzkxNGYwNjQ3YjkzYTllYjA0YmNlMw",
"refresh_token_expire_in":1691487031,
"open_id":"7010736057180325637",
"seller_name":"Jjj test shop",
"seller_base_region":"ID",
"user_type":0
},
"request_id":"2022080809462301024509910319695C45"
}
Bước 3: Làm mới access token
Sau khi một app được ủy quyền bởi một tài khoản seller TikTok Shop, nó nhận được một access_token, vốn là yếu tố thiết yếu để xác thực và gọi đến các API của TikTok Shop.
❗ Quan trọng: access_token phải được làm mới mỗi 7 ngày bằng cách sử dụng refresh_token. Việc không làm mới trước khi hết hạn sẽ dẫn đến lỗi xác thực khi cố gắng yêu cầu dữ liệu thông qua các API của TikTok Shop.
📌 Lưu ý: refresh_token_expire_in tương đương với khoảng thời gian ủy quyền được cung cấp khi seller ban đầu ủy quyền truy cập app.
access_token vẫn còn hiệu lực cho đến refresh_expire_date, vốn được trả về trong phản hồi.
Để làm mới access_token của bạn, hãy gửi một yêu cầu GET đến endpoint sau:
PLAINTEXTWord Wrap
auth.tiktok-shops.com/api/v2/token/refresh
| Parameter | Type | Required? | Description | Sample |
|---|---|---|---|---|
app_key | string | Yes | App key trong trang app của TikTok Shop Partner Center | 65t60877bfejb |
app_secret | string | Yes | App secret trong trang app của Tiktok Shop Partner Center | 15abf8a4972afd1f275d5b19bfa9a17e0d142aa7 |
refresh_token | string | Yes | Một token để làm mới access token | TTP_C2XWDN63ON-FOHJSMR0WSG |
grant_type | string | Yes | Loại grant token. Chỉ chấp nhận refresh_token. | refresh_token |
Yêu cầu của bạn sẽ giống như sau:
PLAINTEXTWord Wrap
https://auth.tiktok-shops.com/api/v2/token/refresh?app_key=65t6a8e8bfejb
&app_secret=f4c770e4b45aa62e
&refresh_token=TTP_EB9rlwAAAADXbnMESTWAZSxIcC-XUA5AyeEOdmGBKY2FiKFYKqON6jco
&grant_type=refresh_token
Nếu tất cả các tham số được nhập trong yêu cầu GET đều hợp lệ, phản hồi sẽ chứa các tham số sau:
| Parameter | Type | Description | Sample |
|---|---|---|---|
access_token | string | User access token cần thiết để gọi đến các endpoint của TikTok Shop Open API. Truyền giá trị này trong header x-tts-access-token của một yêu cầu API để ủy quyền cho yêu cầu đó. | TTP_RLM6CIADWF606TZGFO5XGA |
access_token_expire_in | Unix timestamp | Mốc thời gian hết hạn của access token, với thời gian hết hạn mặc định được đặt là bảy ngày. Unix timestamp biểu thị ngày và giờ access token sẽ hết hạn. | 1630401330 |
refresh_token | string | Một token để làm mới access token | TTP_C2XWDN63ON-FOHJSMR0WSG |
refresh_token_expire_in | Unix timestamp | Mốc thời gian hết hạn của refresh token. Unix timestamp biểu thị ngày và giờ refresh token sẽ hết hạn. | 1630401510 |
open_id | string | Một ID dùng để xác định người dùng đã ủy quyền cho việc truy xuất dữ liệu của họ trong các lệnh gọi API | jKlhBwAAAADxnvrRWZm0h5wx9isdVlL5tdIEOrGL_EZjSlhzJbuXt7_AZssO6oXnuIHC1NyR_ruluQnSaXetBDLjt_Y8d1JG |
seller_name | string | Tên của seller mà bạn đang ủy quyền cho app của mình | Test Seller |
seller_base_region | string | Khu vực nơi seller đặt trụ sở | US |
user_type | int | Loại người dùng, với các giá trị có thể có: |
- 0: Seller
- 1: Creator | 1 |
|
request_id| string | ID để theo dõi yêu cầu API | 2022080809462301024509910319695C45 |
PLAINTEXTWord Wrap
{
"code":0,
"message":"success",
"data":{
"access_token":"TTP_Fw8rBwAAAAAkW03FYd09DG-9INtpw361hWthei8S3fHX8iPJ5AUv99fLSCYD9-UucaqxTgNRzKZxi5-tfFMtdWqglEt5_iCk",
"access_token_expire_in":1660556783,
"refresh_token":"TTP_NTUxZTNhYTQ2ZDk2YmRmZWNmYWY2YWY2YzkxNGYwNjQ3YjkzYTllYjA0YmNlMw",
"refresh_token_expire_in":1691487031,
"open_id":"7010736057180325637",
"seller_name":"Jjj test shop",
"seller_base_region":"ID",
"user_type":0
},
"request_id":"2022080809462301024509910319695C45"
}