Chuyển tới nội dung chính

MCP/API

MCP/API là giao diện lập trình duy nhất tới Qubix. Các client bên ngoài — một trợ lý AI, một script BI, một công cụ tự động hóa — kết nối tới một endpoint duy nhất qua MCP (Model Context Protocol) và gọi các phương thức được liệt kê trên trang này. Mọi lệnh gọi đều chạy nghiêm ngặt trong phạm vi quyền hạn của bạn: quản trị viên truy cập toàn bộ tài khoản, còn buyer chỉ thấy dữ liệu của nhóm mình.

Không có một REST API riêng nào phải học: các phương thức bạn thấy ở đây chính xác là những gì endpoint phục vụ, nên danh mục không bao giờ có thể lệch khỏi giao diện thực tế.

Cùng các phương thức ấy vận hành trợ lý tích hợp sẵn​

Các phương thức này không chỉ dành cho client bên ngoài. Trợ lý AI Qubix tích hợp sẵn — bảng điều khiển có mặt trên mọi màn hình của bảng quản trị, không cần thiết lập — gọi đúng cùng danh mục đó. Vì vậy dù bạn hỏi trợ lý tích hợp sẵn hay kết nối agent AI của riêng mình qua MCP, cả hai đều đọc dữ liệu của bạn và thực hiện hành động qua cùng các phương thức, luôn trong phạm vi quyền hạn của bạn.

Tìm ở đâu​

Trong bảng quản trị, mở menu tài khoản (góc trên bên phải, cạnh tên bạn) và chọn MCP/API.

Endpoint​

Mọi thứ đều đi tới một địa chỉ:

POST https://<your-domain>/api/mcp

Phương thức truyền tải là Streamable HTTP (JSON-RPC 2.0) — một endpoint duy nhất mà các MCP client có sẵn hiểu một cách tự nhiên, và bạn cũng có thể gọi trực tiếp từ bất kỳ ngôn ngữ nào (xem Ví dụ mã bên dưới).

Token API của bạn​

Truy cập theo lập trình dùng một token cá nhân (PAT) — được tạo và quản lý ngay trên trang này, trong khối API Token.

  1. Nhấn Tạo API token (hoặc Tạo lại nếu bạn đã có sẵn).
  2. Sao chép token ngay lập tức — nó chỉ được hiển thị một lần duy nhất.

Token trông như qbx_…. Qubix chỉ lưu hash của nó và không bao giờ hiển thị lại được.

  • Mỗi người dùng một token. Nó kế thừa vai trò và quyền hạn của bạn, nên qua API bạn thấy chính xác cùng dữ liệu và hành động như trong giao diện.
  • Tạo lại cấp một token mới và token cũ ngừng hoạt động ngay lập tức.
  • Thu hồi xóa token và cắt đứt mọi truy cập đã dùng nó.
Hãy đối xử với token như một mật khẩu

Một token cá nhân tương đương với việc đăng nhập dưới danh nghĩa bạn. Đừng công bố hay chia sẻ nó. Nếu nó bị rò rỉ, hãy nhấn Tạo lại tại đây — token cũ chết ngay tức khắc.

Kết nối một client​

Hầu hết các MCP client cần một cấu hình nhỏ: endpoint cộng với header Authorization. Trong khi token được hiển thị ngay sau khi tạo, trang này đã điền sẵn giá trị thật vào ví dụ bên dưới — hãy sao chép nguyên trạng.

JSON
{
  "mcpServers": {
    "qubix": {
      "url": "https://<your-domain>/api/mcp",
      "headers": { "Authorization": "Bearer qbx_YOUR_TOKEN" }
    }
  }
}

Để xem cách thiết lập từng bước cho một trợ lý cụ thể (Claude Code, Claude Desktop, Cursor), xem Kết nối AI bên ngoài.

Ví dụ mã​

Để gọi endpoint từ mã của riêng bạn, hãy gửi một yêu cầu JSON-RPC kèm các header xác thực và Streamable-HTTP. Trang cung cấp sẵn các đoạn mã cho cURL, JavaScript và Python — chỉ cần chuyển tab và sao chép. Ví dụ, liệt kê các phương thức có sẵn:

Bash
curl -X POST 'https://<your-domain>/api/mcp' \
  -H 'Authorization: Bearer qbx_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Python
import requests

res = requests.post(
    "https://<your-domain>/api/mcp",
    headers={
        "Authorization": "Bearer qbx_YOUR_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
    },
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"},
)
print(res.text)
Dành cho tích hợp tùy chỉnh

Các lệnh gọi thô này minh họa giao thức từ bất kỳ ngôn ngữ nào. Các client có sẵn (Claude, Cursor) không cần đến chúng — chúng dùng cấu hình ở trên.

API phơi bày những gì​

Trang liệt kê toàn bộ danh mục phương thức — khoảng một trăm phương thức ở thời điểm hiện tại — và mỗi phương thức được gắn nhãn đọc hoặc ghi. Chúng bao gồm, trong phạm vi quyền hạn của bạn:

  • Phân tích — bảng điều khiển, geo, offer, network, nguồn traffic, các màn hình Facebook và phễu khách truy cập, cùng với phần phân tích chi tiết cho một quảng cáo, chiến dịch, offer, creative, PWA, geo hoặc nguồn traffic cụ thể.
  • Creative — tìm kiếm ngữ nghĩa và các chủ đề creative hiệu quả nhất.
  • Britva — xem các quy tắc tự động hóa, các quảng cáo bị tạm dừng và lịch sử kích hoạt; tạo, chỉnh sửa và phát hành quy tắc.
  • Hành động — tạm dừng và tiếp tục quảng cáo cũng như chiến dịch; quản lý offer, network, nguồn traffic, chiến dịch tracker, pixel, website, domain, PWA và chiến dịch push.
  • Truy vấn tự do — một phương thức truy vấn chỉ-đọc cho những câu hỏi mà các phương thức có sẵn không bao quát.

Mỗi phương thức hiển thị các tham số của nó và liệu nó có thay đổi dữ liệu hay không. Dùng ô tìm kiếm để tìm một phương thức theo tên hoặc mô tả.

Các phương thức ghi là thật

Tạm dừng một quảng cáo, xóa một quy tắc hoặc một offer qua API sẽ thay đổi các chiến dịch đang chạy của bạn. Trong các client trò chuyện, những hành động như vậy chỉ chạy sau khi bạn xác nhận — hãy xem xét những gì được đề xuất trước khi phê duyệt.

Tiếp theo là gì​

Kết nối AI bên ngoài

thiết lập Claude, Cursor hoặc một MCP client khác theo từng bước.

Kết nối

các khóa cho những dịch vụ bên ngoài mà Qubix tích hợp.

Mẫu

những dữ liệu và hành động mà vai trò của bạn — và do đó token của bạn — có thể truy cập.

On this page