Tài liệu dành cho nhà phát triển

Mỗi yêu cầu đều được xác thực bằng một khóa bí mật trong tiêu đề Authorization, thông qua cơ chế Bearer.

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

Nếu các khóa API của bạn được dùng để tạo tài khoản nhà quảng cáo cho người dùng của chính bạn (chế độ Connect — xem phần Xác thực ở trên), bạn sẽ nhận được một phần hoa hồng từ số tiền mà các nhà quảng cáo đó chi trả cho quảng cáo của họ. Tỷ lệ phân chia dưới đây được lấy trực tiếp từ chính điểm cuối này, không bao giờ được cài đặt cố định, và hoàn toàn tách biệt với hoa hồng giới thiệu được đề cập ở phần sau của trang này.

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

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

Cách thức hoạt động

1. Một trong những nhà quảng cáo ở chế độ Connect của bạn thanh toán tiền quảng cáo thông qua hệ thống tích hợp của bạn.
2. Quảng cáo sẽ được xem xét và phê duyệt — tự động hoặc bởi đội ngũ kiểm duyệt của chúng tôi.
3. Phần thưởng của bạn đã được đưa vào danh sách chờ để được thanh toán tự động vào ví của bạn, theo cơ chế tương tự như chương trình giới thiệu dưới đây.

Điều kiện thanh toán

• Một ví nhận tiền điện tử đã được thiết lập trên tài khoản đối tác của bạn.
• Bạn không cần phải thực hiện xác minh danh tính (KYC) — tài khoản đối tác của bạn đã được kiểm tra kỹ lưỡng ngay từ khi được tạo.

Ví dụ: đọc số cổ phần tích lũy

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
}

Mỗi tài khoản nhà quảng cáo đều được cung cấp một bộ công cụ AI tích hợp sẵn — bao gồm công cụ tạo nội dung và hình ảnh quảng cáo, trợ lý trò chuyện, công cụ tư vấn ngân sách và công cụ kiểm tra SEO bên ngoài — được thanh toán bằng tín dụng AI, bên cạnh mức giá cố định hàng năm.

Ví dụ — tạo nội dung quảng cáo

Danh mục và mô tả hoạt động kinh doanh này cũng được sử dụng làm cơ sở cho công cụ tạo hình ảnh bên dưới.

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
}

Tạo hình ảnh phù hợp cho quảng cáo đó:

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
}

Chỉ cần kéo và thả một đơn vị quảng cáo đã được tạo sẵn vào trang web của bạn — không cần bước xây dựng, không cần iframe. Tập lệnh này được hiển thị trực tiếp trên trang trong một Shadow DOM cách ly, do đó các kiểu định dạng của nó sẽ không bao giờ ảnh hưởng đến trang web của bạn, và ngược lại, các kiểu định dạng của trang web bạn cũng sẽ không bao giờ ảnh hưởng đến nó.

Thêm vào trang của bạn

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

Theo mặc định, phần này hiển thị bảng xếp hạng công khai đầy đủ cho danh mục đó — bao gồm tất cả các nhà quảng cáo trên nền tảng, không chỉ những nhà quảng cáo do bạn giới thiệu. Để chỉ hiển thị các quảng cáo từ những nhà quảng cáo mà bạn đã tạo thông qua Chế độ Connect (những nhà quảng cáo mang lại phần chia sẻ cho bạn), hãy thêm thuộc tính `data-partner` kèm theo ID đối tác của bạn (bạn có thể tìm thấy ID này trên trang Nhà phát triển trong bảng điều khiển của chính bạn):

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

Nếu các nhà quảng cáo của bạn thuộc nhiều danh mục khác nhau, hãy loại bỏ hoàn toàn thuộc tính `data-category` — chỉ cần giữ lại thuộc tính `data-partner`, tiện ích sẽ hiển thị tất cả các quảng cáo của bạn thuộc mọi danh mục trong một lưới duy nhất, thay vì phải tạo một khối tiện ích riêng cho từng danh mục:

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

Bạn muốn có một đơn vị quảng cáo kiểu chân trang bên cạnh đơn vị quảng cáo trong nội dung, mỗi đơn vị hiển thị các quảng cáo khác nhau? Hãy thêm một khối widget thứ hai với thuộc tính `data-layout="compact"` (một quảng cáo duy nhất, có thể thu gọn thành ô nhỏ) và thuộc tính `data-offset` được đặt bằng số lượng quảng cáo mà widget đầu tiên của bạn đang hiển thị:

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

Thuộc tính

Cách thức hoa hồng giới thiệu thực sự được chuyển đến đối tác — tỷ lệ phần trăm, cơ chế thanh toán và các điều kiện tiên quyết.

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
}

Điều kiện thanh toán

• Tổng số tiền thu nhập phải thanh toán cho nhà quảng cáo đã đạt đến mức thanh toán tối thiểu.
• Một ví nhận tiền điện tử đã được thiết lập trên tài khoản của họ.
• Tình trạng xác minh danh tính (KYC) của họ đã được xác nhận.

Ví dụ: xem lợi nhuận lũy kế

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
}

Các mức giá (đang áp dụng)

Đọc dữ liệu trực tiếp từ điểm cuối này — tuyệt đối không được ghi cứng các giá trị này, vì chúng có thể thay đổi từ phía chúng tôi. Hãy tạo một công cụ chọn gói dịch vụ cho người dùng của bạn thay vì một trường nhập số tiền miễn phí: mỗi mức giá hiển thị đã là số tiền chính xác cần chuyển khi tạo giao dịch thanh toán, và các lợi ích được mở khóa hiển thị tại đây cho người dùng biết chính xác họ sẽ nhận được gì với mức giá đó, nhờ đó họ có thể chọn mức giá mà họ hiểu rõ thay vì phải đoán mò.

Số lượng yêu cầu được giới hạn theo từng khóa và theo từng phút. Mỗi phản hồi đã được xác thực đều chứa các tiêu đề X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset; nếu vượt quá giới hạn, hệ thống sẽ trả về mã trạng thái 429 Too Many Requests kèm theo tiêu đề Retry-After.

Tùy chọn, cho từng đối tác. Cho đến khi bạn thêm một mục, các khóa của bạn sẽ chấp nhận yêu cầu từ bất kỳ địa chỉ IP nào — mục đầu tiên sẽ chuyển tất cả các khóa của đối tác đó sang chế độ chỉ cho phép các địa chỉ trong danh sách cho phép.

Mỗi webhook đều được ký bằng HMAC-SHA256 bằng cách sử dụng một khóa bí mật được cấp một lần duy nhất tại thời điểm tạo — hãy xác minh chữ ký trước khi tin tưởng vào nội dung tin nhắn. Các sự kiện chỉ được gửi đến đối tác sở hữu nhà quảng cáo liên quan.