تخطَّ إلى المحتوى

نظرة على واجهة REST

تتيح لك واجهة REST من AD80 أن تصل من سكربتاتك وخوادمك إلى البيانات نفسها التي تراها في لوحة المتابعة: التطبيقات، والإعلانات، والمخالفات، والسياسات، و«جرّب سياستك»، والحوادث، واستهلاك الباقة، واشتراكات الإشعارات.

https://api.ad80.dev

تبدأ كل المسارات بـ /v1/. الطلبات والردود بصيغة JSON (UTF-8) ما لم يُذكر غير ذلك. الأوقات بصيغة RFC 3339 وبتوقيت UTC، مثل 2026-10-26T14:03:00Z. أما التواريخ في معاملات الاستعلام فتُكتب YYYY-MM-DD (أيام بتوقيت UTC). وإن أرسلت في جسم الطلب حقلًا لا نعرفه، يُرفض الطلب بالرمز 400.

أرسل مفتاح API الخاص بك كرمز Bearer:

Authorization: Bearer ad80_ck_YOUR_KEY

تنشئ مفاتيح API من صفحة التطبيقات وSDK ← مفاتيح API ← أنشئ مفتاح API، أو عبر POST /v1/keys. يظهر المفتاح السري مرة واحدة فقط. احفظه في مدير أسرار أو في متغير بيئة، ولا تضعه أبدًا داخل تطبيق: من يملكه يستطيع قراءة بياناتك.

تقرأ الأمثلة في هذا الشرح المفتاح من متغير بيئة:

Terminal window
export AD80_API_KEY="ad80_ck_YOUR_KEY"
curl -s https://api.ad80.dev/v1/me -H "Authorization: Bearer $AD80_API_KEY"

لكل مفتاح نطاق واحد أو أكثر. ولا يستطيع المفتاح أن ينشئ مفاتيح إلا بنطاقات يملكها هو نفسه.

النطاقما يسمح به
read:creativesعرض التطبيقات، وقراءة الإعلانات والنظرة العامة والباقة والاستهلاك، وصور «جرّب سياستك» وإعلاناتها النموذجية.
read:verdictsالأحكام (الدرجات والتفسيرات) داخل بيانات الإعلانات، وقائمة المخالفات، وخيارا التصفية rule وminScore، وقراءة السياسات وإصداراتها والتقديرات، وقراءة الحوادث.
write:policiesحفظ السياسات، وتشغيل تجارب المسودّات، ومراجعة الإعلانات («مخالفة مؤكدة» أو «ليست مخالفة»)، ورفع صور «جرّب سياستك» وفحصها وإعادة فحصها، وتحديث الحوادث.
manage:keysعرض المفاتيح وإنشاؤها وتجديدها وإبطالها، وإنشاء التطبيقات.
manage:notificationsكل ما تحت /v1/notifications (الاشتراكات، والتحقق، والاختبارات، والأسرار، وعمليات التسليم).

النطاقان manage:webhooks وread:spend مقبولان عند إنشاء المفتاح، لكنهما لا يفتحان حاليًا أي نقطة نهاية عامة.

مفتاح التقارير المعتاد، للقراءة فقط، يحمل النطاقين read:creatives وread:verdicts.

الأعضاء والدعوات وسجل النشاط وتسجيل الدخول أمور تخص الأشخاص لا المفاتيح. لذلك تحتاج GET /v1/members و/v1/invites و/v1/audit إلى جلسة في لوحة المتابعة، وترد على مفتاح API بالرمز 403 مع code: forbidden.

لكل خطأ الجسم نفسه:

{ "error": "a sentence that explains the problem", "code": "machine_readable_code" }

يظهر code حين يكون على برنامجك أن يتصرف بناءً عليه. رموز الحالة:

