패키지

구매한 모든 것은 패키지가 됩니다. 트래픽 패키지(family: traffic_gateway)는 연결을 만들어 쓰는 기가바이트 용량입니다. 고정 주소 패키지(family: dedicated)는 하나의 로그인과 비밀번호를 쓰는 기간제 주소 N개입니다. 이 페이지의 라우트는 마지막 섹션을 제외하고 두 종류 공통입니다.

POST /api/v1/quote

가격 계산. 아무것도 차감하지 않습니다. 권한 catalog:read. 본문은 구매와 같습니다.

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, 고정 주소는 per_ip.
• total = unit * quantity - discount. discount는 금액 기준 할인, discount_percent는 같은 할인을 퍼센트로 나타낸 값이며 둘 다 문자열입니다.
• 계산된 금액은 같은 본문으로 구매할 때 차감되는 금액과 정확히 같습니다.

POST /api/v1/packages

구매. 권한 packages:write, Idempotency-Key 헤더 필수. 구매는 요청 안에서 완료됩니다: 201 응답에 order_id, package_id, status: completed가 담깁니다.

필요한 필드는 상품에 따라 다릅니다:

필드	Residential	IPv4	의미
product	예	예	카탈로그의 슬러그
volume	예	불가	정수 기가바이트, integer 또는 string
country	-	예	옵션의 국가 코드
operator	-	예	옵션의 위치
period	-	예	week, 2_weeks, month, 2_months, 3_months - 국가의 기간 중에서
quantity	불가	아니요, 1	주소 수. 모두 하나의 패키지가 됨
plan	-	아니요	요금제. 국가에 요금제가 여러 개일 때만 필요
auto_renew	-	아니요, true	패키지 자동 연장 여부
client_reference	아니요	아니요	최대 64자의 내 라벨. 고유하지 않아도 됨

상품과 관계없는 필드와 연결 설정(count, geo, protocol, ttl_minutes 등)은 이름으로 거부됩니다: field 필드와 함께 422 unsupported_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"
}

고정 주소는 응답에 필드가 세 개 더 있습니다:

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

requested는 주문한 주소 수, fulfilled는 발급된 주소 수입니다. 발급된 수가 적으면 차액은 이미 잔액으로 반환되었습니다.

오류:

• 400 - invalid_body(트래픽에 volume 없음, 주소에 country, period 또는 operator 없음, 본문이 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(금액 반환됨, 새 구매로 다시 시도), idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
• 500 - order_failed(금액에 변동 없음, 같은 키로 재시도해도 안전), order_needs_attention(금액 차감됨, 수동으로 처리 중, 재시도하지 말 것), operation_indeterminate(결과가 확정되지 않은 작업의 키로 재시도함)

GET /api/v1/packages

키 소유자의 패키지, 최신순. 권한 packages:read. 파라미터: offset, limit(여기서는 기본값 200), family, product.

파라미터	의미
family	traffic_gateway 또는 dedicated. 알 수 없는 값은 필터 없음
product	슬러그: residential, ipv4. 보유하지 않은 슬러그는 빈 목록

카드 필드	의미
family, product	패키지의 종류와 상품
status	provisioning, active. 트래픽은 추가로 exhausted, 주소는 expired, closed, suspended
name	설정된 경우 tag, 아니면 상품으로 구성: residential · 25 GB, ipv4 · US · United States · x10
traffic	트래픽 잔량. 주소는 null
expires_at	기간 종료. 트래픽은 null - 트래픽은 소멸되지 않음
auto_renew	주소: 패키지가 자동으로 연장되는지 여부
endpoint	주소: country, operator, addresses_count. 트래픽은 null

GET /api/v1/packages/{id}

패키지와 접속 정보. 권한 packages:read.

트래픽 패키지:

{
  "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, limits는 패키지가 발급되기 전까지 함께 null입니다. 완성된 연결 문자열은 POST /api/v1/packages/{id}/proxies에서 받으세요.

고정 주소 패키지:

{
  "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"
      },
      "..."
    ]
  }
}

고정 주소의 각 필드가 무엇을 뜻하는지는 고정 주소 페이지에 있습니다.

오류: 404 not_found.

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

비밀번호 재발급, 두 종류 공통. 권한 packages:write. 로그인은 바뀌지 않습니다.

이전 비밀번호는 즉시 작동을 멈춥니다. applies_in_seconds는 새 비밀번호가 받아들여지기 시작하기까지의 최대 시간입니다.

오류: 404 not_found; 422 package_unavailable(패키지가 아직 발급되지 않음), package_expired(주소 기간 종료 - 먼저 연장하세요); 500 package_failed.

트래픽 패키지 작업

아래 라우트는 Residential 전용입니다. 고정 주소 패키지에서는 422 unsupported_capability로 응답합니다.

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

연결 생성. 권한 packages:write, 멱등성 불필요. 본문은 선택 사항입니다.

필드	타입	기본값	의미
count	integer 1..500	1	생성할 문자열 수
mode	rotating | sticky	rotating	세션 모드
protocol	http | socks5	http	프로토콜
ttl_minutes	integer | null	60	sticky에서 주소가 유지되는 시간, 3..1440
geo.country, geo.state, geo.city, geo.asn	string	-	지역 카탈로그의 코드. state, city, asn은 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"
      }
    }'

sticky 모드에서는 세트의 각 문자열이 자체 세션 라벨을 가지므로 별도의 출구 주소를 제공하며, 각각 자체 rotation_url이 있습니다.

rotating 모드에서는 문자열이 모두 같습니다: 주소가 연결마다 선택되므로 N개의 문자열은 N개의 서로 다른 출구를 제공하며, IP 변경 링크는 없습니다.

빠진 필드는 이전 호출의 값이 아니라 기본값을 사용합니다. 이전에 발급한 문자열은 계속 작동합니다.

오류:

• 400 - invalid_body(필드의 타입 또는 범위)
• 404 - not_found
• 422 - invalid_targeting(field와 value 포함: 카탈로그에 없는 값, 알 수 없는 geo 키, country 없는 범위 지정), package_unavailable(패키지가 아직 발급되지 않음, ttl_minutes가 limits 밖, 지원하지 않는 모드나 프로토콜), unsupported_capability

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

용량 추가. 권한 packages:write, Idempotency-Key 필수. 본문: {"volume": 10}.

응답은 202와 패키지 카드입니다: 새 용량은 카드에 즉시 보이고, 새 한도에 따른 트래픽은 약 2분 뒤부터 통과합니다.

트래픽 추가는 applied_to_package_id를 가진 별도의 주문을 만듭니다.

오류:

• 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(금액 차감 안 됨, 재시도 가능), order_needs_attention (차감 완료, 재시도 금지), operation_indeterminate(결과가 확정되지 않은 작업의 키로 재시도함)

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

IP 변경 링크의 비밀 값 재발급. 권한 packages:write. 모든 /r/{token} 링크를 즉시 무효화합니다. 하나만 폐기할 수는 없습니다. 응답은 패키지 전체입니다.

오류: 404 not_found; 422 unsupported_capability.