Địa chỉ cố định

Các thao tác với gói địa chỉ cố định (family: dedicated, sản phẩm ipv4). Mỗi thao tác áp dụng cho toàn bộ gói: cho mọi địa chỉ của gói cùng lúc. Trên gói lưu lượng, các route này trả về 422 unsupported_capability.

Các thao tác khả dụng cho gói được liệt kê trong capabilities của thẻ gói: prolong, credentials, replace, fingerprint, renewal.

Thời hạn và trạng thái

Trạng thái	Điều gì đang xảy ra	Có thể làm gì
`provisioning`	gói đang được cấp, tối đa 2 phút	chờ
`active`	địa chỉ hoạt động đến `expires_at`	mọi thao tác
`expired`	đã hết hạn, địa chỉ không phản hồi	gia hạn trước `extendable_until` - các địa chỉ cũ sẽ quay lại
`closed`	đã qua `extendable_until`, địa chỉ đã được giải phóng	chỉ có thể mua mới
`suspended`	gói đã bị vô hiệu hóa	liên hệ bộ phận hỗ trợ

Các trường của thẻ liên quan đến thời hạn:

Trường	Ý nghĩa
`expires_at`	thời điểm kết thúc thời hạn đã thanh toán
`extendable_until`	đến thời điểm nào việc gia hạn còn trả lại các địa chỉ cũ
`credentials_retired`	`true` - mật khẩu đã bị vô hiệu hóa sau khi hết hạn; gia hạn sẽ cấp mật khẩu mới

Khi hết hạn, package.expired được ghi vào nhật ký sự kiện.

GET /api/v1/packages/{id}/prolong-options

Có thể gia hạn theo những kỳ hạn nào và chi phí bao nhiêu đối với bạn. Quyền packages:read.

{
  "options": [
    {
      "period": "week",
      "price": "1.98"
    },
    {
      "period": "2_weeks",
      "price": "2.58"
    },
    {
      "period": "month",
      "price": "2.98"
    },
    {
      "period": "2_months",
      "price": "5.96"
    },
    {
      "period": "3_months",
      "price": "8.94"
    }
  ],
  "currency": "USD"
}

price - giá cho toàn bộ gói, cho mọi địa chỉ của gói.

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

Gia hạn gói. Quyền packages:write, Idempotency-Key là bắt buộc: đây là thao tác trừ tiền. Nội dung: {"period": "month"}, kỳ hạn - từ prolong-options.

curl -X POST https://ipv.rent/api/v1/packages/57/prolong \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"period":"month"}'

{
  "order_id": 140,
  "package_id": 57,
  "status": "completed",
  "price": "2.98",
  "expires_at": "2026-12-04T12:00:00+00:00",
  "credentials_reissued": false
}

Kỳ hạn được cộng vào expires_at hiện tại, còn nếu đã hết hạn - vào thời điểm gia hạn.
Địa chỉ và tên đăng nhập giữ nguyên.
credentials_reissued: true - mật khẩu cũ đã bị vô hiệu hóa và mật khẩu mới đã được cấp; hãy lấy nó từ thẻ gói.
Việc gia hạn tạo một đơn hàng riêng với applied_to_package_id.

Lỗi:

400 - invalid_body (không có nội dung hoặc không phải JSON), validation_failed
404 - not_found
409 - idempotency_in_progress
422 - unknown_period, insufficient_balance, prolong_window_closed (không thể lấy lại địa chỉ nữa - gói ở trạng thái closed, cần mua mới), unsupported_capability, purchase_refunded, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed, order_needs_attention, operation_indeterminate - như khi mua

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

Tự động gia hạn. Quyền packages:write. Không trừ tiền.

curl -X POST https://ipv.rent/api/v1/packages/57/renewal \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"enabled":true,"period":"month"}'

Trường	Ý nghĩa
`enabled`	bắt buộc: `true` hoặc `false`
`period`	gia hạn theo kỳ hạn nào mỗi lần; không có trường này - giữ nguyên kỳ hạn hiện tại

Phản hồi - thẻ gói. Cách tự động gia hạn hoạt động:

được bật theo mặc định, kỳ hạn - là kỳ hạn đã mua;
tiền bị trừ một ngày trước expires_at, theo giá tại thời điểm đó; ngày và số tiền - trong renewal.next_charge_at và renewal.next_charge_amount;
nếu không đủ tiền, renewal.last_failure trở thành insufficient_balance, việc thử lại diễn ra vài giờ một lần trong 3 ngày sau expires_at;
sau đó tự động gia hạn tự tắt, renewal.disabled_at được điền.

Lỗi: 400 invalid_body (thiếu enabled); 404 not_found; 422 unknown_period, unsupported_capability.

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

Thay mọi địa chỉ của gói bằng địa chỉ mới ở cùng vị trí. Quyền packages:write. Không cần nội dung yêu cầu. Miễn phí.

Việc thay thế chạy ở chế độ nền. Phản hồi - 202 và thẻ gói với replacement.state: pending. Đọc thẻ cho đến khi state thay đổi, thường mất chưa đến một phút:

`replacement.state`	Ý nghĩa
`pending`	đang thay thế
`done`	`addresses` chứa địa chỉ mới, địa chỉ cũ không hoạt động
`failed`	không có gì thay đổi, có thể yêu cầu lại

Tên đăng nhập, mật khẩu, thời hạn và dấu vân tay không thay đổi. Có thể thay lại sau 30 ngày: replace_available_at trên thẻ cho biết khi nào.

Lỗi:

404 - not_found
409 - replace_in_progress (việc thay thế đang diễn ra)
422 - package_expired (đã hết hạn - hãy gia hạn trước), unsupported_capability
429 - replace_cooldown (địa chỉ vừa được thay gần đây; ngày - trong replace_available_at)

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

Dấu vân tay p0f: các địa chỉ hiện diện như hệ điều hành và trình duyệt đã chọn. Một hồ sơ cho toàn bộ gói. Quyền packages:write. Miễn phí.

curl -X POST https://ipv.rent/api/v1/packages/57/fingerprint \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"profile":"windows_chrome"}'

profile - giá trị từ fingerprint.profiles của thẻ: windows_chrome, windows_edge, windows_firefox, android_chrome, macos_chrome. null tắt việc giả lập.

Dấu vân tay mới được áp dụng sau 2-3 phút. Các kết nối mở trước khi đổi vẫn giữ dấu vân tay cũ - hãy kết nối lại.

Lỗi: 400 validation_failed (hồ sơ không có trong danh sách); 404 not_found; 422 package_expired, unsupported_capability.

Mật khẩu

Cấp lại mật khẩu - route chung POST /api/v1/packages/{id}/password. Tên đăng nhập không thay đổi, mật khẩu cũ ngừng hoạt động ngay lập tức trên mọi địa chỉ của gói.