Tìm hiểu REST API trong Perfex CRM hoạt động như thế nào? (Kèm ví dụ)
Địa chỉ API gốc (API Base URL)
Tất cả các endpoint REST API đều tuân thủ một cấu trúc đồng bộ:
https://databuilder.polyxgo.com/api/v1/{resource}Trong đó {resource} là tên của bất kỳ bảng dữ liệu nào trong Perfex CRM đã được thêm vào cấu hình cho phép (ví dụ: clients, invoices, tasks, projects).
Các phương thức HTTP (HTTP Methods)
| Phương thức | Endpoint mẫu | Hành động thực thi |
|---|---|---|
GET | /clients | Truy xuất danh sách bản ghi (hỗ trợ lọc dữ liệu và phân trang) |
GET | /clients/42 | Lấy chi tiết một bản ghi cụ thể theo khóa chính (Primary Key) |
GET | /clients/schema | Xem cấu trúc bảng dữ liệu (danh sách cột, kiểu dữ liệu) |
POST | /clients | Tạo mới một bản ghi |
PUT | /clients/42 | Cập nhật nội dung bản ghi hiện có |
DELETE | /clients/42 | Xóa bản ghi khỏi hệ thống |
GET | /auth/test | Kiểm tra kết nối và xác thực token |
Ví dụ: Truy xuất danh sách Hóa đơn (List Invoices)
curl -X GET 'https://databuilder.polyxgo.com/api/v1/invoices?per_page=5&sort=-id&fields=id,total,status,clientid' \
-H 'Authorization: Bearer YOUR_TOKEN'Dữ liệu phản hồi (Response):
{
"data": [
{"id": 150, "total": "1500.00", "status": "2", "clientid": "42"},
{"id": 149, "total": "750.00", "status": "1", "clientid": "38"}
],
"meta": {"current_page": 1, "per_page": 5, "total": 150},
"links": {"next": "/api/v1/invoices?page=2&per_page=5"}
}Các tham số truy vấn (Query Parameters)
Vui lòng tham khảo tài liệu hướng dẫn lọc và phân trang chi tiết để nắm rõ các tham số hỗ trợ bao gồm: sort (sắp xếp), fields (chỉ định trường hiển thị), filter (bộ lọc), page (trang hiển thị), per_page (số lượng mỗi trang) và since (lọc theo mốc thời gian).
Cơ chế xử lý lỗi (Error Handling)
Tất cả các thông báo lỗi trả về đều tuân thủ chặt chẽ theo tiêu chuẩn lỗi HTTP RFC 9457 Problem Details. Xem thêm mục Tài liệu tham khảo lỗi để nắm rõ các mã trạng thái và phương án xử lý tương ứng.
Chạy thử nghiệm trực tiếp
Trang API Explorer cung cấp môi trường sandbox trực quan giúp bạn chạy thử nghiệm bất kỳ endpoint nào và tự động sinh mã nguồn tương ứng bằng các ngôn ngữ cURL, JavaScript, PHP và Python. Bạn cũng có thể xuất cấu hình sang định dạng tệp tin cho Postman hoặc OpenAPI 3.0 phục vụ cho quy trình phát triển của mình.