Paket

Semua yang Anda beli menjadi paket. Paket trafik (family: traffic_gateway) adalah volume gigabyte yang menjadi sumber koneksi. Paket alamat tetap (family: dedicated) adalah N alamat untuk suatu periode dengan satu login dan kata sandi. Rute di halaman ini, kecuali bagian terakhir, berlaku untuk kedua jenis.

POST /api/v1/quote

Perhitungan harga. Tidak memotong apa pun. Izin catalog:read. Body sama dengan body pembelian.

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 untuk trafik, per_ip untuk alamat tetap.
• total = unit * quantity - discount; discount - diskon dalam uang, discount_percent - diskon yang sama dalam persen, keduanya berupa string.
• Jumlah yang dihitung adalah persis jumlah yang dipotong saat pembelian dengan body yang sama.

POST /api/v1/packages

Pembelian. Izin packages:write, header Idempotency-Key wajib. Pembelian selesai di dalam permintaan: respons 201 membawa order_id, package_id, dan status: completed.

Field yang dibutuhkan bergantung pada produk:

Field	Residential	IPv4	Arti
product	ya	ya	slug dari katalog
volume	ya	dilarang	gigabyte bulat, integer atau string
country	-	ya	kode negara dari parameter
operator	-	ya	lokasi dari parameter
period	-	ya	week, 2_weeks, month, 2_months, 3_months - dari periode negara tersebut
quantity	dilarang	tidak, 1	berapa alamat; semuanya menjadi satu paket
plan	-	tidak	tarif; hanya diperlukan jika negara punya beberapa tarif
auto_renew	-	tidak, true	perpanjang paket secara otomatis
client_reference	tidak	tidak	label Anda hingga 64 karakter; tidak unik

Field yang tidak berlaku untuk produk, serta pengaturan koneksi (count, geo, protocol, ttl_minutes dan sejenisnya), ditolak berdasarkan namanya: 422 unsupported_field dengan field 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"
}

Untuk alamat tetap, respons memuat tiga field tambahan:

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

requested - berapa alamat yang dipesan, fulfilled - berapa yang diberikan. Jika yang diberikan lebih sedikit, selisihnya sudah kembali ke saldo.

Penolakan:

• 400 - invalid_body (tidak ada volume untuk trafik; tidak ada country, period, atau operator untuk alamat; body bukan 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 (dana dikembalikan, ulangi sebagai pembelian baru), idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
• 500 - order_failed (dana tidak tersentuh, pengulangan dengan kunci yang sama aman), order_needs_attention (dana sudah dipotong, ditangani secara manual, jangan diulang), operation_indeterminate (pengulangan dengan kunci dari operasi yang hasilnya belum pasti)

GET /api/v1/packages

Paket milik pemilik kunci, yang terbaru di atas. Izin packages:read. Parameter: offset, limit (di sini default 200), family, product.

Parameter	Arti
family	traffic_gateway atau dedicated; nilai yang tidak dikenal - tanpa filter
product	slug: residential, ipv4; slug yang tidak Anda miliki menghasilkan daftar kosong

Field kartu	Arti
family, product	jenis dan produk paket
status	provisioning, active; untuk trafik juga exhausted, untuk alamat - expired, closed, suspended
name	tag jika diisi, jika tidak dibentuk dari produk: residential · 25 GB, ipv4 · US · United States · x10
traffic	saldo trafik; untuk alamat null
expires_at	akhir masa berlaku; untuk trafik null - trafik tidak hangus
auto_renew	untuk alamat: apakah paket diperpanjang otomatis
endpoint	untuk alamat: country, operator, addresses_count; untuk trafik null

GET /api/v1/packages/{id}

Paket dan aksesnya. Izin packages:read.

Paket trafik:

{
  "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, dan limits bernilai null bersamaan selama paket belum diberikan. Ambil baris koneksi siap pakai dari POST /api/v1/packages/{id}/proxies.

Paket alamat tetap:

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

Arti setiap field alamat tetap - di halaman Alamat tetap.

Penolakan: 404 not_found.

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

Penerbitan ulang kata sandi, untuk kedua jenis. Izin packages:write. Login tidak berubah.

Kata sandi lama langsung berhenti berfungsi; applies_in_seconds - batas atas waktu hingga yang baru mulai diterima.

Penolakan: 404 not_found; 422 package_unavailable (paket belum diberikan), package_expired (masa berlaku alamat sudah habis - perpanjang dulu); 500 package_failed.

Operasi paket trafik

Rute di bawah ini hanya untuk Residential. Pada paket alamat tetap, rute ini menjawab 422 unsupported_capability.

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

Membuat koneksi. Izin packages:write, idempotensi tidak diperlukan. Body opsional.

Field	Tipe	Default	Arti
count	integer 1..500	1	berapa baris yang dibuat
mode	rotating | sticky	rotating	mode sesi
protocol	http | socks5	http	protokol
ttl_minutes	integer | null	60	berapa lama alamat bertahan dalam sticky, 3..1440
geo.country, geo.state, geo.city, geo.asn	string	-	kode dari katalog geo; state, city, asn memerlukan 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"
      }
    }'

Dalam mode sticky, setiap baris dalam set membawa label sesinya sendiri, artinya memberi alamat keluar tersendiri, dan masing-masing punya rotation_url sendiri.

Dalam mode rotating, baris-barisnya identik: alamat dipilih pada setiap koneksi, sehingga N baris memberi N alamat keluar yang berbeda, dan tidak ada tautan ganti IP.

Field yang tidak dikirim memakai nilai default, bukan nilai dari panggilan sebelumnya. Baris yang sudah diberikan sebelumnya tetap berfungsi.

Penolakan:

• 400 - invalid_body (tipe atau rentang field)
• 404 - not_found
• 422 - invalid_targeting (dengan field dan value: nilai di luar katalog, kunci geo yang tidak dikenal, penyempitan tanpa country), package_unavailable (paket belum diberikan, ttl_minutes di luar limits, mode atau protokol tidak didukung), unsupported_capability

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

Menambah volume. Izin packages:write, Idempotency-Key wajib. Body: {"volume": 10}.

Respons - 202 dan kartu paket: volume baru langsung terlihat di kartu, trafik dengan batas baru mulai berjalan sekitar dua menit kemudian.

Penambahan volume membuat pesanan terpisah dengan applied_to_package_id.

Penolakan:

• 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 (dana tidak dipotong, pengulangan wajar), order_needs_attention (pemotongan sudah terjadi, jangan diulang), operation_indeterminate (pengulangan dengan kunci dari operasi yang hasilnya belum pasti)

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

Penerbitan ulang secret tautan ganti IP. Izin packages:write. Membatalkan semua tautan /r/{token} sekaligus; satu tautan tidak bisa dicabut sendiri. Respons - paket secara utuh.

Penolakan: 404 not_found; 422 unsupported_capability.