مستندات توسعه‌دهنده

هر درخواست با استفاده از طرح Bearer و با کلید مخفی در هدر Authorization احراز هویت می‌شود.

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-mode از طریق یکپارچه‌سازی شما برای یک آگهی هزینه می‌پردازد.
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
}

هر حساب تبلیغ‌دهنده مجموعه‌ای از ابزارهای هوش مصنوعی داخلی را دریافت می‌کند — یک تولیدکننده محتوا و تصویر تبلیغاتی، یک دستیار مکالمه‌ای، یک مشاور بودجه و یک حسابرس سئوی خارجی — که هزینهٔ آن‌ها علاوه بر قیمت ثابت سالانه، با اعتبارات هوش مصنوعی پرداخت می‌شود.

مثال — تولید محتوای تبلیغاتی

همان دسته‌بندی و توضیحات کسب‌وکار همچنین به تولیدکنندهٔ تصویر زیر نیرو می‌بخشند.

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
}

شرایط پرداخت

• مجموع درآمد قابل پرداخت تبلیغ‌دهنده به حداقل مبلغ پرداختی می‌رسد.
• یک کیف‌پول پرداخت رمزارزی روی حساب کاربری آن‌ها پیکربندی شده است.
• وضعیت KYC آنها تأیید شده است.

مثال: خواندن درآمدهای انباشته

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 امضا می‌شود، با استفاده از یک رمز مخفی که تنها یک‌بار در زمان ایجاد صادر می‌شود — پیش از اعتماد به بارگیری، امضا را تأیید کنید. رویدادها تنها به شریکی ارسال می‌شوند که مالک تبلیغ‌دهندهٔ مربوطه است.