Mô-đun mẫu tích hợp API miễn phí cho Perfex CRM Data Builder

Last updated on Jul 10, 2026 5:03 AM

Từ tài liệu hướng dẫn đến mã nguồn chạy thực tế trong 5 phút

Bạn đã đọc qua tài liệu API của Data Builder. Bạn nắm được các điểm cuối (endpoints). Nhưng luôn có một khoảng cách lớn giữa việc đọc tài liệu lý thuyết và viết mã nguồn tích hợp sẵn sàng chạy trong môi trường thực tế.

Mô-đun API Data Builder Sample sinh ra để xóa nhòa khoảng cách đó. Đây là một mô-đun Perfex CRM mã nguồn mở hoàn toàn miễn phí, cung cấp cho bạn các **bản demo tương tác hoạt động trực tiếp** của mọi tính năng API trong Data Builder — ngay trong trang quản trị của bạn.

Hãy cài đặt thử, nhấp trải nghiệm, sao chép code và tự xây dựng tích hợp của riêng bạn.

> Tải về miễn phí trên GitHub →

---

Các tính năng tích hợp sẵn

REST API — Demo đầy đủ các thao tác CRUD

Tab REST API cung cấp một không gian tương tác hoàn chỉnh để thử nghiệm các endpoint REST của Data Builder:

GET    /api/v1/projects         → Lấy danh sách dự án kèm phân trang
GET    /api/v1/projects/42      → Lấy chi tiết một dự án cụ thể
POST   /api/v1/staff            → Tạo mới một nhân viên
PUT    /api/v1/invoices/15      → Cập nhật một hóa đơn
DELETE /api/v1/payments/7       → Xóa một bản ghi thanh toán

Dễ dàng chuyển đổi giữa các tài nguyên thông qua trình đơn thả xuống — Dự án, Nhân viên, Thanh toán, Hóa đơn, Công việc, Khách hàng và nhiều hơn nữa. Mỗi yêu cầu hiển thị rõ ràng:

Phản hồi JSON thô được làm nổi bật cú pháp trực quan
Mã trạng thái HTTP (status codes) và thời gian phản hồi
Mã nguồn PHP mẫu tự sinh tương ứng để bạn sao chép trực tiếp

Các tính năng nâng cao như giới hạn trường hiển thị (?fields=id,total,status), phân trang (?page=2&per_page=10) và sắp xếp (?sort=-total) đều được minh họa bằng các nút điều khiển trực quan thực tế.

GraphQL Playground (Trình soạn thảo GraphQL)

Dành cho các đội ngũ phát triển giao diện hiện đại, tab GraphQL cung cấp một trình soạn thảo truy vấn đầy đủ:

{
  projects(limit: 10) {
    id
    name
    status
    start_date
  }
}

Các mẫu truy vấn định sẵn giúp bạn bắt đầu ngay lập tức:

Truy vấn (Queries): Danh sách dự án, Công việc theo dự án, Danh bạ nhân viên, Tổng hợp hóa đơn, Kiểm tra kết nối
Đột biến (Mutations): Tạo công việc, Tạo nhân viên, Xóa hóa đơn

Mỗi mẫu đều hỗ trợ **truyền tham số (variables)** cho các truy vấn động. Kết quả hiển thị trực quan dưới dạng bảng cấu trúc và dạng JSON thô.

Mô-đun sẽ tự động sinh mã nguồn PHP tương ứng cho mỗi truy vấn bạn vừa chạy — sẵn sàng để dán vào ứng dụng của bạn.

Webhook Listener (Bộ tiếp nhận Webhook)

Tab Webhooks minh họa cách tiếp nhận và xử lý các sự kiện thời gian thực đẩy về từ Data Builder:

Loại sự kiện: table.create, table.update, table.delete
Trình kiểm tra Payload: Xem chi tiết cấu trúc dữ liệu JSON thực tế mà bên nhận sẽ nhận được
Mẫu mã nguồn tích hợp: Các cấu trúc sẵn sàng sử dụng để kết nối dữ liệu đến các dịch vụ bên thứ ba

Cấu hình kết nối (Connection Settings)

Thiết lập thông số kết nối API của bạn từ bảng cấu hình chuyên dụng:

API Base URL — Trỏ tới bất kỳ trang Perfex CRM nào đang chạy Data Builder
API Token — Xác thực bằng Bearer token của bạn
HMAC Secret — Kích hoạt chữ ký bảo mật HMAC-SHA256 phục vụ môi trường thực tế
Test Connection — Kiểm tra kết nối chỉ với một cú nhấp chuột kèm đo lường thời gian phản hồi

---

Các quyết định kiến trúc cốt lõi

Hoạt động độc lập (Standalone Client)

Mô-đun này **không bắt buộc** phải cài đặt trên cùng một cơ sở dữ liệu Perfex CRM chạy Data Builder. Đây là một API client hoạt động độc lập có thể truy vấn đến bất kỳ trang CRM chạy Data Builder nào từ xa. Giải pháp này vô cùng phù hợp cho:

Môi trường phát triển — Cài đặt mô-đun mẫu này trên máy chủ dev nội bộ, và cấu hình trỏ API tới máy chủ production chạy Data Builder thực tế
Demo khách hàng — Trực quan hóa cho khách hàng thấy dữ liệu của họ được truy xuất qua API như thế nào
Học tập & Thử nghiệm — Khám phá cấu trúc API thoải mái mà không lo ảnh hưởng đến dữ liệu sản xuất

