API gói
Đọc các gói proxy không giới hạn của bạn và quản lý IP được phép của từng gói. Thao tác ghi cần API key dạng Bearer; phiên tài liệu đã đăng nhập chỉ đọc được, không ghi được. Mỗi thao tác ghi là một lệnh gọi: không có header điều kiện tiên quyết, và lần ghi thành công gần nhất sẽ được áp dụng.
Liệt kê và đọc#
GET /api/v1/packages
GET /api/v1/packages/{packageId}
Authorization: Bearer lit_...
| Tham số | Quy tắc |
|---|---|
limit |
Số nguyên từ 1 đến 100; mặc định là 50. |
cursor |
page của trang trước, gửi lại nguyên vẹn. |
{
"data": {
"id": 45,
"status": "active",
"product": { "key": "dc-shared-rotating", "name": "DC Shared Rotating" },
"country": "us",
"quantity": 2,
"addOns": ["high-speed"],
"limits": { "speedMbps": 20, "connections": 300, "requestsPerSec": 25 },
"renewsAt": "2027-01-01T00:00:00.000Z",
"endsAt": null,
"tokenIds": [12345, 12346]
}
}
packageId không tồn tại, không thuộc tài khoản của bạn hoặc không phân tích được sẽ trả về 404 PACKAGE_NOT_FOUND.
Trạng thái#
status |
Ý nghĩa | Ngày |
|---|---|---|
awaiting-payment |
Đã đặt hàng, chưa thanh toán. | Cả hai là null. |
setting-up |
Đã thanh toán; một Thiết bị riêng đang được gán thủ công. Gói chuyển sang active khi sẵn sàng. |
Cả hai là null. |
active |
Đang thanh toán, kể cả khi kỳ hiện tại đã được lên lịch kết thúc. | renewsAt là lần gia hạn tiếp theo, hoặc endsAt là lúc gói dừng nếu không gia hạn. |
suspended |
Thanh toán thất bại hoặc gói bị tạm dừng. | endsAt khi đã biết, nếu không thì null. |
ended |
Không còn hoạt động. | endsAt là lúc gói kết thúc. |
setup-failed |
Việc cấp phát chưa hoàn tất. | Cả hai là null. |
product.key là khóa của dòng sản phẩm trong danh mục và product.name là tên hiển thị của nó. addOns liệt kê tên công khai của các tiện ích bổ sung: high-speed, more-allowed-ips, multi-location. limits là mức trần hiệu lực cho mỗi token về tốc độ, số kết nối và tần suất yêu cầu theo cấu hình của gói này, hoặc null khi không xác định được. tokenIds liệt kê các token hiện tại của gói; đọc từng token bằng API token.
IP được phép#
Danh sách IP được phép của một gói cho phép gói nhận các kết nối không cần mật khẩu từ các địa chỉ nguồn IPv4 công khai chính xác. Danh sách áp dụng cho mọi endpoint proxy đã sẵn sàng trong gói; mỗi token đó cũng báo endpoint không cần mật khẩu của riêng mình là ipAuth (xem API token). Thông tin đăng nhập vẫn dùng được dù danh sách có trống hay không. IPv6 không được hỗ trợ; hãy liên hệ hỗ trợ.
GET /api/v1/packages/{packageId}/allowed-ips
Authorization: Bearer lit_...
{
"data": {
"packageId": 45,
"limit": 50,
"ips": ["8.8.8.8", "9.9.9.9"],
"available": true,
"unavailableCode": null
}
}
limit là 1 với gói không có tiện ích bổ sung, hoặc 50 với more-allowed-ips. available: false nghĩa là bản thân tính năng IP được phép hiện không khả dụng; khi đó unavailableCode cho biết lý do.
Thay đổi danh sách#
Đặt toàn bộ danh sách cùng một lúc:
PUT /api/v1/packages/{packageId}/allowed-ips
Authorization: Bearer lit_...
Content-Type: application/json
{"ips": ["8.8.8.8", "9.9.9.9"]}
Được tất cả hoặc không gì cả: một IP không hợp lệ sẽ khiến cả yêu cầu bị từ chối với 400 INVALID_IP nêu rõ IP đó, và danh sách vượt quá limit trả về 409 ALLOWED_IPS_LIMIT_REACHED. Gửi {"ips": []} để xóa danh sách.
Thêm hoặc gỡ một IP riêng lẻ, không cần đọc danh sách trước:
PUT /api/v1/packages/{packageId}/allowed-ips/{ip}
DELETE /api/v1/packages/{packageId}/allowed-ips/{ip}
Authorization: Bearer lit_...
Cả hai đều không có nội dung yêu cầu. Thêm một IP đã có trong danh sách, hoặc gỡ một IP đã không còn, là thao tác thành công và không thay đổi gì. Thao tác gỡ chỉ đánh dấu dòng là đã thu hồi, nên lịch sử kiểm toán vẫn được giữ; IP đó không xuất hiện lại trong ips.
Mọi thao tác ghi IP được phép đều trả về cùng cấu trúc {data: ...} như trên.
An toàn và giới hạn#
Thêm một IP sẽ cấp quyền truy cập không cần mật khẩu từ nguồn đó tới mọi endpoint đã sẵn sàng trong gói; gỡ một IP sẽ thu hồi quyền truy cập. IP được phép thuộc về cả gói, không thuộc về một proxy riêng lẻ, nên để chia sẻ một gói cho nhiều khách hàng, hãy cấp cho mỗi người một proxy riêng và chỉ dùng mật khẩu. Khi đó, cấp lại thông tin đăng nhập của một proxy sẽ ngắt quyền truy cập của khách hàng đó; nhưng không thể đóng một kết nối đã vào qua IP được phép. Thao tác ghi vào một gói bị giới hạn ở 20 lần trong 60 giây, ngoài giới hạn theo từng key; xem giới hạn tần suất.
Lỗi IP được phép#
| Trạng thái | Mã | Ý nghĩa |
|---|---|---|
400 |
INVALID_IP |
Địa chỉ không phải là một IPv4 công khai chính xác. Thông báo nêu rõ địa chỉ đó. |
400 |
IPV6 |
Đã gửi một địa chỉ IPv6. Hãy liên hệ hỗ trợ. |
400 |
INVALID |
Nội dung yêu cầu đặt danh sách không đúng dạng {"ips": [...]}. |
404 |
PACKAGE |
packageId không tồn tại, không thuộc tài khoản của bạn hoặc sai định dạng. |
409 |
ALLOWED |
Danh sách sẽ vượt quá limit. Hãy liên hệ hỗ trợ để tăng giới hạn. |
409 |
PACKAGE |
Gói không hoạt động. Gỡ IP vẫn dùng được. |
409 |
CONCURRENT |
Một thao tác ghi khác vào gói này đến cùng lúc. Hãy thử lại đúng yêu cầu đó. |
429 |
RATE_LIMITED |
Vượt giới hạn theo key hoặc theo gói. Chờ theo Retry-After. |
503 |
ALLOWED |
Kho lưu trữ IP được phép hoặc việc cấp phát cổng tạm thời không khả dụng. Thử lại sau thời gian trong Retry-After. |
Mọi mã được mô tả tại Lỗi API; các schema nằm trong hợp đồng OpenAPI.
Proxy Đa vị trí#
Thành phố và nhà mạng đích của một proxy “Đa vị trí” là cài đặt ở cấp token, không phải cấp gói: đọc và thay đổi chúng bằng API token: Vị trí.