Tài liệu API cục bộ: quản lý hồ sơ trình duyệt bằng script.

Tổng quan

API cục bộ là tính năng của Prism Pro, phù hợp để quản lý hồ sơ hàng loạt bằng script của riêng bạn: tạo hồ sơ từ dữ liệu nghiệp vụ, khởi chạy lần lượt, kiểm tra trạng thái và đóng khi dùng xong. API chỉ quản lý bản thân hồ sơ, không đọc cookie, mật khẩu, thông tin đăng nhập proxy hay nội dung trang web, và cũng không cung cấp endpoint gỡ lỗi cho Puppeteer / Playwright. Khi cần để AI đọc trang web, nhấp và điền biểu mẫu, hãy dùng MCP.

Bắt đầu nhanh

1. Khởi động API cục bộ

   Trong Prism, mở “API tự động hóa” ở thanh bên trái rồi nhấp “Khởi động API cục bộ”. Tính năng này yêu cầu Prism Pro.

2. Sao chép địa chỉ và mã thông báo

   Cửa sổ sẽ hiển thị “Địa chỉ API” và “Mã thông báo truy cập phiên”. Mã thông báo chỉ hiển thị một lần khi khởi động thành công, vì vậy hãy sao chép ngay; nếu sau này cần mã thông báo mới, hãy dừng rồi khởi động lại API.

3. Gửi yêu cầu đầu tiên

   Đặt hai biến trong terminal, rồi kiểm tra trạng thái dịch vụ và liệt kê hồ sơ. Nếu phản hồi có "state": "running" thì địa chỉ và mã thông báo đã dùng được.

PRISM_API='http://127.0.0.1:43123'   # the API address shown in Prism
PRISM_TOKEN='<token>'                # the token shown in Prism

curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/status"
curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles"

Trong Windows PowerShell, curl là bí danh của một lệnh khác; hãy gõ curl.exe, hoặc dùng Invoke-RestMethod có sẵn trong PowerShell:

$api = 'http://127.0.0.1:43123'
$headers = @{ Authorization = 'Bearer <token>' }
(Invoke-RestMethod -Uri "$api/v1/profiles" -Headers $headers).result | Format-Table serialNumber, name, status

Quy tắc yêu cầu

API chỉ chấp nhận yêu cầu do script hoặc chương trình trên máy tính này gửi. Yêu cầu vi phạm một trong các quy tắc dưới đây sẽ không được thực thi và trả về lỗi tương ứng trong bảng:

Prism xử lý lần lượt từng yêu cầu của API cục bộ và MCP theo thứ tự nhận được. Khởi chạy hồ sơ cần kiểm tra proxy và mở trình duyệt, thường mất vài giây; trong thời gian đó, các yêu cầu sau phải xếp hàng chờ. Hãy đợi yêu cầu trước trả về rồi mới gửi yêu cầu tiếp theo.

Danh sách endpoint

{id} là ID hồ sơ, lấy từ kết quả của GET /v1/profiles. Mọi phản hồi thành công đều có trạng thái HTTP 200; trừ GET /v1/status, kết quả nằm trong trường result. API không có endpoint để sửa hay xóa hồ sơ.

Đối tượng hồ sơ

Các endpoint liệt kê hồ sơ, truy vấn trạng thái, khởi chạy và đóng đều trả về cùng một đối tượng hồ sơ:

{
  "result": {
    "id": "8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70",
    "serialNumber": 12,
    "name": "Shop A",
    "group": "Project A",
    "tags": ["automation"],
    "status": "running",
    "lastOpenedAt": "2026-10-02T08:30:00.000Z"
  }
}

Các endpoint không trả về địa chỉ và thông tin đăng nhập proxy, thông số vân tay, cookie, mật khẩu, dữ liệu trang web hay dữ liệu tiện ích mở rộng.

Truy vấn, khởi chạy và đóng

GET /v1/status

Trả về trạng thái dịch vụ, dùng để xác nhận địa chỉ và mã thông báo hoạt động. Đây là phản hồi duy nhất không nằm trong result:

{
  "state": "running",
  "transport": "loopback",
  "protocolVersion": 1
}

GET /v1/profiles

Trả về mảng các đối tượng hồ sơ, hồ sơ được sửa đổi gần nhất xếp trước. Hồ sơ trong thùng rác không có trong danh sách.

