Hướng dẫn Lọc, Sắp xếp và Phân trang dữ liệu trong Perfex CRM API

Last updated on Jul 10, 2026 3:56 AM

Tổng quan về các tham số truy vấn (Query Parameters)

REST API của Data Builder hỗ trợ 6 loại tham số truy vấn giúp bạn truy xuất dữ liệu chuẩn xác:

Tham số	Ví dụ mẫu	Mô tả chức năng
`sort`	`-id`	Sắp xếp giảm dần theo id (thêm dấu `-` phía trước để sắp xếp giảm dần DESC)
`fields`	`id,company,email`	Sparse fieldset – chỉ trả về danh sách các cột được chỉ định cụ thể
`filter`	`status:1`	Lọc bản ghi theo giá trị của trường dữ liệu
`per_page`	`25`	Số lượng bản ghi hiển thị trên mỗi trang (mặc định: 25)
`page`	`2`	Số thứ tự trang hiển thị phục vụ phân trang
`since`	`2026-04-25T00:00:00`	Cơ chế polling – chỉ lấy các bản ghi có thay đổi sau mốc thời gian này

Lọc dữ liệu (Filtering)

# Lọc danh sách khách hàng theo mã quốc gia
GET https://databuilder.polyxgo.com/api/v1/clients?filter=country:243

# Kết hợp nhiều bộ lọc cùng lúc
GET https://databuilder.polyxgo.com/api/v1/invoices?filter=status:2&filter=currency:1

Sắp xếp (Sorting)

# Sắp xếp theo ID mới nhất lên đầu
GET https://databuilder.polyxgo.com/api/v1/invoices?sort=-id

# Sắp xếp theo ngày tạo tăng dần
GET https://databuilder.polyxgo.com/api/v1/tasks?sort=dateadded

Sparse Fieldsets (Chọn trường hiển thị)

# Chỉ trả về các trường được chỉ định cụ thể
GET https://databuilder.polyxgo.com/api/v1/clients?fields=userid,company,phonenumber,email

Phân trang (Pagination)

Dữ liệu phản hồi trả về đi kèm các liên kết điều hướng HATEOAS tiện lợi:

{
  "data": [...],
  "meta": { "current_page": 1, "per_page": 25, "total": 150 },
  "links": {
    "next": "/api/v1/clients?page=2&per_page=25",
    "prev": null
  }
}

Lấy dữ liệu gia tăng với ?since= (v2.2.0)

Đối với các nền tảng tự động hóa, bạn có thể truyền tham số since để chỉ lấy các bản ghi được tạo mới hoặc cập nhật sau một mốc thời gian cụ thể:

# Lấy danh sách hóa đơn có thay đổi trong vòng 1 giờ qua
GET https://databuilder.polyxgo.com/api/v1/invoices?since=2026-04-26T11:00:00

Động cơ xử lý sẽ tự động phát hiện các cột mốc thời gian trong Perfex CRM (như dateadded, datecreated...) và trả về kết quả được sắp xếp theo thứ tự mới nhất lên đầu. Cơ chế này giúp thiết lập các trigger polling tối ưu trên Zapier, Make.com, và n8n.