Paketler

Satın aldığınız her şey bir paket olur. Trafik paketi (family: traffic_gateway) - bağlantıların oluşturulduğu gigabayt hacmidir. Sabit adres paketi (family: dedicated) - tek kullanıcı adı ve parolayla süreli N adrestir. Bu sayfadaki rotalar, son bölüm hariç, her iki tür için ortaktır.

POST /api/v1/quote

Fiyat hesaplama. Hiçbir şey düşmez. Yetki catalog:read. Gövde satın almadakiyle aynıdır.

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: trafikte per_gb, sabit adreslerde per_ip.
total = unit * quantity - discount; discount - para cinsinden indirim, discount_percent - aynı indirimin yüzdesi, ikisi de dize olarak.
Hesaplanan tutar, aynı gövdeyle yapılan satın almada düşülecek tutarın tam olarak kendisidir.

POST /api/v1/packages

Satın alma. Yetki packages:write, Idempotency-Key başlığı zorunludur. Satın alma istek içinde tamamlanır: 201 yanıtı order_id, package_id ve status: completed taşır.

Hangi alanların gerektiği ürüne bağlıdır:

Alan	Residential	IPv4	Anlamı
`product`	evet	evet	katalogdaki slug
`volume`	evet	gönderilemez	tam gigabayt, integer veya string
`country`	-	evet	parametrelerdeki ülke kodu
`operator`	-	evet	parametrelerdeki konum
`period`	-	evet	`week`, `2_weeks`, `month`, `2_months`, `3_months` - ülkenin dönemlerinden
`quantity`	gönderilemez	hayır, 1	kaç adres; hepsi tek bir paket olur
`plan`	-	hayır	tarife; yalnızca ülkede birden fazla varsa gerekir
`auto_renew`	-	hayır, `true`	paketi otomatik olarak uzat
`client_reference`	hayır	hayır	en fazla 64 karakterlik etiketiniz; benzersiz değildir

Ürüne ait olmayan bir alan ve bağlantı ayarları (count, geo, protocol, ttl_minutes ve benzerleri) adıyla reddedilir: field alanıyla 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"
}

Sabit adreslerde yanıtta üç alan daha vardır:

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

requested - kaç adres sipariş edildiği, fulfilled - kaçının verildiği. Daha az verildiyse fark bakiyeye zaten iade edilmiştir.

Retler:

400 - invalid_body (trafikte volume yok; adreslerde country, period veya operator yok; gövde JSON değil), 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 (para iade edildi, yeni bir satın alma olarak tekrarlayın), idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed (paraya dokunulmadı, aynı anahtarla tekrar güvenlidir), order_needs_attention (para düşüldü, elle inceleniyor, tekrarlamayın), operation_indeterminate (sonucu belirsiz bir işlemin anahtarıyla tekrar)

GET /api/v1/packages

Anahtar sahibinin paketleri, en yeniler üstte. Yetki packages:read. Parametreler: offset, limit (burada varsayılan 200), family, product.

Parametre	Anlamı
`family`	`traffic_gateway` veya `dedicated`; bilinmeyen değer - filtresiz
`product`	slug: `residential`, `ipv4`; sizde olmayan bir slug boş liste döndürür

Kart alanı	Anlamı
`family`, `product`	paketin türü ve ürünü
`status`	`provisioning`, `active`; trafikte ayrıca `exhausted`, adreslerde `expired`, `closed`, `suspended`
`name`	ayarlanmışsa `tag`, aksi halde üründen oluşturulur: `residential · 25 GB`, `ipv4 · US · United States · x10`
`traffic`	trafik bakiyesi; adreslerde `null`
`expires_at`	sürenin sonu; trafikte `null` - trafiğin süresi dolmaz
`auto_renew`	adreslerde: paketin kendiliğinden uzayıp uzamadığı
`endpoint`	adreslerde: `country`, `operator`, `addresses_count`; trafikte `null`

GET /api/v1/packages/{id}

Paket ve ona erişim. Yetki packages:read.

Trafik paketi:

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

Paket verilene kadar credentials, connection_options ve limits birlikte null olur. Hazır bağlantı satırlarını POST /api/v1/packages/{id}/proxies üzerinden alın.

Sabit adres paketi:

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

Sabit adreslere ait her alanın anlamı Sabit adresler sayfasındadır.

Retler: 404 not_found.

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

Parola yenileme, her iki tür için. Yetki packages:write. Kullanıcı adı değişmez.

Eski parola anında çalışmayı bırakır; applies_in_seconds - yeni parolanın kabul edilmeye başlaması için üst sınırdır.

Retler: 404 not_found; 422 package_unavailable (paket henüz verilmedi), package_expired (adreslerin süresi doldu - önce uzatın); 500 package_failed.

Trafik paketi işlemleri

Aşağıdaki rotalar yalnızca Residential içindir. Sabit adres paketinde 422 unsupported_capability ile yanıt verirler.

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

Bağlantı oluşturma. Yetki packages:write, idempotency gerekmez. Gövde isteğe bağlıdır.

Alan	Tür	Varsayılan	Anlamı
`count`	integer 1..500	1	kaç satır oluşturulacağı
`mode`	`rotating` \| `sticky`	`rotating`	oturum modu
`protocol`	`http` \| `socks5`	`http`	protokol
`ttl_minutes`	integer \| null	60	`sticky` modunda adresin ne kadar tutulacağı, 3..1440
`geo.country`, `geo.state`, `geo.city`, `geo.asn`	string	-	geo kataloğundaki kodlar; `state`, `city`, `asn` için `country` gerekir

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 modunda kümedeki her satır kendi oturum etiketini taşır, yani ayrı bir çıkış adresi verir, ve her birinin kendi rotation_url değeri vardır.

rotating modunda satırlar aynıdır: adres her bağlantıda seçilir, bu yüzden N satır N farklı çıkış verir ve IP değiştirme bağlantıları yoktur.

Gönderilmeyen alan, önceki çağrının değerini değil varsayılanı alır. Daha önce verilen satırlar çalışmaya devam eder.

Retler:

400 - invalid_body (alanın türü veya aralığı)
404 - not_found
422 - invalid_targeting (field ve value ile: katalog dışı değer, bilinmeyen geo anahtarı, country olmadan daraltma), package_unavailable (paket henüz verilmedi, ttl_minutes limits dışında, mod veya protokol desteklenmiyor), unsupported_capability

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

Hacim ekleme. Yetki packages:write, Idempotency-Key zorunludur. Gövde: {"volume": 10}.

Yanıt - 202 ve paket kartı: yeni hacim kartta hemen görünür, yeni limite göre trafik yaklaşık iki dakika içinde geçmeye başlar.

Hacim ekleme, applied_to_package_id içeren ayrı bir sipariş oluşturur.

Retler:

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 (para düşülmedi, tekrar uygundur), order_needs_attention (tahsilat yapıldı, tekrarlanamaz), operation_indeterminate (sonucu belirsiz bir işlemin anahtarıyla tekrar)

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

IP değiştirme bağlantılarının gizli değerini yenileme. Yetki packages:write. Tüm /r/{token} bağlantılarını aynı anda geçersiz kılar; tek bir bağlantı iptal edilemez. Yanıt - paketin tamamı.

Retler: 404 not_found; 422 unsupported_capability.