Trang Tích hợp API dành cho bạn khi muốn kết nối website hoặc phần mềm của mình với hệ thống của chúng tôi, để tự động mua, gia hạn và quản lý VPS / Proxy - ví dụ khi bạn bán lại dịch vụ cho khách hàng của mình. Tại đây bạn gửi hồ sơ đăng ký sử dụng API, theo dõi trạng thái duyệt, và sau khi được duyệt thì lấy API key, địa chỉ API, tài liệu kỹ thuật.
Không thấy mục Tích hợp API trong menu? Nghĩa là chức năng API chưa được mở cho website này. Hãy liên hệ với chúng tôi qua mục Hỗ trợ nếu bạn có nhu cầu.
1. API dùng để làm gì?
API là "cổng kết nối" giữa máy chủ của bạn và hệ thống của chúng tôi. Thay vì vào website bấm mua từng dịch vụ, phần mềm của bạn gửi yêu cầu qua API và nhận kết quả ngay. Một số việc bạn có thể tự động hóa:
- Xem danh sách sản phẩm, giá; tạo đơn mua VPS / Proxy.
- Xem danh sách dịch vụ, gia hạn, nâng cấp, bật / tắt tự gia hạn.
- Xem số dư và nạp tiền vào Ví API - ví riêng dùng để thanh toán các đơn qua API (xem bài Ví API).
- Nhận thông báo tự động (webhook) khi đơn đã thanh toán, dịch vụ đã kích hoạt, sắp hết hạn, số dư ví thấp…
Quy trình gồm 3 bước: gửi hồ sơ đăng ký → chờ chúng tôi duyệt → tạo API key và bắt đầu kết nối.
2. Gửi hồ sơ đăng ký sử dụng API
Lần đầu vào trang, bạn sẽ thấy form đăng ký. Các ô có dấu * là bắt buộc.
- 1Nhập Tên thương hiệu (tên cửa hàng / dịch vụ của bạn) và Tên miền trang bán hàng (ví dụ shop.example.com).
- 2Mô tả ngắn Mục đích sử dụng API - bạn định dùng API để làm gì.
- 3Ở ô Danh sách IP, gõ địa chỉ IP của máy chủ sẽ gọi API rồi bấm Thêm (hoặc nhấn Enter). Có thể nhập một IP (
203.0.113.10) hoặc một dải IP (203.0.113.0/24). Tối đa 5 địa chỉ, không nhận IP nội bộ. - 4Webhook URL (không bắt buộc): địa chỉ trên máy chủ của bạn để nhận thông báo tự động. Phải bắt đầu bằng
https://và là tên miền công khai. Có thể bỏ trống và khai báo sau. - 5Kiểm tra phần Người liên hệ kỹ thuật, Email, Điện thoại - đã điền sẵn theo tài khoản của bạn, sửa lại nếu người phụ trách kỹ thuật là người khác. Đây là người chúng tôi liên hệ khi có vấn đề kỹ thuật, ví dụ email báo khi webhook gửi tới máy chủ của bạn thất bại nhiều lần.
- 6Tích ô Tôi đã đọc và đồng ý Điều khoản sử dụng API (xem ), rồi bấm Gửi yêu cầu đăng ký.
Lưu ý về danh sách IP: chỉ những máy chủ có IP nằm trong danh sách mới gọi được API. Nếu bạn gõ IP vào ô nhưng chưa bấm Thêm, hệ thống sẽ tự thêm khi gửi. Nếu IP sai định dạng, màn hình báo lỗi ngay và không cho thêm.
3. Điều khoản sử dụng API
Bấm vào chữ Điều khoản sử dụng API để đọc nội dung. Bấm Tôi đồng ý trong cửa sổ này thì ô đồng ý trên form được tích sẵn.
Tóm tắt những điều bạn cam kết:
- Giữ bí mật API key / secret, không chia sẻ cho người khác.
- Chỉ gọi API từ các IP đã khai báo.
- Chịu trách nhiệm về mọi giao dịch thực hiện bằng API key của mình.
- Tuân thủ giới hạn tần suất gọi API.
- Chúng tôi có quyền tạm khóa hoặc thu hồi quyền dùng API nếu phát hiện vi phạm.
Mỗi lần gửi (kể cả gửi lại sau khi bị từ chối) bạn đều phải tích đồng ý lại.
4. Theo dõi trạng thái duyệt
Sau khi gửi, trang Tích hợp API hiển thị theo trạng thái hồ sơ của bạn:
| Trạng thái | Ý nghĩa và việc bạn cần làm |
|---|---|
| Đang chờ duyệt | Hồ sơ đã gửi, chúng tôi đang xem xét. Bạn chỉ cần chờ - không gửi thêm được hồ sơ khác trong lúc này. |
| Bị từ chối | Trang hiện khung đỏ "Yêu cầu trước đã bị từ chối" kèm lý do. Form bên dưới đã điền sẵn thông tin cũ - bạn sửa theo lý do rồi gửi lại. |
| Đang hoạt động | Đã được duyệt. Trang chuyển sang màn hình Thông tin API (xem ), menu trái có thêm mục Ví API. |
| Tạm khóa | Mọi yêu cầu API tạm thời bị từ chối. Bạn vẫn xem được thông tin, key và hướng dẫn nhưng không tạo key mới, không sửa IP / webhook, không nạp thêm Ví API. API key và số dư ví được giữ nguyên - khi được mở lại, bạn dùng tiếp ngay. |
| Đã thu hồi | Toàn bộ API key bị hủy vĩnh viễn, số dư Ví API vẫn được giữ. Bạn không tự gửi lại đăng ký được - hãy liên hệ với chúng tôi nếu muốn mở lại. |
5. Màn hình Thông tin API sau khi được duyệt
Khi hồ sơ đã được duyệt, trang chia làm 2 cột: bên trái là Thông tin API (thông tin kết nối và API key), bên phải là các tab Hướng dẫn tích hợp API, Nhật ký gọi API, Webhook. Góc trên bên phải có nút Môi trường thử nghiệm.
Các khối thông tin ở cột trái
| Khối | Ý nghĩa |
|---|---|
| Thương hiệu | Tên thương hiệu và trang bán hàng bạn đã khai báo. |
| Địa chỉ API (Base URL) | Địa chỉ gốc mà phần mềm của bạn gọi tới. Bấm để sao chép. Mọi yêu cầu phải gửi đúng địa chỉ này - gọi qua địa chỉ khác sẽ bị từ chối. Nếu khối này báo chưa có địa chỉ API, hãy liên hệ với chúng tôi. |
| Tải tài liệu API đầy đủ (PDF) | Tải về bộ tài liệu kỹ thuật dạng PDF, trong đó các đường dẫn ví dụ đã điền sẵn đúng Địa chỉ API của bạn - gửi cho lập trình viên của bạn là dùng được ngay. |
| Loại dịch vụ được bán | Các loại dịch vụ bạn được phép mua qua API (ví dụ VPS Việt Nam, VPS GPU, Proxy Việt Nam). Mua loại không có trong danh sách sẽ bị từ chối. Danh sách này do chúng tôi thiết lập khi duyệt hồ sơ. |
| Danh sách IP được phép gọi | Các IP máy chủ được gọi API, kèm số lượng đang dùng / tối đa 5. Bấm Sửa để thêm, bớt IP (xem ). |
| Webhook URL | Địa chỉ nhận thông báo tự động, hoặc Chưa cấu hình. Khi đã có webhook, bên dưới hiện tình trạng Webhook secret (mã dùng để kiểm tra thông báo đúng là do hệ thống gửi). |
| API key | Danh sách khóa truy cập API đang dùng, kèm số lượng / tối đa 2 (xem ). |
Các tab ở cột phải
- Hướng dẫn tích hợp API - tài liệu kỹ thuật ngay trên trang: các bước bắt đầu, cách ký yêu cầu, danh mục API, mã lỗi… Nút Tải tài liệu đầy đủ (PDF) ở đầu tab tải cùng bộ tài liệu PDF như ở cột trái.
- Nhật ký gọi API - lịch sử các yêu cầu API của bạn (xem ).
- Webhook - 50 thông báo tự động gần nhất và tình trạng gửi tới máy chủ của bạn, kèm hướng dẫn kiểm tra chữ ký.
6. Tạo và quản lý API key
API key giống như "tên đăng nhập + mật khẩu" dành cho phần mềm. Mỗi key gồm 2 phần: Key ID (bắt đầu bằng ak_) và Secret. Key tạo ở trang này là key thật - đơn tạo bằng key này trừ tiền Ví API và tạo dịch vụ thật. Muốn thử trước, hãy dùng key thử nghiệm ở bài Môi trường thử nghiệm.
- 1Trong khối API key, bấm Tạo key.
- 2Đặt Tên gợi nhớ để phân biệt (ví dụ Website bán hàng chính) rồi bấm Tạo key.
- 3Cửa sổ "API key đã được tạo" hiện Key ID và Secret. Bấm để sao chép từng phần và lưu vào nơi an toàn.
- 4Tích ô xác nhận đã lưu, rồi bấm Xác nhận và đóng. Cửa sổ này không đóng được cho tới khi bạn tích xác nhận.
Secret chỉ hiển thị đúng 1 lần. Sau khi đóng cửa sổ, trang chỉ còn hiện 4 ký tự cuối của Secret. Nếu làm mất, bạn phải thu hồi key đó và tạo key mới.
Mỗi key trong danh sách hiện tên, Key ID (có nút sao chép), 4 ký tự cuối của Secret, ngày tạo và lần dùng gần nhất. Lưu ý thêm:
- Tối đa 2 key đang dùng cùng lúc - đủ để bạn đổi key mới mà không làm gián đoạn: tạo key mới, cập nhật vào phần mềm, rồi thu hồi key cũ.
- Bấm Thu hồi ở dòng key để hủy key đó. Mọi yêu cầu dùng key này bị từ chối ngay lập tức.
- Key đã thu hồi được ẩn đi; bấm Xem … key đã thu hồi ở cuối khối để xem lại (phục vụ tra cứu nhật ký).
Thu hồi key không hoàn tác được. Hãy chắc chắn phần mềm của bạn đã chuyển sang key khác trước khi thu hồi.
Trong khối API key thấy dòng "Vui lòng đọc và đồng ý Điều khoản sử dụng API trước khi tạo key"? Trường hợp này xảy ra khi API được mở sẵn cho tài khoản của bạn mà bạn chưa đồng ý điều khoản. Bấm Xem & đồng ý Điều khoản, đọc rồi bấm Tôi đồng ý - nút Tạo key sẽ hiện ra.
7. Sửa danh sách IP và Webhook
Sửa danh sách IP
- 1Ở khối Danh sách IP được phép gọi, bấm Sửa.
- 2Gõ IP mới rồi bấm Thêm; bấm dấu × trên IP muốn bỏ. Phải còn ít nhất 1 IP, tối đa 5.
- 3Bấm Lưu.
Thay đổi có hiệu lực ngay: yêu cầu từ IP không còn trong danh sách sẽ bị từ chối. Hãy thêm IP máy chủ mới trước khi chuyển phần mềm sang máy chủ đó. Bạn sẽ nhận thông báo về mỗi lần thay đổi.
Cấu hình Webhook
- Bấm Sửa ở khối Webhook URL, nhập địa chỉ (bắt buộc
https://) rồi bấm Lưu. Để trống rồi lưu nghĩa là tắt webhook. - Lần đầu bật webhook, hệ thống tạo webhook secret và hiện đúng 1 lần - sao chép, lưu lại, tích xác nhận rồi bấm Xác nhận và đóng.
- Bấm Tạo lại secret nếu nghi secret bị lộ. Secret cũ ngừng hiệu lực ngay, nên bạn phải cập nhật secret mới vào máy chủ nhận webhook.
- Muốn kiểm tra máy chủ đã nhận được thông báo chưa, dùng nút Gửi thử ở trang Môi trường thử nghiệm.
8. Xem nhật ký gọi API
Tab Nhật ký gọi API ghi lại từng yêu cầu phần mềm của bạn gửi tới bằng key thật - rất hữu ích khi cần tìm nguyên nhân lỗi.
| Cột | Ý nghĩa |
|---|---|
| Thời gian | Lúc hệ thống nhận yêu cầu. |
| Yêu cầu | Thao tác bằng tiếng Việt (ví dụ Tạo đơn hàng, Gia hạn dịch vụ) và đường dẫn API đã gọi. |
| Kết quả | Huy hiệu xanh = thành công; huy hiệu đỏ = lỗi, kèm mã lỗi và giải thích (ví dụ INSUFFICIENT_BALANCE - Số dư Ví API không đủ; IP_NOT_ALLOWED - IP không nằm trong danh sách IP). |
| Đơn hàng | Mã đơn được tạo bởi yêu cầu đó (nếu có). Bấm vào để mở chi tiết đơn. |
| IP / API key | IP đã gửi yêu cầu và tên gợi nhớ của key đã dùng. |
| Xử lý | Thời gian hệ thống xử lý yêu cầu (mili giây). |
- Bấm Thành công / Lỗi để lọc nhanh; Tất cả để bỏ lọc. Nút tải lại danh sách.
- Ô tìm kiếm nhận IP, mã lỗi hoặc mã đơn.
- Số dòng mỗi trang: 30, 50, 100, 200 hoặc 500.
- Nhật ký chỉ lưu thông tin yêu cầu (không lưu nội dung gửi lên, secret hay chữ ký) và được giữ 90 ngày.
9. Câu hỏi thường gặp
Đã gửi đăng ký nhưng chưa thấy mục Ví API trong menu?
Ví API chỉ được tạo khi hồ sơ của bạn được duyệt. Trong lúc trang còn hiện Đang chờ duyệt, bạn chỉ cần chờ; sau khi được duyệt, tải lại trang là thấy mục Ví API.
Phần mềm gọi API bị báo lỗi IP_NOT_ALLOWED?
IP của máy chủ đang gọi không nằm trong danh sách. Xem đúng IP ở cột IP / API key trong tab Nhật ký gọi API, rồi thêm IP đó qua nút Sửa ở khối Danh sách IP được phép gọi.
Tôi lỡ làm mất Secret của API key?
Secret không xem lại được. Hãy tạo một key mới (bạn được dùng tối đa 2 key cùng lúc), cập nhật key mới vào phần mềm, sau đó Thu hồi key cũ.
Muốn mua thêm loại dịch vụ chưa có trong "Loại dịch vụ được bán"?
Danh sách này do chúng tôi thiết lập khi duyệt hồ sơ. Hãy liên hệ với chúng tôi qua mục Hỗ trợ và cho biết loại dịch vụ bạn cần.