GET /v1/profiles/{id}/status

Trả về trạng thái hiện tại của một hồ sơ. Nếu hồ sơ không tồn tại hoặc đã được chuyển vào thùng rác, API trả về 404 PROFILE_NOT_FOUND.

POST /v1/profiles/{id}/start

• Tương tự như nhấp “Mở” trong ứng dụng: Prism kiểm tra nhân và giấy phép nhân Pro, kiểm tra proxy và sự thay đổi IP đầu ra, rồi mở cửa sổ trình duyệt. Khi thành công, API trả về đối tượng hồ sơ có trạng thái running.
• Nếu hồ sơ đang chạy, API trả về ngay trạng thái hiện tại và không mở thêm lần nữa.
• Prism chỉ xử lý yêu cầu tiếp theo sau khi một yêu cầu khởi chạy đã trả về. Để khởi chạy hàng loạt, chỉ cần gọi lần lượt cho từng hồ sơ; số hồ sơ có thể chạy cùng lúc phụ thuộc vào bộ nhớ và CPU của máy tính.
• Nếu thiếu nhân tương ứng, kiểm tra proxy không đạt, IP đầu ra của proxy đã thay đổi (khi chính sách là block) hoặc còn tiến trình sót lại, việc khởi chạy sẽ thất bại và trả về 502, trong đó error.message nêu rõ nguyên nhân.
• Qua API, những trường hợp mà ứng dụng cần bạn xác nhận mới tiếp tục được sẽ thất bại ngay, ví dụ khi dữ liệu vị trí địa lý của đầu ra proxy mâu thuẫn giữa các nguồn. Khi gặp những lỗi này, bạn có thể mở hồ sơ đó trong ứng dụng Prism, hoặc chuyển danh tính mạng của hồ sơ sang manual.
• Các hồ sơ mà bạn đã gọi endpoint khởi chạy (kể cả hồ sơ đang chạy sẵn lúc gọi) được ghi nhận lại và sẽ cùng bị đóng khi bạn nhấp “Dừng khẩn cấp” trong cửa sổ “API tự động hóa”. “Dừng API” cũng như các nút dừng và dừng khẩn cấp trong cửa sổ MCP chỉ dừng API; các hồ sơ này vẫn mở.

POST /v1/profiles/{id}/close

Đóng cửa sổ trình duyệt, giữ nguyên dữ liệu hồ sơ và trả về đối tượng hồ sơ có trạng thái closed; nếu hồ sơ không chạy, API cũng trả về closed ngay. Nếu trình duyệt chưa thoát sau 8 giây và vẫn chiếm thư mục dữ liệu, trạng thái trả về là orphaned; gọi endpoint đóng thêm một lần nữa sẽ kết thúc tiến trình sót lại.

PROFILE_ID='8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70'   # an id from GET /v1/profiles
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/start"
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/close"

Tạo hồ sơ

Các endpoint tạo hồ sơ lưu hồ sơ mới ở trạng thái đã đóng và không mở trình duyệt. Mọi trường đều có thể bỏ qua: trường bị bỏ qua sẽ dùng cùng giá trị mặc định như “Hồ sơ mới” trong ứng dụng, và mỗi hồ sơ đều được tạo seed vân tay mới. Yêu cầu có trường không xác định sẽ bị từ chối.

Tạo một hồ sơ

curl -X POST "$PRISM_API/v1/profiles" \
  -H "Authorization: Bearer $PRISM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-b-001" \
  -d '{
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "startUrls": ["https://example.com/"],
    "proxy": { "protocol": "socks5", "host": "203.0.113.10", "port": 1080, "username": "user", "password": "pass" }
  }'

Khi thành công, API trả về hồ sơ mới:

{
  "result": {
    "id": "3b1f7a52-9c4e-4d2b-8f60-1a2b3c4d5e6f",
    "serialNumber": 13,
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "status": "closed"
  }
}

Tạo hàng loạt

