API Litport
API Litport cho phép một hệ thống tích hợp truy cập token, gói và dữ liệu trả theo GB (PPG) của chính bạn. Nó có thể tạo, thay đổi và xóa proxy trả theo GB, mỗi proxy có giới hạn lưu lượng và ngày hết hạn riêng, đồng thời cấp lại thông tin đăng nhập của bất kỳ proxy nào bạn sở hữu. Nó đọc mức sử dụng của nhiều proxy cùng lúc, và đổi vị trí token, xoay, IP mới, cũng như IP được phép của gói. Dùng nó để bán lại proxy hoặc cấp proxy riêng cho từng thành viên nhóm hoặc công cụ: tạo một proxy trả theo GB cho mỗi khách hàng, đặt giới hạn lưu lượng và đọc mức sử dụng của nhiều proxy cùng lúc.
URL gốc:
https://litport.net/api/v1
Hồ sơ VPN được tạo trong bảng điều khiển; API chưa thể tạo hay thay đổi chúng. Xem Truy cập VPN.
Các nhóm#
| Nhóm | Tiền tố | Trang tài liệu |
|---|---|---|
| Token | /tokens |
API token |
| Mức sử dụng | /usage |
Mức sử dụng của nhiều token |
| Gói | /packages |
API gói |
| Trả theo GB | /pay-per-gb |
API Trả theo GB |
Xác thực#
Tạo API key tại Cài đặt. Giá trị đầy đủ của key vẫn xem được ở đó sau khi tạo hoặc đổi.
export LITPORT_API_KEY='lit_replace_with_your_key'
curl 'https://litport.net/api/v1/tokens' \
-H "Authorization: Bearer $LITPORT_API_KEY"
Client bên ngoài dùng đúng lược đồ Bearer. Không gửi key trong chuỗi truy vấn, nội dung JSON, cookie hoặc tên người dùng proxy. Lưu key như một bí mật, chỉ cho phép các tác vụ phía máy chủ truy cập, và đổi key nếu có thể đã bị lộ.
Các nút Chạy trên những trang tài liệu này dùng tài khoản Litport đang đăng nhập của bạn và chỉ cho yêu cầu GET. Mọi thao tác ghi đều cần API key Bearer.
Ranh giới thông tin đăng nhập#
| Thông tin đăng nhập | Mục đích |
|---|---|
| Tên người dùng/mật khẩu của token proxy | Mở các kết nối dữ liệu qua proxy. |
| ID token proxy / ID gói | Chọn một token hoặc gói trong lệnh gọi API; không phải bí mật. |
API key người dùng (lit_…) |
Xác thực các yêu cầu điều khiển tài khoản. |
Quy tắc chung của API#
Mọi endpoint ở mọi nhóm đều theo cùng các quy tắc, nên một hệ thống tích hợp chỉ cần học một lần.
Định danh. Dùng tokenId và packageId là số công khai. Chọn pool trả theo GB bằng authKey của nó và một IP được phép bằng chính IP đó. Không endpoint nào nhận hoặc trả về ID cơ sở dữ liệu.
Đặt tên. Các trường dùng camelCase. Các giá trị liệt kê và slug mới là kebab-case chữ thường, ví dụ awaiting-payment, more-allowed-ips, package-inactive. Mã lỗi giữ dạng UPPER_SNAKE. Văn bản tự do (nhãn, thông tin đăng nhập, tên pool) không bị hạn chế. Một vài giá trị giữ cách viết hiện có thay vì đổi tên cho khớp: trafficBasis: "customer_chargeable" và timezone: "UTC" trong mức sử dụng, cùng các giá trị type/status của token.
Giá trị. Thời gian theo ISO-8601 UTC, kết thúc bằng Z. Số byte lớn là chuỗi thập phân, không phải số JSON, để client không bao giờ mất độ chính xác.
Dạng phản hồi. Một đối tượng đơn là {"data": {...}}. Endpoint trả về danh sách luôn trả lời {"data": [...], "page": {"nextCursor": ...}}. Có hai loại danh sách:
- danh sách phân trang (
GET /tokens,GET /usage,GET /packages,GET /pay-per-gb/geo) nhậnlimitvàcursor; - danh sách đầy đủ (
GET /pay-per-gb/pools,GET /tokens/{tokenId}/location/options) luôn trả về mọi mục, không nhậnlimithaycursor, và báopage.nextCursor: null.
Một mảng nằm trong đối tượng, chẳng hạn buckets của mức sử dụng, ips của IP được phép, hay tokenIds của một gói, là trường thông thường, không phải danh sách của endpoint. GET /usage là danh sách phân trang có data là một đối tượng: range, và các proxy trong data.tokens.
Phân trang. limit từ 1–100, mặc định 50. cursor là page.nextCursor của phản hồi trước, gửi lại nguyên vẹn; hãy coi nó là giá trị opaque, không phân tích hay sửa. limit sai là 400 INVALID_LIMIT; cursor sai hoặc của người khác là 400 INVALID_CURSOR. Tiếp tục yêu cầu page.nextCursor cho đến khi nó là null.
Lỗi. Mọi lỗi có dạng {"error": {"code", "message", "requestId", "docsUrl", "retryable"}}, kèm nextChangeAt khi cần chờ. retryable cho biết cùng yêu cầu đó, khi gửi lại, có thể thành công và gửi lại có an toàn hay không. Xem Lỗi API để có bảng trạng thái đầy đủ và một mục chi tiết cho mỗi mã.
Thao tác ghi. Mọi thao tác ghi đều cần API key Bearer; phiên tài liệu đã đăng nhập chỉ có thể đọc. Gửi nội dung JSON khi endpoint có nội dung đó. Không có header điều kiện tiên quyết: thao tác ghi đã xác nhận gần nhất được áp dụng. Mọi thao tác ghi đều an toàn để lặp lại, trừ POST /tokens/{tokenId}/new-ip trên token tĩnh (với token xoay, lặp lại chỉ cho một IP khác), POST /tokens không có externalRef (lặp lại có thể tạo proxy thứ hai), POST /tokens/{tokenId}/credentials không có requestId (lặp lại cấp thêm một cặp khác), và PUT /tokens/{tokenId}/location với {"random": true} (lặp lại có thể chuyển proxy lần nữa). Hãy gửi externalRef với mỗi lần tạo và requestId với mỗi lần cấp lại mà bạn có thể cần thử lại; xem Tạo và quản lý proxy.
Giới hạn tần suất#
Có ba giới hạn, đều báo qua các header chuẩn.
- 120 yêu cầu mỗi 60 giây, theo từng API key, tính chung đọc và ghi. Vượt quá là
429 RATE_LIMITED. - 10 lần đọc danh sách mức sử dụng (
GET /usage) mỗi 60 giây, theo từng API key. Giới hạn của key được kiểm tra trước; yêu cầu vượt qua giới hạn đó và là lần đọc danh sách mức sử dụng sẽ kiểm tra tiếp giới hạn này và báo header của bộ giới hạn này. - 20 lần ghi IP được phép mỗi 60 giây, theo từng gói (
PUT/DELETE /packages/{packageId}/allowed-ips…). Giới hạn của key được kiểm tra trước; yêu cầu vượt qua giới hạn đó và cũng là lần ghi IP được phép sẽ kiểm tra tiếp giới hạn của gói và báo header của bộ giới hạn này.
Đọc RateLimit-Limit, RateLimit-Remaining và RateLimit-Reset trên mọi phản hồi; yêu cầu bị từ chối còn có thêm Retry-After.
Quy ước#
- Phản hồi là JSON.
X-Request-IDđịnh danh yêu cầu; hãy kèm nó khi báo lỗi.- Phản hồi đã xác thực có
Cache-Control: private, no-storevàVary: Authorization. - API này không có ETag và không có điều kiện tiên quyết
If-Matchở bất kỳ đâu.
Hợp đồng cho máy đọc#
Dùng tài liệu OpenAPI 3.1 cho mọi đường dẫn, tham số, nội dung yêu cầu và lược đồ phản hồi. Hãy xử lý lớp bọc lỗi trước khi dùng dữ liệu của từng endpoint.