دليل Taboola API: نقاط النهاية (Backstage)، المصادقة والاستخدامات الحقيقية

Taboola API — المعروف رسميًا باسم Backstage API — هو واجهة REST الخاصة بـ Taboola للمعلنين. تقوم بالمصادقة باستخدام بيانات اعتماد OAuth 2.0 client credentials، ثم تقرأ وتكتب كل ما يمكنك الوصول إليه في Ads Console: الحملات، العناصر الإبداعية، الاستهداف، الميزانيات، وتقارير الأداء، كلها تحت https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. إنها الطبقة التي يستخدمها مشترو الوسائط لأتمتة تغييرات العطاءات والميزانيات، رفع الإبداعات بكميات كبيرة، مزامنة الإنفاق في مستودع البيانات، وبناء محركات القواعد التي لا توفرها واجهة Taboola. ما لا تعرضه عمدًا هو بيانات أي شخص آخر — للحصول على رؤية تنافسية للشبكة تحتاج إلى API مختلف تمامًا، وهو ما نغطيه في النهاية.

ما يغطيه Backstage API#

يعكس Backstage لوحة تحكم المعلن تقريبًا واحد لواحد. عمليًا، أربع مجالات تقوم بمعظم العمل:

• إدارة الحملات. إنشاء، قراءة، تحديث، وإيقاف الحملات؛ تعيين CPCs، الميزانيات اليومية والإجمالية، استهداف المنطقة الجغرافية/المنصة، وحظر المواقع. أي شيء كنت ستغيره يدويًا في السابعة صباحًا بعد مراجعة أرقام الليل يمكن أن يكون نصًا برمجيًا بدلاً من ذلك.
• العناصر (الإبداعات). تحتوي كل حملة على عناصر — وحدات الصورة والعنوان التي يتم عرضها فعليًا. يتيح لك الـ API إضافة عناصر بكميات كبيرة، تحديث حالتها، وقراءة حالة المراجعة لكل عنصر، وهي الطريقة التي تنقل بها الحسابات الكبيرة عشرات المتغيرات الإبداعية دون لمس الواجهة. (إذا كنت لا تزال تقوم بإعداد حملاتك الأولى يدويًا، ابدأ مع شرحنا خطوة بخطوة لإعداد حملة Taboola — يفترض الـ API أنك تعرف مفاهيم الواجهة بالفعل).
• التقارير. نقاط نهاية الأداء المُجمَّعة مقسمة حسب الأبعاد — اليوم، الحملة، الموقع، الدولة، المنصة، العنصر — المادة الخام لأي تحسين آلي.
• القواميس. نقاط نهاية للبحث عن القيم الثابتة التي يعتمد عليها كل شيء آخر: رموز الدول، المنصات، شرائح الجمهور.

يأتي الوصول على شكل معرّف عميل وكلمة سر تصدر لحسابك — مطلوبة تاريخيًا عبر مدير حسابك في Taboola — والمرجع الرسمي لـ Backstage هو المصدر الموثوق به لأشكال نقاط النهاية الحالية وإجراءات الوصول. مسارات نقاط النهاية أدناه هي الحالية وقت كتابة هذا المقال؛ تحقق من المرجع قبل البدء في البناء.

المصادقة: من بيانات اعتماد العميل إلى رمز Bearer#

يستخدم Backstage آلية OAuth 2.0 client-credentials flow القياسية. استبدل معرّفك وكلمة السر لتحصل على رمز:

curl -X POST "https://backstage.taboola.com/backstage/oauth/token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

تحتوي الاستجابة على access_token ترسله كرأس Bearer في كل استدعاء:

curl "https://backstage.taboola.com/backstage/api/1.0/users/current/allowed-accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"

