Endereços fixos

Operações com o pacote de endereços fixos (family: dedicated, produto ipv4). Cada uma vale para o pacote inteiro: para todos os seus endereços de uma vez. Em um pacote de tráfego essas rotas respondem 422 unsupported_capability.

As operações disponíveis para o pacote estão listadas em capabilities da sua ficha: prolong, credentials, replace, fingerprint, renewal.

Período e status

Status	O que acontece	O que fazer
provisioning	o pacote está sendo entregue, até 2 minutos	aguardar
active	os endereços funcionam até expires_at	tudo
expired	o período terminou, os endereços não respondem	prolongar até extendable_until - os mesmos endereços voltam
closed	extendable_until passou, os endereços foram liberados	só uma nova compra
suspended	o pacote foi desativado	falar com o suporte

Campos da ficha relacionados ao período:

Campo	Significado
expires_at	fim do período pago
extendable_until	até quando o prolongamento devolve os mesmos endereços
credentials_retired	true - a senha foi desativada após o fim do período; o prolongamento emitirá uma nova

Quando o período termina, package.expired chega ao log de eventos.

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

Para quais períodos é possível prolongar e quanto custa para você. Permissão 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 é o preço do pacote inteiro, de todos os seus endereços.

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

Prolongar o pacote. Permissão packages:write, Idempotency-Key obrigatório: é um débito. Corpo: {"period": "month"}, com o período vindo 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
}

• O período é somado ao expires_at atual ou, se o período já terminou, ao momento do prolongamento.
• Os endereços e o usuário continuam os mesmos.
• credentials_reissued: true - a senha antiga foi desativada e uma nova foi emitida; pegue-a na ficha do pacote.
• O prolongamento cria um pedido separado com applied_to_package_id.

Recusas:

• 400 - invalid_body (sem corpo ou não é JSON), validation_failed
• 404 - not_found
• 409 - idempotency_in_progress
• 422 - unknown_period, insufficient_balance, prolong_window_closed (não é mais possível recuperar os endereços - pacote closed, é preciso uma nova compra), unsupported_capability, purchase_refunded, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
• 500 - order_failed, order_needs_attention, operation_indeterminate - como na compra

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

Renovação automática. Permissão packages:write. Não debita 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	obrigatório: true ou false
period	por qual período prolongar a cada vez; sem o campo, mantém o atual

A resposta é a ficha do pacote. Como funciona a renovação automática:

• ela vem ativada por padrão, com o período que foi comprado;
• o débito ocorre um dia antes de expires_at, pelo preço daquele momento; data e valor ficam em renewal.next_charge_at e renewal.next_charge_amount;
• se faltar dinheiro, renewal.last_failure passa a insufficient_balance, e as tentativas se repetem a cada poucas horas por mais 3 dias após expires_at;
• depois disso a renovação automática se desativa sozinha, e renewal.disabled_at é preenchido.

Recusas: 400 invalid_body (sem enabled); 404 not_found; 422 unknown_period, unsupported_capability.

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

Substituir todos os endereços do pacote por novos no mesmo local. Permissão packages:write. Sem corpo. Gratuito.

A substituição roda em segundo plano. A resposta é 202 com a ficha e replacement.state: pending. Leia a ficha até state mudar, normalmente em menos de um minuto:

replacement.state	Significado
pending	substituição em andamento
done	addresses traz os novos endereços, os antigos não funcionam
failed	nada mudou, é possível pedir de novo

Usuário, senha, período e impressão digital não mudam. Uma nova substituição é possível após 30 dias: replace_available_at na ficha mostra quando.

Recusas:

• 404 - not_found
• 409 - replace_in_progress (a substituição já está em andamento)
• 422 - package_expired (o período terminou - prolongue primeiro), unsupported_capability
• 429 - replace_cooldown (os endereços foram substituídos recentemente; a data está em replace_available_at)

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

Impressão digital p0f: os endereços se apresentam como o SO e o navegador escolhidos. Um perfil para o pacote inteiro. Permissão packages:write. Gratuito.

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 é um valor de fingerprint.profiles da ficha: windows_chrome, windows_edge, windows_firefox, android_chrome, macos_chrome. null desativa a falsificação.

A nova impressão digital é aplicada em 2-3 minutos. Conexões abertas antes da mudança mantêm a anterior - reconecte-se.

Recusas: 400 validation_failed (perfil fora da lista); 404 not_found; 422 package_expired, unsupported_capability.

Senha

A geração de nova senha usa a rota comum POST /api/v1/packages/{id}/password. O usuário não muda, e a senha antiga para de funcionar na hora em todos os endereços do pacote.