Hướng dẫn sử dụng GraphQL trong Perfex CRM để truy vấn dữ liệu linh hoạt

Last updated on Jul 10, 2026 2:18 AM

Tại sao nên sử dụng GraphQL cho CRM?

Các hệ thống REST API truyền thống luôn trả về các cấu trúc dữ liệu cố định. Trong khi đó, GraphQL cho phép bạn chỉ định chính xác các trường thông tin mình cần hiển thị chỉ trong một câu lệnh truy vấn duy nhất. Đối với dữ liệu CRM vốn chứa hàng chục bảng và các mối quan hệ liên kết phức tạp, cơ chế này giúp giảm số lượng yêu cầu gọi API và tối giản hóa dung lượng tải về.

Địa chỉ Endpoint duy nhất

POST https://databuilder.polyxgo.com/api/v1/graphql
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

Viết các câu lệnh truy vấn dữ liệu (Querying)

# Lấy danh sách nhân viên kèm các trường cụ thể
{
  staffs(limit: 10) {
    id firstname lastname email
  }
}

# Lọc và sắp xếp dữ liệu
{
  invoices(limit: 5, sort: "-total", filter: "status:2") {
    id total status datecreated
  }
}

# Gọi dữ liệu từ nhiều bảng khác nhau trong một yêu cầu
{
  clients(limit: 5) { userid company }
  projects(limit: 5, sort: "-id") { id name }
  tasks(limit: 10, filter: "status:1") { id name }
}

Mutations: Tạo mới, Cập nhật, Xóa

GraphQL mutations hỗ trợ đầy đủ các thao tác CRUD với các kiểu dữ liệu đầu vào (input types) được tự động sinh ra:

# Tạo mới một dự án
mutation {
  createProject(input: {
    name: "API Integration Project"
    clientid: 42
    start_date: "2026-05-01"
  }) {
    id name clientid
  }
}

# Cập nhật thông tin công việc
mutation {
  updateTask(id: 603, input: {
    name: "Updated task name"
    status: 2
  }) {
    id name status
  }
}

# Xóa một bản ghi chi phí
mutation {
  deleteExpense(id: 15) {
    success message
  }
}

Các thao tác ghi dữ liệu bắt buộc sử dụng API token có quyền ghi (write) và được phân quyền cụ thể trên từng bảng. Các cột dữ liệu nhạy cảm (mật khẩu, token, API keys...) sẽ tự động bị loại bỏ khỏi kiểu dữ liệu đầu vào.

Khi nào nên dùng GraphQL và khi nào nên dùng REST?

Trường hợp áp dụng	Lựa chọn tối ưu	Lý do giải thích
Ứng dụng di động	GraphQL	Tối ưu hóa dữ liệu truyền tải, gộp yêu cầu gọi API
Tự động hóa (Zapier/Make)	REST	Định dạng dữ liệu webhook đơn giản, dễ xử lý
Dashboard báo cáo	GraphQL	Truy vấn đồng thời dữ liệu từ nhiều bảng liên kết
Thao tác CRUD đơn giản	REST	Sử dụng các phương thức HTTP quen thuộc
Đồng bộ gia tăng (Polling)	REST	Tận dụng tham số lọc mốc thời gian `?since=`
Tích hợp WordPress	Cả hai đều tốt	Cả hai giải pháp đều tương thích tốt với hàm fetch()

Để tìm hiểu so sánh chi tiết, xem bài viết REST và GraphQL trong Perfex CRM.

Các giới hạn bảo mật

Giới hạn độ sâu truy vấn (Query depth limit) – ngăn chặn các truy vấn lồng nhau quá sâu làm treo máy chủ.
Điểm độ phức tạp (Complexity scoring) – chặn đứng các truy vấn nặng gây quá tải tài nguyên database.
Phạm vi hoạt động của Token (Token scopes) – thiết lập chi tiết bảng dữ liệu và quyền hạn được phép thao tác.
Chuẩn lỗi RFC 9457 – đồng bộ định dạng thông tin báo lỗi trả về.