استدعاء allowed-accounts هذا هو الطلب الأول المناسب: يعيد قيم account_id (المعرفات الرقمية والأسماء المقروءة) التي تحتاجها كل نقطة نهاية أخرى في مسارها. تنتهي صلاحية الرموز — قم بتخزين واحد وإعادة التحديث عند تلقي استجابة 401 بدلاً من إنشاء رمز جديد لكل طلب، سواءً من أجل زمن الاستجابة أو لأن طلبات الرمز مُقيّدة بالمعدل بشكل أكثر تشددًا من طلبات البيانات.

نقاط النهاية التي ستستخدمها فعليًا#

تأخذ نقاط نهاية التقارير معاملات الاستعلام start_date و end_date بالإضافة إلى عوامل تصفية اختيارية، ويقرر مقطع dimension (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) طريقة التقسيم. site_breakdown هو الأكثر أهمية للتحسين: إنه تدفق الأداء لكل ناشر الذي يقود أتمتة قائمة الحظر.

ما يقوم مشترو الوسائط بأتمتته فعليًا#

يكسب الـ API تكلفة إعداده في أربع مهام متكررة:

1. محركات القواعد. الكلاسيكية: كل ساعة، اسحب site_breakdown للحملات النشطة؛ أي موقع أنفق أكثر من N× CPA المستهدف مع صفر تحويلات يوضع في قائمة المواقع المحظورة للحملة عبر تحديث الحملة. هذه هي نفس حلقة "اقطع الخاسرين" التي يديرها كل معلن Taboola جاد يدويًا — مشفرة، غير عاطفية، وتعمل في الثالثة صباحًا.
2. إدارة العطاءات. تعديل CPCs للحملات (ومعاملات العطاءات لكل موقع حيثما تتوفر) للأعلى في الأيام والمناطق الجغرافية التي تتفوق على المستهدف، وللأسفل عندما ينحرف CPA — تعديلات صغيرة، متكررة، مملة تتراكم.
3. عمليات الإبداع الكمي. رفع 30 متغيرًا للعنوان/الصورة لكل حملة، إيقاف كل ما يقل عن متوسط CTR أسبوعيًا، والحفاظ على تناوب الإبداعات متقدمًا على التعب دون قضاء ظهر كامل في النقر.
4. مسارات الإنفاق. مهمة ليلية تسحب campaign-summary حسب اليوم إلى المستودع، بحيث يصل إنفاق Taboola بجانب إيرادات التحويل وكل قناة أخرى في لوحة تحكم واحدة.

خطة تكامل بسيطة#

إذا كنت تبدأ من الصفر، فإن هذا التسلسل يوصلك إلى أتمتة مفيدة في يوم عمل تقريبًا، مع إمكانية التحقق من كل خطوة قبل التالية:

1. رحلة الذهاب والإياب للرمز (Token). استبدل بيانات الاعتماد لتحصل على رمز واستدعِ allowed-accounts. إذا نجح هذا، فإن المصادقة والصلاحيات قد حُلّت.
2. التقارير للقراءة فقط. اسحب campaign-summary حسب اليوم للأسبوع الماضي ووفق الأرقام مع Ads Console. لا تكتب أي شيء حتى تتطابق قراءاتك مع ما تظهره الواجهة.
3. تغيير آمن واحد. أوقف وأعد تشغيل حملة تجريبية واحدة عبر PUT. تأكد من ظهور التغيير في الواجهة وأن حالة العرض تتبع.
4. مزامنة الإنفاق الليلية. جدولة سحب التقارير إلى قاعدة البيانات الخاصة بك. هذا وحده يُبرر التكامل لمعظم الفرق.
5. محرك القواعد، في وضع التجربة (dry-run). احسب قرارات حظر المواقع وسجل ما سيحدث لمدة أسبوع قبل السماح له بالكتابة. مقارنة خياراته مع ما تقوم به يدويًا هي أرخص اختبار ضمان جودة ستقوم به على الإطلاق.

تخطي الخطوات مباشرة إلى الخطوة الخامسة هو الخطأ الشائع — الأخطاء في مسار الكتابة ضد حساب إعلاني حي هي دروس باهظة الثمن.

