Documentação para programadores

Cada pedido é autenticado com uma chave secreta no cabeçalho «Authorization», utilizando o esquema «Bearer».

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

Se as suas chaves API criarem contas de anunciante para os seus próprios utilizadores (modo Connect — consulte a secção «Autenticação» acima), receberá uma parte do que esses anunciantes pagam pelos seus anúncios. A repartição abaixo é lida em tempo real a partir deste mesmo ponto de extremidade, nunca é codificada de forma estática e é totalmente distinta da comissão por indicação que se encontra mais abaixo nesta página.

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

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

Como funciona

1. Um dos seus anunciantes no modo «Connect» paga por um anúncio através da sua integração.
2. O anúncio é analisado e aprovado — automaticamente ou pela nossa equipa de moderação.
3. A sua participação está na fila para pagamento automático na sua carteira, seguindo o mesmo mecanismo do programa de referência abaixo.

Condições de pagamento

• Está configurada uma carteira de pagamentos em criptomoedas na sua conta de parceiro.
• Não é necessário que faça a verificação de identidade (KYC) — a sua conta de parceiro já foi verificada no momento da criação.

Exemplo: leitura das ações acumuladas

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
}

Cada conta de anunciante dispõe de um conjunto de ferramentas de IA integradas — um gerador de conteúdo e elementos visuais para anúncios, um assistente conversacional, um consultor de orçamento e um auditor externo de SEO — pagas com créditos de IA, para além do preço fixo anual.

Exemplo — gerar conteúdo publicitário

A mesma categoria e descrição da empresa também servem de base para o gerador de imagens abaixo.

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
}

Criar um elemento visual correspondente para o mesmo anúncio:

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
}

Insira um bloco de anúncios já pronto no seu próprio site — sem necessidade de criação, sem iframe. O script é renderizado diretamente na página, dentro de um Shadow DOM isolado, pelo que os seus estilos nunca interferem no seu site e os estilos do seu site nunca interferem nele.

Adiciona-o à tua página

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

Por predefinição, isto apresenta a classificação pública completa da categoria — todos os anunciantes da plataforma, e não apenas aqueles que angariou. Para mostrar apenas os anúncios dos anunciantes que criou através do modo Connect (aqueles que geram a sua comissão), adicione «data-partner» com o seu ID de parceiro (encontra-o na página «Desenvolvedores» do seu próprio painel de controlo):

<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 os seus anunciantes abrangerem várias categorias, elimine completamente o atributo «data-category» — ao utilizar apenas o atributo «data-partner», o widget mostra todos os seus anúncios de todas as categorias numa única grelha, em vez de ser necessário um bloco de widget por categoria:

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

Queres uma unidade do tipo rodapé a acompanhar a que está no corpo do conteúdo, cada uma a mostrar anúncios diferentes? Adiciona um segundo bloco de widget com data-layout="compact" (um único anúncio, que pode ser recolhido num pequeno «pill») e data-offset definido para o número de anúncios que o teu primeiro widget já mostra:

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

Atributos

Como é que a comissão por indicação de um parceiro chega efetivamente até ele — a percentagem, o mecanismo de pagamento e as condições prévias.

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
}

Condições de pagamento

• Os ganhos totais a pagar ao anunciante atingem o montante mínimo de pagamento.
• Foi configurada uma carteira de pagamentos em criptomoedas na conta deles.
• O seu estatuto KYC foi verificado.

Exemplo: leitura dos resultados acumulados

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
}

Níveis de preços (em vigor)

Leia os dados em tempo real a partir deste ponto de acesso — nunca codifique estes valores de forma estática, pois podem sofrer alterações da nossa parte. Crie um seletor de planos para os seus próprios utilizadores, em vez de um campo de valor livre: cada preço apresentado já corresponde ao montante exato a enviar ao efetuar o pagamento, e os benefícios desbloqueados aqui apresentados indicam aos utilizadores exatamente o que esse preço lhes proporciona, para que escolham um preço que compreendam, em vez de adivinharem um valor.

O número de pedidos está limitado por chave, por minuto. Cada resposta autenticada inclui os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; se o limite for ultrapassado, é devolvido o código de erro 429 Too Many Requests com o cabeçalho Retry-After.

Opcional, por parceiro. Até adicionar uma entrada, as suas chaves aceitam pedidos de qualquer endereço IP — a primeira entrada altera todas as chaves desse parceiro para que só aceitem endereços da lista de permissões.

Cada webhook é assinado com HMAC-SHA256 utilizando um segredo emitido uma única vez, no momento da criação — verifique a assinatura antes de confiar na carga útil. Os eventos são enviados apenas ao parceiro a quem pertence o anunciante em questão.