고정 주소

고정 주소 패키지(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가 바뀔 때까지 카드를 읽으세요. 보통 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와 브라우저로 보이게 합니다. 패키지 전체에 프로필 하나. 권한 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입니다. 로그인은 바뀌지 않으며, 이전 비밀번호는 패키지의 모든 주소에서 즉시 작동을 멈춥니다.