Thân yêu cầu của POST /v1/profiles/batch là mảng profiles, mỗi yêu cầu 1–50 hồ sơ; mỗi phần tử viết giống như khi tạo một hồ sơ, chỉ khác là requestKey phải đặt ở cấp gốc của thân yêu cầu hoặc trong header. Prism kiểm tra toàn bộ cấu hình trước; chỉ cần một hồ sơ có lỗi là không hồ sơ nào được tạo, và thông báo lỗi sẽ chỉ rõ hồ sơ nào, trường nào bị sai (profiles[1] là hồ sơ thứ hai, vì chỉ số bắt đầu từ 0). Kết quả được trả về theo thứ tự đầu vào:

{
  "requestKey": "shops-batch-001",
  "profiles": [
    { "name": "Shop C", "group": "Project A" },
    { "name": "Shop D", "group": "Project A", "fingerprint": { "platform": "windows" } }
  ]
}

{
  "result": {
    "profiles": [
      { "id": "…", "serialNumber": 14, "name": "Shop C", "group": "Project A", "tags": [], "status": "closed" },
      { "id": "…", "serialNumber": 15, "name": "Shop D", "group": "Project A", "tags": [], "status": "closed" }
    ],
    "count": 2
  }
}

Các trường của hồ sơ

Các trường proxy

Các trường vân tay

Mẫu phần cứng

Nếu mẫu không khớp với platform, yêu cầu sẽ bị từ chối. Vị trí và kích thước cửa sổ, cookie, dữ liệu tiện ích mở rộng và các thiết lập tương tự không thể đặt qua API; bạn có thể thay đổi chúng trong ứng dụng Prism sau khi tạo.

Thử lại và chống trùng lặp

Khi mạng bị gián đoạn hoặc yêu cầu hết thời gian chờ, bạn có thể không biết hồ sơ đã được tạo hay chưa. Hãy gắn một mã yêu cầu cho mỗi lần tạo, khi đó việc thử lại sẽ không tạo trùng hồ sơ:

• Gửi mã yêu cầu dài 8–128 ký tự trong header Idempotency-Key hoặc trường requestKey của thân yêu cầu; được dùng chữ cái Latinh không dấu, chữ số và . _ : -. Nếu gửi ở cả hai nơi, hai giá trị phải giống nhau.
• Thử lại với cùng mã và cùng nội dung trong vòng 24 giờ sẽ trả về các hồ sơ đã tạo ở lần đầu (HTTP 200), kể cả sau khi Prism khởi động lại.
• Cùng mã nhưng khác nội dung sẽ trả về 409 IDEMPOTENCY_CONFLICT. Nếu hồ sơ tạo ở lần đầu đã bị xóa (kể cả khi chuyển vào thùng rác), API trả về 409 IDEMPOTENCY_RESULT_GONE chứ không âm thầm tạo lại; nếu cần tạo lại, hãy dùng mã khác.
• Sau 24 giờ, cùng một mã sẽ được coi là yêu cầu mới.
• Trong 24 giờ, Prism lưu tối đa 1.000 yêu cầu có kèm mã; giới hạn này dùng chung với việc tạo hồ sơ qua MCP (mỗi lần MCP tạo hồ sơ đều chiếm một suất). Khi đạt giới hạn, API trả về 429 IDEMPOTENCY_CAPACITY cho đến khi các bản ghi cũ hết hạn.
• Mã yêu cầu và nội dung yêu cầu chỉ được lưu trên máy tính này dưới dạng giá trị băm có khóa; mật khẩu proxy không bao giờ được lưu ở dạng văn bản thuần.

Nên tạo mã yêu cầu từ dữ liệu nghiệp vụ của bạn, chẳng hạn số dòng trong bảng tính hoặc mã đơn hàng: shop-b-001.

Xử lý lỗi

Khi yêu cầu bị từ chối ngay ở bước tiếp nhận (xem “Quy tắc yêu cầu”), error là một chuỗi, ví dụ {"error":"unauthorized"}. Khi Prism gặp lỗi trong lúc xử lý yêu cầu, error là một đối tượng:

{
  "error": {
    "code": "INVALID_PROFILE_INPUT",
    "message": "Invalid profile creation request; see details",
    "retryable": false,
    "details": [
      { "path": "profiles[1].proxy.port", "message": "Too big: expected number to be <=65535" }
    ]
  }
}

