EnglishTiếng Việt
Đăng nhập Cài miễn phí

Nhà phát triển

Tự động hoá ZoPanel: API cấp phát với token và idempotency key, webhook có chữ ký và hook script, module billing, CLI và llms.txt.

Cập nhật 07/10/2026

ZoPanel được thiết kế để phần mềm khác điều khiển. Hệ thống billing tạo và tạm khoá tài khoản qua API cấp phát, công cụ của bạn phản ứng với sự kiện qua webhook có chữ ký, còn quản trị viên viết script cho server bằng dòng lệnh. Trang này là điểm khởi đầu; chi tiết nằm trong tài liệu.

API cấp phát (Provisioning API)

API cấp phát (/api/v1) tạo và quản lý tài khoản hosting trên server ZoPanel. Đây cũng chính là API mà các module WHMCS, Blesta, HostBill và Paymenter sử dụng, nên mọi thứ các module làm được thì CMS hay mã billing của bạn cũng làm được.

  • Tài khoản được xác định bằng username, gói bằng tên gói. Phía bạn không cần lưu bất kỳ ID nào của ZoPanel.
  • Vòng đời: tạo (có thể kèm website đầu tiên, được cấp SSL nếu tên miền đã trỏ về server), tạm khoá, mở khoá, đổi gói, đặt mật khẩu, huỷ.
  • Gói: liệt kê các gói bạn được bán, hoặc đẩy gói của riêng bạn bằng PUT /api/v1/packages/{name}.
  • Đăng nhập một chạm: POST /api/v1/accounts/{username}/login trả về một liên kết dùng một lần trong 60 giây, cho nút "Đăng nhập control panel" ở khu vực khách hàng.
  • Tài nguyên: dung lượng đĩa và băng thông trong tháng của mọi tài khoản bạn quản lý.
T="Authorization: Bearer zpat_xxx"; P=https://panel.example.com:8888/api/v1

# Đẩy một gói
curl -X PUT -H "$T" \
  -d '{"max_sites":3,"disk_mb":10240,"memory_mb":1024,"cpu_percent":100,"sftp":true}' \
  $P/packages/Starter

# Bán gói: tạo tài khoản và website đầu tiên
curl -X POST -H "$T" -H "Idempotency-Key: order-1042-create" \
  -d '{"username":"shop1","password":"S3cure-Pass-1","email":"owner@shop1.example","package":"Starter","domain":"shop1.example"}' \
  $P/accounts

# Hoá đơn quá hạn, rồi đã thanh toán
curl -X POST -H "$T" $P/accounts/shop1/suspend
curl -X POST -H "$T" $P/accounts/shop1/unsuspend

Lỗi được trả về dạng JSON ({"error": "…"}) kèm mã trạng thái rõ nghĩa: 400 dữ liệu không hợp lệ, 402 đạt giới hạn license, 403 token không được phép, 404 không có tài khoản, 429 quá nhiều yêu cầu.

Tài liệu đầy đủ: Provisioning API.

Xác thực bằng API token

  1. Trong ZoPanel, mở Tài khoản của tôi → API tokens.
  2. Tạo token với quyền Provisioning only và giới hạn theo địa chỉ IP của server billing.
  3. Gửi token kèm mọi yêu cầu: Authorization: Bearer zpat_….

Phạm vi của token phụ thuộc vào chủ sở hữu. Token của quản trị viên bán các gói của quản trị viên và thấy mọi tài khoản hosting; token của đại lý chỉ bán gói của đại lý đó, chỉ thấy khách của họ và luôn nằm trong giới hạn gói của chính đại lý. Token cấp phát không truy cập được phần nào khác của panel: không có cài đặt server, không có file, không có terminal. Token bị thu hồi khi chủ sở hữu đổi mật khẩu hoặc 2FA, và việc tạo token đòi hỏi mật khẩu của chủ sở hữu.

API token cần license trả phí.

Idempotency key và giới hạn tần suất

Mạng có lúc lỗi, và hệ thống billing sẽ thử lại. Hãy gửi header Idempotency-Key duy nhất với mọi yêu cầu POST, PUT và DELETE (ví dụ whmcs-create-<service id>):

  • gửi lại yêu cầu với cùng key trong vòng 24 giờ sẽ nhận lại câu trả lời đầu tiên, kèm header Idempotent-Replayed: true, thay vì thực hiện lại thao tác, nên việc thử lại sau timeout không bao giờ tạo tài khoản hai lần;
  • khi yêu cầu đầu tiên vẫn đang chạy, yêu cầu lặp lại nhận mã 409;
  • lỗi server (5xx) không được lưu lại, nên các yêu cầu đó có thể thử lại bình thường.

