Gói

Mọi thứ bạn mua đều trở thành một gói. Gói lưu lượng (family: traffic_gateway) - một dung lượng gigabyte, từ đó tạo ra các kết nối. Gói địa chỉ cố định (family: dedicated) - N địa chỉ trong một thời hạn với một tên đăng nhập và mật khẩu. Các route trên trang này, trừ phần cuối cùng, dùng chung cho cả hai loại.

POST /api/v1/quote

Tính giá. Không trừ tiền. Quyền catalog:read. Nội dung yêu cầu - giống như khi mua.

curl -X POST https://ipv.rent/api/v1/quote \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{
      "product": "ipv4",
      "country": "us",
      "operator": "united-states",
      "period": "month",
      "quantity": 10
    }'

{
  "unit": "1.49",
  "unit_label": "per_ip",
  "quantity": 10,
  "discount": "0.00",
  "discount_percent": "0.00",
  "total": "14.90",
  "currency": "USD"
}

unit_label: per_gb với lưu lượng, per_ip với địa chỉ cố định.
total = unit * quantity - discount; discount - chiết khấu bằng tiền, discount_percent - cùng khoản chiết khấu đó tính bằng phần trăm, cả hai đều là chuỗi.
Số tiền được tính chính xác bằng số tiền sẽ bị trừ khi mua với cùng nội dung yêu cầu.

POST /api/v1/packages

Mua. Quyền packages:write, header Idempotency-Key là bắt buộc. Giao dịch mua hoàn tất ngay trong yêu cầu: phản hồi 201 mang order_id, package_id và status: completed.

Các trường cần thiết phụ thuộc vào sản phẩm:

Trường	Residential	IPv4	Ý nghĩa
`product`	có	có	slug từ danh mục
`volume`	có	không được	số gigabyte nguyên, integer hoặc string
`country`	-	có	mã quốc gia từ tham số
`operator`	-	có	vị trí từ tham số
`period`	-	có	`week`, `2_weeks`, `month`, `2_months`, `3_months` - từ các kỳ hạn của quốc gia
`quantity`	không được	không, 1	số địa chỉ; tất cả sẽ trở thành một gói
`plan`	-	không	gói cước; chỉ cần khi quốc gia có nhiều gói cước
`auto_renew`	-	không, `true`	tự động gia hạn gói
`client_reference`	không	không	nhãn của bạn, tối đa 64 ký tự; không cần duy nhất

Trường không thuộc về sản phẩm và các thiết lập kết nối (count, geo, protocol, ttl_minutes và tương tự) bị từ chối theo tên: 422 unsupported_field với trường field.

curl -X POST https://ipv.rent/api/v1/packages \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  -d '{
      "product": "residential",
      "volume": 25,
      "client_reference": "deal-8891"
    }'

{
  "order_id": 128,
  "package_id": 42,
  "status": "completed",
  "price": "50.00",
  "client_reference": "deal-8891"
}

Với địa chỉ cố định, phản hồi có thêm ba trường:

{
  "order_id": 131,
  "package_id": 57,
  "status": "completed",
  "price": "14.90",
  "client_reference": null,
  "package_ids": [57],
  "requested": 10,
  "fulfilled": 10
}

requested - số địa chỉ đã đặt, fulfilled - số địa chỉ đã cấp. Nếu cấp ít hơn, phần chênh lệch đã được hoàn vào số dư.

Lỗi:

400 - invalid_body (thiếu volume với lưu lượng; thiếu country, period hoặc operator với địa chỉ; nội dung không phải JSON), validation_failed, unknown_product
409 - idempotency_in_progress
422 - invalid_volume, invalid_quantity, country_unavailable, unknown_plan, unknown_operator, unknown_period, out_of_stock, type_unavailable, insufficient_balance, unsupported_field, purchase_refunded (tiền đã được hoàn, hãy thử lại như một lần mua mới), idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed (tiền không bị động đến, thử lại với cùng khóa là an toàn), order_needs_attention (tiền đã bị trừ, đang được xử lý thủ công, không thử lại), operation_indeterminate (thử lại với khóa của một thao tác chưa xác định được kết quả)

GET /api/v1/packages

