Forfaits

Tout ce que vous achetez devient un forfait. Un forfait de trafic (family: traffic_gateway) est un volume de gigaoctets à partir duquel les connexions sont générées. Un forfait d’adresses fixes (family: dedicated) correspond à N adresses pour une durée, avec un seul identifiant et mot de passe. Les routes de cette page, sauf la dernière section, sont communes aux deux types.

POST /api/v1/quote

Calcul du prix. Ne débite rien. Droit catalog:read. Le corps est le même que pour l’achat.

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 pour le trafic, per_ip pour les adresses fixes.
total = unit * quantity - discount ; discount - la remise en argent, discount_percent - la même remise en pourcentage, toutes deux en chaînes.
Le montant calculé est exactement celui qui sera débité lors d’un achat avec le même corps.

POST /api/v1/packages

Achat. Droit packages:write, l’en-tête Idempotency-Key est obligatoire. L’achat se termine à l’intérieur de la requête : la réponse 201 porte order_id, package_id et status: completed.

Les champs requis dépendent du produit :

Champ	Residential	IPv4	Signification
`product`	oui	oui	slug du catalogue
`volume`	oui	interdit	gigaoctets entiers, integer ou string
`country`	-	oui	code pays tiré des paramètres
`operator`	-	oui	emplacement tiré des paramètres
`period`	-	oui	`week`, `2_weeks`, `month`, `2_months`, `3_months` - parmi les périodes du pays
`quantity`	interdit	non, 1	nombre d’adresses ; elles formeront toutes un seul forfait
`plan`	-	non	tarif ; nécessaire seulement s’il y en a plusieurs dans le pays
`auto_renew`	-	non, `true`	prolonger le forfait automatiquement
`client_reference`	non	non	votre étiquette, jusqu’à 64 caractères ; non unique

Un champ qui ne concerne pas le produit, ainsi que les réglages de connexion (count, geo, protocol, ttl_minutes et similaires), sont refusés par leur nom : 422 unsupported_field avec le champ 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"
}

Pour les adresses fixes, la réponse contient trois champs de plus :

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

requested - combien d’adresses ont été commandées, fulfilled - combien ont été délivrées. S’il en a été délivré moins, la différence est déjà revenue sur le solde.

Erreurs :

400 - invalid_body (pas de volume pour le trafic ; pas de country, period ou operator pour les adresses ; corps qui n’est pas du 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 (argent remboursé, réessayez comme un nouvel achat), idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed (argent non touché, une nouvelle tentative avec la même clé est sans risque), order_needs_attention (argent débité, traité manuellement, ne pas réessayer), operation_indeterminate (nouvelle tentative avec la clé d’une opération dont l’issue est indéterminée)

GET /api/v1/packages

Les forfaits du titulaire de la clé, les plus récents en premier. Droit packages:read. Paramètres : offset, limit (ici 200 par défaut), family, product.

Paramètre	Signification
`family`	`traffic_gateway` ou `dedicated` ; une valeur inconnue - sans filtre
`product`	slug : `residential`, `ipv4` ; un slug que vous n’avez pas donne une liste vide

Champ de la fiche	Signification
`family`, `product`	type et produit du forfait
`status`	`provisioning`, `active` ; pour le trafic aussi `exhausted`, pour les adresses - `expired`, `closed`, `suspended`
`name`	`tag` s’il est défini, sinon construit à partir du produit : `residential · 25 GB`, `ipv4 · US · United States · x10`
`traffic`	solde de trafic ; pour les adresses `null`
`expires_at`	fin de la durée ; pour le trafic `null` - le trafic n’expire pas
`auto_renew`	pour les adresses : le forfait se prolonge-t-il tout seul
`endpoint`	pour les adresses : `country`, `operator`, `addresses_count` ; pour le trafic `null`

GET /api/v1/packages/{id}

Le forfait et l’accès à celui-ci. Droit packages:read.

Forfait de trafic :

{
  "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 et limits valent null ensemble tant que le forfait n’est pas délivré. Prenez les lignes de connexion prêtes à l’emploi dans POST /api/v1/packages/{id}/proxies.

Forfait d’adresses fixes :

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

La signification de chaque champ des adresses fixes - sur la page Adresses fixes.

Erreurs : 404 not_found.

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

Régénération du mot de passe, pour les deux types. Droit packages:write. L’identifiant ne change pas.

L’ancien mot de passe cesse de fonctionner immédiatement ; applies_in_seconds - la limite supérieure du délai au bout duquel le nouveau commence à être accepté.

Erreurs : 404 not_found ; 422 package_unavailable (forfait pas encore délivré), package_expired (la durée des adresses est terminée - prolongez d’abord) ; 500 package_failed.

Opérations sur un forfait de trafic

Les routes ci-dessous concernent uniquement Residential. Sur un forfait d’adresses fixes, elles répondent 422 unsupported_capability.

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

Générer des connexions. Droit packages:write, l’idempotence n’est pas nécessaire. Le corps est facultatif.

Champ	Type	Par défaut	Signification
`count`	integer 1..500	1	nombre de lignes à générer
`mode`	`rotating` \| `sticky`	`rotating`	mode de session
`protocol`	`http` \| `socks5`	`http`	protocole
`ttl_minutes`	integer \| null	60	durée de conservation de l’adresse en `sticky`, 3..1440
`geo.country`, `geo.state`, `geo.city`, `geo.asn`	string	-	codes du catalogue géo ; `state`, `city`, `asn` exigent `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"
      }
    }'

En mode sticky, chaque ligne de l’ensemble porte sa propre étiquette de session, c’est-à-dire qu’elle donne une adresse de sortie distincte, et chacune a sa propre rotation_url.

En mode rotating, les lignes sont identiques : l’adresse est choisie à chaque connexion, donc N lignes donnent N sorties différentes, et il n’y a pas de liens de changement d’IP.

Un champ absent prend la valeur par défaut, et non la valeur de l’appel précédent. Les lignes délivrées auparavant continuent de fonctionner.

Erreurs :

400 - invalid_body (type ou plage d’un champ)
404 - not_found
422 - invalid_targeting (avec field et value : valeur hors catalogue, clé geo inconnue, restriction sans country), package_unavailable (forfait pas encore délivré, ttl_minutes hors limits, mode ou protocole non pris en charge), unsupported_capability

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

Ajouter du trafic. Droit packages:write, Idempotency-Key obligatoire. Corps : {"volume": 10}.

La réponse est 202 avec la fiche du forfait : le nouveau volume est visible immédiatement dans la fiche, le trafic selon la nouvelle limite commence à passer au bout d’environ deux minutes.

L’ajout de trafic crée une commande distincte avec applied_to_package_id.

Erreurs :

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 (argent non débité, une nouvelle tentative est appropriée), order_needs_attention (le débit a eu lieu, ne pas réessayer), operation_indeterminate (nouvelle tentative avec la clé d’une opération dont l’issue est indéterminée)

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

Régénération du secret des liens de changement d’IP. Droit packages:write. Annule tous les liens /r/{token} d’un coup ; impossible d’en révoquer un seul. La réponse est le forfait complet.

Erreurs : 404 not_found ; 422 unsupported_capability.