Truy vấn trực tiếp ở Client (Browser-Side Fetch)

Tất cả các lệnh gọi API đều sử dụng hàm fetch() ở phía trình duyệt client thay vì cURL ở backend PHP. Điều này giúp tránh hiện tượng nghẽn mạng cURL loopback khi cả hai mô-đun cùng chạy trên một máy chủ, đồng thời phản ánh chuẩn xác hành vi CORS thực tế để kiểm thử.

Xử lý lỗi mạnh mẽ

Mô-đun xử lý thông minh các phản hồi không phải định dạng JSON (các trang lỗi HTML, lỗi máy chủ 500) và đưa ra thông tin chẩn đoán rõ ràng thay vì các thông báo lỗi biên dịch khó hiểu.

---

Hướng dẫn cài đặt

Cách 1: Sao chép thư mục trực tiếp

Tải về hoặc clone mã nguồn từ GitHub
Sao chép thư mục api_data_builder_sample vào thư mục modules/ trong nguồn Perfex CRM của bạn
Truy cập Cài đặt admin --> Hệ thống --> Modules và nhấp Kích hoạt (Activate)

Cách 2: Tải lên tệp ZIP

Tải mã nguồn về dưới dạng tệp nén .zip
In Perfex CRM, go to Admin --> Setup --> Modules --> Browse
Tải tệp ZIP lên và tiến hành cài đặt
Kích hoạt mô-đun

Cấu hình thông số

Nhấp chọn API Samples --> Cấu hình (Settings) trên thanh menu bên
Nhập đường dẫn API Base URL (ví dụ: https://your-crm.com)
Dán mã API Token (được tạo trong Data Builder --> API Tokens)
Nhập mã HMAC Secret nếu bạn muốn kiểm thử chế độ ký bảo mật dữ liệu
Nhấp Test Connection để hoàn tất xác thực kết nối!

---

Requirements

Perfex CRM phiên bản 3.0.0 trở lên
Có cài đặt mô-đun Data Builder phiên bản v2.0.0+ trên hệ thống đích cần truy vấn
A valid API Token created in Data Builder --> API Tokens

---

Cấu trúc thư mục mô-đun

api_data_builder_sample/
├── api_data_builder_sample.php      # Khai báo thông tin mô-đun & menu sidebar
├── install.php                       # File cấu hình khi kích hoạt
├── controllers/
│   └── Api_data_builder_sample.php   # Bộ điều khiển Admin controller
├── helpers/
│   └── api_sample_helper.php         # Các hàm bổ trợ helper
└── views/admin/
    ├── dashboard.php                 # Tổng quan & trạng thái kết nối
    ├── rest.php                      # Trang demo tương tác REST API
    ├── graphql.php                   # Trang soạn thảo GraphQL playground
    ├── webhooks.php                  # Bộ lắng nghe và kiểm tra Webhook
    └── settings.php                  # Cài đặt kết nối API

---

Các trường hợp sử dụng thực tế

Dành cho Lập trình viên

Tham chiếu mã nguồn mẫu — Xem chi tiết cách thức xác thực, phân trang, lọc dữ liệu và sắp xếp dữ liệu phản hồi từ API
Sinh mã nguồn nhanh — Mỗi yêu cầu gọi thử đều sinh ra code PHP tương ứng để sao chép sử dụng ngay
Môi trường thử nghiệm — Xác thực nhanh phân quyền của API token trước khi viết mã nguồn tích hợp chính thức

Dành cho Quản trị dự án

Đánh giá năng lực API — Trực quan hóa các khả năng tích hợp của Data Builder cho các bên liên quan
Kiểm chứng giải pháp (Proof of Concept) — Minh họa cách thức dữ liệu từ CRM đồng bộ mượt mà sang các ứng dụng ngoài
Công cụ đào tạo — Giúp các lập trình viên mới tiếp cận dự án nhanh chóng qua các ví dụ thực tế tương tác trực quan

Dành cho Chủ doanh nghiệp

Khảo sát khả năng tích hợp — Hiểu rõ các giá trị khai thác từ kho dữ liệu CRM của mình
Đánh giá nhà cung cấp — So sánh năng lực hạ tầng API của Data Builder với các giải pháp khác trên thị trường
Tối ưu hóa chi phí ROI — Nhìn nhận rõ lượng thời gian phát triển được tiết kiệm tối đa nhờ hạ tầng API xây dựng sẵn

---

Bắt đầu ngay hôm nay

Mô-đun API Data Builder Sample được cung cấp hoàn toàn miễn phí và mở nguồn dưới giấy phép MIT License. Hãy cài đặt, khám phá API và bắt đầu xây dựng các tích hợp tự động hóa tuyệt vời cho doanh nghiệp của bạn chỉ trong vài phút.

> Tải về miễn phí trên GitHub →

Mô-đun này được phát triển đồng bộ cùng giải pháp chính Data Builder — Báo cáo trực quan, REST API & GraphQL cho Perfex CRM, giải pháp chuẩn doanh nghiệp giúp biến hệ thống Perfex CRM của bạn thành một nền tảng API toàn diện tích hợp bảo mật sản xuất và tài liệu hướng dẫn tự động.

> Sở hữu Data Builder trên CodeCanyon →

---

Data Builder cho Perfex CRM — Từ các bảng dữ liệu đến các hệ thống thúc đẩy quyết định kinh doanh.