Tài liệu API
Mọi thao tác trên web đều gọi được bằng API. Tất cả endpoint dùng chung một địa chỉ gốc và trả về JSON.
Địa chỉ gốc
Mọi endpoint bắt đầu bằng địa chỉ dưới đây. Chỉ nhận HTTPS.
Xác thực
Mỗi port có một key riêng, xem trong trang quản lý. Gửi key qua tham số key trên URL, hoặc qua header nếu bạn muốn giấu key khỏi log.
Ngoài key của từng port, tài khoản của bạn còn cấp được một token dùng chung cho mọi port — xem mục Token tài khoản. Key hợp khi bạn chia lẻ từng port cho từng người; token hợp khi một chương trình của bạn quản cả dàn.
ip2_a1b2c3d4e5f6, ip2a_xxxxxxxxxxxxxxxx và rsl_xxxxxxxxxxxx chỉ để cho thấy hình dạng — thay bằng chuỗi thật của bạn thì mới gọi được, gọi nguyên như trong tài liệu sẽ nhận invalid_key hoặc invalid_token.Cách kết nối proxy
Port hỗ trợ cả HTTP và SOCKS5 trên cùng một cổng. Đăng nhập bằng tài khoản mật khẩu, hoặc thêm IP máy bạn vào danh sách trắng rồi kết nối thẳng không cần mật khẩu.
Địa chỉ kết nối lấy từ trường host của /v1/info, hoặc xem trong trang quản lý. Ví dụ dưới dùng 113.161.94.28 cho dễ hình dung.
Thư viện SDK
Có SDK chính thức cho JavaScript và Python, bọc sẵn mọi endpoint bên dưới, không phụ thuộc thư viện ngoài. Cài một dòng là gọi được.
Bên làm tool nhúng mã giới thiệu công khai để ăn hoa hồng giới thiệu — cách làm có trong README của gói ip2vn. Đừng nhúng key hay token vào tool phát đi. Muốn tự bán proxy cho khách thì xem API đại lý.
Xem trạng thái port
Trả về IP hiện tại, cổng, hạn dùng và tình trạng hẹn giờ. Gọi bao nhiêu lần cũng được.
/v1/infokhông giới hạnline là tên máy đang chạy port của bạn, đúng như tên hiện trong bảng điều khiển: S1, S2… Mỗi máy là một đường truyền Viettel riêng.
Trường trả về
| Trường | Ý nghĩa |
|---|---|
| host | Địa chỉ kết nối tới port. Có thể đổi, nên đọc lại mỗi phiên. |
| ip | IP đang dùng ngay lúc gọi |
| cooldown | Số giây còn phải chờ mới xoay được. Bằng 0 là xoay được ngay. |
| auto.next_in | Còn bao nhiêu giây nữa tới lần tự xoay kế tiếp |
| expire_at | Thời điểm port hết hạn |
| rotations | Tổng số lần đã xoay từ khi thuê |
| migrated_at | Lần gần nhất port được tự chuyển sang máy khác vì sự cố, null là chưa bao giờ. Giá trị đổi nghĩa là host (có thể cả port) đã đổi, tool phải nối lại bằng địa chỉ mới. |
Đổi IP
Xin IP mới từ nhà mạng. Lệnh chờ tới khi port ra IP mới rồi mới trả về — thường 20–45 giây, tối đa 90 giây, nên đặt hạn chờ của tool từ 100 giây. Quá 90 giây mà máy vẫn đang quay lại (tổng đài trả đúng IP cũ) thì lệnh trả về với ip bằng previous_ip; port vẫn quay tiếp, gọi /v1/info sau ít phút để thấy IP mới. Trong lúc đổi, kết nối cũ bị ngắt nên tool cần chờ rồi thử lại.
/v1/rotatecách nhau tối thiểu 180 giâyhost, port và line là địa chỉ kết nối ngay lúc xoay. Tool chỉ gọi xoay mà không gọi /v1/info thì so hai trường này với địa chỉ đang dùng: khác nhau là port đã được chuyển sang máy khác.
429 cooldown kèm số giây còn phải chờ trong retry_after. Lượt xoay trước vẫn đang chạy (máy quay tiếp tới khi ra IP khác, có thể mất vài phút) thì nhận 429 rotate_dang_chay — đợi nó xong rồi gọi lại, đừng gửi chồng.Tham số
| Tên | Bắt buộc | Mô tả |
|---|---|---|
| key | có | Key của port |
| wait | không | Đặt false để trả về ngay, không chờ IP mới. Mặc định là true. |
Hẹn giờ tự xoay
Đặt chu kỳ để port tự đổi IP mà không cần gọi lệnh. Chu kỳ tính bằng giây, thấp nhất là 180.
/v1/autotối thiểu 180 giây| Tên | Bắt buộc | Mô tả |
|---|---|---|
| key | có | Key của port |
| every | có | Chu kỳ tính bằng giây, từ 180 trở lên. Đặt 0 để tắt. |
Lịch sử IP
Danh sách IP mà port đã đi qua, mới nhất trước. Dùng để đối chiếu tránh trùng khi nuôi tài khoản dài hạn.
/v1/historytối đa 500 dòng mỗi lần| Tên | Bắt buộc | Mô tả |
|---|---|---|
| limit | không | Số dòng trả về, mặc định 50, cao nhất 500 |
| since | không | Chỉ lấy từ mốc thời gian này trở đi, dạng ISO 8601 |
Gia hạn
Trừ tiền trong ví để kéo dài hạn dùng của port, days nhận 1, 7 hoặc 30. Hạn mới cộng dồn từ hạn cũ. Nếu ví không đủ, lệnh trả lỗi 402 và không trừ gì cả.
Port ca ngày / ca đêm cũng gia hạn được: gia hạn tính theo ngày và chuyển port sang ca 24 giờ (chuyen_sang_24h: true), không gia hạn lại theo ca. Gia hạn bằng key, bằng token hay bấm trên web đều cùng một giá, cùng một luật, và máy chạy port nhận hạn mới ngay.
Gọi lại an toàn: gửi kèm idempotency_key (chuỗi 8–100 ký tự do bạn đặt, ví dụ mã đơn) — rớt mạng rồi gọi lại với cùng khoá thì chỉ bị trừ tiền một lần, lần sau trả lại đúng kết quả lần trước.
/v1/renewToken tài khoản
Key ở trên chỉ mở đúng một port. Nếu bạn thuê nhiều port và muốn một chương trình quản hết, hãy dùng token cấp ở cấp tài khoản: một chuỗi duy nhất điều khiển mọi port bạn đang thuê, port mua thêm tự nằm trong tầm với mà không phải sửa lại mã nguồn.
Tạo token trong bảng điều khiển, mục API của tôi. Chuỗi thô chỉ hiện đúng lần tạo — máy chủ chỉ lưu bản băm, không đọc lại được từ bất kỳ đường nào.
/v1/api/portsmọi port đang thuêDanh sách rỗng vẫn trả ok: true — chưa thuê port nào là trạng thái hợp lệ, không phải lỗi. Mọi câu trả lời của nhóm này đều bọc trong data.
/v1/api/ports/:id/rotatecách nhau tối thiểu 180 giâyid lấy từ trường id của /v1/api/ports. Trần gọi nhân theo số port bạn thuê: mỗi port thêm 40 lượt ghi và 120 lượt gọi mỗi phút, nên khách trăm port vẫn xoay hàng loạt thoải mái miễn là gọi gộp.
Các endpoint khác
| Endpoint | Việc |
|---|---|
| GET /v1/api/ports/:id | Một port |
| GET /v1/api/ports/:id/credentials | Tài khoản proxy của port: proxy_user và proxy_pass. Lấy một lần lúc dựng kết nối, đừng gọi mỗi vòng lặp |
| PATCH /v1/api/ports/:id/auto-rotate | Hẹn giờ tự xoay: giay từ 180 trở lên, 0 là tắt |
| PATCH /v1/api/ports/:id/kho-ip | Bật tắt kho IP riêng 24 giờ: bat true hoặc false |
| PATCH /v1/api/ports/:id/loc-kho | Lọc hai kho cho lượt xoay: kho1_giay (null tắt · 0 vĩnh viễn · >0 số giây nhìn lại) và kho2 (true/false — hỏi API ngoài chấm IP sạch). Mặc định tắt cả hai. |
| PATCH /v1/api/ports/:id/auto-renew | Bật tắt tự gia hạn: auto_renew và so_ngay |
| POST /v1/api/ports/:id/renew | Gia hạn: so_ngay nhận 1, 7 hoặc 30 — trừ ví chính |
| GET /v1/api/ip-history | Lịch sử IP, lọc một port bằng rental_id |
| GET /v1/api/ports/:id/loc-ten-mien | Tên miền port đang lọc, kèm số IP đang bị tránh |
| POST /v1/api/ports/:id/loc-ten-mien | Thêm một tên miền vào bộ lọc: domain |
| DELETE /v1/api/ports/:id/loc-ten-mien | Bỏ một tên miền khỏi bộ lọc: domain |
| POST /v1/api/ports/:id/diem-an-danh | Chấm điểm ẩn danh phần IP: IP đi ra, đường DNS, nhãn proxy, danh sách đen, ba mốc độ trễ |
| POST /v1/api/ports/diem-an-danh-nhieu | Chấm nhiều cổng trong MỘT lời gọi: rental_ids là mảng id, tối đa 60 |
kho-ip thì lệnh xoay mang theo những IP port đó đã ra trong 24 giờ qua, node gặp lại một trong số đó sẽ quay tiếp thay vì nhận. Tổng đài cấp lại IP cũ là chuyện thường của mạng dân cư, đây là cách quay giùm bạn.x.com cho một port thì mỗi lượt xoay của port đó bỏ qua mọi IP mà bất kỳ port nào trong hệ thống đã dùng để vào x.com trong 24 giờ qua — bên kia nhận ra IP chứ không nhận ra ai đang thuê nó. Quá 24 giờ thì IP được dùng lại bình thường. Mỗi port lọc tối đa 3 tên miền.ping_cong_ms (máy chủ IP2 tới máy chạy port), ping_trong_nuoc_ms (qua cổng tới máy chủ trong nước khác nhà mạng) và ping_quoc_te_ms (qua cổng tới máy chủ thật ở châu Âu hoặc Mỹ, không phải CDN). Số thường thấy trên đường Viettel: 9 · 23 · 250 ms. Có cả trăm port thì gọi diem-an-danh-nhieu, đừng gọi từng cái.Mã lỗi
Lỗi luôn trả về ok: false kèm error dạng chữ và message tiếng Việt để bạn hiện thẳng cho người dùng.
| Mã | error | Nghĩa |
|---|---|---|
| 401 | invalid_key | Key sai hoặc đã bị thay |
| 402 | insufficient_funds | Ví không đủ tiền để gia hạn |
| 403 | ip_not_allowed | IP gọi API không nằm trong danh sách trắng |
| 404 | port_not_found | Port không tồn tại |
| 409 | expired | Port đã hết hạn, cần gia hạn trước |
| 429 | cooldown | Chưa đủ 180 giây kể từ lần xoay trước |
| 400 | invalid_days | Thời hạn chỉ nhận 1, 7 hoặc 30 ngày |
| 400 | invalid_every | Chu kỳ tự xoay phải là 0 hoặc từ 180 giây trở lên |
| 400 | invalid_since | Tham số since phải theo dạng ISO 8601 |
| 400 | too_many_ips | Danh sách trắng tối đa 20 IP |
| 503 | line_down | Máy giữ port mất liên lạc, lệnh xoay không gửi xuống được. Riêng một đường rớt trong khi máy còn sống thì vẫn xoay được — xoay chính là cách đường đó lên lại |
| 400 | invalid_ip | Địa chỉ IP trong danh sách trắng không hợp lệ |
| 400 | ca_ngay_khong_gia_han | Port ca lẻ không bật tự gia hạn được (hết ca là hết) — gia hạn tay một lần là chuyển sang ca 24 giờ, rồi bật |
| 429 | rotate_dang_chay | Cổng đang xoay dở — node quay tiếp tới khi ra IP khác, đừng gửi lệnh thứ hai |
| 400 | ten_mien_khong_hop_le | Gõ dạng x.com, đừng gõ cả đường dẫn |
| 400 | qua_nhieu_ten_mien | Mỗi port lọc tối đa 3 tên miền, bỏ bớt rồi thêm |
| 503 | node_chua_san_sang | Máy chứa port chưa báo địa chỉ về, thử lại sau ít phút |
| 503 | khong_ra_duoc | Port chưa ra được Internet nên chưa chấm điểm ẩn danh được |
Riêng token tài khoản
| Mã | error | Nghĩa |
|---|---|---|
| 401 | invalid_token | Token sai hoặc đã bị thu hồi |
| 403 | account_suspended | Tài khoản đang bị khoá |
| 400 | qua_nhieu_token | Đã đạt trần token đang dùng, thu hồi bớt token cũ |
Mã lỗi riêng của nhóm đại lý (not_reseller, out_of_stock, key_not_found…) nằm ở trang API đại lý.
Ví dụ hoàn chỉnh
Xoay IP rồi chờ tới khi kết nối được, mẫu này xử lý sẵn cả trường hợp gặp cooldown.