Chương trình nên dựa vào trạng thái HTTP và code để xử lý; message là phần mô tả dành cho người đọc, một phần bằng tiếng Trung và cách diễn đạt có thể thay đổi giữa các phiên bản. Khi retryable là true, có thể thử lại nguyên yêu cầu đó sau. details chỉ xuất hiện trong lỗi tham số tạo hồ sơ, tối đa 20 mục, và không lặp lại các giá trị đã gửi.

MCP_REQUEST_FAILED là tên lỗi chung được dùng trong nội bộ Prism; API cục bộ cũng dùng tên này.

Ví dụ mã

Thay địa chỉ và mã thông báo trong ví dụ bằng giá trị hiển thị trong cửa sổ Prism. Ví dụ sẽ tạo hồ sơ, rồi khởi chạy và đóng hồ sơ vừa tạo.

Python

Cần có requests (pip install requests):

import requests

API = "http://127.0.0.1:43123"   # the API address shown in Prism
TOKEN = "<token>"                # the token shown in Prism

session = requests.Session()
session.headers["Authorization"] = f"Bearer {TOKEN}"

def call(method, path, **kwargs):
    response = session.request(method, API + path, timeout=70, **kwargs)
    body = response.json()
    if not response.ok:
        raise RuntimeError(f"{response.status_code}: {body['error']}")
    return body.get("result", body)

created = call("POST", "/v1/profiles/batch",
               headers={"Idempotency-Key": "shops-batch-002"},
               json={"profiles": [{"name": "Shop C"}, {"name": "Shop D"}]})
for profile in created["profiles"]:
    print("created", profile["serialNumber"], profile["id"])

profiles = call("GET", "/v1/profiles")
for profile in profiles:
    print(profile["serialNumber"], profile["name"], profile["status"])

first = created["profiles"][0]["id"]
print(call("POST", f"/v1/profiles/{first}/start")["status"])   # running
print(call("POST", f"/v1/profiles/{first}/close")["status"])   # closed

Node.js

Node.js 18 trở lên có sẵn fetch, không cần cài thêm gói phụ thuộc:

// prism.mjs — run with: node prism.mjs (Node.js 18 or later)
const API = 'http://127.0.0.1:43123' // the API address shown in Prism
const TOKEN = '<token>'              // the token shown in Prism

async function call(method, path, body, headers = {}) {
  const response = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${TOKEN}`, ...(body ? { 'Content-Type': 'application/json' } : {}), ...headers },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(70_000),
  })
  const data = await response.json()
  if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(data.error)}`)
  return data.result ?? data
}

const profile = await call('POST', '/v1/profiles', {
  name: 'Shop E',
  fingerprint: { language: 'en-US', timezone: 'America/New_York', networkIdentityMode: 'manual' },
}, { 'Idempotency-Key': 'shop-e-001' })
console.log('created', profile.serialNumber, profile.id)

console.log((await call('POST', `/v1/profiles/${profile.id}/start`)).status) // running
console.log((await call('POST', `/v1/profiles/${profile.id}/close`)).status) // closed

API cục bộ và MCP

API cục bộ dành cho script do bạn tự viết; ứng dụng AI nên kết nối với Prism qua MCP. MCP dùng mã thông báo và quyền riêng: AI chỉ thấy những hồ sơ được cho phép trong “AI cục bộ · MCP”, và AI không thể gọi API cục bộ. Cả hai dùng chung một dịch vụ cục bộ và hạn mức 120 yêu cầu mỗi 60 giây; khi dừng MCP hoặc dừng khẩn cấp MCP, API cục bộ cũng dừng theo.

AI cũng có thể tạo hồ sơ bằng các công cụ MCP prism_create_profile và prism_create_profiles, với tham số giống như trên trang này. Để làm vậy, bạn cần bật “Cho phép AI tạo hồ sơ” trong “AI cục bộ · MCP” (mặc định tắt); việc AI có điều khiển được hồ sơ mới hay không phụ thuộc vào chế độ cấp quyền hồ sơ bạn đã đặt. Mã yêu cầu của MCP và của API cục bộ được tính riêng, nhưng dùng chung giới hạn 1.000 bản ghi trong 24 giờ.

Khuyến nghị bảo mật

