固定アドレス

固定アドレスのパッケージ (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 の 1 日前に、その時点の価格で行われます。日時と金額は 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 が変わるまで詳細を取得してください。通常は 1 分以内です:

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 フィンガープリント: アドレスを選んだ OS とブラウザに見せかけます。パッケージ全体で 1 つのプロファイルです。権限 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 です。 ログインは変わらず、古いパスワードはパッケージのすべてのアドレスで直ちに使えなくなります。