Paquetes

Todo lo que compra se convierte en un paquete. Un paquete de tráfico (family: traffic_gateway) es un volumen de gigabytes a partir del cual se arman las conexiones. Un paquete de direcciones fijas (family: dedicated) son N direcciones por un plazo con un mismo usuario y contraseña. Las rutas de esta página, salvo la última sección, son comunes a ambos tipos.

POST /api/v1/quote

Cálculo de precio. No cobra nada. Alcance catalog:read. El cuerpo es el mismo que el de la compra.

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 en tráfico, per_ip en direcciones fijas.
total = unit * quantity - discount; discount es el descuento en dinero, discount_percent es el mismo descuento en porcentaje, ambos como cadenas.
El importe calculado es exactamente el que se cobrará al comprar con el mismo cuerpo.

POST /api/v1/packages

Compra. Alcance packages:write, el encabezado Idempotency-Key es obligatorio. La compra se completa dentro de la solicitud: la respuesta 201 lleva order_id, package_id y status: completed.

Los campos necesarios dependen del producto:

Campo	Residential	IPv4	Significado
`product`	sí	sí	slug del catálogo
`volume`	sí	no permitido	gigabytes enteros, integer o string
`country`	-	sí	código de país de los parámetros
`operator`	-	sí	ubicación de los parámetros
`period`	-	sí	`week`, `2_weeks`, `month`, `2_months`, `3_months`, de los períodos del país
`quantity`	no permitido	no, 1	cuántas direcciones; todas formarán un solo paquete
`plan`	-	no	plan; solo es necesario si el país tiene varios
`auto_renew`	-	no, `true`	prolongar el paquete automáticamente
`client_reference`	no	no	su etiqueta de hasta 64 caracteres; no es única

Un campo que no corresponde al producto y los ajustes de conexión (count, geo, protocol, ttl_minutes y similares) se rechazan por nombre: 422 unsupported_field con el campo 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"
}

En las direcciones fijas la respuesta lleva tres campos más:

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

requested indica cuántas direcciones se pidieron y fulfilled, cuántas se entregaron. Si se entregaron menos, la diferencia ya volvió al saldo.

Rechazos:

400 - invalid_body (falta volume en tráfico; falta country, period u operator en direcciones; el cuerpo no es 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 (el dinero se devolvió, repita como una compra nueva), idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed (el dinero no se tocó, repetir con la misma clave es seguro), order_needs_attention (el dinero se cobró, se revisa manualmente, no repetir), operation_indeterminate (reintento con la clave de una operación cuyo resultado no está determinado)

GET /api/v1/packages

Paquetes del titular de la clave, los más nuevos primero. Alcance packages:read. Parámetros: offset, limit (aquí por defecto 200), family, product.

Parámetro	Significado
`family`	`traffic_gateway` o `dedicated`; un valor desconocido equivale a sin filtro
`product`	slug: `residential`, `ipv4`; un slug que usted no tiene da una lista vacía

Campo de la ficha	Significado
`family`, `product`	tipo y producto del paquete
`status`	`provisioning`, `active`; en tráfico también `exhausted`, en direcciones `expired`, `closed`, `suspended`
`name`	`tag` si está definido; si no, se arma a partir del producto: `residential · 25 GB`, `ipv4 · US · United States · x10`
`traffic`	saldo de tráfico; en direcciones `null`
`expires_at`	fin del plazo; en tráfico `null`: el tráfico no caduca
`auto_renew`	en direcciones: si el paquete se prolonga solo
`endpoint`	en direcciones: `country`, `operator`, `addresses_count`; en tráfico `null`

GET /api/v1/packages/{id}

El paquete y el acceso a él. Alcance packages:read.

Paquete de tráfico:

{
  "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 y limits son null a la vez mientras el paquete no se haya entregado. Las líneas de conexión listas se obtienen de POST /api/v1/packages/{id}/proxies.

Paquete de direcciones fijas:

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

Qué significa cada campo de las direcciones fijas se explica en la página Direcciones fijas.

Rechazos: 404 not_found.

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

Regeneración de la contraseña, para ambos tipos. Alcance packages:write. El usuario no cambia.

La contraseña anterior deja de funcionar de inmediato; applies_in_seconds es el tiempo máximo que tarda la nueva en empezar a aceptarse.

Rechazos: 404 not_found; 422 package_unavailable (el paquete aún no se ha entregado), package_expired (el plazo de las direcciones terminó; prolónguelo primero); 500 package_failed.

Operaciones con el paquete de tráfico

Las rutas siguientes son solo para Residential. En un paquete de direcciones fijas responden 422 unsupported_capability.

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

Armar conexiones. Alcance packages:write, no requiere idempotencia. El cuerpo es opcional.

Campo	Tipo	Por defecto	Significado
`count`	integer 1..500	1	cuántas líneas armar
`mode`	`rotating` \| `sticky`	`rotating`	modo de sesión
`protocol`	`http` \| `socks5`	`http`	protocolo
`ttl_minutes`	integer \| null	60	cuánto se mantiene la dirección en `sticky`, 3..1440
`geo.country`, `geo.state`, `geo.city`, `geo.asn`	string	-	códigos del catálogo geográfico; `state`, `city`, `asn` requieren `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 el modo sticky cada línea del conjunto lleva su propia etiqueta de sesión, es decir, da una dirección de salida distinta, y cada una tiene su propia rotation_url.

En el modo rotating las líneas son idénticas: la dirección se elige en cada conexión, así que N líneas dan N salidas distintas, y no hay enlaces de cambio de IP.

Un campo ausente toma el valor por defecto, no el de la llamada anterior. Las líneas entregadas antes siguen funcionando.

Rechazos:

400 - invalid_body (tipo o rango del campo)
404 - not_found
422 - invalid_targeting (con field y value: valor fuera del catálogo, clave desconocida en geo, restricción sin country), package_unavailable (el paquete aún no se ha entregado, ttl_minutes fuera de limits, modo o protocolo no admitido), unsupported_capability

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

Recargar volumen. Alcance packages:write, Idempotency-Key es obligatorio. Cuerpo: {"volume": 10}.

La respuesta es 202 con la ficha del paquete: el nuevo volumen se ve en la ficha de inmediato, y el tráfico con el nuevo límite empieza a pasar en unos dos minutos.

La recarga de volumen crea un pedido aparte con applied_to_package_id.

Rechazos:

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 (el dinero no se cobró, se puede repetir), order_needs_attention (el cobro se realizó, no se debe repetir), operation_indeterminate (reintento con la clave de una operación cuyo resultado no está determinado)

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

Regeneración del secreto de los enlaces de cambio de IP. Alcance packages:write. Anula todos los enlaces /r/{token} a la vez; no se puede revocar uno solo. La respuesta es el paquete completo.

Rechazos: 404 not_found; 422 unsupported_capability.