Dokumentacja dla programistów

Każde żądanie jest uwierzytelniane za pomocą tajnego klucza zawartego w nagłówku „Authorization”, z wykorzystaniem schematu „Bearer”.

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

Jeśli Twoje klucze API służą do tworzenia kont reklamodawców dla Twoich użytkowników (tryb Connect — zob. sekcję „Uwierzytelnianie” powyżej), otrzymujesz część kwoty, jaką ci reklamodawcy płacą za swoje reklamy. Poniższy podział jest odczytywany na bieżąco z tego samego punktu końcowego, nigdy nie jest zakodowany na stałe i jest całkowicie niezależny od prowizji za polecenie, o której mowa w dalszej części tej strony.

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

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

Jak to działa

1. Jeden z reklamodawców korzystających z trybu Connect opłaca reklamę za pośrednictwem Twojej integracji.
2. Reklama jest sprawdzana i zatwierdzana — automatycznie lub przez nasz zespół moderatorów.
3. Twoja część została umieszczona w kolejce do automatycznej wypłaty na Twój portfel – działa to na tej samej zasadzie, co opisany poniżej program poleceń.

Warunki wypłaty

• Na koncie partnerskim skonfigurowano portfel do wypłat kryptowalut.
• Nie musisz przechodzić procesu weryfikacji tożsamości (KYC) — Twoje konto partnerskie zostało już zweryfikowane w momencie jego utworzenia.

Przykład: odczyt liczby zgromadzonych udziałów

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
}

Każde konto reklamodawcy otrzymuje zestaw wbudowanych narzędzi opartych na sztucznej inteligencji — generator treści i elementów wizualnych reklam, asystenta konwersacyjnego, doradcę ds. budżetu oraz zewnętrzny audyt SEO — za które płaci się kredytami AI, oprócz stałej opłaty rocznej.

Przykład — generowanie treści reklamowej

Ta sama kategoria i opis działalności stanowią również podstawę działania poniższego generatora obrazów.

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
}

Wygeneruj pasujący element graficzny do tej samej reklamy:

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
}

Umieść gotowy blok reklamowy na swojej stronie — bez konieczności tworzenia go od podstaw i bez użycia iframe. Skrypt wyświetla się bezpośrednio na stronie w izolowanym Shadow DOM, dzięki czemu jego style nigdy nie przenikają do Twojej witryny, a style Twojej witryny nigdy nie przenikają do niego.

Dodaj to do swojej strony

<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>

Domyślnie wyświetlany jest pełny, publiczny ranking dla danej kategorii — obejmujący wszystkich reklamodawców na platformie, a nie tylko tych, których pozyskałeś. Aby wyświetlić wyłącznie reklamy reklamodawców, których utworzyłeś w trybie Connect (czyli tych, którzy generują Twój udział), dodaj atrybut „data-partner” wraz ze swoim identyfikatorem partnera (znajdziesz go na stronie „Deweloperzy” w swoim panelu użytkownika):

<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>

Jeśli Twoi reklamodawcy należą do kilku kategorii, całkowicie pomiń atrybut „data-category” — dzięki samemu atrybutowi „data-partner” widżet wyświetli wszystkie Twoje reklamy ze wszystkich kategorii w jednej siatce, zamiast wymagać osobnego bloku widżetu dla każdej kategorii:

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

Chcesz, aby obok widżetu umieszczonego w treści pojawił się widżet w stopce, a każdy z nich wyświetlał inne reklamy? Dodaj drugi blok widżetu z atrybutem data-layout="compact" (pojedyncza reklama, którą można zwinąć do niewielkiej pigułki) oraz ustaw atrybut data-offset na liczbę reklam, które wyświetla już pierwszy widżet:

<!-- 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>

Atrybuty

Jak prowizja za polecenie faktycznie trafia do partnera — stawka procentowa, sposób wypłaty oraz warunki wstępne.

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
}

Warunki wypłaty

• Łączna kwota należnych wynagrodzeń reklamodawcy osiąga minimalną kwotę wypłaty.
• Na ich koncie skonfigurowano portfel służący do wypłat kryptowalut.
• Ich status KYC został zweryfikowany.

Przykład: odczytanie skumulowanych zysków

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
}

Poziomy cenowe (aktualne)

Odczytuj dane na żywo z tego punktu końcowego — nigdy nie wpisuj tych wartości na stałe, ponieważ mogą one ulec zmianie z naszej strony. Zamiast pola z kwotą bezpłatną, stwórz dla swoich użytkowników selektor pakietów: każda wyświetlana cena jest już dokładną kwotą do wysłania podczas tworzenia płatności, a wyświetlane tutaj odblokowane korzyści dokładnie informują użytkowników, co otrzymują za tę cenę, dzięki czemu wybierają cenę, którą rozumieją, zamiast zgadywać kwotę.

Liczba żądań jest ograniczona na klucz na minutę. Każda uwierzytelniona odpowiedź zawiera nagłówki X-RateLimit-Limit, X-RateLimit-Remaining oraz X-RateLimit-Reset; przekroczenie limitu powoduje zwrot kodu 429 Too Many Requests wraz z nagłówkiem Retry-After.

Opcjonalne, dla każdego partnera. Dopóki nie dodasz wpisu, klucze tego partnera akceptują żądania z dowolnego adresu IP — pierwszy wpis powoduje, że wszystkie klucze tego partnera będą akceptować żądania wyłącznie z listy dozwolonych adresów.

Każdy webhook jest podpisywany algorytmem HMAC-SHA256 przy użyciu klucza tajnego generowanego jednorazowo w momencie utworzenia — przed uznaniem treści za wiarygodną należy zweryfikować podpis. Zdarzenia są przekazywane wyłącznie do partnera, który jest właścicielem danego reklamodawcy.