Các gói của chủ sở hữu khóa, mới nhất ở trên. Quyền packages:read. Tham số: offset, limit (ở đây mặc định là 200), family, product.

Tham số	Ý nghĩa
`family`	`traffic_gateway` hoặc `dedicated`; giá trị không xác định - không lọc
`product`	slug: `residential`, `ipv4`; slug mà bạn không có gói nào sẽ trả về danh sách rỗng

Trường của thẻ	Ý nghĩa
`family`, `product`	loại và sản phẩm của gói
`status`	`provisioning`, `active`; với lưu lượng còn có `exhausted`, với địa chỉ - `expired`, `closed`, `suspended`
`name`	`tag` nếu được đặt, nếu không thì được tạo từ sản phẩm: `residential · 25 GB`, `ipv4 · US · United States · x10`
`traffic`	số dư lưu lượng; với địa chỉ là `null`
`expires_at`	thời điểm hết hạn; với lưu lượng là `null` - lưu lượng không hết hạn
`auto_renew`	với địa chỉ: gói có tự động gia hạn hay không
`endpoint`	với địa chỉ: `country`, `operator`, `addresses_count`; với lưu lượng là `null`

GET /api/v1/packages/{id}

Gói và quyền truy cập vào gói. Quyền packages:read.

Gói lưu lượng:

{
  "id": 42,
  "order_id": 128,
  "product": "residential",
  "family": "traffic_gateway",
  "tag": null,
  "name": "residential · 25 GB",
  "status": "active",
  "traffic": {
    "purchased_gb": "25.000",
    "used_gb": "2.566",
    "left_gb": "22.434",
    "synced_at": "..."
  },
  "expires_at": null,
  "created_at": "...",
  "endpoint": null,
  "credentials": {
    "username": "...",
    "password": "..."
  },
  "connection_options": [
    {
      "mode": "rotating",
      "protocol": "http",
      "host": "residential.ipv.rent",
      "port": 9000
    },
    {
      "mode": "rotating",
      "protocol": "socks5",
      "host": "residential.ipv.rent",
      "port": 11000
    },
    {
      "mode": "sticky",
      "protocol": "http",
      "host": "residential.ipv.rent",
      "port": 10000
    },
    {
      "mode": "sticky",
      "protocol": "socks5",
      "host": "residential.ipv.rent",
      "port": 12000
    }
  ],
  "limits": {
    "lifetime_min_minutes": 3,
    "lifetime_max_minutes": 1440,
    "lifetime_default_minutes": 60,
    "modes": ["rotating", "sticky"],
    "protocols": ["http", "socks5"]
  }
}

credentials, connection_options và limits cùng bằng null cho đến khi gói được cấp. Lấy chuỗi kết nối sẵn dùng từ POST /api/v1/packages/{id}/proxies.

Gói địa chỉ cố định:

{
  "id": 57,
  "order_id": 131,
  "product": "ipv4",
  "family": "dedicated",
  "name": "ipv4 · US · United States · x2",
  "status": "active",
  "traffic": null,
  "expires_at": "2026-11-04T12:00:00+00:00",
  "created_at": "...",
  "auto_renew": true,
  "endpoint": {
    "country": "us",
    "operator": "United States",
    "addresses_count": 2,
    "...": "..."
  },
  "credentials": {
    "username": "...",
    "password": "..."
  },
  "addresses": [
    {
      "host": "198.51.100.11",
      "port_http": 10010,
      "port_socks": 10011
    },
    {
      "host": "198.51.100.12",
      "port_http": 10012,
      "port_socks": 10013
    }
  ],
  "capabilities": ["prolong", "credentials", "replace", "fingerprint", "renewal"],
  "credentials_retired": false,
  "extendable_until": "2026-12-11T12:00:00+00:00",
  "replace_available_at": null,
  "replacement": null,
  "renewal": {
    "enabled": true,
    "period": "month",
    "next_charge_at": "2026-11-03T12:00:00+00:00",
    "next_charge_amount": "2.98",
    "last_failure": null,
    "disabled_at": null
  },
  "fingerprint": {
    "profile": null,
    "profiles": [
      {
        "value": "windows_chrome",
        "label": "Windows 11 · Chrome"
      },
      "..."
    ]
  }
}

