نظرة على واجهة REST
تتيح لك واجهة REST من AD80 أن تصل من سكربتاتك وخوادمك إلى البيانات نفسها التي تراها في لوحة المتابعة: التطبيقات، والإعلانات، والمخالفات، والسياسات، و«جرّب سياستك»، والحوادث، واستهلاك الباقة، واشتراكات الإشعارات.
العنوان الأساسي
Section titled “العنوان الأساسي”https://api.ad80.devتبدأ كل المسارات بـ /v1/. الطلبات والردود بصيغة JSON (UTF-8) ما لم يُذكر غير ذلك. الأوقات بصيغة RFC 3339 وبتوقيت
UTC، مثل 2026-10-26T14:03:00Z. أما التواريخ في معاملات الاستعلام فتُكتب YYYY-MM-DD (أيام بتوقيت UTC). وإن أرسلت
في جسم الطلب حقلًا لا نعرفه، يُرفض الطلب بالرمز 400.
المصادقة
Section titled “المصادقة”أرسل مفتاح API الخاص بك كرمز Bearer:
Authorization: Bearer ad80_ck_YOUR_KEYتنشئ مفاتيح API من صفحة التطبيقات وSDK ← مفاتيح API ← أنشئ مفتاح API،
أو عبر POST /v1/keys. يظهر المفتاح السري مرة واحدة فقط. احفظه في مدير أسرار أو في
متغير بيئة، ولا تضعه أبدًا داخل تطبيق: من يملكه يستطيع قراءة بياناتك.
تقرأ الأمثلة في هذا الشرح المفتاح من متغير بيئة:
export AD80_API_KEY="ad80_ck_YOUR_KEY"curl -s https://api.ad80.dev/v1/me -H "Authorization: Bearer $AD80_API_KEY"النطاقات
Section titled “النطاقات”لكل مفتاح نطاق واحد أو أكثر. ولا يستطيع المفتاح أن ينشئ مفاتيح إلا بنطاقات يملكها هو نفسه.
| النطاق | ما يسمح به |
|---|---|
read:creatives | عرض التطبيقات، وقراءة الإعلانات والنظرة العامة والباقة والاستهلاك، وصور «جرّب سياستك» وإعلاناتها النموذجية. |
read:verdicts | الأحكام (الدرجات والتفسيرات) داخل بيانات الإعلانات، وقائمة المخالفات، وخيارا التصفية rule وminScore، وقراءة السياسات وإصداراتها والتقديرات، وقراءة الحوادث. |
write:policies | حفظ السياسات، وتشغيل تجارب المسودّات، ومراجعة الإعلانات («مخالفة مؤكدة» أو «ليست مخالفة»)، ورفع صور «جرّب سياستك» وفحصها وإعادة فحصها، وتحديث الحوادث. |
manage:keys | عرض المفاتيح وإنشاؤها وتجديدها وإبطالها، وإنشاء التطبيقات. |
manage:notifications | كل ما تحت /v1/notifications (الاشتراكات، والتحقق، والاختبارات، والأسرار، وعمليات التسليم). |
النطاقان manage:webhooks وread:spend مقبولان عند إنشاء المفتاح، لكنهما لا يفتحان حاليًا أي نقطة نهاية عامة.
مفتاح التقارير المعتاد، للقراءة فقط، يحمل النطاقين read:creatives وread:verdicts.
ما لا تستطيعه مفاتيح API
Section titled “ما لا تستطيعه مفاتيح API”الأعضاء والدعوات وسجل النشاط وتسجيل الدخول أمور تخص الأشخاص لا المفاتيح. لذلك تحتاج GET /v1/members
و/v1/invites و/v1/audit إلى جلسة في لوحة المتابعة، وترد على مفتاح API بالرمز 403 مع code: forbidden.
الأخطاء
Section titled “الأخطاء”لكل خطأ الجسم نفسه:
{ "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 ثانية. |
حدود الباقة (entitlement)
Section titled “حدود الباقة (entitlement)”إن لم تشمل باقتك إجراءً ما، أو نفد رصيد شهري، يكون الرد 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 osimport 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"])// Node 18+ (built-in fetch)const API = 'https://api.ad80.dev';const headers = { Authorization: `Bearer ${process.env.AD80_API_KEY}` };
async function* allViolations(filters = {}) { const params = new URLSearchParams({ limit: '200', ...filters }); while (true) { const res = await fetch(`${API}/v1/violations?${params}`, { headers }); if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`); const body = await res.json(); yield* body.creatives; if (!body.nextCursor) return; params.set('cursor', body.nextCursor); }}
for await (const c of allViolations({ review: 'unreviewed' })) console.log(c.id, c.appId);حدود الطلبات وإعادة المحاولة
Section titled “حدود الطلبات وإعادة المحاولة”لا تعلن AD80 حدودًا ثابتة لعدد الطلبات على واجهة REST. لكن لبعض الإجراءات حدودها الخاصة (مثل اختبارات الإشعارات
والتحقق منها). إن وصلك 429 أو 503، فانتظر عدد الثواني المذكور في Retry-After قبل أن تعيد المحاولة. وأعد محاولة
ردود 5xx مع زيادة مدة الانتظار في كل مرة.
التخزين المؤقت
Section titled “التخزين المؤقت”تحمل ردود الواجهة Cache-Control: no-store. وروابط الصور تنتهي صلاحيتها؛ اقرأ روابط الصور الموقّعة.
نقاط النهاية
Section titled “نقاط النهاية”| المجال | الصفحة |
|---|---|
| من أنا، والباقة والاستهلاك، والنظرة العامة | الحساب والباقة |
| التطبيقات والمفاتيح | التطبيقات والمفاتيح |
| الإعلانات والمخالفات والمراجعات | الإعلانات والمخالفات |
| الصور | روابط الصور الموقّعة |
| السياسات وتجارب المسودّات | السياسات |
| جرّب سياستك | جرّب سياستك |
| الحوادث (Enterprise) | الحوادث |
| الإشعارات وWebhooks | الإشعارات |