Back to Main Site

Hướng dẫn toàn diện về REST API PolyCMS cho RISE CRM

Last updated on Nov 22, 2026 7:38 AM 7:38 AM 2,025.77 ms

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

  1. Mở PolyCMS > Settings > REST API (#tab-api) trong quản trị RISE CRM.
  2. Bật công tắc Enable REST API.
  3. 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.
  4. Đ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ế.
  5. 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ẫu cms/api/v1.*+ qua bộ lọc app_filter_app_csrf_exclude_uris của RISE CRM. Nhờ đó các ứng dụng ngoài gọi POST, PUT, PATCH, DELETE bằng X-PolyCMS-API-Key khô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 Unauthorized hoặc 403 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 định 60 yêu cầu mỗi phút.
  • Thao tác ghi (POST, PUT, PATCH, DELETE): Mặc định 30 yê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ái 429 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 định 1), per_page (mặc định 10, tối đa 100), status (published, draft), category_id, author_id, search, sort_by (mặc định created_at), sort_order (mặc định DESC).
  • Lấy chi tiết: GET /cms/api/v1/posts/{id} (trả về đầy đủ HTML content và mảng tags).
  • 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ặc PATCH /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 đủ content và description).
  • Tạo mới: POST /cms/api/v1/pages (bắt buộc có title; tùy chọn slug, 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óa children).
  • 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ộc name khi tạo; tùy chọn slug, 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ường usage_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:

  1. 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).
  2. 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.
  3. 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 header Content-Type do client gửi lên.
  4. 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).
  5. 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.
  6. 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ư &lt;?php, &lt;script hoặ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:

  1. Xóa tệp vật lý: Xóa cả ảnh gốc lẫn ảnh thu nhỏ (thumbnail) trong files/polycms/.
  2. 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.
  3. Gỡ liên kết dây chuyền (Reference Cascade): Tự động xóa trắng feature_image và feature_image_id trê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 trong files/polycms/ (ví dụ 2026/05/17/cover-photo.jpg)
  • url - URL đầy đủ dùng để hiển thị trực tiếp
  • alt_text - Văn bản thay thế phục vụ SEO
  • title - Tiêu đề hình ảnh
  • caption - Chú thích hoặc mô tả ảnh
  • mime_type - Loại MIME đã xác thực (ví dụ image/jpeg)
  • file_size - Dung lượng tính theo byte
  • width / height - Kích thước ảnh theo pixel đo bằng getimagesize()
  • 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 qua polycms_purify_content(), sử dụng trực tiếp thư viện vendor/ezyang/htmlpurifier đi kèm plugin thông qua polycms_html_purify() (lưu cache tại writable/polycms/htmlpurifier/), kết hợp lọc bỏ thẻ &lt;script&gt; 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ằng strip_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 Forbidden cho 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