Hunter Ad Library cho nhà phát triển

REST API, MCP server cho công cụ AI, OAuth và webhook. Dữ liệu: quảng cáo Facebook đang chạy của các thương hiệu lớn tại Việt Nam, chấm điểm và giải mã bằng AI, cập nhật mỗi tuần.

Bắt đầu trong 2 phút

1. Tạo tài khoản và xác minh email (tặng 30 credit dùng thử).
2. Vào API & MCP trong ứng dụng, bấm Tạo khoá mới. Khoá dạng adl_… chỉ hiện một lần.
3. Gửi khoá qua header Authorization: Bearer adl_…. Mỗi lượt gọi trừ credit trong ví, như khi dùng trên web.

curl -H "Authorization: Bearer adl_KHOA_CUA_BAN" "https://adlib.hunteragency.vn/v1/ads?q=kem%20chong%20nang&preset=long&limit=10"

MCP cho công cụ AI

Địa chỉ https://adlib.hunteragency.vn/mcp, chuẩn Streamable HTTP (không giữ phiên). Hỗ trợ OAuth: công cụ AI tự mở trang đăng nhập Hunter Ad Library, bạn bấm Cho phép là xong, không cần dán khoá.

claude.ai, Claude Desktop

Vào Cài đặt › Connectors › Add custom connector, dán URL https://adlib.hunteragency.vn/mcp, đăng nhập và cho phép khi được hỏi. Kết nối hiện trong danh sách khoá ở mục API & MCP, thu hồi được bất cứ lúc nào.

ChatGPT

1. Trên chatgpt.com mở Plugin ở thanh bên, bấm Thêm › Thêm server MCP tùy chỉnh. Cần ChatGPT Plus trở lên. Bản cũ không có nút này: vào Cài đặt › Ứng dụng › Nâng cao, bật Chế độ nhà phát triển rồi bấm Tạo.
2. Điền tên Hunter Ad Library, URL server là https://adlib.hunteragency.vn/mcp, xác thực OAuth, đánh dấu Tôi hiểu và muốn tiếp tục rồi bấm Tạo, sau đó Kết nối Hunter Ad Library.
3. Đăng nhập Hunter Ad Library và bấm Cho phép.
4. Trong khung chat gõ @Hunter Ad Library (hoặc bấm +) rồi hỏi. Deep Research cũng dùng được (qua công cụ search và fetch).

Tên mục có thể khác chút tuỳ bản ChatGPT. Gói Business, Enterprise cần quản trị viên cho phép ứng dụng tuỳ chỉnh.

Claude Code

claude mcp add --transport http adlib https://adlib.hunteragency.vn/mcp --header "Authorization: Bearer adl_KHOA_CUA_BAN"

Cursor, Windsurf, VS Code

{
  "mcpServers": {
    "adlib": {
      "url": "https://adlib.hunteragency.vn/mcp",
      "headers": {
        "Authorization": "Bearer adl_KHOA_CUA_BAN"
      }
    }
  }
}

OpenAI API (Responses), Agents SDK

Gắn kho vào ứng dụng, chatbot của bạn chạy bằng model OpenAI: khai báo công cụ loại mcp, gửi khoá adlib trong headers.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-5",
  "tools": [
    {
      "type": "mcp",
      "server_label": "adlib",
      "server_url": "https://adlib.hunteragency.vn/mcp",
      "headers": {
        "Authorization": "Bearer adl_KHOA_CUA_BAN"
      },
      "require_approval": "never"
    }
  ],
  "input": "Ngành mỹ phẩm đang thắng với công thức quảng cáo nào?"
}'

Công cụ không đặt được header và không hỗ trợ OAuth: dùng https://adlib.hunteragency.vn/mcp/adl_KHOA_CUA_BAN (ai có link đều dùng được credit của bạn, chỉ dán vào công cụ của chính bạn). n8n, Make, Zapier: gọi thẳng REST bên dưới.

REST API

Kết quả dạng { "ok": true, "data": …, "credits_charged": 1, "balance": 49 }. Mô tả máy đọc được: https://adlib.hunteragency.vn/v1. Ảnh và video trả về bằng link có chữ ký, mở được không cần đăng nhập.

Công cụ và giá mỗi lượt

1 credit = 1.000đ. Giá như nhau ở REST và MCP. Lỗi phía hệ thống thì credit tự hoàn. Tài khoản miễn phí nhận dữ liệu như trên web (ẩn điểm và nhãn AI chi tiết, không dùng công cụ AI).

Mỗi lần tìm trả tối đa 50 quảng cáo, mỗi bộ lọc xem tối đa 20 trang. API chỉ đọc dữ liệu đã có trong kho.

Gói API

Hạn mức theo gói của tài khoản. Gói API Pro, API Business có khi nạp gói credit tương ứng, kéo dài theo số ngày của gói. Xem bảng giá.

Webhook quảng cáo mới

Tạo webhook ở mục API & MCP. Mỗi giờ, quảng cáo mới của các brand bạn đang theo dõi được gửi POST tới URL https của bạn (tối đa 100 quảng cáo mỗi lần, phần còn lại gửi lượt sau). Không tốn credit. Trả mã 2xx trong 10 giây là thành công; lỗi thì gửi lại giờ sau, lỗi 20 lần liên tiếp thì webhook tự tắt.

{
  "event": "ads.new",
  "delivery_id": "8f0c…",
  "sent_at": "2026-11-01T08:20:00.000Z",
  "data": {
    "count": 1,
    "brands": [
      {
        "brand_id": 186,
        "brand": "Cỏ Mềm",
        "ads": [
          {
            "ad_id": "1327124515525837",
            "start_date": "2026-10-31",
            "media_type": "video",
            "title": "…",
            "body": "…",
            "thumb": "https://adlib.hunteragency.vn/v1/m/…",
            "library_url": "https://www.facebook.com/ads/library/?id=1327124515525837"
          }
        ]
      }
    ]
  }
}

Header X-Adlib-Event (ads.new hoặc ping khi bấm Gửi thử) và X-Adlib-Signature: t=<giây>,v1=<HMAC-SHA256> ký trên chuỗi t + "." + body bằng secret whsec_… của webhook.

// Node.js: kiểm tra chữ ký webhook
const crypto = require("crypto");
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 600) return false;      // chống gửi lại
  const mac = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

Mã lỗi

MCP trả lỗi nghiệp vụ trong kết quả công cụ (isError: true) để công cụ AI đọc được và báo lại cho bạn.