Документация за разработчици

Всяко заявка се удостоверява с таен ключ в заглавката „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-аудитор — които се заплащат с AI-кредити в допълнение към фиксираната годишна цена.

Пример — създаване на рекламно съдържание

Същата категория и описание на дейността се използват и за генератора на изображения по-долу.

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, като се използва тайник, издаден еднократно при създаването му — проверете подписа, преди да се доверите на полезния товар. Събитията се изпращат само до партньора, който е собственик на съответния рекламодател.