# FineProxy Agent Pack

Phiên bản: 2026-09-22

Sử dụng tệp này để đánh giá liệu một tích hợp proxy hiện có có thể di chuyển sang FineProxy hay không. Tệp không chứa khóa API, dữ liệu tài khoản hoặc endpoint riêng tư.

## Nguồn thông tin chuẩn

- Tài liệu API client tương tác: `https://fineproxy.org/account_new/docs`
- Thiết lập MCP: `https://fineproxy.org/account_new/mcp`
- Đặc tả OpenAPI client hiện tại: tải từ tài liệu API trong bảng điều khiển khách hàng.
- Tạo và quản lý khóa API: `https://fineproxy.org/account_new/settings`
- Endpoint MCP: `https://fineproxy.org/account_new/api/v1/mcp`

Không bao giờ tự tạo endpoint từ phần tổng quan này. Hãy sử dụng đặc tả OpenAPI hiện tại cho đường dẫn yêu cầu, schema, tham số và phản hồi.

## Tổng quan nền tảng

- REST API: OpenAPI 3.1, 49 thao tác dành cho khách hàng đã được lập tài liệu.
- MCP: 49 công cụ qua JSON-RPC 2.0 không trạng thái và Streamable HTTP.
- Xác thực: khóa API bearer được tạo trong bảng điều khiển khách hàng.
- API và MCP sử dụng cùng các quyền có phạm vi.
- Tài liệu API đối tác chỉ hiển thị cho các tài khoản có trạng thái đối tác đang hoạt động.

## Quy trình được hỗ trợ

### Mua và cấp phát

- Liệt kê các quốc gia và lượng IP hiện có theo thời gian thực.
- Báo giá chính xác cho gói đa quốc gia mà không mua.
- Mua từ ví trên bảng điều khiển với cơ chế bảo vệ giá và khóa idempotency.

Trình tự mua MCP tiêu chuẩn là:

1. `list_countries`
2. `quote_composite`
3. `order_composite`

### Quản lý dịch vụ

- Đọc và quản lý dịch vụ.
- Gia hạn, tạm ngưng, khôi phục hoặc hủy khi được hỗ trợ.
- Bật hoặc tắt tự động gia hạn.
- Thay thế hoặc thêm địa chỉ IP.
- Thay đổi thông tin xác thực dịch vụ.
- Đọc và quản lý giới hạn của danh sách IP cho phép.
- Liệt kê, mua và hủy các tiện ích bổ sung tương thích.

### Phân tích và chẩn đoán

- Tổng quan mức sử dụng và chuỗi thời gian.
- Các đích đến hàng đầu.
- Danh mục lỗi.
- Khuyến nghị vận hành.

### Thanh toán và hỗ trợ

- Đọc hóa đơn và tải tệp PDF hóa đơn.
- Liệt kê các cổng thanh toán.
- Bắt đầu nạp tiền vào ví và đọc trạng thái.
- Tạo, đọc, trả lời và đóng ticket hỗ trợ.

### Truy cập proxy và tài khoản

- Đọc cấu hình kết nối proxy xoay vòng.
- Thay đổi tên đăng nhập và mật khẩu dịch vụ.
- Quản lý giới hạn kết nối theo từng IP trong danh sách cho phép.
- Đọc thông tin hồ sơ, IP của bên gọi và lịch sử đăng nhập.
- Cấu hình webhook.

## Phạm vi quyền

- `customer:read` — đọc thông tin khách hàng và tài khoản.
- `customer:write` — cập nhật thông tin khách hàng.
- `wallet:read` — đọc thông tin ví.
- `wallet:deposit` — tạo và theo dõi các khoản nạp.
- `wallet:spend` — chi tiêu tiền trong ví. Hãy coi đây là quyền tài chính.
- `services:read` — đọc dịch vụ và cài đặt proxy.
- `services:write` — tạo hoặc sửa đổi dịch vụ và tiện ích bổ sung.
- `tickets:read` — đọc ticket hỗ trợ.
- `tickets:write` — tạo, trả lời, cập nhật hoặc đóng ticket.
- `catalog:read` — đọc sản phẩm, tùy chọn, quốc gia và lượng IP hiện có.
- `usage:read` — đọc dữ liệu sử dụng và chẩn đoán.
- `webhooks` — quản lý đăng ký webhook.

