Pacotes

Tudo o que você compra vira um pacote. Um pacote de tráfego (family: traffic_gateway) é um volume de gigabytes a partir do qual as conexões são montadas. Um pacote de endereços fixos (family: dedicated) são N endereços por um período com um único usuário e senha. As rotas desta página, exceto a última seção, são comuns aos dois tipos.

POST /api/v1/quote

Cálculo de preço. Não debita nada. Permissão catalog:read. O corpo é o mesmo da 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 no tráfego, per_ip nos endereços fixos.
total = unit * quantity - discount; discount é o desconto em dinheiro, discount_percent é o mesmo desconto em porcentagem, ambos como strings.
O valor calculado é exatamente o que será debitado na compra com o mesmo corpo.

POST /api/v1/packages

Compra. Permissão packages:write, o cabeçalho Idempotency-Key é obrigatório. A compra é concluída dentro da requisição: a resposta 201 traz order_id, package_id e status: completed.

Os campos necessários dependem do produto:

Campo	Residential	IPv4	Significado
`product`	sim	sim	slug do catálogo
`volume`	sim	proibido	gigabytes inteiros, integer ou string
`country`	-	sim	código do país dos parâmetros
`operator`	-	sim	local dos parâmetros
`period`	-	sim	`week`, `2_weeks`, `month`, `2_months`, `3_months` - entre os períodos do país
`quantity`	proibido	não, 1	quantos endereços; todos formam um único pacote
`plan`	-	não	plano; necessário só se o país tiver mais de um
`auto_renew`	-	não, `true`	prolongar o pacote automaticamente
`client_reference`	não	não	seu rótulo de até 64 caracteres; não é único

Um campo que não pertence ao produto e as configurações de conexão (count, geo, protocol, ttl_minutes e similares) são recusados pelo nome: 422 unsupported_field com o 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"
}

Nos endereços fixos, a resposta traz mais três campos:

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

requested - quantos endereços foram pedidos, fulfilled - quantos foram entregues. Se foram entregues menos, a diferença já voltou para o saldo.

Recusas:

400 - invalid_body (falta volume no tráfego; falta country, period ou operator nos endereços; corpo não é 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 (dinheiro devolvido, repita como uma nova compra), idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed (dinheiro intocado, repetir com a mesma chave é seguro), order_needs_attention (dinheiro debitado, análise manual, não repita), operation_indeterminate (repetição com a chave de uma operação cujo resultado não está definido)

GET /api/v1/packages

Pacotes do dono da chave, os mais novos primeiro. Permissão packages:read. Parâmetros: offset, limit (aqui o padrão é 200), family, product.

Parâmetro	Significado
`family`	`traffic_gateway` ou `dedicated`; valor desconhecido - sem filtro
`product`	slug: `residential`, `ipv4`; um slug que você não tem retorna lista vazia

Campo da ficha	Significado
`family`, `product`	tipo e produto do pacote
`status`	`provisioning`, `active`; no tráfego também `exhausted`, nos endereços - `expired`, `closed`, `suspended`
`name`	`tag`, se definido; caso contrário, é montado a partir do produto: `residential · 25 GB`, `ipv4 · US · United States · x10`
`traffic`	saldo de tráfego; nos endereços `null`
`expires_at`	fim do período; no tráfego `null` - o tráfego não expira
`auto_renew`	nos endereços: se o pacote é prolongado automaticamente
`endpoint`	nos endereços: `country`, `operator`, `addresses_count`; no tráfego `null`

GET /api/v1/packages/{id}

O pacote e o acesso a ele. Permissão packages:read.

Pacote de tráfego:

{
  "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 e limits são null juntos enquanto o pacote não for entregue. Pegue as linhas de conexão prontas em POST /api/v1/packages/{id}/proxies.

Pacote de endereços fixos:

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

O significado de cada campo dos endereços fixos está na página Endereços fixos.

Recusas: 404 not_found.

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

Nova senha, para os dois tipos. Permissão packages:write. O usuário não muda.

A senha antiga para de funcionar imediatamente; applies_in_seconds é o tempo máximo até a nova começar a ser aceita.

Recusas: 404 not_found; 422 package_unavailable (pacote ainda não entregue), package_expired (o período dos endereços terminou - prolongue primeiro); 500 package_failed.

Operações com o pacote de tráfego

As rotas abaixo são só para o Residential. Em um pacote de endereços fixos elas respondem 422 unsupported_capability.

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

Montar conexões. Permissão packages:write, idempotência não é necessária. O corpo é opcional.

Campo	Tipo	Padrão	Significado
`count`	integer 1..500	1	quantas linhas montar
`mode`	`rotating` \| `sticky`	`rotating`	modo de sessão
`protocol`	`http` \| `socks5`	`http`	protocolo
`ttl_minutes`	integer \| null	60	quanto tempo o endereço é mantido em `sticky`, 3..1440
`geo.country`, `geo.state`, `geo.city`, `geo.asn`	string	-	códigos do catálogo geográfico; `state`, `city`, `asn` exigem `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"
      }
    }'

No modo sticky, cada linha do conjunto leva seu próprio rótulo de sessão, ou seja, dá um endereço de saída separado, e cada uma tem sua própria rotation_url.

No modo rotating, as linhas são iguais: o endereço é escolhido a cada conexão, então N linhas dão N saídas diferentes, e não há links de troca de IP.

Um campo ausente usa o padrão, e não o valor da chamada anterior. As linhas emitidas antes continuam funcionando.

Recusas:

400 - invalid_body (tipo ou intervalo do campo)
404 - not_found
422 - invalid_targeting (com field e value: valor fora do catálogo, chave geo desconhecida, refinamento sem country), package_unavailable (pacote ainda não entregue, ttl_minutes fora de limits, modo ou protocolo não suportado), unsupported_capability

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

Recarregar volume. Permissão packages:write, Idempotency-Key obrigatório. Corpo: {"volume": 10}.

A resposta é 202 com a ficha do pacote: o novo volume aparece na ficha na hora, e o tráfego pelo novo limite começa a passar em cerca de dois minutos.

A recarga cria um pedido separado com applied_to_package_id.

Recusas:

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 (dinheiro não debitado, pode repetir), order_needs_attention (o débito foi feito, não repita), operation_indeterminate (repetição com a chave de uma operação cujo resultado não está definido)

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

Novo segredo para os links de troca de IP. Permissão packages:write. Invalida todos os links /r/{token} de uma vez; não é possível revogar um só. A resposta é o pacote inteiro.

Recusas: 404 not_found; 422 unsupported_capability.