وثائق المطورين

يتم توثيق كل طلب باستخدام مفتاح سري في رأس «Authorization»، وذلك وفقًا لنظام «Bearer».

POST https://api.adhub365.com/v1/partner/ads
Authorization: Bearer sk_sandbox_...
Content-Type: application/json

إذا كانت مفاتيح واجهة برمجة التطبيقات (API) الخاصة بك تُنشئ حسابات معلنين لمستخدميك (وضع «Connect» — انظر «المصادقة» أعلاه)، فإنك تحصل على حصة مما يدفعه هؤلاء المعلنون مقابل إعلاناتهم. يتم قراءة التوزيع الموضح أدناه بشكل مباشر من نقطة النهاية هذه نفسها، ولا يتم ترميزه أبدًا بشكل ثابت، كما أنه منفصل تمامًا عن عمولة الإحالة المذكورة في أسفل هذه الصفحة.

GET https://api.adhub365.com/v1/partner-program

{
  "partner_share_percentage": 0.7,
  "platform_share_percentage": 0.3
}

كيف يعمل

1. يقوم أحد المعلنين في وضع «Connect» بدفع ثمن إعلان عبر نظام التكامل الخاص بك.
2. يتم مراجعة الإعلان والموافقة عليه — إما تلقائيًا أو من قِبل فريق الإشراف لدينا.
3. تم إدراج حصتك في قائمة الانتظار ليتم دفعها تلقائيًّا إلى محفظتك، وذلك بنفس الآلية المتبعة في برنامج الإحالة المذكور أدناه.

شروط الدفع

• تم تهيئة محفظة دفع بالعملات المشفرة على حساب الشريك الخاص بك.
• لا يلزم من جانبك تقديم أي معلومات للتعرف على العميل (KYC) — فقد تم بالفعل التحقق من حساب الشريك الخاص بك عند إنشائه.

مثال: قراءة الأسهم المتراكمة

GET https://api.adhub365.com/v1/partner/ad-revenue/earnings
Authorization: Bearer sk_sandbox_...

{
  "shares": [
    {
      "id": "share_1a2b...",
      "payment_id": "pay_9f2a...",
      "ad_id": "ad_7c31...",
      "partner_amount_usd": 140.0,
      "platform_amount_usd": 60.0,
      "status": "paid",
      "payable_after": "2026-08-03T00:00:00Z",
      "paid_at": "2026-08-05T10:12:00Z"
    }
  ],
  "total_payable_pending_usd": 0.0,
  "total_payable_usd": 0.0,
  "total_processing_usd": 0.0,
  "total_paid_usd": 140.0
}

يحصل كل حساب معلن على مجموعة من أدوات الذكاء الاصطناعي المدمجة — وهي أداة لتوليد محتوى الإعلانات والعناصر المرئية، ومساعد محادثة، ومستشار ميزانية، ومدقق خارجي لتحسين محركات البحث (SEO) — يتم دفع تكاليفها باستخدام أرصدة الذكاء الاصطناعي، بالإضافة إلى السعر السنوي الثابت.

مثال — إنشاء محتوى إعلاني

وتُستخدم الفئة نفسها ووصف النشاط التجاري أيضًا لتشغيل أداة إنشاء الصور أدناه.

POST https://api.adhub365.com/v1/advertisers/{advertiser_id}/ai/creative-studio
Authorization: Bearer <session access token>
Content-Type: application/json

{
  "category_name": "Furniture",
  "business_description": "We sell handmade oak dining tables"
}

{
  "title": "Handmade Oak Dining Tables — Built to Last",
  "description": "Solid oak dining tables crafted by hand, built to last a lifetime.",
  "keywords": ["oak furniture", "dining table", "handmade"],
  "credits_remaining": 8
}

إنشاء صورة مطابقة لنفس الإعلان:

POST https://api.adhub365.com/v1/advertisers/{advertiser_id}/ai/creative-studio/image
Authorization: Bearer <session access token>
Content-Type: application/json

{
  "category_name": "Furniture",
  "business_description": "We sell handmade oak dining tables"
}

{
  "visual_url": "https://cdn.uploadscenter.com/file_01m1...",
  "credits_remaining": 4
}

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

أضفه إلى صفحتك

<div
  class="annualads-widget"
  data-category="YOUR_CATEGORY_ID"
  data-geo="global"
  data-count="4"
  data-columns="2"
></div>
<script async src="https://adhub365.com/widget.js"></script>