• Mã thông báo giống như chìa khóa để quản lý hồ sơ trên máy tính này: đừng đưa nó vào kho mã, nhật ký hay lịch sử trò chuyện. Nếu nghi ngờ bị lộ, hãy dừng rồi khởi động lại API; mã thông báo cũ sẽ mất hiệu lực ngay lập tức.
• API chỉ lắng nghe trên 127.0.0.1, nên các thiết bị khác trong mạng nội bộ hay trên Internet không thể truy cập trực tiếp. Bước kiểm tra Host chủ yếu dùng để chặn trình duyệt và việc vô tình dùng sai, không thay thế được cơ chế kiểm soát truy cập; đừng để lộ API ra ngoài bằng chuyển tiếp cổng hoặc reverse proxy.
• Chương trình khác trên máy tính này cũng có thể gọi API nếu lấy được mã thông báo. Chỉ bật API trên máy tính đáng tin cậy, và nhấp “Dừng API” khi dùng xong.
• “Dừng khẩn cấp” trong cửa sổ “API tự động hóa” sẽ dừng API và đóng các hồ sơ do API khởi chạy trong phiên này mà vẫn đang chạy.
• Mọi yêu cầu mà Prism thực thi đều được ghi vào nhật ký kiểm toán cục bộ vault/logs/automation-audit.jsonl (trong thư mục dữ liệu của Prism); nhật ký ghi thời gian, hành động, kết quả, ID yêu cầu, ID hồ sơ và nguyên nhân thất bại, không ghi mã thông báo, nội dung yêu cầu hay nội dung trang web. Các yêu cầu bị từ chối do vi phạm quy tắc yêu cầu và các lệnh gọi GET /v1/status không được ghi lại.

Câu hỏi thường gặp

Có thể gọi API từ trang web hoặc tiện ích mở rộng trình duyệt không?

Không. Yêu cầu do trình duyệt gửi sẽ kèm header Origin, và API sẽ từ chối. Hãy gọi API từ terminal, script hoặc chương trình trên máy.

Vì sao dùng localhost lại trả về 403?

API yêu cầu header Host khớp chính xác với 127.0.0.1 và cổng trong địa chỉ API, nên localhost sẽ bị từ chối. Hãy dùng 127.0.0.1 làm tên máy chủ trong địa chỉ.

Cửa sổ “API tự động hóa” hiển thị đang chạy nhưng không có mã thông báo thì phải làm gì?

Sau khi bật MCP, Prism tự động khởi động dịch vụ cục bộ dùng chung cho API và MCP, nên lúc này cửa sổ chỉ hiển thị địa chỉ. Mã thông báo chỉ hiển thị một lần, khi bạn nhấp “Khởi động API cục bộ” thành công: hãy nhấp “Dừng API”, rồi nhấp “Khởi động API cục bộ” để nhận mã thông báo mới. Trong thời gian dừng, kết nối MCP cũng bị ngắt.

Sau khi khởi động lại Prism, mã thông báo cũ còn dùng được không?

Không. Mỗi lần khởi động API đều tạo cổng và mã thông báo mới; sau khi dừng API hoặc thoát Prism, mã thông báo cũ sẽ mất hiệu lực.

Có thể dùng API để sửa hoặc xóa hồ sơ không?

Không. API có thể tạo, truy vấn, khởi chạy và đóng hồ sơ; việc sửa cấu hình và xóa hồ sơ cần thực hiện trong ứng dụng Prism.

Có thể kết nối Puppeteer, Playwright hoặc Selenium không?

Không. API không cung cấp cổng gỡ lỗi hay địa chỉ WebDriver. Khi cần thao tác ở cấp trang, bạn có thể để ứng dụng AI thực hiện qua MCP.

Có thể khởi chạy nhiều hồ sơ cùng lúc không?

Có thể, hãy gọi endpoint khởi chạy lần lượt cho từng hồ sơ. Prism xử lý các yêu cầu theo thứ tự, khởi chạy xong một hồ sơ rồi mới xử lý yêu cầu tiếp theo; số hồ sơ chạy cùng lúc phụ thuộc vào bộ nhớ và CPU của máy tính.

Có dùng được trên Windows không?

Có. Prism Pro trên macOS và Windows đều cung cấp API cục bộ với các endpoint giống nhau. Trong Windows PowerShell, hãy dùng curl.exe hoặc Invoke-RestMethod.

Tính năng và hướng dẫn liên quan