Hướng dẫn toàn diện về REST API PolyCMS cho RISE CRM
REST API của PolyCMS (/cms/api/v1/) biến PolyCMS cho RISE CRM thành một hệ thống Headless CMS chuẩn doanh nghiệp với đầy đủ các endpoint CRUD cho Bài viết, Trang tĩnh, Chuyên mục, Thẻ tag và Thư viện phương tiện quản lý bằng cơ sở dữ liệu. Được bảo vệ bởi khóa API 192-bit mang tiền tố pcms_*, so sánh thời gian hằng hash_equals(), cơ chế tự động miễn trừ CSRF của RISE CRM, giới hạn tần suất theo IP, cô lập dữ liệu nghiêm ngặt và hàng rào tải ảnh 6 lớp, API giúp ứng dụng di động, frontend React/Vue/Next.js và công cụ tự động hóa kết nối nội dung an toàn mà không chạm tới dữ liệu lõi của RISE CRM.
Bắt đầu nhanh
- Mở PolyCMS > Settings > REST API (
#tab-api) trong quản trị RISE CRM. - Bật công tắc Enable REST API.
- Chọn Generate New API Key để sinh khóa mã hóa 192-bit bắt đầu bằng
pcms_rồi lưu cài đặt. - Điều chỉnh hạn mức yêu cầu đọc (Read) và ghi (Write) mỗi phút theo lưu lượng thực tế.
- Truy cập PolyCMS > API Explorer để kiểm thử trực tiếp các endpoint kèm mã mẫu cURL, PHP, JavaScript và Python. Xem thêm tại Hướng dẫn sử dụng API Explorer.
Xác thực API và Tự động miễn trừ CSRF trên RISE CRM
Mọi yêu cầu gửi tới /cms/api/v1/* phải đính kèm khóa API hợp lệ bằng một trong hai cách:
- HTTP Header (Khuyến nghị):
X-PolyCMS-API-Key: pcms_your_key_here - Tham số truy vấn URL:
?api_key=pcms_your_key_here
curl -X GET \
-H "X-PolyCMS-API-Key: pcms_your_key_here" \
-H "Accept: application/json" \
"https://your-rise-site.com/cms/api/v1/posts"
Bảo mật xác thực và cơ chế miễn trừ CSRF tự động
- Độ mạnh khóa 192-bit: Khóa được sinh bằng
random_bytes(24)(48 ký tự hệ thập lục phân) gắn tiền tốpcms_. - So sánh thời gian hằng (
hash_equals()): Ngăn chặn hoàn toàn tấn công suy đoán ký tự theo độ trễ phản hồi (timing attack). - Tự động miễn trừ CSRF trên RISE CRM:
plugins/polycms/index.phpđăng ký mẫucms/api/v1.*+qua bộ lọcapp_filter_app_csrf_exclude_uriscủa RISE CRM. Nhờ đó các ứng dụng ngoài gọiPOST,PUT,PATCH,DELETEbằngX-PolyCMS-API-Keykhông cần cookie phiên trình duyệt, trong khi mọi biểu mẫu quản trị RISE CRM vẫn giữ nguyên lớp bảo vệ CSRF. - Đóng mặc định an toàn: Nếu chưa tạo khóa API hoặc công tắc REST API đang tắt, mọi yêu cầu đều bị từ chối ngay (
401 Unauthorizedhoặc403 Forbidden).
Giới hạn tần suất gọi (Rate Limiting)
API áp dụng giới hạn theo từng địa chỉ IP và lưu bộ đếm riêng tư tại thư mục writable/polycms/rate_limit/.
- Thao tác đọc (
GET): Mặc định60yêu cầu mỗi phút. - Thao tác ghi (
POST,PUT,PATCH,DELETE): Mặc định30yêu cầu mỗi phút.
Mọi phản hồi API đều kèm các HTTP header chuẩn:
X-RateLimit-Limit- Số yêu cầu tối đa trong cửa sổ 60 giây hiện tại.X-RateLimit-Remaining- Số lượt gọi còn lại trước khi bị giới hạn.Retry-After- Số giây cần chờ khi vượt ngưỡng (đi kèm mã trạng thái429 Too Many Requests).
Bảng tổng hợp các Endpoints
Tất cả endpoint đều nằm dưới tiền tố /cms/api/v1/:
| Tài nguyên | Đường dẫn gốc | GET | POST | PUT / PATCH | DELETE |
|---|---|---|---|---|---|
| Posts (Bài viết) | /cms/api/v1/posts |
Danh sách & Chi tiết (/{id}) |
Tạo mới | Cập nhật (/{id}) |
Xóa (/{id}) |
| Pages (Trang tĩnh) | /cms/api/v1/pages |
Danh sách & Chi tiết (/{id}) |
Tạo mới | Cập nhật (/{id}) |
Xóa (/{id}) |
| Categories (Chuyên mục) | /cms/api/v1/categories |
Sơ đồ cây & Chi tiết (/{id}) |
Tạo mới | Cập nhật (/{id}) |
Xóa (/{id}) |
| Tags (Thẻ) | /cms/api/v1/tags |
Danh sách & Chi tiết (/{id}) |
Tạo mới | Cập nhật (/{id}) |
Xóa (/{id}) |
| Media (Phương tiện) | /cms/api/v1/media |
Danh sách phân trang từ DB | Tải ảnh multipart | Không áp dụng | Xóa (/{path} hoặc ?id={id}) |
Chi tiết từng nhóm Endpoint
Bài viết (Posts)
- Lấy danh sách:
GET /cms/api/v1/posts- Tham số lọc:
page(mặc định1),per_page(mặc định10, tối đa100),status(published,draft),category_id,author_id,search,sort_by(mặc địnhcreated_at),sort_order(mặc địnhDESC).
- Tham số lọc:
- Lấy chi tiết:
GET /cms/api/v1/posts/{id}(trả về đầy đủ HTMLcontentvà mảngtags). - Tạo mới:
POST /cms/api/v1/posts(trả về mã201 Created). - Cập nhật:
PUT /cms/api/v1/posts/{id}hoặcPATCH /cms/api/v1/posts/{id}. - Xóa:
DELETE /cms/api/v1/posts/{id}.
{
"title": "Ra mắt Cổng Thông Tin Khách Hàng trên RISE CRM",
"slug": "ra-mat-cong-thong-tin-khach-hang-rise-crm",
"description": "Cách đồng bộ tin tức sản phẩm và tài liệu hướng dẫn ngay trong RISE CRM.",
"content": "<p>Nội dung HTML chi tiết đã được kiểm duyệt an toàn.</p>",
"status": "published",
"visibility": "public",
"feature_image": "polycms/2026/05/17/portal-cover.jpg",
"category_ids": [1, 2],
"tags": ["rise-crm", "phat-hanh"]
}
Trang tĩnh (Pages)
- Lấy danh sách:
GET /cms/api/v1/pages(hỗ trợpage,per_page,status,search). - Lấy chi tiết:
GET /cms/api/v1/pages/{id}(bao gồm đầy đủcontentvàdescription). - Tạo mới:
POST /cms/api/v1/pages(bắt buộc cótitle; tùy chọnslug,content,description,status,template,menu_order). - Cập nhật / Xóa:
PUT /cms/api/v1/pages/{id},PATCH /cms/api/v1/pages/{id},DELETE /cms/api/v1/pages/{id}.
Chuyên mục (Categories)
- Lấy cây chuyên mục:
GET /cms/api/v1/categories(trả về cấu trúc cây lồng nhau qua khóachildren). - Lấy chi tiết:
GET /cms/api/v1/categories/{id}. - CRUD đầy đủ:
POST /cms/api/v1/categories,PUT /cms/api/v1/categories/{id},DELETE /cms/api/v1/categories/{id}(bắt buộcnamekhi tạo; tùy chọnslug,description,parent_id,status).
Thẻ tag (Tags)
- Lấy danh sách:
GET /cms/api/v1/tags(hỗ trợpage,per_page,search, kèm trườngusage_count). - Lấy chi tiết:
GET /cms/api/v1/tags/{id}. - CRUD đầy đủ:
POST /cms/api/v1/tags,PUT /cms/api/v1/tags/{id},DELETE /cms/api/v1/tags/{id}.
Thư viện phương tiện (Media quản lý qua Database)
Duyệt danh sách Media (GET /cms/api/v1/media)
Truy vấn trực tiếp bảng {prefix}blog_media để phân trang tức thời thay vì quét đệ quy thư mục ổ đĩa.
| Tham số | Mô tả | Mặc định |
|---|---|---|
page |
Số trang cần lấy | 1 |
per_page |
Số mục mỗi trang (tối đa 100) |
10 |
search |
Tìm theo filename, alt_text hoặc title |
Không có |
mime |
Lọc theo tiền tố MIME (ví dụ image) |
Không có |
Tải ảnh lên (POST /cms/api/v1/media)
Gửi ảnh bằng multipart/form-data với tên trường file (tối đa 10 MB). Tệp lưu tại files/polycms/ (được khóa quyền thực thi bằng .htaccess, web.config và index.html) đồng thời ghi nhận vào bảng {prefix}blog_media. Khi thành công (201 Created), phản hồi trả về id (dùng làm feature_image_id), url, path, filename, original_name, size, type và thumbnail_url.
curl -X POST \
-H "X-PolyCMS-API-Key: pcms_your_key_here" \
-F "file=@cover-photo.jpg" \
"https://your-rise-site.com/cms/api/v1/media"
Quy trình bảo mật tải ảnh 6 lớp
Mọi tệp gửi lên endpoint media phải vượt qua lần lượt 6 lớp kiểm tra:
- Giới hạn dung lượng và danh sách đuôi tệp nghiêm ngặt: Giới hạn 10 MB và chỉ chấp nhận ảnh hợp lệ (
jpg,jpeg,png,gif,webp). - Chặn null byte và đuôi tệp kép: Từ chối tên tệp chứa ký tự null hoặc đuôi thực thi ẩn như
payload.php.jpg,shell.phtml.png. - Xác thực MIME phía máy chủ (
finfo): Đọc trực tiếp nội dung tệp thay vì tin tưởng headerContent-Typedo client gửi lên. - Kiểm tra chữ ký nhị phân (Magic Bytes): Đối chiếu header nhị phân chuẩn của JPEG (
FF D8 FF), PNG, GIF87a/GIF89a hoặc WebP (RIFF....WEBP). - Tái xử lý điểm ảnh qua PHP GD: Giải mã và mã hóa lại hình ảnh từ dữ liệu pixel thuần nhằm tước sạch siêu dữ liệu EXIF và mã độc giấu trong ảnh.
- Quét mã độc sau GD: Quét tệp đã tái tạo để chặn hoàn toàn các chuỗi nguy hiểm còn sót như
<?php,<scripthoặc__HALT_COMPILER.
Xóa Media (DELETE /cms/api/v1/media/{path} hoặc ?id={id})
Hỗ trợ xóa theo đường dẫn tương đối (/cms/api/v1/media/2026/05/17/photo.jpg), tham số truy vấn (?id=42 hoặc ?path=...) hoặc JSON body ({"path": "..."}). Sau bước kiểm tra realpath() chống duyệt thư mục ngược bên trong files/polycms/, hệ thống thực hiện quy trình dọn dẹp 3 lớp:
- Xóa tệp vật lý: Xóa cả ảnh gốc lẫn ảnh thu nhỏ (thumbnail) trong
files/polycms/. - Xóa bản ghi cơ sở dữ liệu: Loại bỏ dòng theo dõi tương ứng trong
{prefix}blog_media. - Gỡ liên kết dây chuyền (Reference Cascade): Tự động xóa trắng
feature_imagevàfeature_image_idtrên mọi bài viết hoặc trang tĩnh đang tham chiếu ảnh đó để tránh hiển thị ảnh lỗi ngoài frontend.
Kiến trúc cơ sở dữ liệu Media (blog_media)
Toàn bộ tệp phương tiện đều được lập chỉ mục trong bảng {prefix}blog_media (rise_blog_media) với các trường siêu dữ liệu:
filename- Tên tệp đã chuẩn hóa trên máy chủpath- Đường dẫn tương đối trongfiles/polycms/(ví dụ2026/05/17/cover-photo.jpg)url- URL đầy đủ dùng để hiển thị trực tiếpalt_text- Văn bản thay thế phục vụ SEOtitle- Tiêu đề hình ảnhcaption- Chú thích hoặc mô tả ảnhmime_type- Loại MIME đã xác thực (ví dụimage/jpeg)file_size- Dung lượng tính theo bytewidth/height- Kích thước ảnh theo pixel đo bằnggetimagesize()author_id- ID nhân viên RISE CRM đã tải tệp lên
Liên kết ảnh đại diện và Tự động đồng bộ
Bài viết và Trang tĩnh lưu khóa tham chiếu feature_image_id trỏ sang blog_media.id song song với chuỗi đường dẫn feature_image để hiển thị nhanh không cần truy vấn JOIN. Mỗi khi PolyCMS được cài đặt hoặc kích hoạt lại trong RISE CRM, hai tác vụ Blog_media_model::sync_from_filesystem() và sync_feature_image_ids() tự động chạy an toàn (idempotent) để đồng bộ các tệp sẵn có trong files/polycms/ và ghép khớp ảnh đại diện cho bài viết.
Định dạng phản hồi JSON tiêu chuẩn
Mọi phản hồi thành công đều thống nhất cấu trúc kèm các HTTP header bảo mật (X-PolyCMS-API: v1.0, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Cache-Control: no-store, no-cache, must-revalidate):
{
"success": true,
"message": "Posts retrieved",
"data": [
{
"id": 1,
"title": "Chào mừng đến với PolyCMS cho RISE CRM",
"slug": "chao-mung-den-voi-polycms-cho-rise-crm",
"status": "published",
"author": {
"id": 1,
"name": "Alex Morgan"
}
}
],
"meta": {
"total": 1,
"page": 1,
"per_page": 10,
"pages": 1
}
}
Khi phát sinh lỗi, API trả về {"success": false, "message": "..."} kèm mã HTTP chuẩn (400, 401, 403, 404, 405, 413, 429, 500), bao gồm cả bộ xử lý shutdown đảm bảo lỗi nghiêm trọng vẫn xuất ra JSON sạch thay vì trang HTML.
Bảo mật và Cô lập Dữ liệu
Phạm vi dữ liệu nghiêm ngặt: Chỉ thao tác trên bảng CMS
REST API chỉ truy cập các bảng dành riêng cho PolyCMS (blog_posts, blog_post_meta, blog_post_categories, blog_post_tags, blog_pages, blog_page_meta, blog_categories, blog_tags, blog_media). API hoàn toàn không có quyền đọc hay ghi đối với các bảng nghiệp vụ cốt lõi của RISE CRM như khách hàng, hóa đơn, dự án, cơ hội bán hàng, báo giá, phiếu hỗ trợ hay mật khẩu nhân sự. Bảng RISE duy nhất được tham chiếu là bảng users ở chế độ chỉ đọc (chỉ lấy họ tên để hiển thị tác giả bài viết).
Phòng chống SQL Injection và XSS
- Truy vấn bằng Query Builder: Toàn bộ câu lệnh chạy qua Query Builder của CodeIgniter với ràng buộc tham số tự động, ép kiểu
(int)cho mọi ID/phân trang và kiểm tra danh sách cột sắp xếp hợp lệ. - Thư viện HTMLPurifier nội bộ plugin: Mọi trường HTML (
content,description) gửi qua API đều đi quapolycms_purify_content(), sử dụng trực tiếp thư việnvendor/ezyang/htmlpurifierđi kèm plugin thông quapolycms_html_purify()(lưu cache tạiwritable/polycms/htmlpurifier/), kết hợp lọc bỏ thẻ<script>và các thuộc tính sự kiện JavaScript nội dòng (onclick,onerror, v.v.). - Làm sạch văn bản thuần: Các trường văn bản như
title,slug,status,visibility,templateđược xử lý bằngstrip_tags(). - Công tắc tắt khẩn cấp và giới hạn phạm vi quản trị: Tắt công tắc REST API lập tức trả
403 Forbiddencho toàn bộ endpoint. Không một endpoint API nào được phép thay đổi cấu hình hệ thống RISE, phân quyền vai trò, giao diện hay danh sách plugin.
Tài liệu liên quan
- API Explorer - Môi trường thử nghiệm REST API - Kiểm thử trực tiếp toàn bộ endpoint ngay trong thanh bên quản trị RISE CRM.
- Hướng dẫn Thư viện Media - Quản lý ảnh tải lên, thumbnail và siêu dữ liệu bảng
blog_media. - Xây dựng Plugin tùy biến cho PolyCMS - Mở rộng nghiệp vụ CMS kết hợp với các hệ thống gọi REST API.
- Tài liệu tham khảo đầy đủ về Hooks và Filters - Lắng nghe các sự kiện bài viết, trang tĩnh và media.
- Tổng quan kiến trúc PolyCMS - Tìm hiểu 19 bảng cơ sở dữ liệu và lớp định tuyến trên CodeIgniter 4.