بشكل افتراضي، يعرض هذا التصنيف العام الكامل للفئة — أي جميع المعلنين على المنصة، وليس فقط أولئك الذين قمت بجلبهم. لعرض الإعلانات الصادرة عن المعلنين الذين أنشأتهم عبر وضع «Connect» (الذين يدرون حصتك) فقط، أضف «data-partner» مع معرّف شريكك (يمكنك العثور عليه في صفحة «المطورين» في لوحة التحكم الخاصة بك):

<div
  class="annualads-widget"
  data-category="YOUR_CATEGORY_ID"
  data-geo="global"
  data-partner="YOUR_PARTNER_ID"
></div>
<script async src="https://adhub365.com/widget.js"></script>

إذا كان المعلنون لديك ينتمون إلى عدة فئات، فاستبعد «data-category» تمامًا — باستخدام «data-partner» وحده، تعرض الأداة كل إعلاناتك في جميع الفئات ضمن شبكة واحدة، بدلاً من الحاجة إلى كتلة أداة واحدة لكل فئة:

<div
  class="annualads-widget"
  data-geo="global"
  data-partner="YOUR_PARTNER_ID"
></div>
<script async src="https://adhub365.com/widget.js"></script>

هل تريد وحدة على غرار التذييل إلى جانب الوحدة الموجودة داخل المحتوى، بحيث تعرض كل منهما إعلانات مختلفة؟ أضف كتلة واجهة مستخدم ثانية مع data-layout="compact" (إعلان واحد، قابل للطي إلى شكل حبة صغيرة) وقم بتعيين data-offset على عدد الإعلانات التي تعرضها واجهة المستخدم الأولى بالفعل:

<!-- in your content -->
<div
  class="annualads-widget"
  data-category="YOUR_CATEGORY_ID"
  data-geo="global"
  data-count="4"
  data-columns="2"
></div>

<!-- in your footer, showing different ads via data-offset -->
<div
  class="annualads-widget"
  data-category="YOUR_CATEGORY_ID"
  data-geo="global"
  data-layout="compact"
  data-offset="4"
></div>
<script async src="https://adhub365.com/widget.js"></script>

الخصائص

كيف تصل عمولة الإحالة إلى الشريك فعليًّا — النسبة المئوية، وآلية الدفع، والشروط المسبقة.

GET https://api.adhub365.com/v1/referral-program

{
  "levels": [
    {
      "level": 1,
      "percentage": 0.1
    }
  ],
  "leaders_pool_percentage_of_gmv": 0.05,
  "founding_advertiser_pool_percentage_of_gmv": 0.05,
  "payout_verification_window_hours": 48,
  "min_payout_usd": 1
}

شروط الدفع

• يصل إجمالي الأرباح المستحقة الدفع للمعلن إلى الحد الأدنى لمبلغ الدفع.
• يتم تهيئة محفظة لتلقي مدفوعات العملات المشفرة على حسابهم.
• تم التحقق من حالة "اعرف عميلك" الخاصة بهم.

مثال: قراءة الأرباح المتراكمة

GET https://api.adhub365.com/v1/partner/referrals/{code}/earnings
Authorization: Bearer sk_sandbox_...

{
  "code": "ann-2f8c",
  "earnings": [
    {
      "id": "earn_1a2b...",
      "payment_id": "pay_9f2a...",
      "amount_usd": 30.0,
      "status": "paid",
      "payable_after": "2026-08-01T00:00:00Z",
      "paid_at": "2026-08-03T14:22:00Z"
    }
  ],
  "total_payable_pending_usd": 0.0,
  "total_payable_usd": 0.0,
  "total_processing_usd": 0.0,
  "total_paid_usd": 30.0
}

مستويات الأسعار (قيد التشغيل)

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

يتم تحديد الحد الأقصى لعدد الطلبات لكل مفتاح وفي الدقيقة. تحتوي كل استجابة تم المصادقة عليها على رؤوس X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset؛ وفي حالة تجاوز الحد الأقصى، يتم إرجاع رمز الخطأ 429 Too Many Requests مع رأس Retry-After.

اختياري، لكل شريك. إلى أن تضيف إدخالاً، تقبل مفاتيحك الطلبات الواردة من أي عنوان IP — ويؤدي الإدخال الأول إلى تحويل جميع مفاتيح ذلك الشريك إلى وضع «قائمة المسموح لهم فقط».

يتم توقيع كل ويبهوك باستخدام خوارزمية HMAC-SHA256، وذلك باستخدام مفتاح سري يتم إصداره مرة واحدة فقط عند الإنشاء — يجب التحقق من التوقيع قبل الوثوق بالحمولة. ولا يتم تسليم الأحداث إلا إلى الشريك الذي يمتلك المعلن ذي الصلة.