API (Application Programming Interface) là phương thức cho phép các ứng dụng phần mềm giao tiếp và trao đổi dữ liệu với nhau một cách có cấu trúc. Nó đóng vai trò như một “cầu nối” giúp hệ thống này gửi yêu cầu và nhận phản hồi từ hệ thống khác một cách an toàn, nhanh chóng và hiệu quả.
API của PionLogin sử dụng định dạng JSON cho cả yêu cầu (Request) và phản hồi (Response). Tất cả dữ liệu gửi đi và nhận về đều được mã hóa dưới dạng JSON, đảm bảo tính nhất quán, dễ đọc và dễ xử lý khi tích hợp với script, tool tự động hóa hoặc ứng dụng bên thứ ba.
Mục đích của tài liệu API
Tài liệu API PionLogin được thiết kế dành cho người dùng và lập trình viên, giúp bạn quản lý trình duyệt profile một cách lập trình hóa (programmatically). Thông qua API, bạn có thể thực hiện các thao tác chính sau đây:
- Tạo mới profile với cấu hình fingerprint, proxy, noise settings, OS, language… tùy chỉnh
- Cập nhật, chỉnh sửa thông tin profile (tên, proxy, cookie, noise, nhóm…)
- Kiểm tra trạng thái, lấy chi tiết profile hoặc nhóm
1/ Browser Engines: API for managing browser
GET /api/browsers
Đây là API giúp bạn liệt kê tất cả các phiên bản trình duyệt hiện có trong hệ thống để sử dụng cho các profile.
1.1. Cách test nhanh (trong Swagger UI)
→ Mở Swagger docs của PionLogin.
→ Chọn GET /api/browsers.
→ Nhấn Try it out (không cần điền gì).
→ Nhấn Execute.
→ Kiểm tra response: Nếu success true → danh sách engine xuất hiện trong "data".
2/Profile Groups: API for managing profile groups
GET /api/profile-groups
2.1. Chức năng: Tìm kiếm và liệt kê các nhóm profile (Search profile groups).
2.2. Giải thích các tham số (Parameters)
Khi gọi API này, bạn có thể truyền vào các tham số sau (đều là dạng query string):
→ keyword (string): Từ khóa để tìm kiếm nhóm profile theo tên hoặc thông tin liên quan.
→ pageIndex (integer): Số thứ tự trang muốn lấy. Giá trị mặc định là 1.
→ pageSize (integer): Số lượng bản ghi (nhóm) hiển thị trên mỗi trang. Giá trị mặc định là 10.
→ sortBy (string): Tiêu chí sắp xếp dữ liệu.
Ví dụ: createdAt.desc (Sắp xếp theo thời gian tạo, mới nhất lên đầu).\
2.3. Cách test nhanh (trong Swagger UI)
→Mở Swagger docs của PionLogin.
→ Chọn GET /api/profile-groups.
→ Nhấn Try it out.
→ Điền các tham số nếu cần (keyword, pageIndex, pageSize, sortBy).
→ Nhấn Execute.
→ Kiểm tra response: success true → danh sách nhóm trong "data".
3/Profiles: API for managing profiles
GET /api/profiles
3.1.1 Chức năng: Tìm kiếm danh sách các profile dựa trên các điều kiện lọc.
3.1.2. Các tham số lọc (Query Parameters)
→ keyword (string): Tìm kiếm profile theo tên hoặc từ khóa liên quan.
→pageIndex (integer): Số trang (mặc định là 1).
→pageSize (integer): Số lượng profile trên mỗi trang (mặc định là 10).
→sortBy (string): Sắp xếp kết quả (Ví dụ: createdAt.desc để hiện profile mới tạo lên đầu).
→browserStatus (string): Lọc theo trạng thái trình duyệt. Bạn chỉ có thể chọn 1 trong 2 giá trị: OPENING (đang mở) hoặc CLOSED (đã đóng).
→profileGroupId (string - dạng ID): Lọc các profile thuộc về một nhóm cụ thể nào đó. Bạn có thể lấy ID này từ API Profile Groups trước đó.
3.1.3.Cách thực hiện Test nhanh
→Nhấn "Try it out".
→Nếu bạn muốn tìm các profile đang mở, hãy chọn OPENING ở mục browserStatus.
→Nếu muốn tìm profile trong một nhóm nhất định, dán ID của nhóm đó vào ô profileGroupId.
→Nhấn "Execute" để xem danh sách trả về.
POST /api/profiles
3.2.1. Chức năng: Tạo một profile trình duyệt mới với fingerprint, cấu hình hệ điều hành, ngôn ngữ, user-agent, cookie và các thông số noise randomization riêng biệt. Mỗi profile hoạt động như một môi trường trình duyệt độc lập, giúp quản lý nhiều tài khoản một cách an toàn, tránh bị phát hiện liên kết giữa các tài khoản.
3.2.2.Parameters
Không có query parameters (No parameters).
Chỉ sử dụng Request body (bắt buộc, Content-Type: application/json).
3.3.3. Cách test nhanh (trong Swagger UI)
→ Mở Swagger docs của PionLogin.
→Chọn POST /api/profiles.
→Nhấn Try it out.
→Paste body JSON mẫu vào phần Request body.
→Nhấn Execute.
→Kiểm tra response: Nếu success true → copy data.id để sử dụng tiếp
GET /api/profiles/{id}
3.3.1. Chức năng: Trả về toàn bộ thông tin chi tiết của một profile đã tạo trước đó. Bạn chỉ cần cung cấp ID profile (lấy từ response của POST /api/profiles hoặc từ GET /api/profiles list).
3.3.2. Parameters (Path Parameter – bắt buộc)
id (string, required, path): ID của profile cần lấy chi tiết.
3.4.1. Chức năng: Cập nhật một hoặc nhiều trường của profile hiện có. Các trường bạn gửi trong body sẽ ghi đè lên giá trị cũ; các trường không gửi sẽ giữ nguyên. Endpoint này hỗ trợ partial update (chỉ cập nhật những gì cần).
3.4.2. Parameters (Path Parameter – bắt buộc)
id (string, required, path): ID của profile cần cập nhật.
3.4.3. Cách test nhanh (trong Swagger UI)
→ Mở Swagger docs của PionLogin.
→ Chọn POST /api/profiles/{id}.
→ Nhấn Try it out.
→ Dán ID profile vào ô id.
→ Paste body JSON (chỉ các trường cần update) vào Request body.
→ Nhấn Execute.
→ Kiểm tra response success true → sau đó dùng GET /api/profiles/{id} để verify thay đổi.
POST /api/profiles/ {id}/delete
3.5.1. Chức năng: Xóa profile theo ID được chỉ định. Sau khi xóa, profile sẽ không còn xuất hiện trong danh sách (GET /api/profiles) và không thể mở lại hoặc cập nhật. Endpoint này thường dùng để quản lý sạch sẽ khi farm acc, loại bỏ profile hỏng hoặc đã hoàn thành nhiệm vụ.
3.5.2. Parameters (Path Parameter – bắt buộc)
id (string, required, path): ID của profile cần xóa.
3.5.3.Cách test nhanh (trong Swagger UI)
→Mở Swagger docs của PionLogin.
→Chọn POST /api/profiles/{id}/delete.
→Nhấn Try it out.
→Dán ID profile cần xóa vào ô id.
→Không cần điền body (nếu Swagger yêu cầu body thì để rỗng {}).
→Nhấn Execute.
→Kiểm tra response: Nếu success true → profile đã xóa.
POST /api/profiles/{id}/force-delete
3.6.1. Chức năng: Force-delete profile theo ID được cung cấp.
Bỏ qua kiểm tra trạng thái (không quan tâm profile đang OPENING hay CLOSED).
Tự động kill process browser nếu profile đang chạy.
Xóa vĩnh viễn toàn bộ dữ liệu profile (fingerprint, proxy, cookie, noise settings...).
Không thể khôi phục sau khi thực hiện.
3.6.2. Parameters (Path Parameter – bắt buộc)
id (string, required, path): ID của profile cần force-delete.
3.6.3. Cách test nhanh (trong Swagger UI)
→Mở Swagger docs của PionLogin.
→Chọn POST /api/profiles/{id}/force-delete.
→Nhấn Try it out.
→Điền ID profile vào ô id
→Không cần body (để rỗng nếu Swagger yêu cầu).
→Nhấn Execute.
→Kiểm tra response:
→Nếu "success": true → profile đã xóa.
→Verify bằng GET /api/profiles hoặc GET /api/profiles/{id} → profile không còn tồn tại.
GET /api/profiles/{id}/start
3.7.1. Chức năng: Mở profile theo ID được chỉ định.
Nếu profile đang CLOSED → sẽ mở mới cửa sổ trình duyệt.
Nếu profile đã OPENING → một số phiên bản có thể trả lỗi hoặc bỏ qua (tùy config, khuyến nghị check status trước).
Hỗ trợ tùy chỉnh vị trí, kích thước cửa sổ khi mở (rất tiện khi chạy multi-profile trên màn hình lớn hoặc nhiều màn hình).
3.7.2. Parameters
id (string, required, path): ID của profile cần mở.
