Bán dịch vụ lưu trữ Zinn® từ WHMCS

Module Zinn Digital® chuyển đổi các nút bấm của WHMCS thành các thao tác thực tế trên nền tảng của chúng tôi. Một đơn hàng sẽ cấp phát dịch vụ lưu trữ cho khách hàng của bạn. Tự động hóa hóa đơn quá hạn của WHMCS sẽ tạm ngưng dịch vụ đó. Việc đánh dấu hóa đơn đã thanh toán sẽ khôi phục dịch vụ. Việc hủy sẽ lên lịch xóa. Và khách hàng của bạn sẽ nhận được nút Đăng nhập vào bảng điều khiển lưu trữ trong khu vực khách hàng để đăng nhập trực tiếp vào hệ thống.

Nó hoàn toàn miễn phí, được cấp phép theo GPL-2.0-or-later và không có đường dẫn đặc quyền nào vào nền tảng của chúng tôi: mọi lệnh gọi mà nó thực hiện đều là một điểm cuối (endpoint) đã được tài liệu hóa mà chính bạn cũng có thể tự thực hiện bằng khóa API của mình.

Trước khi bạn bắt đầu

Bạn cần có hai điều, và điều thứ hai thường làm mọi người bỡ ngỡ.

Tài khoản đại lý Zinn® có chương trình đang hoạt động. Đăng ký tại zinndigital.com và bật tính năng bán lại.
Gói đại lý có dung lượng trang web. Các trang web mà khách hàng của bạn đặt mua sẽ được tính vào gói của bạn, vì vậy bạn cần chọn gói có đủ dung lượng trống.

⚠️ Kiểm tra Kết nối không thể cho bạn biết liệu một đơn hàng có thành công hay không. Nó chỉ đọc chương trình của bạn và không cấp phát bất kỳ thứ gì, do đó nó báo cáo tài khoản active (hoạt động) nhưng chưa thể bán được bất kỳ thứ gì. Nếu đơn hàng đầu tiên của bạn thất bại với thông báo "Tổ chức này không có gói lưu trữ, vì vậy chưa thể lưu trữ trang web", đó chính là nguyên nhân — hãy mua hoặc gia hạn gói đại lý của bạn và đặt hàng lại. Mô-đun hoàn toàn không gặp lỗi gì.

1. Tạo khóa API

Trong bảng điều khiển Zinn® của bạn, hãy mở phần Khóa API và tạo một khóa với chính xác mười một quyền hạn sau:

| Quyền hạn | Lý do cần thiết | | -------------------- | ----------------------------------------------------------- | | org.create | Mở tài khoản Zinn® cho khách hàng vào đơn hàng đầu tiên của họ. | | org.read | Đọc thông tin các tài khoản khách hàng của bạn. | | sites.create | Cấp phát trang web. | | sites.view | Đọc thông tin dịch vụ và mức sử dụng của dịch vụ đó. | | sites.delete | Chấm dứt dịch vụ. | | reseller.view | Liệt kê những gì bạn đã bán, đồng thời đọc dung lượng đĩa và băng thông. | | reseller.provision | Tạm ngưng, khôi phục, đăng nhập hộ khách hàng, thiết lập gói và thay đổi gói dịch vụ của họ. | | billing.view | Đọc chi phí nâng cấp trước khi thực hiện. | | sites.manage | Xóa bộ nhớ đệm và tạo bản sao lưu từ các nút bấm. | | sites.panel_access | Thay đổi mật khẩu quản trị viên WordPress. | | hosting.php.manage | Chuyển đổi phiên bản PHP khi nâng cấp hoặc hạ cấp. |

⛔ Không cấp quyền reseller.manage. Một khóa được dán vào bảng thanh toán chỉ nên có khả năng khóa tài khoản khách hàng do chưa thanh toán và đăng nhập hộ họ. Khóa đó không được phép đọc và ghi đè thông tin xác thực cổng thanh toán của chính bạn. Quyền reseller.provision tồn tại để bạn không phải cấp quyền lớn hơn. ⛔ org.create là bắt buộc không thể thiếu. Nếu không có quyền này, mô-đun có thể đọc tài khoản của bạn nhưng không thể mở tài khoản mới, do đó Kiểm tra Kết nối vẫn thành công nhưng đơn hàng đầu tiên sẽ trả về lỗi 403. ⛔⛔ Hãy cấp toàn bộ các quyền trong bảng, và lưu ý rằng Kiểm tra Kết nối không thể cho bạn biết nếu bạn bỏ sót. Nó chỉ đọc chương trình đại lý của bạn và không cấp phát gì cả, vì vậy nó vẫn hiện màu xanh đối với một khóa bị thiếu bất kỳ quyền nào trong số này. Thay vào đó, bạn sẽ nhận được lỗi 403 tại đúng thao tác mà quyền bị thiếu chi phối, xảy ra từ một khách hàng nhiều tháng sau đó.

