אסימוני גישה ל-TikTok API for Business: 24 שעות, רענון וביטול
אסימון גישה (Access Token) של TikTok API for Business תקף 24 שעות ונשלח בכותרת הבקשה Access-Token. האפליקציה מקבלת אותו בהחלפת קוד ההרשאה של בעל החשבון בנקודת הקצה /tt_user/oauth2/token/, יחד עם אסימון רענון התקף שנה, שמחדש את הגישה בנקודת הקצה /tt_user/oauth2/refresh_token/. הביטול נעשה בנקודת הקצה /tt_user/oauth2/revoke/, ואת ההיקפים שהוענקו לאסימון בודקים דרך נקודת הקצה /tt_user/token_info/get/ שמחזירה אותם.
משך התוקף של אסימון הגישה לחשבון TikTok; כל תגובת אסימון מציינת בשדה expires_in את מספר השניות שנותרו.
תוקף אסימון הרענון שהונפק יחד איתו; השדה refresh_token_expires_in נותן את מספר השניות שנותרו לו.
משך התוקף של קוד ההרשאה בכתובת ההפניה; אפשר להחליף אותו פעם אחת בלבד.
המזהה הייחודי של החשבון ביישום, שמוחזר עם כל אסימון ונשלח בשדה business_id בקריאות ל-Accounts API של החשבון.
סוג האסימון שמוחזר: מי שמחזיק בו יכול להשתמש בו כדי לגשת למשאבי החשבון, כפי שמתואר בתיעוד.
מזהה החשבון שמוחזר בנקודת הקצה /tt_user/token_info/get/ לצד היקף האסימון, וניתן לשלוח אותו בשדה business_id בקריאות ל-Accounts API לחשבון.
איך קוד ההרשאה מגיע לאפליקציה שלכם?
דרך כתובת האישור של בעל החשבון ב-TikTok, שמופקת ליישום פיתוח תחת My Apps, App Detail, Basic Information, ברגע שליישום יש את ההרשאה TikTok Accounts. בעל החשבון פותח את הכתובת, בודק את ההרשאות ומאשר אותן. אחר כך הדפדפן מופנה לכתובת ההפניה של היישום, ומצורף אליה auth_code וכל ערך state שהגיע בכתובת האישור. הקוד תקף 10 דקות, ואפשר להחליף אותו פעם אחת בלבד.
- כתובת ה-URL של ההפניה: מוחלטת, מתחילה ב-https://, מסתיימת בלוכסן /, בלי מחרוזת שאילתה, עוגן או פורט, ואורכה בין 10 ל-512 תווים.
- עד 10 כתובות הפניה לכל יישום, פעילה אחת בכל רגע; הפעלת כתובת מייצרת כתובת אישור משלה.
- state: ערך אופציונלי שמוחזר בהפניה, ומומלץ להשתמש בו כהגנה מפני CSRF.
disable_auto_auth=1: מציג את מסך הבדיקה לבעלי חשבון שאישרו בעבר את אותן הרשאות, שאחרת מופנים אליהם מיד.
איך מחליפים את הקוד באסימונים?
עם POST אל נקודת הקצה /tt_user/oauth2/token/ מהשרת שלכם, בפורמט JSON. השדה client_id והשדה client_secret הם ה-App ID וה-Secret המופיעים תחת My Apps, App Detail, Basic Information. השדה grant_type הוא authorization_code, השדה auth_code הוא הקוד מההפניה, והשדה redirect_uri חייב להיות זהה לכתובת ההפניה של בעל החשבון שהוגדרה ביישום.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/token/' \
-H 'Content-Type: application/json' \
-d '{
"client_id": "<APP_ID>",
"client_secret": "<APP_SECRET>",
"grant_type": "authorization_code",
"auth_code": "<AUTH_CODE>",
"redirect_uri": "https://app.example.com/tiktok/callback/"
}'מה תגובת האסימון כוללת?
התשובה היא אובייקט JSON עם השדות code, message, request_id ו-data, ובו כל הנתונים. הערך 0 בשדה code פירושו שההחלפה הצליחה, ובשדה data מופיעים שני האסימונים ומזהה החשבון:
access_token: האסימון הקצר לקריאות ה-API, תקף ליום אחד.token_type: Bearer, שלפי תיאור TikTok מאפשר לכל מי שמחזיק באסימון להשתמש בו.- scope: ההרשאות שניתנו לאסימון, כמחרוזת אחת מופרדת בפסיקים.
expires_in: מספר השניות שנותרו עד פקיעת אסימון הגישה; בדוגמה של TikTok הערך הוא 86400 שניות.refresh_token: האסימון שמחדש את הגישה, תקף שנה; ההנחיה של TikTok היא לשמור אותו.refresh_token_expires_in: מספר השניות שנותרו עד שאסימון הרענון יפוג.open_id: המזהה הייחודי של חשבון ה-TikTok ביישום.
{
"code": 0,
"message": "OK",
"request_id": "<REQUEST_ID>",
"data": {
"access_token": "<ACCESS_TOKEN>",
"token_type": "Bearer",
"scope": "user.info.basic,user.info.stats,user.insights,video.list,video.insights,video.publish,comment.list,comment.list.manage",
"expires_in": 86400,
"refresh_token": "<REFRESH_TOKEN>",
"refresh_token_expires_in": 31536000,
"open_id": "<OPEN_ID>"
}
}איך שולחים את האסימון בקריאות ה-API?
בכותרת בקשה בשם Access-Token, בכל נקודות הקצה של Accounts API, מהנתיב /business/get/ ועד לנתיב /business/video/publish/ כולל. את החשבון עצמו מציינים בשדה business_id, שמוגדר לערך open_id מאותה תגובה. נקודות הקצה של OAuth פועלות בכיוון ההפוך: בנקודת הקצה /tt_user/oauth2/token/, בנקודת הקצה /tt_user/oauth2/refresh_token/ ובנקודת הקצה /tt_user/oauth2/revoke/ מקבלים את client_id ואת client_secret של היישום בגוף JSON, בלי כותרת הבקשה הזו.
איך מחדשים את אסימון הגישה?
עם POST אל נקודת הקצה /tt_user/oauth2/refresh_token/, שנושאת את client_id, את client_secret, את grant_type עם הערך refresh_token ואת אסימון הרענון השמור. התשובה מכילה את אותם שדות כמו ההחלפה הראשונה: access_token חדש עם expires_in שלו, refresh_token לשמירה לחידוש הבא, ומספר השניות שנותרו לאסימון הרענון. מתזמנים את החידוש לפני תום 24 השעות, ולא ממתינים לשגיאה 40102 כדי לחדש.
import os, time, requests
API = "https://business-api.tiktok.com/open_api/v1.3"
def renew(refresh_token: str) -> dict:
r = requests.post(f"{API}/tt_user/oauth2/refresh_token/", json={
"client_id": os.environ["TIKTOK_APP_ID"],
"client_secret": os.environ["TIKTOK_APP_SECRET"],
"grant_type": "refresh_token",
"refresh_token": refresh_token,
}, timeout=30).json()
if r["code"] != 0: # 40103: the refresh token expired, so the owner authorizes again
raise RuntimeError(f"{r['code']}: {r['message']}")
d, now = r["data"], time.time()
return {
"access_token": d["access_token"],
"access_expires_at": now + d["expires_in"],
"refresh_token": d["refresh_token"], # keep it for the next renewal
"refresh_expires_at": now + d["refresh_token_expires_in"],
}איך מבטלים את הגישה?
מצד היישום, עם POST אל נקודת הקצה /tt_user/oauth2/revoke/, שנושאת את client_id, את client_secret ואת access_token שיש לבטל. הצלחה מחזירה 0 בשדה code ואובייקט data ריק. מצד החשבון, בעל החשבון פותח את אפליקציית TikTok, נכנס להגדרות ולפרטיות, לאבטחה, לניהול הרשאות היישום, בוחר ביישום ובוחר באפשרות להסיר את הגישה. מרגע הביטול לא נשלחים ליישום אירועי comment.update לאותו חשבון.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/revoke/' \
-H 'Content-Type: application/json' \
-d '{"client_id": "<APP_ID>", "client_secret": "<APP_SECRET>", "access_token": "<ACCESS_TOKEN>"}'
# {"code": 0, "message": "OK", "request_id": "<REQUEST_ID>", "data": {}}איך בודקים אסימון?
עם POST אל נקודת הקצה /tt_user/token_info/get/, שאינה דורשת הרשאה משלה. שולחים את app_id ואת access_token, ובשדה data מוחזרים app_id, scope ו-creator_id. השדה scope מציין מה העניק בעל החשבון, והשדה creator_id הוא המזהה הייחודי של החשבון ביישום, הערך שנשלח בשדה business_id בקריאות ל-Accounts API של החשבון. התיעוד של TikTok מפנה לכאן מפתחים בכל פעם ששדה דורש היקף שלאסימון עשוי לחסור.
אילו שגיאות נובעות מהאסימונים?
השגיאות מוחזרות בשדה code של התשובה, בדרך כלל תחת סטטוס HTTP 200, ולכן בודקים את הערך של code לפני שסומכים על קריאה. קודי ההחזרה שקשורים לאסימונים ולהחלפתם:
- 40102: אסימון הגישה פג; מחדשים אותו וקוראים שוב.
- 40103: אסימון הרענון פג; רק אישור חדש של בעל החשבון מחליף אותו.
- 40104: הבקשה לא כללה אסימון גישה.
- 40105: אסימון הגישה לא חוקי או שגוי.
- 40107: אסימון הרענון לא חוקי או שגוי, למשל כזה שנשלח כדי לחדש אסימון של Marketing API, שאינו פוקע לעולם.
- 40110: קוד ההרשאה בוטל, כבר נוצל או פג תוקפו.
- 40131: שגיאת אימות בשתי נקודות הקצה של האסימונים, עקב מזהה או סוד שגויים של היישום, קוד שפג, או אסימון רענון לא חוקי או שפג תוקפו.
מה easyCoexistence מחדש בשבילכם?
הכול אחרי ההתחברות: המערכת מחליפה את הקוד ברגע שההפניה חוזרת מ-TikTok, שומרת את שני האסימונים מוצפנים ומחדשת את אסימון הגישה בעצמה: לפני קריאה כשנותרו פחות מ-15 דקות, ובבדיקה שהיא מריצה על כל חשבון בערך כל 6 שעות כששנותרו פחות מ-8 שעות. כל חידוש שומר את אסימון הרענון החדש ואת תוקפו, וקריאות שמגיעות יחד חולקות חידוש אחד.
- אסימון שנדחה: כש-TikTok עונה 40102, 40104 או 40105, החיבור מסומן לחיבור מחדש ובעל החשבון מקבל אימייל. משתמשי Partner API מקבלים גם את האירוע channel.disconnected, כך שהמערכת שלהם יודעת על כך.
- הקוד שלכם:
get_social_credentials, או GET /channels/{id}?credentials=1 ב-Partner API, מחזירים את האסימון הנוכחי עםtoken_expires_at, ולכן שולפים אותו בכל משימה. - הסרה: הסרת החיבור בלוח הבקרה, או בקריאה DELETE /channels/{id}, מבטלת את האסימון ב-TikTok דרך נקודת הקצה /
tt_user/oauth2/revoke/ בזמן שהחיבור נמחק.
טעויות נפוצות
- החלפת קוד ההרשאה בדפדפן. ההחלפה שולחת את client_secret של היישום, ולכן עושים אותה מהשרת בתוך 10 דקות מההפניה.
- קריאה ל-expires_in כתאריך. השדה מציין את מספר השניות שנותרו, ולכן מוסיפים אותו לזמן התגובה כדי לדעת מתי האסימון פג.
- ביטול עם אסימון הרענון. נקודת הקצה /tt_user/oauth2/revoke/ מקבלת את access_token, יחד עם השדה client_id והשדה client_secret של היישום.
- התייחסות להיעדר מסך הבדיקה ככשל. מסך הבדיקה מדולג להרשאות שבעל החשבון אישר בעבר; כדי להציג אותו שוב, מוסיפים לכתובת את הפרמטר disable_auto_auth=1, שמציג את המסך.
המערכת מחליפה את הקוד כשחשבון TikTok נכנס, מחדשת את אסימון הגישה של 24 השעות לפני שהוא פג ובודקת את החשבון בערך כל 6 שעות, כך ש-Claude, ChatGPT או הקוד שלכם קוראים ל-TikTok עם אסימון עדכני, שאותו שולף get_social_credentials לסקריפטים שלכם. US$ 9 עד US$ 0.75 לחיבור בחודש, יורד ככל שמוסיפים חיבורים, עם 3 ימי ניסיון בחינם.
שאלות נפוצות
כמה זמן חי אסימון גישה של TikTok API for Business?
24 שעות. כל תגובת אסימון מציינת בשדה expires_in את מספר השניות שנותרו, ואסימון הרענון, התקף שנה, מחדש אותו.
האם נקודת הקצה לרענון של TikTok דורשת redirect_uri?
טבלת הפרמטרים שלה כוללת את client_id, client_secret, grant_type וגם את refresh_token, בלי redirect_uri, אף שמדריך האימות של TikTok קובע שנקודות הקצה לאסימונים דורשות שדה redirect_uri בכל קריאה.
האם ביטול אסימון TikTok עוצר את הוובהוקים (Webhook) שלו?
כן. ליישום לא נשלחים עוד אירועי comment.update לאותו חשבון, עד שבעל החשבון מאשר שוב את היישום.
מאיפה לוקחים את השדה business_id לחשבון?
מהשדה open_id בתגובת האסימון, שקריאות Accounts API לוקחות כשדה business_id. נקודת הקצה /tt_user/token_info/get/ מחזירה את אותו מזהה, בשדה creator_id, לצד היקף האסימון.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-