API Đối tác

API giữa máy chủ với máy chủ dành cho đối tác: phát hành khóa, đọc cấu hình gian hàng và vị trí, tạo khách hàng, cấp gói và quản lý liên kết đăng ký từ trang web hoặc bot Telegram của riêng bạn.

API Đối tác cho phép bạn xây dựng trang web riêng, bảng điều khiển riêng hoặc bot Telegram trên nền CreateYourVPN.

API bao gồm khách hàng, đăng ký, gói và cấu hình gian hàng. Hạ tầng như máy chủ, node, bảng điều khiển và thông tin đăng nhập SSH nằm ngoài hợp đồng công khai.

Chỉ dùng giữa máy chủ với máy chủ. Hãy lưu khóa API trên máy chủ của bạn và đừng đưa nó vào mã frontend. Các yêu cầu có header của trình duyệt bị từ chối với 403 browser_forbidden.

Lấy khóa

Mở bảng điều khiển → Menu tài khoản → «API», tab «Khóa».

Đặt tên cho khóa (bot Telegram, trang landing) và chỉ chọn những quyền mà nó cần.

Chọn «Phát hành khóa» và sao chép toàn bộ giá trị. Phần bí mật chỉ hiện một lần, vì hệ thống chỉ lưu giá trị hash của nó.

Mỗi đối tác có thể có tối đa 5 khóa đang hoạt động. Để xoay vòng khóa, hãy phát hành khóa mới, cập nhật tích hợp rồi thu hồi khóa cũ.

Xác thực

Gửi khóa dưới dạng bearer token:

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

X-API-Key: cyv_live_… cũng hoạt động, dành cho trường hợp Authorization đã bị proxy chiếm dụng.

Khóa có dạng cyv_live_<key_id>_<secret>. Nửa đầu (key_id) là công khai: đó là phần bạn thấy trong bảng điều khiển và có thể yên tâm báo cho bộ phận hỗ trợ. Nửa sau là phần bí mật.

Quyền (scopes)

Quyền	Cho phép gì
`config:read`	Đọc cấu hình gian hàng, các gói, vị trí và `/me`.
`users:read`	Đọc khách hàng, đăng ký và lưu lượng của họ.
`users:write`	Tạo khách hàng, cấp gói, đặt lại liên kết đăng ký, xóa khách hàng.

config:read là đủ cho các tích hợp chỉ đọc dữ liệu gian hàng. Chỉ thêm users:read hoặc users:write khi tích hợp cần các thao tác tương ứng với khách hàng.

Hợp đồng đầy đủ, chạy được nằm trong bộ sưu tập Postman công khai. Bộ sưu tập chứa mọi endpoint, quyền, tham số, body yêu cầu, ví dụ phản hồi và mã lỗi ổn định. Bộ sưu tập được tạo từ hợp đồng backend và là nguồn hiện hành cho schema của yêu cầu và phản hồi.

Mở bộ sưu tập Postman công khai

Khám phá mọi endpoint và sao chép bộ sưu tập vào workspace của bạn.

Giới hạn tần suất

Giới hạn được tính riêng cho từng khóa, không phụ thuộc vào địa chỉ IP của yêu cầu.

Tổng cộng 120 yêu cầu/phút cho mỗi khóa.
Riêng GET /users là 10 yêu cầu/phút.

GET /users có giới hạn riêng vì mỗi yêu cầu tải toàn bộ danh sách khách hàng. Với các lần tra cứu thường xuyên, hãy dùng GET /users/{id} hoặc tìm theo externalId.

Cách truy cập nên dùng. Lưu ID khách hàng CreateYourVPN được trả về khi tạo và dùng GET /users/{id} cho các lần tra cứu sau. Bạn có thể liên kết ID này với mã định danh của riêng bạn qua externalId.

Tính idempotent

Ba thao tác yêu cầu header Idempotency-Key: cấp gói, đặt lại liên kết đăng ký và xóa khách hàng.

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

Lặp lại một yêu cầu với cùng khóa trong vòng 24 giờ sẽ trả về phản hồi đã lưu thay vì chạy lại thao tác. Điều này ngăn các thay đổi trùng lặp khi tích hợp thử lại sau khi hết thời gian chờ.

Hãy tạo một khóa cho mỗi sự kiện nghiệp vụ (ví dụ một khoản thanh toán hoặc một hành động) và dùng lại nó cho mọi lần thử lại của sự kiện đó.

Nếu lần thử đầu tiên vẫn đang chạy hoặc kết quả của nó tạm thời chưa rõ, API trả về 409 conflict mà không thực hiện lại thao tác. Hãy kiểm tra trạng thái hiện tại của khách hàng trước khi quyết định thử lại.

Hãy dùng bộ sưu tập Postman công khai ở trên làm nguồn chuẩn cho schema của yêu cầu và phản hồi.