API para desenvolvedores

Você pode comprar e gerenciar proxies a partir do seu próprio código: fazer pedidos, ler pacotes, prolongar, acompanhar eventos. Tudo o que você compra vira um pacote. Há dois tipos de pacote, diferenciados pelo campo family:

	Residential	IPv4
family	traffic_gateway	dedicated
O que você compra	volume de tráfego em gigabytes	N endereços dedicados por um período
Como você paga	por gigabytes, o tráfego não expira	por endereço por período: semana, 2 semanas, mês, 2 ou 3 meses
Conexões	você monta quantas linhas quiser com qualquer geo	lista fixa de endereços com um único usuário e senha
Troca de IP	rotação ou link de troca de IP	substituição de todos os endereços do pacote a cada 30 dias
Produto	Residential	IPv4

Compra, lista de pacotes e ficha do pacote são rotas comuns aos dois tipos. As operações que só existem em um tipo são descritas à parte: tráfego e endereços fixos.

URL base e autenticação

https://ipv.rent

curl https://ipv.rent/api/v1/balance \
  -H 'Authorization: Bearer YOUR_API_KEY'

Cadastre-se em app.ipv.rent e depois confirme seu e-mail: sem a confirmação você não consegue entrar.

A chave é criada no painel: Perfil → Chaves de API → Criar chave. O segredo aparece uma única vez, e cada conta mantém até 20 chaves ativas.

Uma chave revogada deixa de ser aceita na hora, e o evento api_key.revoked entra no log.

401 invalid_api_key - a chave não foi aceita. 403 insufficient_scope - a chave não tem a permissão exigida pela rota.

Os esquemas de requisição e resposta com todos os campos e exemplos estão na referência OpenAPI.

Permissões da chave

Uma chave criada sem indicar permissões recebe todas. O conjunto de uma chave já criada não pode ser alterado.

Permissão	O que libera
catalog:read	produtos e seus parâmetros, catálogo geográfico, cálculo de preço
packages:read	lista de pacotes, ficha do pacote, opções de prolongamento
packages:write	compra e todas as operações com pacotes: recarga de volume, conexões, senha, prolongamento, substituição de endereços, impressão digital, renovação automática
orders:read	pedidos
orders:write	reservada - hoje nenhuma rota a exige
billing:read	saldo e transações
events:read	log de eventos

Rotas

Catálogo e compra - para os dois tipos:

Rota	Permissão	Idempotency-Key
GET /api/v1/products	catalog:read	-
GET /api/v1/products/{product}/options	catalog:read	-
POST /api/v1/quote	catalog:read	não
POST /api/v1/packages	packages:write	obrigatório
GET /api/v1/packages	packages:read	-
GET /api/v1/packages/{id}	packages:read	-
POST /api/v1/packages/{id}/password	packages:write	não

Somente Residential:

Rota	Permissão	Idempotency-Key
GET /api/v1/geo/countries, /states, /cities, /asns	catalog:read	-
POST /api/v1/packages/{id}/proxies	packages:write	não
POST /api/v1/packages/{id}/topup	packages:write	obrigatório
POST /api/v1/packages/{id}/rotation-secret	packages:write	não

Somente IPv4:

Rota	Permissão	Idempotency-Key
GET /api/v1/packages/{id}/prolong-options	packages:read	-
POST /api/v1/packages/{id}/prolong	packages:write	obrigatório
POST /api/v1/packages/{id}/replace	packages:write	não
POST /api/v1/packages/{id}/fingerprint	packages:write	não
POST /api/v1/packages/{id}/renewal	packages:write	não

Conta:

Rota	Permissão	Idempotency-Key
GET /api/v1/orders, /orders/{id}	orders:read	-
GET /api/v1/balance, /transactions	billing:read	-
GET /api/v1/events	events:read	-

Uma operação do outro tipo sobre um pacote responde 422 unsupported_capability.

A recarga de saldo e o gerenciamento de chaves ficam só no painel.

Limites

120 requisições por minuto por chave, mais 30 por minuto para requisições que alteram algo (POST). Toda resposta traz RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; ao exceder - 429 com retry_after e Retry-After: aguarde o número de segundos indicado e repita.

Suporte

Telegram: @ipvrent_support, e-mail [email protected]. Anexe o request_id do corpo da recusa.

Novidades e status do serviço no canal t.me/ipvrent.