Documentazione per sviluppatori

Ogni richiesta viene autenticata tramite una chiave segreta nell'intestazione Authorization, utilizzando lo schema Bearer.

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

Se le tue chiavi API creano account pubblicitari per i tuoi utenti (modalità Connect — vedi la sezione “Autenticazione” sopra), guadagni una percentuale su quanto pagano tali inserzionisti per i propri annunci. La ripartizione riportata di seguito viene letta in tempo reale da questo stesso endpoint, non è mai hardcoded ed è completamente separata dalla commissione di referral indicata più in basso in questa pagina.

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

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

Come funziona

1. Uno dei tuoi inserzionisti in modalità Connect paga un annuncio tramite la tua integrazione.
2. L'annuncio viene esaminato e approvato, automaticamente o dal nostro team di moderazione.
3. La tua quota è in coda per il pagamento automatico sul tuo portafoglio, con lo stesso meccanismo del programma di referral descritto di seguito.

Condizioni di pagamento

• Sul tuo account partner è stato configurato un portafoglio per i pagamenti in criptovaluta.
• Non è richiesta alcuna procedura KYC da parte tua: il tuo account partner è già stato verificato al momento della creazione.

Esempio: lettura delle quote accumulate

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
}

Ogni account pubblicitario dispone di una serie di strumenti basati sull’intelligenza artificiale integrati — un generatore di contenuti e immagini pubblicitarie, un assistente conversazionale, un consulente per la gestione del budget e uno strumento di verifica SEO esterno — pagabili con crediti AI, oltre al canone annuale forfettario.

Esempio — generare contenuti pubblicitari

La stessa categoria e la stessa descrizione dell'attività sono alla base anche del generatore di immagini riportato di seguito.

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
}

Genera un'immagine corrispondente per lo stesso annuncio:

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
}

Inserisci un blocco pubblicitario già pronto sul tuo sito: nessuna fase di creazione, nessun iframe. Lo script viene visualizzato direttamente nella pagina all’interno di uno Shadow DOM isolato, quindi i suoi stili non interferiscono mai con il tuo sito e viceversa.

Aggiungilo alla tua pagina

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

Per impostazione predefinita, viene visualizzata la classifica pubblica completa della categoria, ovvero tutti gli inserzionisti presenti sulla piattaforma, non solo quelli che hai acquisito tu. Per visualizzare solo gli annunci degli inserzionisti che hai creato tramite la modalità Connect (quelli che generano la tua quota), aggiungi "data-partner" con il tuo ID partner (lo trovi nella pagina "Sviluppatori" della tua dashboard):

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

Se i tuoi inserzionisti appartengono a diverse categorie, elimina del tutto "data-category": utilizzando solo "data-partner", il widget mostrerà tutti i tuoi annunci di tutte le categorie in un'unica griglia, invece di richiedere un blocco widget per ogni categoria:

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

Vuoi un'unità in stile piè di pagina accanto a quella inserita nel contenuto, in modo che ciascuna mostri annunci diversi? Aggiungi un secondo blocco widget con data-layout="compact" (un singolo annuncio, comprimibile in una piccola pillola) e data-offset impostato sul numero di annunci già visualizzati dal tuo primo widget:

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

Attributi

Come viene effettivamente corrisposta al partner la commissione di segnalazione: la percentuale, le modalità di pagamento e i requisiti necessari.

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
}

Condizioni di pagamento

• I guadagni totali dovuti all'inserzionista raggiungono l'importo minimo di pagamento.
• Sul loro conto è stato configurato un portafoglio per il prelievo di criptovalute.
• Il loro stato KYC è stato verificato.

Esempio: lettura degli utili accumulati

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
}

Livelli di prezzo (attivi)

Leggi i dati in tempo reale da questo endpoint — non inserire mai questi valori in modo statico, poiché potrebbero cambiare da parte nostra. Crea un selettore di livelli per i tuoi utenti invece di un campo con importo libero: ogni prezzo visualizzato corrisponde già all’importo esatto da inviare al momento della creazione del pagamento, e i vantaggi sbloccati qui indicati spiegano agli utenti esattamente cosa ottengono con quel prezzo, in modo che scelgano un prezzo che comprendono invece di indovinare una cifra.

Il numero di richieste è limitato per chiave e al minuto. Ogni risposta autenticata include le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; il superamento del limite comporta la restituzione del codice di errore 429 Too Many Requests con l'intestazione Retry-After.

Opzionale, per partner. Finché non si aggiunge una voce, le chiavi accettano richieste da qualsiasi indirizzo IP; la prima voce imposta tutte le chiavi di quel partner in modo che accettino solo gli indirizzi presenti nella lista bianca.

Ogni webhook è firmato con HMAC-SHA256 utilizzando una chiave segreta generata una sola volta al momento della creazione: verificare la firma prima di considerare attendibile il payload. Gli eventi vengono inviati esclusivamente al partner a cui appartiene l'inserzionista in questione.