Tài liệu tham khảo API

Base URL

Mọi yêu cầu API đều gửi đến địa chỉ gốc này:

https://www.7275.com/api/v1

Bắt buộc dùng HTTPS. Yêu cầu HTTP sẽ bị từ chối (không chuyển hướng).

Xác thực

Mọi yêu cầu cần Bearer token trong header Authorization. Tạo token tại bảng điều khiển → Cài đặt → API Keys. Key có hai loại live và test, mỗi loại chỉ truy cập được môi trường của riêng nó.

curl https://www.7275.com/api/v1/accounts \
  -H "Authorization: Bearer dxk_live_...your-key..."

• Định dạng key live: bắt đầu bằng dxk_live_, 64 ký tự
• Định dạng key test: bắt đầu bằng dxk_test_, chỉ dùng cho tài khoản sandbox
• Không bao giờ dùng key trong mã front-end — hãy đi qua backend của bạn làm proxy
• Nếu key bị lộ, hãy thu hồi và tạo lại ngay trên bảng điều khiển

Dùng trực tiếp từ Claude Desktop / Cursor (máy chủ MCP)

Chúng tôi cung cấp máy chủ Model Context Protocol không phụ thuộc thư viện nào, để các ứng dụng MCP như Claude Desktop và Cursor đọc trực tiếp trạng thái AdWhiz của bạn. Không cần viết code — sao chép khối cấu hình, dán API key và khởi động lại ứng dụng.

• Năm công cụ chỉ đọc: liệt kê tài khoản quảng cáo, xem đề xuất của AI, xem khoản tiết kiệm tháng này, xem hoạt động gần đây, kiểm tra hạn mức API
• Các công cụ ghi (apply / pause) cố ý chưa được mở — chờ bộ tối ưu thoát shadow mode và có đủ bằng chứng hiệu chỉnh để kiểm soát chúng
• Một script Node 18+ duy nhất. Không cần npm install. Chạy tốt trên máy offline / cách ly mạng (airgapped)
• API key không bao giờ rời khỏi máy của bạn. Mọi yêu cầu đi thẳng qua HTTPS đến www.7275.com

Thêm đoạn này vào claude_desktop_config.json của Claude Desktop (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "adwhiz": {
      "command": "node",
      "args": ["/path/to/mcp-server/src/index.mjs"],
      "env": {
        "ADWHIZ_API_KEY": "dxk_live_..."
      }
    }
  }
}

Hướng dẫn cài đặt đầy đủ, cấu hình Cursor và khắc phục sự cố trên GitHub: github.com/dexun-inc/adwhiz/mcp-server.

Endpoint

API v1 cung cấp 13 endpoint cốt lõi, bao gồm định danh, đọc tài khoản, tạo đề xuất (áp dụng chưa khả dụng), nhật ký kiểm tra, quản lý API key, tra cứu hạn mức và nguồn changelog.

Ví dụ yêu cầu

Tạo đề xuất tối ưu mới cho cả ba nền tảng:

curl -X POST https://www.7275.com/api/v1/recommendations/generate \
  -H "Authorization: Bearer dxk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "ga-548-203-7184",
    "platforms": ["google_ads", "meta_ads", "tiktok_ads"],
    "window": "7d"
  }'

Ví dụ phản hồi:

{
  "summary": "Pausing 3 high-CPA keywords and reallocating budget...",
  "recommendations": [
    {
      "id": "rec_001",
      "type": "pause_keyword",
      "target": { "accountId": "ga-548-203-7184", "keywordText": "wool socks" },
      "title": "Pause broad-match 'wool socks'",
      "reason": "7-day CPA $45.82 vs target $8",
      "expectedImpact": "Save ~$412/week",
      "confidence": "high"
    }
  ]
}

Truy vấn tăng dần /changelog

/api/v1/changelog là endpoint công khai (không cần API key) với bốn cách tiết kiệm băng thông: ETag + If-None-Match, Last-Modified + If-Modified-Since (curl -z), ?since=YYYY-MM-DD để lọc theo ngày và ?limit=N để giới hạn kích thước. SDK và script cron có thể kết hợp chúng để truy vấn thường xuyên mà không tải lại cùng một JSON.

# 1. First call — store the ETag (or Last-Modified) you get back.
curl -i 'https://www.7275.com/api/v1/changelog?limit=10'

# 2. Subsequent calls — pass the stored ETag.
#    Server returns 304 with empty body if nothing has shipped.
curl -i 'https://www.7275.com/api/v1/changelog?limit=10' \
  -H 'If-None-Match: "abc123..."'

# 3. Or anchor on a date instead of an ETag.
#    Only entries whose `date >= since` come back; pair with ?limit
#    to cap the response size.
curl 'https://www.7275.com/api/v1/changelog?since=2026-01-01&limit=20'

# 4. curl -z for Last-Modified-style conditional GET (no ETag needed):
curl -z 'Mon, 20 May 2026 00:00:00 GMT' \
  'https://www.7275.com/api/v1/changelog'

Giới hạn tần suất

Phân cấp theo gói đăng ký để tránh gây quá tải hạn mức API upstream của Google / Meta / TikTok:

• Professional: 120 yêu cầu/phút
• Business: 600 yêu cầu/phút
• Enterprise: tùy chỉnh (thường là 3.000 yêu cầu/phút)
• Vượt giới hạn sẽ trả về 429 + header retry-after — nên dùng exponential backoff

Mã lỗi

Mọi lỗi đều trả về JSON gồm error.code, error.message và error.request_id: