Bán dịch vụ lưu trữ Zinn® từ các hệ thống của riêng quý vị

Quý vị bán lại dịch vụ lưu trữ (hosting) của chúng tôi. Khách hàng của quý vị là của riêng quý vị: giá của quý vị, hóa đơn của quý vị, cổng thanh toán của quý vị. Đây là cách quý vị điều khiển nền tảng của chúng tôi từ bất kỳ hệ thống nào quý vị đang vận hành — bảng điều khiển thanh toán, trang web WordPress của riêng quý vị, hoặc một tập lệnh (script).

Những gì khách hàng của quý vị thực sự nhìn thấy

Trước khi đi vào cơ chế kỹ thuật: khách hàng của quý vị không bao giờ nhìn thấy chúng tôi. Có ba giao diện tiếp xúc, và quý vị chọn giao diện mình muốn sử dụng.

⛔ Dù quý vị chọn cách nào, quý vị là đơn vị bán hàng chính thức (merchant of record) đối với khách hàng của mình: giá của quý vị, hóa đơn của quý vị, mã số thuế VAT của quý vị, nhà cung cấp dịch vụ thanh toán của quý vị. Chúng tôi xuất hóa đơn cho quý vị, mỗi tháng một lần, theo giá bán buôn.

Sau khi đã thiết lập hostname cho bảng điều khiển, hãy nhập thông tin đó vào trường Panel address của plugin WordPress và không điền vào đâu khác — các liên kết đăng nhập do API này tạo ra sẽ tự động sử dụng địa chỉ đó.

Bốn phương thức tiếp cận

Có bốn phương thức tiếp cận, và tất cả đều thực hiện cùng một chức năng ở phía dưới:

1. Lấy khóa API

Trong trang tổng quan của quý vị, hãy chuyển đến Khóa API và tạo một khóa mới. Chỉ cấp đúng các quyền cần thiết:

⛔ Không cấp quyền reseller.manage cho một bản tích hợp. Quyền hạn này cho phép chỉnh sửa bảng giá và thông tin xác thực cổng thanh toán của riêng quý vị. Quyền reseller.provision được tạo ra chính là để khóa mà quý vị dán vào bảng điều khiển thanh toán hoặc trang web không cần đến quyền quản lý đó.

Khóa chỉ hiển thị một lần duy nhất. Hãy lưu trữ khóa ở nơi quý vị lưu các thông tin xác thực khác — tuyệt đối không lưu trong tệp mà máy chủ web của quý vị có thể phân phát công khai.

2. Thực hiện lệnh gọi đầu tiên

curl https://api.zinndigital.com/v1/reseller/services \
  -H "Authorization: Bearer zdk_live_…"

Lệnh đó sẽ trả về mọi dịch vụ quý vị đã khởi tạo, mỗi trang web một hàng, cùng với thông tin khách hàng sở hữu, trạng thái, và mức giá quý vị tính cho dịch vụ đó. Trên một tài khoản mới, kết quả trả về là một danh sách trống — đây là phản hồi chính xác, không phải lỗi.

3. Toàn bộ quy trình tích hợp, trong sáu lệnh gọi

KHI                      LỆNH GỌI
đơn hàng được thanh toán POST   /v1/orgs                                   một lần cho mỗi KHÁCH HÀNG
                         POST   /v1/sites                                  một lần cho mỗi DỊCH VỤ
họ chưa thanh toán       POST   /v1/reseller/services/{siteId}/suspend
họ thanh toán            POST   /v1/reseller/services/{siteId}/unsuspend
họ hủy dịch vụ           DELETE /v1/sites/{siteId}
"đăng nhập vào hosting"  POST   /v1/reseller/services/{siteId}/sso

Việc khởi tạo bao gồm hai lệnh gọi, và các khóa định danh rất quan trọng:

# 1. tài khoản của khách hàng — định danh theo mã khách hàng của QUÝ VỊ
curl -X POST https://api.zinndigital.com/v1/orgs \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-4211" \
  -d '{"type":"customer","name":"Acme Ltd"}'

# 2. trang web của họ — định danh theo mã dịch vụ của QUÝ VỊ
curl -X POST https://api.zinndigital.com/v1/sites \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: service-9915" \
  -d '{"org_id":"<from step 1>","product_line":"mainstream","primary_domain":"acme.com"}'

Hai quy tắc khiến quý vị mất tiền nếu làm sai

1. Định danh tài khoản theo KHÁCH HÀNG và định danh trang web theo DỊCH VỤ của quý vị. Đơn hàng thứ hai của khách hàng phải được đưa vào đúng tài khoản mà họ đã có. Nếu định danh cả hai theo dịch vụ, một khách hàng sẽ có ba tài khoản không liên quan và ba bảng điều khiển riêng biệt.
2. Gửi Idempotency-Key trên mỗi lệnh POST, được tạo từ mã định danh riêng của quý vị cho đối tượng đó. Mọi hệ thống thanh toán đều có cơ chế thử lại — lệnh gọi lại từ cổng thanh toán gửi đến hai lần, quản trị viên chạy lại một tác vụ khởi tạo thất bại, khách hàng nhấp đúp chuột. Nếu không có khóa này, lần thử thứ hai sẽ tạo ra trang web thứ hai và quý vị sẽ bị tính phí cho trang web đó.

Ba phản hồi quý vị không được gộp chung thành hai

• unsuspend có thể trả về 409. Điều đó có nghĩa là đội ngũ chống lạm dụng của chúng tôi đang tạm giữ trang web, không phải do quý vị. Hãy hiển thị thông báo; không thử lại.
• **Hủy dịch vụ là lên lịch xóa, không phải xóa ngay lập tức.** Ngày xóa được trả về dưới dạng pending_deletion_at. Việc thông báo với khách hàng rằng dữ liệu của họ đã bị xóa trong khi thực tế chưa xóa còn tệ hơn là không thông báo gì.
• disk_used_bytes có thể là null, và null không phải là số không. Giá trị này có nghĩa là chúng tôi không thể đo lường, không phải là chưa sử dụng dung lượng nào. Hãy bỏ qua — không ghi 0 vào hồ sơ của quý vị, nếu không quý vị sẽ hiển thị thanh dung lượng màu xanh lá cây cho khách hàng đối với một trang web mà quý vị không có số liệu đo lường.

4. Đăng nhập cho khách hàng

POST /v1/reseller/services/{siteId}/sso trả về một URL sử dụng một lần để đưa khách hàng của quý vị vào thẳng tài khoản của họ ở trạng thái đã đăng nhập sẵn.

⛔ Hãy tạo liên kết khi họ nhấp vào, tuyệt đối không tạo khi quý vị kết xuất (render) trang. Liên kết này chỉ sử dụng một lần và hết hạn trong vòng vài phút, vì vậy liên kết được ghi tĩnh vào trang sẽ bị vô hiệu hóa ngay lần xem trang đầu tiên và bị lưu lại trong mọi bộ nhớ đệm giữa quý vị và trình duyệt.

5. Cài đặt module thay thế

• WHMCS — sao chép module vào modules/servers/zinn/, thêm máy chủ với Password là khóa API của quý vị, và thiết lập dòng sản phẩm trên sản phẩm. Nhấn Test Connection: hệ thống sẽ thực hiện một lệnh gọi thực tế và thông báo cho quý vị phản hồi từ nền tảng.
• HostBill — sao chép vào includes/modules/Hosting/zinn/ và kết nối theo cách tương tự.
• WordPress — bộ công cụ Zinn® Reseller Toolkit: tìm kiếm tên miền, liên kết đăng nhập vào gói hosting của khách hàng, và tự động khởi tạo dịch vụ trên WooCommerce khi đơn hàng được thanh toán. Mã nguồn mở tại <https://github.com/Zinn-Digital/zinn-reseller-toolkit>, hoặc tải xuống từ mục Plugins trong trang tổng quan của quý vị.

6. Đi vào hoạt động chính thức

Hãy kiểm tra các mục này trước khi quý vị tiếp nhận đơn hàng thực tế:

• Kiểm tra kết nối thành công trên module, hoặc lệnh curl đầu tiên của quý vị trả về một danh sách.
• Bảng giá của quý vị đã được thiết lập (Đại lý → Giá của quý vị).
• Cổng thanh toán của quý vị đã được kết nối (Đại lý → Cổng thanh toán) — khách hàng thanh toán cho quý vị thông qua tài khoản của chính quý vị.
• Thông tin công ty của quý vị đã được điền (Đại lý → Công ty của quý vị) để hóa đơn của khách hàng hiển thị pháp nhân và mã số thuế VAT của quý vị, không phải của chúng tôi.
• Quý vị đã đặt thử nghiệm hoàn chỉnh một đơn hàng thực tế từ đầu đến cuối và thấy trang web xuất hiện.

Các tài liệu khác

Tài liệu tham khảo API đầy đủ — mọi điểm cuối (endpoint), được tạo tự động từ đặc tả kỹ thuật của chúng tôi, kèm theo các quyền cần thiết cho từng điểm cuối — có tại <https://zinndigital.com/developers/api>.