固定地址

固定地址套餐（family: dedicated，产品 ipv4）的操作。每个操作都作用于整个套餐： 同时作用于其全部地址。在流量套餐上这些路由返回 422 unsupported_capability。

套餐可用的操作列在其详情的 capabilities 中：prolong、 credentials、replace、fingerprint、renewal。

期限与状态

状态	发生了什么	可以做什么
provisioning	套餐交付中，最多 2 分钟	等待
active	地址在 expires_at 之前可用	所有操作
expired	已到期，地址不响应	在 extendable_until 之前续期 - 恢复相同的地址
closed	已过 extendable_until，地址已释放	只能重新购买
suspended	套餐已停用	联系客服

详情中与期限相关的字段：

字段	含义
expires_at	已付费期限的结束时间
extendable_until	在此时间之前续期可恢复相同的地址
credentials_retired	true - 到期后密码已停用；续期时会签发新密码

到期时，事件日志中会出现 package.expired。

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

可续期的周期以及你需要支付的价格。权限 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 - 整个套餐（全部地址）的价格。

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

续期套餐。权限 packages:write，Idempotency-Key 必填：这是一次扣款。请求体： {"period": "month"}，周期取自 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
}

• 周期加在当前 expires_at 之上；如果已经到期，则从续期时刻起算。
• 地址和登录名保持不变。
• credentials_reissued: true - 旧密码已停用并签发了新密码；请从套餐详情中获取。
• 续期会创建一个带有 applied_to_package_id 的单独订单。

错误：

• 400 - invalid_body（没有请求体或不是 JSON），validation_failed
• 404 - not_found
• 409 - idempotency_in_progress
• 422 - unknown_period, insufficient_balance, prolong_window_closed（地址已无法恢复 - 套餐为 closed，需要重新购买）, unsupported_capability, purchase_refunded, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
• 500 - order_failed, order_needs_attention, operation_indeterminate - 与 购买相同

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

自动续期。权限 packages:write。不扣款。

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"}'

字段	含义
enabled	必填：true 或 false
period	每次续期的周期；不传则保持原值

响应为套餐详情。自动续期的工作方式：

• 默认开启，周期为购买时的周期；
• 在 expires_at 前一天扣款，按当时的价格；日期和金额见 renewal.next_charge_at 和 renewal.next_charge_amount；
• 如果余额不足，renewal.last_failure 变为 insufficient_balance，在 expires_at 之后的 3 天内每隔几小时重试一次；
• 之后自动续期自行关闭，renewal.disabled_at 被填写。

错误：400 invalid_body（缺少 enabled）；404 not_found；422 unknown_period、 unsupported_capability。

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

将套餐内的全部地址更换为同一位置的新地址。权限 packages:write。无需请求体。 免费。

更换在后台进行。响应为 202 和带有 replacement.state: pending 的套餐详情。请持续读取详情， 直到 state 发生变化，通常不到一分钟：

replacement.state	含义
pending	更换进行中
done	addresses 中为新地址，旧地址已失效
failed	没有任何变化，可以再次请求

登录名、密码、期限和指纹不变。30 天后可再次更换： 详情中的 replace_available_at 显示具体时间。

错误：

• 404 - not_found
• 409 - replace_in_progress（更换已在进行中）
• 422 - package_expired（已到期 - 请先续期），unsupported_capability
• 429 - replace_cooldown（地址最近已更换过；日期见 replace_available_at）

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

p0f 指纹：地址以所选的操作系统和浏览器呈现。整个套餐使用一个配置。 权限 packages:write。免费。

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 - 详情中 fingerprint.profiles 的值：windows_chrome、windows_edge、 windows_firefox、android_chrome、macos_chrome。null 关闭伪装。

新指纹在 2-3 分钟后生效。更改前打开的连接保留原指纹 - 请重新连接。

错误：400 validation_failed（配置不在列表中）；404 not_found；422 package_expired、 unsupported_capability。

密码

重新生成密码使用通用路由 POST /api/v1/packages/{id}/password。登录名不变， 旧密码在套餐的所有地址上立即失效。