Direcciones fijas

Operaciones con el paquete de direcciones fijas (family: dedicated, producto ipv4). Cada una actúa sobre todo el paquete: sobre todas sus direcciones a la vez. En un paquete de tráfico estas rutas responden 422 unsupported_capability.

Las operaciones disponibles para el paquete se enumeran en capabilities de su ficha: prolong, credentials, replace, fingerprint, renewal.

Plazo y estados

Estado	Qué ocurre	Qué se puede hacer
`provisioning`	el paquete se está entregando, hasta 2 minutos	esperar
`active`	las direcciones funcionan hasta `expires_at`	todo
`expired`	el plazo terminó, las direcciones no responden	prolongar antes de `extendable_until`: vuelven las mismas direcciones
`closed`	pasó `extendable_until`, las direcciones se liberaron	solo una compra nueva
`suspended`	el paquete está desactivado	escribir a soporte

Campos de la ficha relacionados con el plazo:

Campo	Significado
`expires_at`	fin del plazo pagado
`extendable_until`	hasta qué momento la prolongación devuelve las mismas direcciones
`credentials_retired`	`true`: la contraseña se desactivó al terminar el plazo; la prolongación emitirá una nueva

Cuando el plazo termina, llega package.expired al registro de eventos.

GET /api/v1/packages/{id}/prolong-options

Para qué períodos se puede prolongar y cuánto le cuesta. Alcance packages:read.

{
  "options": [
    {
      "period": "week",
      "price": "1.98"
    },
    {
      "period": "2_weeks",
      "price": "2.58"
    },
    {
      "period": "month",
      "price": "2.98"
    },
    {
      "period": "2_months",
      "price": "5.96"
    },
    {
      "period": "3_months",
      "price": "8.94"
    }
  ],
  "currency": "USD"
}

price es el precio de todo el paquete, por todas sus direcciones.

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

Prolongar el paquete. Alcance packages:write, Idempotency-Key es obligatorio: es un cobro. Cuerpo: {"period": "month"}, con un período de prolong-options.

curl -X POST https://ipv.rent/api/v1/packages/57/prolong \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"period":"month"}'

{
  "order_id": 140,
  "package_id": 57,
  "status": "completed",
  "price": "2.98",
  "expires_at": "2026-12-04T12:00:00+00:00",
  "credentials_reissued": false
}

El período se suma al expires_at actual o, si el plazo ya terminó, al momento de la prolongación.
Las direcciones y el usuario se mantienen.
credentials_reissued: true: la contraseña anterior se había desactivado y se emitió una nueva; tómela de la ficha del paquete.
La prolongación crea un pedido aparte con applied_to_package_id.

Rechazos:

400 - invalid_body (falta el cuerpo o no es JSON), validation_failed
404 - not_found
409 - idempotency_in_progress
422 - unknown_period, insufficient_balance, prolong_window_closed (las direcciones ya no se pueden recuperar: el paquete está closed, se necesita una compra nueva), unsupported_capability, purchase_refunded, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed, order_needs_attention, operation_indeterminate, igual que en la compra

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

Renovación automática. Alcance packages:write. No cobra nada.

curl -X POST https://ipv.rent/api/v1/packages/57/renewal \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"enabled":true,"period":"month"}'

Campo	Significado
`enabled`	obligatorio: `true` o `false`
`period`	para qué período prolongar cada vez; sin el campo, se mantiene el anterior

La respuesta es la ficha del paquete. Cómo funciona la renovación automática:

está activada por defecto, con el período que se compró;
el cobro se hace un día antes de expires_at, al precio vigente en ese momento; la fecha y el importe están en renewal.next_charge_at y renewal.next_charge_amount;
si el saldo no alcanzó, renewal.last_failure pasa a insufficient_balance y los intentos se repiten cada pocas horas durante 3 días más después de expires_at;
después, la renovación automática se desactiva sola y renewal.disabled_at recibe un valor.

Rechazos: 400 invalid_body (falta enabled); 404 not_found; 422 unknown_period, unsupported_capability.

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

Reemplazar todas las direcciones del paquete por otras nuevas en la misma ubicación. Alcance packages:write. No requiere cuerpo. Gratis.

El reemplazo se hace en segundo plano. La respuesta es 202 con la ficha y replacement.state: pending. Lea la ficha hasta que state cambie; normalmente tarda menos de un minuto:

`replacement.state`	Significado
`pending`	el reemplazo está en curso
`done`	`addresses` contiene las direcciones nuevas, las anteriores no funcionan
`failed`	no cambió nada, se puede volver a solicitar

El usuario, la contraseña, el plazo y la huella no cambian. Se puede volver a reemplazar al cabo de 30 días: replace_available_at en la ficha indica cuándo.

Rechazos:

404 - not_found
409 - replace_in_progress (el reemplazo ya está en curso)
422 - package_expired (el plazo terminó; prolónguelo primero), unsupported_capability
429 - replace_cooldown (las direcciones se reemplazaron hace poco; la fecha está en replace_available_at)

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

Huella p0f: las direcciones se presentan como el SO y el navegador elegidos. Un perfil para todo el paquete. Alcance packages:write. Gratis.

curl -X POST https://ipv.rent/api/v1/packages/57/fingerprint \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"profile":"windows_chrome"}'

profile es un valor de fingerprint.profiles de la ficha: windows_chrome, windows_edge, windows_firefox, android_chrome, macos_chrome. null desactiva la suplantación.

La nueva huella se aplica en 2-3 minutos. Las conexiones abiertas antes del cambio conservan la anterior: vuelva a conectarse.

Rechazos: 400 validation_failed (el perfil no está en la lista); 404 not_found; 422 package_expired, unsupported_capability.

Contraseña

La regeneración de la contraseña es una ruta común: POST /api/v1/packages/{id}/password. El usuario no cambia, y la contraseña anterior deja de funcionar de inmediato en todas las direcciones del paquete.