الحالةمعناها
400الطلب غير صالح (JSON غير سليم، أو حقل غير معروف، أو قيمة خارج المدى). يخبرك error بالسبب.
401المفتاح مفقود أو غير معروف أو مُبطَل أو منتهي الصلاحية. يحمل الرد WWW-Authenticate: Bearer realm="ad80".
403ينقص المفتاحَ نطاقٌ (missing scope read:verdicts)، أو أن باقتك لا تسمح بهذا الإجراء (code: entitlement، انظر أدناه).
404غير موجود. والكائن الذي يخص مؤسسة أخرى يرد أيضًا بالرمز 404.
409تعارض، مثل تطبيق موجود من قبل.
413, 415, 422ملف أكبر من المسموح، أو نوع غير مدعوم، أو صورة لا يمكن استخدامها (في رفع صور «جرّب سياستك»).
429طلبات أكثر من اللازم. انتظر عدد الثواني المذكور في Retry-After.
502تعذّر الوصول إلى وجهة الإشعار (في الاختبارات وعمليات التحقق).
503الخدمة غير متاحة مؤقتًا. أعد المحاولة بعد Retry-After ثانية.

إن لم تشمل باقتك إجراءً ما، أو نفد رصيد شهري، يكون الرد 403:

{
"error": "monthly manual classification allowance reached",
"code": "entitlement",
"entitlement": "manual_classifications_per_month",
"limit": 200,
"used": 200,
"upgradeTo": "enterprise"
}
الحقلمعناه
entitlementالشيء المحدود: sdk_ingest، max_active_policies، manual_classifications_per_month، monitored_impressions_per_month، expedited_notifications_per_month، notification_channels، incident_management.
limit, usedأين وصلت. limit: 0 يعني أن باقتك لا تشمله.
upgradeToالباقة التي تسمح به (starter أو enterprise)، أو null.

الأرقام في المثال للتوضيح فقط. حدودك الفعلية تجدها في GET /v1/plan.

تقسيم النتائج إلى صفحات

Section titled “تقسيم النتائج إلى صفحات”

ترجع نقاط نهاية القوائم صفحة واحدة ومعها nextCursor:

{ "creatives": [ ... ], "nextCursor": "eyJ0IjoxNzYx..." }

لتحصل على الصفحة التالية مرّر cursor=<nextCursor>. وفي الصفحة الأخيرة تكون قيمة nextCursor هي null. المؤشرات غامضة عن قصد: لا تبنها بنفسك ولا تعدّلها. يحدد limit حجم الصفحة (من 1 إلى 200، والافتراضي 50) ما لم تذكر نقطة النهاية غير ذلك.

import os
import requests
API = "https://api.ad80.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['AD80_API_KEY']}"}
def all_violations(**filters):
params = {"limit": 200, **filters}
while True:
page = requests.get(f"{API}/v1/violations", headers=HEADERS, params=params, timeout=30)
page.raise_for_status()
body = page.json()
yield from body["creatives"]
if not body["nextCursor"]:
return
params["cursor"] = body["nextCursor"]
for creative in all_violations(review="unreviewed"):
print(creative["id"], creative["appId"])

حدود الطلبات وإعادة المحاولة

Section titled “حدود الطلبات وإعادة المحاولة”

لا تعلن AD80 حدودًا ثابتة لعدد الطلبات على واجهة REST. لكن لبعض الإجراءات حدودها الخاصة (مثل اختبارات الإشعارات والتحقق منها). إن وصلك 429 أو 503، فانتظر عدد الثواني المذكور في Retry-After قبل أن تعيد المحاولة. وأعد محاولة ردود 5xx مع زيادة مدة الانتظار في كل مرة.

تحمل ردود الواجهة Cache-Control: no-store. وروابط الصور تنتهي صلاحيتها؛ اقرأ روابط الصور الموقّعة.

المجالالصفحة
من أنا، والباقة والاستهلاك، والنظرة العامةالحساب والباقة
التطبيقات والمفاتيحالتطبيقات والمفاتيح
الإعلانات والمخالفات والمراجعاتالإعلانات والمخالفات
الصورروابط الصور الموقّعة
السياسات وتجارب المسودّاتالسياسات
جرّب سياستكجرّب سياستك
الحوادث (Enterprise)الحوادث
الإشعارات وWebhooksالإشعارات