آخر تحديث 1 نوفمبر 2026

المصادقة

يحمل كل طلب مفتاح API خاصًا بمساحة العمل كرمز Bearer. المفاتيح محددة النطاق وقابلة للإلغاء ومرتبطة بمحفظة الرصيد لمساحة عمل واحدة.

مفاتيح Bearer

أرسل المفتاح في الترويسة Authorization بالصيغة Bearer <key>. تبدو المفاتيح هكذا: ttk_live_<id>_<secret>، وتعرضها لوحة التحكم بالبادئة ttk_live_<id>. أنشئها من Settings → API keys؛ ويُعرض المفتاح كاملًا مرة واحدة فقط. يعمل المفتاح نيابةً عن مالك مساحة العمل، في حدود نطاقاته.

curl "https://api.toktokdata.live/v1/rankings/regions" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

محفظة واحدة

يستهلك المفتاح رصيد مساحة العمل التي يتبع لها. ويظهر الاستخدام من واجهة API ومن لوحة التحكم معًا في Settings → Usage.

النطاقات

لا يمكن للمفتاح استدعاء إلا نقاط النهاية التي تشملها نطاقاته. اختر أصغر مجموعة تؤدي الغرض؛ فبإمكانك دائمًا إنشاء مفتاح ثانٍ. الطلبات الواقعة خارج نطاقات المفتاح، والمسارات الخاصة بلوحة التحكم وحدها (قائمة المتابعة، وغرف البث، ومساحة العمل، والفوترة)، تُرجع 403 مع الرمز insufficient_scope؛ أما الباقة التي لا تتضمن الوحدة فتُرجع module_not_entitled.

النطاق	ما يمنحه
`live:read`	جلسات LIVE، والجلسة الواحدة، وأداء صانع المحتوى، وتحديث حالة البث المباشر. يتطلب وحدة LIVE.
`rank:read`	لوحات التصنيف الرسمية والمناطق وسجل لوحات التصنيف. يتطلب وحدة LIVE.
`shop:read`	مطلوب أيضًا للوحات التسوق (قيمة board التي تبدأ بـ shopping).
`creator:read`	البحث عن صنّاع المحتوى، والملفات الشخصية، والتحليل، والتغييرات، والحسابات المتابَعة، والمتابعون، والرؤى. يتطلب وحدة البحث (Lookup).
`content:read`	الفيديوهات، وتعليقات الفيديو، وفيديوهات صانع المحتوى. يتطلب وحدة البحث (Lookup).
`trend:read`	الاتجاهات الإقليمية. يتطلب وحدة البحث (Lookup).
`export`	إنشاء ملفات التصدير وعرضها وتنزيلها.
`webhook:manage`	قواعد التنبيه على جميع القنوات، واختبارات القواعد. يتطلب وحدة LIVE.
`keys:manage`	عرض مفاتيح API وإنشاؤها وإلغاؤها؛ وقراءة استحقاقات الباقة والاستخدام.
`live:stream · gifter:read`	محجوزة لنقاط نهاية قادمة؛ ولا تمنح أي صلاحية حتى الآن.

تدوير المفاتيح

أنشئ المفتاح البديل أولًا وانشره، ثم ألغِ المفتاح القديم من الشاشة نفسها. يسري الإلغاء فورًا: تكتمل الطلبات الجارية، وتفشل الطلبات الجديدة بالرمز 401.

يمكن أيضًا إنشاء المفاتيح مع تاريخ expiresAt، وبعده تُرجع 401.

الأخطاء

الحالة	الرمز	المعنى
401	`unauthorized`	مفتاح مفقود أو مشوّه أو ملغى أو منتهي الصلاحية، أو مساحة عمل غير نشطة.
403	`insufficient_scope`	المفتاح صالح لكنه يفتقر إلى النطاق، أو أن المسار خاص بلوحة التحكم وحدها.
403	`module_not_entitled`	باقة مساحة العمل لا تتضمن وحدة LIVE أو وحدة البحث (Lookup).
402	`credit_cap_exceeded`	نفد رصيد الشهر. راجع وحدات الرصيد والأخطاء.

هل كانت هذه الصفحة مفيدة؟