개발자 문서

모든 요청은 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 모드 광고주 중 한 곳이 귀사의 연동 기능을 통해 광고 비용을 결제합니다.
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
}

모든 광고주 계정에는 연간 정액 요금 외에 AI 크레딧으로 결제되는 일련의 내장형 AI 도구(광고 콘텐츠 및 시각 자료 생성기, 대화형 어시스턴트, 예산 자문 도구, 외부 SEO 감사 도구)가 제공됩니다.

예시 — 광고 콘텐츠 생성

아래의 이미지 생성기 역시 동일한 카테고리와 사업 설명을 기반으로 작동합니다.

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 모드를 통해 생성한 광고주(귀하의 수익 분배 대상이 되는 광고주)의 광고만 표시하려면, 파트너 ID(자신의 대시보드 내 ‘개발자’ 페이지에서 확인 가능)를 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 헤더가 포함되며, 제한을 초과할 경우 Retry-After 헤더가 포함된 429 Too Many Requests 오류가 반환됩니다.

선택 사항이며, 파트너별로 적용됩니다. 항목을 추가하기 전까지는 해당 파트너의 모든 키가 모든 IP의 요청을 수락하지만, 첫 번째 항목을 추가하면 해당 파트너의 모든 키가 허용 목록으로만 제한됩니다.

모든 웹훅은 생성 시점에 한 번 발급된 비밀 키를 사용하여 HMAC-SHA256 방식으로 서명됩니다. 페이로드를 신뢰하기 전에 서명을 확인하십시오. 이벤트는 관련 광고주를 소유한 파트너에게만 전달됩니다.