2. Cài đặt mô-đun

Tải xuống mô-đun và giải nén nó.
Tải thư mục zinn lên cài đặt WHMCS của bạn để tệp mô-đun nằm tại đường dẫn modules/servers/zinn/zinn.php.

⛔ Thư mục bắt buộc phải có tên là zinn. WHMCS lấy tên hàm của mô-đun cấp phát từ tên thư mục của nó, vì vậy việc đổi tên thành zinn-whmcs hoặc zinndigital sẽ tạo ra một mô-đun mà WHMCS liệt kê, cho phép bạn chọn, nhưng sau đó sẽ không bao giờ gọi đến — mà không hiển thị bất kỳ lỗi nào. Tệp zip đã được giải nén sẵn với đúng tên; bạn chỉ cần không đổi tên nó.

3. Thêm máy chủ

Trong WHMCS: Cấu hình (Configuration) → Cài đặt Hệ thống (System Settings) → Máy chủ (Servers) → Thêm Máy chủ Mới (Add New Server).

Tên: bất kỳ, ví dụ Zinn Digital®
Tên máy chủ: api.zinndigital.com
Loại: Zinn Digital®
Mật khẩu: khóa API của bạn từ bước 1

⛔ Khóa này được nhập vào trường Mật khẩu, nơi WHMCS lưu trữ dưới dạng mã hóa. Không đặt khóa này vào tùy chọn cấu hình sản phẩm — những tùy chọn đó là văn bản thuần túy trong cơ sở dữ liệu và hiển thị cho mọi quản trị viên, trong khi thông tin xác thực này có thể tạo và hủy bỏ không gian lưu trữ của khách hàng bạn.

Nhấn Kiểm tra Kết nối (Test Connection). Thao tác này thực hiện một lệnh gọi thực tế và báo cáo phản hồi từ nền tảng của chúng tôi, thay vì chỉ kiểm tra xem các trường đã được điền hay chưa.

4. Tạo sản phẩm

Cấu hình (Configuration) → Cài đặt Hệ thống (System Settings) → Sản phẩm/Dịch vụ (Products/Services), sau đó đặt Cài đặt Mô-đun (Module Settings) thành máy chủ bạn vừa thêm. Các trường gồm có:

| Trường | Bắt buộc | Nội dung | | ---------------- | -------- | -------------------------------------------------------------------------- | | Dòng sản phẩm | có | Dòng sản phẩm Zinn® mà bạn đang bán — mainstream (WordPress được quản lý), footprint_free, wordpress, linux, cloud, agency, app_hosting, ai_hosting, lms_hosting, managed_database, vector_hosting, zinn_compute, fleet_linux, fleet_enterprise, mail hoặc reseller. | | Ngăn xếp | có | Những gì sẽ được xây dựng: wordpress (mặc định), woocommerce, php, static, node, one_click, headless_cms, nextcloud hoặc owncloud. | | Ứng dụng | không | Chỉ dành cho các ngăn xếp one_click và headless_cms — ứng dụng nào sẽ được cài đặt. Việc chỉ định một ứng dụng trên bất kỳ ngăn xếp nào khác sẽ bị từ chối, vì ngăn xếp đó đã tự quyết định những gì được cài đặt rồi. | | Phiên bản PHP | không | ví dụ: 8.3. Để trống nếu dùng phiên bản mặc định của dòng sản phẩm. Một phiên bản không được cung cấp bởi dòng sản phẩm sẽ bị từ chối kèm theo danh sách các phiên bản được hỗ trợ. | | Mã gói | có | Gói Zinn® mà sản phẩm này bán. GET /v1/reseller/prices liệt kê các gói của bạn. Đơn hàng thiếu mã gói sẽ bị từ chối — xem cảnh báo bên dưới. | | Chu kỳ thanh toán | không | monthly (mặc định) hoặc annual — chu kỳ mà dòng bán sỉ của bạn cho khách hàng này được áp dụng. Khoản tiền bạn thu phí khách hàng của mình được thiết lập trên sản phẩm WHMCS và không bị ảnh hưởng. |

⛔⛔ Mã gói là bắt buộc, và đơn hàng không có mã gói sẽ bị từ chối có chủ đích. Cho đến ngày 2026-09-01, trường này chỉ mang tính trang trí và không có bộ phận nào đọc nó, do đó mô-đun đã đặt dịch vụ lưu trữ hoàn toàn không đi kèm gói nào — và mọi hệ quả của việc đó đều diễn ra âm thầm. Báo cáo bán sỉ của bạn được tổng hợp từ các gói đăng ký đang hoạt động của khách hàng, vì vậy không có dòng nào cho dịch vụ đó và bạn không bị lập hóa đơn đồng nào trong suốt thời gian dịch vụ chạy; khách hàng của bạn không được thừa hưởng hạn mức nào, do đó không có hạn mức đĩa hoặc tệp nào được áp dụng cho trang web của họ; và Tính năng Thay đổi Gói không có gì để thay đổi, do đó việc nâng cấp mà bạn đã bán không thể thực hiện được. Trang web vẫn được cấp phát và hoạt động hoàn hảo trong suốt thời gian đó.

Giờ đây, mô-đun sẽ từ chối đơn hàng thay vì làm vậy, bởi vì không có gói an toàn nào để nó tự đoán: việc phỏng đoán sẽ cấp phát lưu trữ trên một gói mà bạn không chọn và có thể chưa định giá, và — không giống như việc từ chối mà bạn có thể đọc được ngay lập tức — lỗi đó sẽ chỉ nổi lên khi bảng sao kê đến tay, nếu có.

Đặt Tự động Cài đặt (Auto Setup) theo tùy chọn bạn thích — mô-đun này có tính lũy đẳng (idempotent) đối với ID dịch vụ của WHMCS, do đó việc thử cấp phát lại sẽ trả về cùng một trang web thay vì tính phí bạn cho trang web thứ hai.

Mỗi thao tác WHMCS thực hiện những gì

| Thao tác WHMCS | Điều gì xảy ra ở phía chúng tôi | | --------------------------- | ---------------------------------------------------------------------------------------- | | Tạo (Create) | Tạo tài khoản Zinn® cho khách hàng (hoặc sử dụng lại tài khoản họ đã có) và cấp phát trang web của họ. | | Tạm ngưng (Suspend) | Đặt trang web vào trạng thái giữ do chưa thanh toán. Nội dung được giữ lại; không có gì bị xóa. | | Bỏ tạm ngưng (Unsuspend) | Gỡ bỏ trạng thái giữ của bạn. | | Chấm dứt (Terminate) | Lên lịch xóa trang web, có thời gian ân hạn. Ngày tháng hiển thị trong khu vực khách hàng. | | Cập nhật sử dụng | Làm mới dung lượng đĩa và băng thông trên mọi dịch vụ, mỗi ngày một lần. | | Đăng nhập vào bảng điều khiển lưu trữ | Mở một liên kết đăng nhập một lần đi thẳng vào bảng điều khiển của khách hàng bạn. | | Thay đổi Gói (Change Package) | Nâng cấp hoặc hạ cấp dịch vụ. Di chuyển gói dịch vụ và phiên bản PHP nếu sản phẩm mới có chỉ định. | | Thay đổi Mật khẩu (Change Password) | Đặt mật khẩu quản trị viên WordPress. Hộp này không xuất hiện trên các ngăn xếp không có tài khoản như vậy. | | Gia hạn (Renew) | Xác nhận dịch vụ vẫn tồn tại. Lưu trữ Zinn® hoạt động liên tục, vì vậy không có thời hạn từ xa nào cần gia hạn. | | Đồng bộ Sử dụng / Xóa Bộ nhớ đệm / Tạo Bản sao lưu | Các nút trên trang dịch vụ quản trị. Khách hàng của bạn có nút Xóa Bộ nhớ đệm và Tạo Bản sao lưu trong khu vực khách hàng của họ. | | Tab Dịch vụ | Trạng thái, gói, dung lượng đĩa, băng thông, bất kỳ lịch xóa nào, và ai là người đã đặt lệnh tạm ngưng. | | Nhập (Import) | ListAccounts đọc mọi trang, do đó việc nhập sẽ không bị dừng âm thầm ở trang đầu tiên. |

Nâng cấp: ai tính phí ai

Khách hàng của bạn không bao giờ nhận hóa đơn từ Zinn®, cho dù là đơn hàng hay nâng cấp. Bạn tính phí họ thông qua WHMCS; chúng tôi tính phí bạn trên bảng sao kê bán sỉ của bạn. Do đó, tính năng Thay đổi Gói sẽ chuyển quyền lợi của khách hàng và dòng dịch vụ trên bảng sao kê kỳ tới của bạn, và hoàn toàn không chạm vào thẻ tín dụng nào — WHMCS đã thu tiền của khách hàng và tính toán tỷ lệ phân bổ của riêng mình.