Bắt đầu kiểm tra di chuyển với các quyền chỉ đọc. Chỉ thêm quyền ghi hoặc quyền tài chính sau khi các thay đổi được đề xuất đã được xem xét.

## Cơ chế an toàn

- Các công cụ tài chính yêu cầu `wallet:spend`.
- Giao dịch mua kèm theo tổng số dự kiến đã được báo giá. Nếu giá không khớp, thao tác sẽ bị từ chối.
- Các thao tác không thể đảo ngược yêu cầu xác nhận rõ ràng.
- Các lần thử lại yêu cầu tài chính sử dụng khóa idempotency để cùng một thao tác không bị tính phí hai lần.
- Lượng IP hiện có, điều kiện của gói và quyền tài khoản có thể ngăn một thao tác vốn hợp lệ.
- FineProxy MCP vận hành tài khoản khách hàng. MCP không có quyền truy cập mã nguồn trừ khi người dùng cấp riêng cho agent lập trình quyền truy cập vào kho mã.

## Mẫu cấu hình MCP

```json
{
  "mcpServers": {
    "fineproxy": {
      "url": "https://fineproxy.org/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}
```

Lưu khóa thật trong biến môi trường hoặc trình quản lý bí mật. Không commit khóa cùng với cấu hình MCP.

## Danh sách kiểm tra khả năng tương thích khi di chuyển

Kiểm tra tích hợp hiện có về:

1. Việc khởi tạo client của nhà cung cấp và tất cả import dành riêng cho nhà cung cấp.
2. Header xác thực, thông tin xác thực, biến môi trường và lưu trữ bí mật.
3. Quy trình mua, gia hạn, hủy và thay thế IP.
4. Định danh quốc gia và các giả định về lượng IP hiện có.
5. Định dạng danh sách proxy, giao thức, cổng, tên đăng nhập, mật khẩu và danh sách IP cho phép.
6. Phân trang và lọc.
7. Cơ chế thử lại, xử lý hết thời gian chờ và idempotency.
8. Mô hình lỗi và xử lý giới hạn tốc độ.
9. Phân tích mức sử dụng và chẩn đoán.
10. Thanh toán, hóa đơn và khoản nạp.
11. Tích hợp ticket hỗ trợ.
12. Webhook và các giả định về payload sự kiện.
13. Kiểm thử, fixture, mock và bí mật CI gắn với nhà cung cấp hiện tại.

Phân loại từng quy trình là:

- Tương thích mà không cần thay đổi.
- Tương thích thông qua thay đổi cấu hình.
- Cần adapter hoặc chuyển đổi dữ liệu.
- Cần quy trình vận hành khác.
- Không được hỗ trợ hoặc chưa được tài liệu hiện tại xác nhận.

## Kết quả kiểm tra bắt buộc

Kết quả kiểm tra cần bao gồm:

1. Danh mục mọi phần phụ thuộc vào nhà cung cấp hiện tại.
2. Đánh giá khả năng tương thích theo từng quy trình.
3. Các phạm vi quyền FineProxy bắt buộc.
4. Chính xác các tệp và đường dẫn mã sẽ thay đổi.
5. Các thay đổi về xác thực và quản lý bí mật.
6. Các câu hỏi mở cần đặc tả OpenAPI hiện tại hoặc xác nhận từ bộ phận hỗ trợ.
7. Kế hoạch di chuyển theo giai đoạn có phương án quay lui.
8. Các kiểm thử tích hợp bắt buộc trước khi chuyển đổi.

Không sửa đổi mã trong lượt kiểm tra đầu tiên.