لماذا يتوقف اتصال TikTok API، وكيف تُبقيه نشطًا
يتوقف اتصال TikTok API for Business عن العمل حين لا يُجدَّد رمز الوصول (access token) البالغ مدته 24 ساعة، أو ينتهي رمز التحديث (refresh token) البالغ مدته سنة، أو يسحب المالك وصول التطبيق، أو يكون الرمز المُرسل ناقصًا أو خاطئًا. ويُعيد TikTok رموز هذه الحالات بالأكواد 40102 و40103 و40104 و40105. ويُبقيه نشطًا تجديده مبكرًا، والتحقق من كل حساب وفق جدول، وطلب تفويض جديد من المالك قبل انتهاء السنة.
يُبقي easyCoexistence كل اتصال TikTok نشطًا بنفسه: يُجدّد الرمز 24 ساعة قبل انتهائه، ويفحص الحساب تقريبًا كل 6 ساعات، وحين يرفض TikTok الرمز يضع القناة في حالة تحتاج إلى إعادة الاتصال ويرسل إليك بريدًا، سواء لـ Claude أو ChatGPT أو منصتك الخاصة.
مدة صلاحية رمز الوصول لحساب TikTok من API for Business؛ يجدِّده /tt_user/oauth2/refresh_token/.
مدة رمز التحديث؛ بعد انتهائه يجب على مالك الحساب تفويض التطبيق من جديد.
سبب الفشل عندما يسحب المالك وصول التطبيق أثناء معالجة TikTok لمنشور؛ ويقول TikTok إنه لا ينبغي إعادة المحاولة.
أحداث يتوقف TikTok عن إرسالها لحساب ما بعد انتهاء تفويض المالك أو سحبه.
أسباب ظهور authorization.removed من TikTok for Developers: قطع المستخدم الاتصال، أو حذف الحساب، أو تغيّر العمر، أو الحظر، أو إلغاء المطور.
تكرار فحص easyCoexistence لكل حساب TikTok متصل؛ يجدّد الرمز 24 ساعة بنفسه ويرسل إليك بريدًا إذا لزم إعادة الاتصال.
لماذا يتوقف اتصال TikTok API؟
لأسباب قليلة، أغلبها مرتبط برموز الحساب أو بموافقة المالك. بعضها يُنهي الاتصال تمامًا، وبعضها يتركه نصف عامل، فتُرفض بعض الاستدعاءات ويستجيب الباقي:
ما الخطأ الذي يُعيده كل سبب، وما الحل؟
يُسمّي حقل code لدى TikTok أغلبها، ضمن استجابة HTTP 200 لا ضمن حالة خطأ، وتضيف حالة النشر سبب فشل خاصًا بها. ويرد الرمز 40100 في الجدول لأن الاستدعاء المقيَّد قد يبدو كاتصال مفقود. ما يعنيه كل منها، والحل:
| What it means | The fix | |
|---|---|---|
| 40102 | The access token is past its 24 hours | Renew with the refresh token, store both new tokens, repeat the call |
| 40103 | The refresh token has expired | A new authorization by the owner; nothing renews it |
| 40104 | The request carried no access token | A bug in the request: send the Access-Token header |
| 40105 | The access token is invalid or incorrect | Check what was sent, renew, then ask the owner to authorize again |
| 40107 | The refresh token is invalid or incorrect | Send the refresh token from the latest response, or a new authorization |
| 40131 | Authentication failed at a token endpoint | Check the app ID and secret, then the code or the refresh token |
| 40001 | A permission or scope is missing | Add it to the app, then have the owner authorize again |
| auth_removed | Access was removed while a post was processing | No retry; publish again after a new authorization |
| 40100 | Throttled, not disconnected | Pause the endpoint 5 minutes; the token still works |
كم تدوم الرموز، ومتى يُجدَّد؟
في API for Business يدوم رمز الوصول 24 ساعة، ويُعطي expires_in في كل استجابة رمز عدد الثواني المتبقية؛ ويدوم رمز التحديث سنة، ولها عداد خاص في refresh_token_expires_in. جدِّد قبل انتهاء اليوم بوقت كافٍ، وفق جدول لا بعد استدعاء فاشل، واحفظ رمز التحديث الذي يعيده كل تجديد، لأن ملاحظة TikTok على هذا الحقل تنص على الاحتفاظ به. تعامل مع refresh_token_expires_in كموعد نهائي: ففي مثال التجديد لدى TikTok يتناقص العداد بدل أن يبدأ سنة جديدة.
ماذا يحدث عندما يسحب المالك وصول التطبيق؟
يفقد التطبيق أذونات Accounts API التي منحها المالك، فتتوقف الاستدعاءات بذلك الرمز، ولا يوثّق TikTok في API for Business أي حدث يعلن ذلك. يستطيع المالك فعل ذلك في أي وقت من تطبيق TikTok، عبر الإعدادات والخصوصية، ثم الأمان، ثم إدارة أذونات التطبيقات، ثم إزالة الوصول. وتظهر العلامات في مكان آخر: منشور كان TikTok يعالجه يفشل بالحالة auth_removed، ويقول TikTok إنه لا ينبغي إعادة المحاولة، وتتوقف أحداث comment.update للحساب عن الوصول.
ماذا يفعل تغيّر نوع الحساب بالاتصال؟
لا يربط TikTok أي خطأ رمز بهذا التغيير في وثائقه؛ ما يتغير هو ما تعيده الواجهة. تحتاج بيانات مثل unique_video_views وdaily_new_followers وaudience_activity إلى Advanced Access أو حساب أعمال موثّق، وكذلك واجهتا Mentions وBusiness Messaging، ولا تتضمن privacy_level_options لدى الحساب الخاص القيمة PUBLIC_TO_EVERYONE. ومنذ 16 أكتوبر 2026 لا تكون قيمة is_business_account صحيحة إلا لحسابات الأعمال الموثّقة، وتُبلغ has_advanced_access عن Advanced Access؛ لذلك فقراءة الاثنين معًا، تحت user.account.type، تُظهر التغيير قبل أن يتعثر استدعاء فيه.
كيف تكتشف الاتصال الميت قبل أن يكتشفه العميل؟
بفحوص تعمل سواء نشر أحد شيئًا أم لا:
- استدعاء خفيف لكل حساب وفق جدول، مثل /business/get/ مع الحقل username، الذي يُعيد خطأ رمز حين يتوقف الرمز عن العمل.
- /
tt_user/token_info/get/، الذي لا يحتاج إذنًا ويُعيد نطاق الرمز، للتأكد من أن الصلاحيات لا تزال تغطي ما تستدعيه ميزاتك. - تحويل
refresh_token_expires_inإلى تاريخ عند وصول كل استجابة، مع تذكير للمالك قبل ذلك بأسابيع. - صمت comment.update لحساب يتلقى تعليقات عادةً، لأن TikTok يوقف تلك الأحداث بعد انتهاء التفويض أو سحبه.
- عدّ الأكواد 40102 و40103 و40104 و40105 لكل حساب، حتى يبرز الحساب المتعثر بين كثير من الحسابات.
كيف تُعيد ربط حساب؟
بتشغيل التفويض من جديد للحساب نفسه. شارك رابط تفويض صاحب حساب TikTok مع قيمة state تربط العودة بالحساب، ومعها disable_auto_auth=1 إذا كان ينبغي للمالك أن يرى صفحة الأذونات من جديد. بادل auth_code الجديد عند /tt_user/oauth2/token/ خلال 10 دقائق، ثم استبدل الرمزين المحفوظين معًا. open_id هو المعرّف الخاص بالتطبيق لدى TikTok للحساب، فطابق الرموز الجديدة مع السجل المحفوظ به بدلًا من إنشاء سجل ثانٍ.
هل تنتهي اتصالات Content Posting API بالطريقة نفسها؟
لا. يخدم TikTok for Developers واجهتي Content Posting وDisplay، وحدّث صفحات الرموز في 2 نوفمبر 2026: تنتهي رموز وصول المستخدم خلال ساعتين، وتدوم رموز التحديث 180 يومًا من أول إصدار. وهي تتبدّل، فكل تحديث ناجح يعيد رمزًا جديدًا ويُبطل فورًا الرمز المُرسل، فإذا واصل خادم استخدام رمز استُبدل، تفشل التجديدات اللاحقة ويضطر المستخدم إلى التفويض من جديد. يفشل رمز التحديث الخاطئ بالخطأ invalid_grant، ورمز الوصول الخاطئ بالخطأ access_token_invalid وHTTP 401، ويوضح خطاف الويب (webhook) الخاص بـ authorization.removed سبب مغادرة المستخدم.
ماذا يفعل easyCoexistence للإبقاء على اتصال TikTok نشطًا؟
يُجدّد ويفحص بنفسه، ويخبرك حين لا يستطيع إصلاح الأمر إلا المالك:
- التجديد: قبل استدعاء حين يبقى أقل من 15 دقيقة، وأثناء الفحص حين يبقى أقل من 8 ساعات، مع حفظ رمز التحديث الجديد وتاريخ انتهائه في كل مرة.
- تجديد واحد في كل وقت لكل حساب، فتشترك الاستدعاءات التي تصل معًا فيه.
- الفحص: استدعاء /business/get/ لاسم مستخدم الحساب كل 6 ساعات تقريبًا.
- رمز مرفوض، أي 40102 أو 40104 أو 40105: تُظهر القناة الحالة «تحتاج إلى إعادة الاتصال»، ويتلقى المالك بريدًا واحدًا، وتتلقى المنصة channel.disconnected مع رسالة TikTok في الحقل
disconnected_reason. - إلى أن يحدث ذلك، تجيب الأدوات بأن الحساب يحتاج إلى إعادة الاتصال، ويفشل المنشور المجدول بالحالة reconnect بدلًا من الوصول إلى TikTok.
- إعادة الاتصال: بالضغط على Connect TikTok في صفحة القناة، أو بجلسة ربط جديدة، يُعاد تسجيل الدخول مع الإبقاء على
account_idنفسه ووجهة الأحداث نفسها.
كيفية إعداده
- Store both tokens with datesSave access_token, refresh_token, open_id and scope, and turn expires_in and refresh_token_expires_in into dates as each response arrives.
- Renew ahead of the dayCall /tt_user/oauth2/refresh_token/ well before the 24 hours end, one renewal per account at a time, and keep the refresh token it returns.
- Check each accountMake one light call per account on a schedule and record any 40102, 40103, 40104 or 40105 against that account.
- Ask before the year endsSend the owner the authorization URL before refresh_token_expires_in runs out, and replace both tokens when the new code arrives.
- Reconnect on a token errorWhen renewal fails or the token is refused, stop calling for that account and send its owner the authorization URL.
الأخطاء الشائعة
- الخلط بين هدوء webhook التعليقات وهدوء الحساب. يوقف TikTok comment.update للحساب بعد انتهاء تفويضه، فافحص الحساب بدلًا من انتظار الأحداث.
- إعادة الربط في سجل جديد. طابق الرموز الجديدة بـ open_id، وهو المعرّف الخاص بالتطبيق لدى TikTok للحساب، وحدّث السجل المحفوظ في مكانه مع الإبقاء على سجله وإعداداته.
- إعادة المحاولة بالرمز نفسه عند 40103 أو 40107. لا يزول أيٌّ منهما بإعادة المحاولة: الأول يحتاج تفويضًا جديدًا، والثاني يحتاج رمز التحديث من آخر استجابة أو تفويضًا جديدًا.
- قراءة 40100 على أنه اتصال مفقود. هو استدعاء مقيَّد؛ أوقف النقطة الطرفية 5 دقائق، أو حتى الساعة 00:00 UTC بعد حد يومي، فيواصل الرمز نفسه العمل.
من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ينخفض كلما أضفت اتصالات، مع أول 3 أيام مجانًا.
الأسئلة الشائعة
هل يمكن أن يبقى اتصال TikTok API إلى الأبد دون المالك؟
لا. يحمله التجديد عبر سنة رمز التحديث كحد أقصى؛ بعد ذلك يكون المسار الموثّق لدى TikTok تفويضًا جديدًا من مالك الحساب.
لماذا فشلت اتصالات TikTok لعدة حسابات في وقت واحد؟
انظر إلى التطبيق قبل الحسابات: يعني الكود 40113 أن التطبيق محظور أو أن معرّفه وسره لا يتطابقان، ويستطيع TikTok سحب وصول التطبيق إلى Accounts API عند إساءة الاستخدام.
هل تستلزم الميزة الجديدة إعادة ربط حسابات TikTok؟
نعم، إذا احتاجت نطاقًا لم يمنحه المالك قط. يحتفظ الرمز بالنطاقات التي وافق عليها المالك عند التفويض، لذلك يفوّض المالك التطبيق من جديد لإضافة نطاق.
ماذا يحدث للمنشورات المجدولة على TikTok أثناء حاجة الحساب إلى إعادة الربط؟
على easyCoexistence تفشل في وقتها بالحالة reconnect بدلًا من الوصول إلى TikTok، ويُرسل بريد إلى المالك، ويعيد زر Retry إرسالها بعد ربط الحساب من جديد.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في