Dịch vụ thứ hai của khách hàng. Trên cùng một gói, đó là một trang web khác thuộc hạn mức trang web của chính gói đó và không có thêm quyền lợi nào được cấp. Trên một gói khác, yêu cầu sẽ bị từ chối: việc thay thế gói đang hoạt động sẽ khiến một trong hai dịch vụ không được tính tiền. Hoặc bán cả hai trên cùng một gói, hoặc thiết lập cho khách hàng đó thành một bản ghi khách hàng riêng biệt trong WHMCS.

Thay đổi Mật khẩu chỉ tồn tại cho WordPress. Lưu trữ Zinn® không có "mật khẩu dịch vụ" duy nhất nào — khách hàng của bạn truy cập bảng điều khiển bằng nút đăng nhập — và một trang web php hoặc static không có tài khoản ứng dụng nào để thay đổi. WHMCS ẩn hoàn toàn khung này thay vì hiển thị một khung không thể hoạt động.

Ba câu trả lời bạn không được gộp làm hai

Bỏ tạm ngưng có thể trả về thông báo từ chối. Điều đó có nghĩa là trang web đã bị tạm ngưng bởi đội ngũ xử lý vi phạm của chúng tôi chứ không phải do bạn, và không bảng thanh toán nào được phép giải phóng nó. Thông báo đã nêu rõ điều đó; hãy hiển thị nó cho quản trị viên của bạn thay vì thử lại.
Chấm dứt dịch vụ chỉ lên lịch xóa, chứ không thực hiện xóa ngay. Ngày tháng sẽ được trả về dưới dạng pending_deletion_at và khu vực khách hàng sẽ hiển thị điều đó. Việc nói với khách hàng rằng dữ liệu của họ đã biến mất khi thực tế không phải vậy còn tệ hơn là không nói gì với họ.
Dung lượng đĩa và băng thông có thể không xác định, và không xác định không có nghĩa là không. Khi chúng tôi không thể đọc được số liệu, mô-đun sẽ giữ nguyên con số đó thay vì ghi 0 — nếu không, WHMCS sẽ hiển thị cho khách hàng của bạn một thanh dung lượng trống trông có vẻ an tâm đối với một trang web mà chúng tôi chưa lấy được số liệu nào.

Khắc phục sự cố

Kiểm tra Kết nối thành công nhưng đơn hàng đầu tiên thất bại với lỗi quyền hạn. Khóa API đang bị thiếu quyền org.create. Mô-đun cần phải mở tài khoản của khách hàng trước khi có thể tạo trang web của họ.

Đơn hàng thất bại với thông báo tổ chức không có gói lưu trữ. Gói đại lý của bạn đã hết hạn mức trang web, hoặc bạn chưa sở hữu gói nào. Xem phần Trước khi bạn bắt đầu ở trên.

Đơn hàng thất bại có nhắc đến ngăn xếp. Trường Ngăn xếp trên sản phẩm đang trống hoặc đang đặt tên cho một thứ mà chúng tôi không xây dựng. Hãy đặt nó thành wordpress trừ khi bạn đang bán một thứ gì đó khác.

Lệnh hủy đang bị thất bại. Hãy đảm bảo bạn đang dùng mô-đun phiên bản 1.0.0 trở lên. Các bản dựng trước đó không gửi xác nhận xóa và mọi lệnh chấm dứt đều bị từ chối, khiến cho dịch vụ vẫn tiếp tục chạy và tính phí.

Thông báo từ chối có nêu tên trường. Các lỗi xác thực của chúng tôi sẽ nêu tên trường và lý do nằm trong dấu ngoặc vuông sau thông báo, ví dụ: (php_version: 7.2 không được cung cấp trên dòng sản phẩm này). Đó mới là nửa có thể hành động được — câu văn đứng trước nó được viết chung chung một cách có chủ đích.

Xác minh bản tải xuống

Mọi tệp lưu trữ đều được phục vụ qua giao thức TLS từ tên máy chủ của chính chúng tôi và không bao giờ chuyển hướng đến máy chủ của bên thứ ba. Tổng kiểm tra SHA-256 của nó được in bên cạnh liên kết tải xuống trên trang tải xuống. Hãy so sánh nó sau khi tải xuống:

macOS hoặc Linux: shasum -a 256 zinn-whmcs-1.0.0.zip
Windows: certutil -hashfile zinn-whmcs-1.0.0.zip SHA256

Không dùng WHMCS?

Có sẵn một mô-đun HostBill và một ứng dụng khách PHP đơn tệp dành cho các nền tảng khác, cả hai đều miễn phí và đều có trên cùng một trang tải xuống. Mọi điểm cuối mà các mô-đun sử dụng đều nằm trong tài liệu tham khảo API.