Mỗi token được gửi 1.200 yêu cầu mỗi phút. Vượt mức này, câu trả lời là 429 kèm Retry-After: 60.

Webhook và event hook

ZoPanel phát sự kiện khi có thay đổi trên server:

account.created, account.deleted, account.suspended, account.unsuspended, site.created, site.deleted, ssl.issued, database.created, database.deleted, mail.domain_created, mail.mailbox_created, backup.completed.

Webhook. Quản trị viên thêm URL webhook trên trang Hooks, mỗi URL có secret riêng và danh sách sự kiện tuỳ chọn. ZoPanel gửi một yêu cầu POST dạng JSON:

{"event": "account.created", "time": 1759795200, "server": "web1.example.com", "data": { … }}

kèm các header:

Header Nội dung
X-ZoPanel-Event Tên sự kiện
X-ZoPanel-Delivery ID duy nhất của lần gửi này
X-ZoPanel-Signature sha256= theo sau là HMAC-SHA256 dạng hex của nguyên văn body, khoá bằng secret của webhook

Hãy kiểm tra chữ ký trên nguyên văn body trước khi tin dữ liệu, và so sánh theo thời gian hằng định. Lần gửi thất bại được thử lại hai lần (sau 5 và 30 giây). Trang Hooks hiển thị các lần gửi gần đây và có thể gửi sự kiện thử. Dữ liệu sự kiện không bao giờ chứa thông tin bí mật.

Hook script. Để tự động hoá ngay trên server, các file thực thi trong /etc/zopanel/hooks/<event>.d/ chạy sau mỗi sự kiện, nhận JSON của sự kiện qua đầu vào chuẩn. Chỉ root mới cài được script qua SSH, không bao giờ qua panel: script chỉ chạy khi cả script và thư mục chứa nó thuộc sở hữu root và group hay người khác không ghi được.

Module billing

Các module có sẵn hỗ trợ tạo tài khoản (dùng tên miền của đơn hàng làm website đầu tiên), tạm khoá và mở khoá, huỷ, đổi gói và đăng nhập một chạm; với hệ thống billing hỗ trợ, module còn báo cáo tài nguyên và đổi mật khẩu.

Hệ thống Gói cài đặt
WHMCS 8.x / 9.x zopanel-whmcs-module.zip: xem module WHMCS
Blesta 5.x zopanel-blesta-module.zip
HostBill zopanel-hostbill-module.zip
Paymenter 1.x zopanel-paymenter-extension.zip

Mỗi gói có README hướng dẫn cài đặt. Đại lý có thể kết nối hệ thống billing riêng bằng token từ tài khoản đại lý. Xem Tích hợp.

Dòng lệnh

Quản trị viên quản lý server bằng zopanel ctl qua SSH: info (phiên bản, server ID, gói license), reset-password, disable-2fa, allow-ip --clear khi bị danh sách IP chặn ngoài, rebuild để tạo lại cấu hình web server và PHP từ database của panel, doctor để kiểm tra sức khoẻ, support-bundle, và dr-restore để khôi phục thảm hoạ. zopanel update và zopanel rollback cài và hoàn tác bản cập nhật. Tài liệu: Dòng lệnh.

llms.txt cho trợ lý AI

Nếu bạn dùng trợ lý AI hoặc coding agent với ZoPanel, hãy trỏ nó tới:

  • /llms.txt: mục lục tài liệu kèm tóm tắt một dòng;
  • /llms-full.txt: toàn bộ tài liệu trong một file Markdown.

Cả hai theo quy ước llms.txt và được sinh từ chính các trang tài liệu bạn đang đọc, nên luôn cập nhật.

Đặc tả OpenAPI

Bản mô tả OpenAPI 3.0 của API cấp phát v1 (provisioning-openapi.yaml) được duy trì cùng API, bao gồm các endpoint, trường của gói, mã lỗi và cách xác thực nêu trên. Bạn có thể dùng nó để sinh client hoặc nhập API vào công cụ của mình. Các endpoint nội bộ khác mà giao diện panel sử dụng không phải API công khai và có thể thay đổi giữa các phiên bản; hãy xây dựng tích hợp trên /api/v1, webhook và hook script.

Cần hỗ trợ?

Câu hỏi về tích hợp, hoặc tính năng mà quy trình tự động của bạn cần: gửi ticket với danh mục Technical trên trang hỗ trợ.