Metadata-Version: 2.4
Name: ip2vn
Version: 1.1.0
Summary: SDK chính thức của IP2.VN — điều khiển proxy xoay IP dân cư Viettel cho bên làm tool tích hợp.
Author: IP2.VN
License: MIT
Project-URL: Homepage, https://ip2.vn
Keywords: ip2,ip2vn,proxy,rotating-proxy,residential-proxy,viettel,sdk
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: Proxy Servers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ip2vn

SDK Python chính thức của [IP2.VN](https://ip2.vn) — điều khiển proxy xoay IP dân
cư Viettel cho bên làm tool tích hợp. Không phụ thuộc thư viện ngoài (chỉ dùng
`urllib` chuẩn), cần Python 3.8+.

```bash
pip install ip2vn
```

## Mô hình giới thiệu (hoa hồng 10%)

Tool của bạn nhúng **mã giới thiệu công khai** của bạn và đưa người dùng đăng ký
qua `IP2.ref_link('MÃ')`. Người dùng tự mua proxy, tự tạo **key theo từng cổng**
rồi dán vào tool; bạn ăn 10% chi tiêu của họ.

> **An toàn:** chỉ nhúng mã giới thiệu (công khai). TUYỆT ĐỐI không nhúng key,
> mật khẩu hay token vào tool phát đi — tool nào cũng bung xem được. Key là của
> chính người dùng cuối, không phải của bạn.

## Dùng

```python
from ip2vn import IP2, IP2Error

# Link đưa cho người dùng để họ gắn với bạn:
print(IP2.ref_link("MÃ_GIỚI_THIỆU_CỦA_BẠN"))   # https://ip2.vn/?ref=...

# Người dùng dán key cổng của họ vào tool của bạn:
cong = IP2("ip2_xxxxxxxxxxxx")

tin = cong.info()        # host, port, ip, cooldown, expire_at, ...
kq  = cong.rotate()      # { ip, previous_ip, took, next_allowed_in }
cong.auto(300)           # hẹn tự xoay mỗi 300s (0 để tắt, thấp nhất 180)
ls  = cong.history(limit=20)
cong.renew(30)           # gia hạn 1/7/30 ngày, trừ ví người dùng

# Chuỗi proxy sẵn dùng (user/pass proxy do người dùng nhập):
px = cong.proxy("u", "p")
print(px["url"])   # http://u:p@host:port
print(px["tho"])   # host:port:u:p

try:
    cong.rotate()
except IP2Error as e:
    print(e.code, e.message, e.retry_after)
```

## Khoá theo mã giới thiệu (tuỳ chọn)

Muốn tool **chỉ chạy cho khách đã đăng ký qua bạn**? Truyền `ref` là mã giới thiệu
của bạn — SDK hỏi máy chủ xem chủ key có phải khách của bạn không, không phải thì
mọi lệnh ném `IP2Error` code `sai_ref`:

```python
cong = IP2(key_nguoi_dung, ref="MÃ_GIỚI_THIỆU_CỦA_BẠN")
cong.rotate()   # chỉ chạy nếu key thuộc khách bạn giới thiệu
```

Không truyền `ref` thì không khoá gì. Lưu ý: đây là **khoá mềm** — phép kiểm đúng
ở máy chủ, nhưng quyết định khoá nằm trong SDK nên người bẻ khoá tool vẫn qua
được, và chỉ chặn lệnh đi qua SDK, không chặn ai cắm thẳng `host:port:user:pass`.

## Phương thức

| Gọi | Trả về |
|---|---|
| `info()` | host, port, line, ip, protocol, auto, cooldown, expire_at, rotations |
| `rotate(wait=True)` | ip, previous_ip, took, next_allowed_in |
| `auto(giây)` | auto, every, next_at |
| `history(limit, since)` | total, items[{ip, at}] |
| `renew(1\|7\|30)` | days_added, charged, wallet_balance, expire_at |
| `proxy(username, password, protocol)` | host, port, url, tho |
| `IP2.ref_link(mã)` | `https://ip2.vn/?ref=mã` |

Lỗi ném ra `IP2Error` với `.code` (máy đọc), `.message` (tiếng Việt), `.status`
(HTTP), `.retry_after` (giây, khi dính `cooldown`).

Cổng nghe cả HTTP lẫn SOCKS5 trên cùng một port — chọn giao thức chỉ đổi cách
viết chuỗi, không đổi port.

MIT © IP2.VN