حدود المعدل والمزالق العملية#

• احترم الحد الأقصى. ينفذ Backstage حدود معدل لكل حساب؛ قم بتجميع عمليات القراءة (استدعاء تقرير واحد لكل حملة في الساعة، وليس واحدة في الدقيقة) وتراجع عند تلقي استجابة 429s. راجع المرجع للحدود الحالية بدلاً من الافتراض.
• تأخر التقارير عن العرض. تستقر بيانات الساعات الأخيرة مع الوقت؛ ابنِ القواعد اعتمادًا على بيانات متأخرة ببضع ساعات على الأقل وإلا ستوقف الحملات على أرقام غير مكتملة.
• التعديلات ليست فورية. تغييرات الحملة تنتشر إلى العرض مع تأخير، وتعديلات العناصر يمكن أن تعيد تشغيل المراجعة. يجب أن تتحمل الأتمتة الفجوة بدلاً من إعادة إصدار كتابات "فاشلة".
• قم بتخزين المعرفات، وليس الأسماء. يتم تحرير أسماء الحملات والعناصر بواسطة البشر؛ المعرفات الرقمية هي مفاصل ربط مستقرة.
• حمِ مسار الكتابة. محرك قواعد به خطأ يمكن أن يوقف الإنفاق الكامل لحساب أو يضاعف العطاء 10 مرات. سجل كل تعديل، أضف حدودًا منطقية (لا تغير العطاء أكثر من X٪ لكل مرور)، وابدأ أي قاعدة جديدة في وضع التجربة (dry-run).

Taboola API الآخر: البيانات التنافسية#

كل ما ورد أعلاه يرى حسابًا واحدًا بالضبط: حسابك. لن يخبرك Backstage أبدًا عن المعلنين الذين يتوسعون في مجال عملك، أو الإبداعات التي يعرضونها، أو المدة التي صمدت فيها حملة منافس — لا تنشر الشبكة مكتبة إعلانات خاصة بها، ولا تعرض أي نقطة نهاية رسمية نشاط المعلنين الآخرين.

هذه هي الفجوة التي يغطيها API المطور الخاص بـ OpenAdLibrary. تحتوي الفهرسة على أكثر من 206,000 إعلان Taboola حي (يوليو 2026) داخل مجموعة من 725,000+ إعلان أصلي عبر 49 شبكة، ويمكن الاستعلام عن نفس البيانات وراء مكتبة إعلانات Taboola عبر REST: ابحث عن الإبداعات حسب المعلن، المجال، المنطقة الجغرافية، ومدة البقاء؛ اسحب العناوين وصفحات الهبوط؛ تتبع متى يطلق المنافسون الحملات ويوقفونها. يوثق دليل API بيانات الإعلانات الأصلية نقاط النهاية، وإذا كان سير عملك يعمل داخل وكيل LLM فهناك خادم MCP يعرض نفس المجموعة كأدوات لـ Claude و ChatGPT. يغطي المفتاح المجاني الاستخدام الخفيف ويظل التسعير ثابتًا للباقي؛ تمت دراسة المشهد الأوسع للوصول إلى ذكاء الإعلانات البرمجي في أدوات تجسس الإعلانات مع API.

يتناغم الـ APIان بشكل طبيعي: Backstage يٌأتمت التنفيذ على حسابك، بينما يٌأتمت API الاستخبارات البحث على حسابات الجميع الآخرين. المشترون الذين يحصلون على أقصى استفادة من الأتمتة يشغلون كليهما — محرك قواعد يحافظ على حملاتهم الخاصة مُقلّمة، وتدفق تنافسي يشير إلى متى يبدأ معلن جديد في التوسع في مجالهم بحيث لا يتم اختيار الاختبار التالي أبدًا بشكل أعمى. ابدأ مع أداة تجسس Taboola لرؤية المجموعة التنافسية في المتصفح، ثم انتقل إلى نفس الاستعلامات برمجيًا عندما يثبت سير العمل فاعليته.