Ý nghĩa của từng trường của địa chỉ cố định - trên trang Địa chỉ cố định.

Lỗi: 404 not_found.

POST /api/v1/packages/{id}/password

Cấp lại mật khẩu, cho cả hai loại. Quyền packages:write. Tên đăng nhập không thay đổi.

Mật khẩu cũ ngừng hoạt động ngay lập tức; applies_in_seconds - giới hạn trên của khoảng thời gian để mật khẩu mới bắt đầu được chấp nhận.

Lỗi: 404 not_found; 422 package_unavailable (gói chưa được cấp), package_expired (thời hạn của địa chỉ đã hết - hãy gia hạn trước); 500 package_failed.

Thao tác với gói lưu lượng

Các route dưới đây chỉ dành cho Residential. Trên gói địa chỉ cố định, chúng trả về 422 unsupported_capability.

POST /api/v1/packages/{id}/proxies

Tạo kết nối. Quyền packages:write, không cần idempotency. Nội dung yêu cầu là tùy chọn.

Trường	Kiểu	Mặc định	Ý nghĩa
`count`	integer 1..500	1	số chuỗi cần tạo
`mode`	`rotating` \| `sticky`	`rotating`	chế độ phiên
`protocol`	`http` \| `socks5`	`http`	giao thức
`ttl_minutes`	integer \| null	60	địa chỉ được giữ bao lâu ở chế độ `sticky`, 3..1440
`geo.country`, `geo.state`, `geo.city`, `geo.asn`	string	-	mã từ danh mục địa lý; `state`, `city`, `asn` yêu cầu `country`

curl -X POST https://ipv.rent/api/v1/packages/42/proxies \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{
      "count": 3,
      "mode": "sticky",
      "protocol": "http",
      "ttl_minutes": 30,
      "geo": {
        "country": "us"
      }
    }'

Ở chế độ sticky, mỗi chuỗi trong bộ mang nhãn phiên riêng, tức là cho một địa chỉ đầu ra riêng, và mỗi chuỗi có rotation_url riêng.

Ở chế độ rotating, các chuỗi giống nhau: địa chỉ được chọn ở mỗi lần kết nối, vì vậy N chuỗi cho N đầu ra khác nhau, và không có liên kết đổi IP.

Trường bị bỏ qua nhận giá trị mặc định, không phải giá trị của lần gọi trước. Các chuỗi đã cấp trước đó vẫn tiếp tục hoạt động.

Lỗi:

400 - invalid_body (kiểu hoặc phạm vi của trường)
404 - not_found
422 - invalid_targeting (với field và value: giá trị ngoài danh mục, khóa geo không xác định, thu hẹp mà không có country), package_unavailable (gói chưa được cấp, ttl_minutes nằm ngoài limits, chế độ hoặc giao thức không được hỗ trợ), unsupported_capability

POST /api/v1/packages/{id}/topup

Nạp thêm dung lượng. Quyền packages:write, Idempotency-Key là bắt buộc. Nội dung: {"volume": 10}.

Phản hồi - 202 và thẻ gói: dung lượng mới hiển thị trên thẻ ngay lập tức, lưu lượng theo giới hạn mới bắt đầu đi qua sau khoảng hai phút.

Việc nạp thêm tạo một đơn hàng riêng với applied_to_package_id.

Lỗi:

400 - invalid_body
404 - not_found
409 - idempotency_in_progress
422 - invalid_volume, type_unavailable, insufficient_balance, package_unavailable, unsupported_capability, purchase_refunded, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - package_failed (tiền chưa bị trừ, có thể thử lại), order_needs_attention (đã trừ tiền, không được thử lại), operation_indeterminate (thử lại với khóa của một thao tác chưa xác định được kết quả)

POST /api/v1/packages/{id}/rotation-secret

Cấp lại khóa bí mật của các liên kết đổi IP. Quyền packages:write. Vô hiệu hóa mọi liên kết /r/{token} cùng lúc; không thể thu hồi riêng một liên kết. Phản hồi - toàn bộ gói.

Lỗi: 404 not_found; 422 unsupported_capability.