Tổng quan về ủy quyền (202407)
Yêu cầu
Trước khi app có thể được ủy quyền bởi người dùng trực tuyến, app cần đáp ứng một số điều kiện tiên quyết.
Đối với custom apps:
- App đã bật ít nhất một API scope user: seller, creator, và/hoặc partner.
- App vượt qua "enrollment review"
Đối với public apps:
- App đã bật ít nhất một API scope user: seller, creator, và/hoặc partner.
- App vượt qua "enrollment review"
- App vượt qua "USDS/OPIS review" (chỉ áp dụng cho thị trường mục tiêu US)
- App vượt qua "Listing Review"
- App vượt qua "App review"
- App vượt qua "Beta Testing" (chỉ áp dụng cho connector apps)
Bật API Scope
Trước khi phát triển một app, nhà phát triển nên bật hoặc đăng ký các API scope cần thiết tùy thuộc vào loại hình kinh doanh của app.
📌 Lưu ý: Bật các scope không cần thiết có thể dẫn đến thời gian app review lâu hơn và tỷ lệ ủy quyền của người dùng thấp hơn.
Lấy authorization link
Tạo authorization link bằng cách nhấp vào Copy authorization link trong mục Authorization của app:
📌 Lưu ý: Nếu app đang trong giai đoạn phát triển, nút Copy authorization link sẽ không hiển thị. Vui lòng xem các hướng dẫn seller authorization, creator authorization, hoặc partner authorization để biết thêm thông tin.
📌 Lưu ý: Tùy thuộc vào thị trường bạn đang hoạt động, authorization link sẽ hơi khác nhau.
US: https://services.tiktokshops.us/open/authorize?service_id=7369437808455026474
- ROW (rest of the world): https://services.tiktokshop.com/open/authorize?service_id=7431458374265161478
Bạn nên thêm tham số state vào authorization link để tăng cường bảo mật. 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.
Sau khi người dùng truy cập authorization link, họ phải chấp nhận hoặc từ chối ủy quyền.
Nếu người dùng chấp nhận yêu cầu ủy quyền, họ sẽ được chuyển hướng đến Redirect URL, trong đó còn chứa thêm một code tạm thời dưới dạng tham số. Code này sẽ được dùng làm auth_code khi lấy access token ở bước tiếp theo.
Ví dụ Redirect URL và auth_code:
PLAINTEXTWord Wrap
{redirect_url}?code=FeBoANmHP3yqdoUI9fZOCw&state={state}
❗ Quan trọng: auth_code hết hạn sau 30 phút và chỉ có thể sử dụng một lần.
Nếu người dùng từ chối yêu cầu ủy quyền, họ vẫn sẽ được chuyển hướng đến Redirect URL, nhưng khi đó code sẽ là null: code=null&error=auth_denied.
Get Access Token API
Để yêu cầu access_token và refresh_token, hãy thực hiện một request GET đến endpoint auth.tiktok-shops.com/api/v2/token/get, với các tham số sau:
| 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 | Mã ủy quyền lấy được thông qua authorization link. | TTP_FeBoANmHP3yqdoUI9fZOCw |
| grant_type | string | Yes | Loại grant token. Chỉ chấp nhận giá trị authorized_code. | authorized_code |
Request của bạn sẽ trông giống như sau:
PLAINTEXTWord Wrap
https://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ố nhập trong request GET đều hợp lệ, response sẽ chứa các tham số sau:
| Parameter | Type | Description | Sample |
|---|---|---|---|
| code | int | Mã phản hồi máy có thể đọc được, đại diện cho kết quả của request. 0 cho biết thành công. Để biết thêm thông tin về các mã lỗi, hãy xem Common error codes. | 0 |
| message | string | Thông báo dạng dễ đọc cho người, mô tả thành công hay thất bại của API request. | success |
| request_id | string | ID để theo dõi API request. | 20220808094623010 |
| 24509910319695C45 | |||
| data | object | Phần dữ liệu payload của response. | |
| └ access_token | string | User access token cần thiết để gọi đến các TikTok Shop Open API endpoint. Truyền giá trị này trong header x-tts-access-token của API request để ủy quyền cho request. | TTP_RLM6CIADWF |
| 606TZGFO5XGA | |||
| └ access_token_expire_in | Unix timestamp | Thời điểm 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 | Token dùng để làm mới access token. | TTP_C2XWDN63ON- |
| FOHJSMR0WSG | |||
| └ refresh_token_expire_in | Unix timestamp | Thời điểm 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 | ID dùng để nhận diện người dùng đã ủy quyền cho việc truy xuất dữ liệu của họ trong các API call. | ephr6QAAAADhos3OBM |
| ztFEwRCWQGzDmfXm_ | |||
| 7O2OTJyaYKA15pIaiEg | |||
| └ seller_name | string | Tên của seller mà bạn đang ủy quyền cho app của bạn. | 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 | | └ granted_scopes | []string | Các API scope đã được ủy quyền cho app. Trường này sẽ trả về giá trị Scope Key của các API scope đã được ủy quyền.
| ["seller.affiliate_collaboration.read",
"seller.affiliate_collaboration.write"] |
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,
"granted_scopes": [
"seller.affiliate_collaboration.read",
"seller.affiliate_collaboration.write"
]
},
"request_id":"2022080809462301024509910319695C45"
}
Get Refresh Token API
Để làm mới access_token của bạn, hãy thực hiện một request GET đến endpoint auth.tiktok-shops.com/api/v2/token/refresh, với các tham số sau:
| 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 | Refresh token lấy được trong các tham số response của Get Access Token API. | TTP_C2XWDN63ON-FOHJSMR0WSG |
| grant_type | string | Yes | Loại grant token. Chỉ chấp nhận refresh_token. | refresh_token |
Request của bạn sẽ trông 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ố nhập trong request GET đều hợp lệ, response sẽ chứa các tham số sau:
| Parameter | Type | Description | Sample |
|---|---|---|---|
| code | int | Mã phản hồi máy có thể đọc được, đại diện cho kết quả của request. | |
0 cho biết thành công. Để biết thêm thông tin về các mã lỗi, hãy xem Common error codes. | 0 | ||
| message | string | Thông báo dạng dễ đọc cho người, mô tả thành công hay thất bại của API request. | success |
| request_id | string | ID để theo dõi API request. | 20220808094623010 |
| 24509910319695C45 | |||
| data | object | Phần dữ liệu payload của response. | |
| └ access_token | string | User access token cần thiết để gọi đến các TikTok Shop Open API endpoint. Truyền giá trị này trong header x-tts-access-token của API request để ủy quyền cho request. | TTP_RLM6CIADWF |
| 606TZGFO5XGA | |||
| └ access_token_expire_in | Unix timestamp | Thời điểm 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 | Token dùng để làm mới access token. | TTP_C2XWDN63ON- |
| FOHJSMR0WSG | |||
| └ refresh_token_expire_in | Unix timestamp | Thời điểm 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 | ID dùng để nhận diện người dùng đã ủy quyền cho việc truy xuất dữ liệu của họ trong các API call. | jKlhBwAAAADxnvrRWZm |
| 0h5wx9isdVlL5tdIEOrGL_ | |||
| EZjSlhzJbuXt7_ | |||
| AZssO6oXnuIHC1NyR_ | |||
| ruluQnSaXetBDLjt_Y8d1JG | |||
| └ seller_name | string | Tên của seller mà bạn đang ủy quyền cho app của bạn. | 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
- 3: Partner | 1 | | └ granted_scopes | []string | Các API scope đã được ủy quyền cho app. Trường này sẽ trả về giá trị Scope Key của các API scope đã được ủy quyền.
| ["seller.affiliate_collaboration.read",
"seller.affiliate_collaboration.write"] |
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
"granted_scopes": [
"seller.affiliate_collaboration.read",
"seller.affiliate_collaboration.write"
]
},
"request_id":"2022080809462301024509910319695C45"
}