CLOUD PRIME API

VPS

VPS

Endpoints para gerenciar as instâncias VPS da sua conta: listar, provisionar, controlar energia, consultar status e métricas, trocar a senha, gerenciar chaves SSH e resetar. Todas as rotas exigem autenticação e operam apenas sobre as VPS que pertencem ao cliente autenticado.

Listar VPS

GET /api/vps

Lista todas as VPS do cliente autenticado, em formato resumido.

Exemplo de resposta

{
    "data": [
        {
            "id": "9f1c8a2e-3b4d-4c5e-9a1b-2c3d4e5f6a7b",
            "hostname": "vps-web-01.cliente.com.br",
            "ipv4": "203.0.113.10",
            "ipv6": "2001:db8:abcd::10",
            "power_state": "running",
            "is_online": true,
            "os": "Ubuntu 22.04 LTS",
            "datacenter": {
                "id": "4a2b1c3d-...",
                "name": "Sudeste - SE1",
                "location": "São Paulo, BR"
            },
            "service": {
                "id": "7c8d9e0f-...",
                "name": "VPS Cloud 4GB",
                "status": "active"
            }
        }
    ]
}

Provisionar VPS

POST /api/vps/provision

Provisiona uma nova VPS. O pagamento é automático: a plataforma tenta usar créditos primeiro e, se insuficiente, cobra no cartão padrão. Responde 201 em caso de sucesso. Os IDs vêm de Produtos (product_id) e Datacenters (datacenter_id, os_template_id).

Corpo (JSON)

Campo Tipo Descrição
product_id obrigatório uuid ID do produto VPS (ativo e do tipo VPS).
datacenter_id obrigatório uuid ID do datacenter (deve ter IPs disponíveis).
os_template_id obrigatório uuid ID do template de sistema operacional.
root_password obrigatório string (8–128) Senha root da VPS.
billing_cycle string Ciclo contratado: monthly, quarterly, semiannually ou annually. Padrão monthly. Precisa estar entre os billing_cycles do produto.
hostname string (≤253) Hostname desejado. Gerado automaticamente se omitido.
ssh_public_key string Chave pública SSH a injetar na VPS.
addons object Mapa { resource_id: quantidade }. Addons obrigatórios são incluídos automaticamente.
Contratando por mais de um mês
Sem billing_cycle, a contratação é mensal. Com ele, você cobra o termo inteiro de uma vez e a próxima cobrança já pula para o fim do período — data.billing_cycle devolve o ciclo, os meses, o valor cobrado e a data da renovação.

Os ciclos válidos são os que o produto listar em billing_cycles nos Produtos. Um ciclo fora dessa lista retorna 422: não há queda silenciosa para mensal, porque uma integração não teria como perceber a troca e acabaria contratando um ano ao preço de um mês.

O desconto do ciclo é do plano. Os addons são cobrados pelo preço mensal repetido a cada mês do termo, sem desconto — um addon de R$ 10 num plano anual soma R$ 120.

O status vem na resposta — você não envia esse campo
No corpo 201, data.status reflete o resultado do pagamento: provisioning = pagamento confirmado e provisionamento já iniciado; pending_payment = cobrança ainda não confirmada pelo gateway (o provisionamento dispara automaticamente quando o pagamento confirmar). Já os erros de regra de negócio (produto inativo, datacenter sem IP, cartão expirado) nem chegam a criar a VPS — retornam 422.

Exemplo de resposta

{
    "success": true,
    "data": {
        "service_id": "7c8d9e0f-...",
        "vps_id": "9f1c8a2e-...",
        "status": "provisioning",
        "hostname": "vps-web-01.cliente.com.br",
        "ssh_port": 22,
        "product": {
            "id": "1a2b3c4d-...",
            "name": "VPS Cloud 4GB"
        },
        "billing_cycle": {
            "cycle": "annually",
            "months": 12,
            "price": 970.92,
            "next_billing_date": "2027-06-28T00:00:00+00:00"
        },
        "invoice": {
            "invoice_number": "INV-2026-000123",
            "amount": 970.92,
            "status": "paid"
        },
        "payment": {
            "method": "card",
            "credits_used": 0,
            "card_last_digits": "4242"
        }
    }
}

Detalhar VPS

GET /api/vps/{id}

Retorna os detalhes completos de uma VPS: acesso, serviço, tráfego, monitoramento, backup e timestamps.

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS (deve pertencer à sua conta).
A senha root nunca é exposta — apenas access.has_root_password. Retorna 404 se a VPS não existir ou não for sua.

Exemplo de resposta

{
    "data": {
        "id": "9f1c8a2e-...",
        "hostname": "vps-web-01.cliente.com.br",
        "ipv4": "203.0.113.10",
        "power_state": "running",
        "is_online": true,
        "os": "Ubuntu 22.04 LTS",
        "service": {
            "name": "VPS Cloud 4GB",
            "status": "active",
            "price": 89.9,
            "billing_cycle": "monthly",
            "next_billing_date": "2026-07-28T00:00:00+00:00"
        },
        "access": {
            "has_root_password": true,
            "ipv4": "203.0.113.10",
            "ssh_port": 22
        },
        "traffic": {
            "used": 5368709120,
            "limit": 1099511627776,
            "percentage": 0.49,
            "formatted": "5 GB / 1 TB"
        },
        "backup": {
            "enabled": true,
            "schedule": "daily",
            "last_backup_at": "2026-06-28T03:00:00+00:00"
        }
    }
}

Ligar VPS

POST /api/vps/{id}/start

Inicia (liga) a VPS. Retorna 409 se ela já estiver ligada.

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS.

Exemplo de resposta

{
    "message": "VPS start initiated",
    "data": {
        "id": "9f1c8a2e-...",
        "hostname": "vps-web-01.cliente.com.br",
        "power_state": "running"
    }
}

Desligar VPS

POST /api/vps/{id}/stop

Desliga a VPS de forma graciosa (shutdown). Retorna 409 se já estiver desligada.

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS.

Exemplo de resposta

{
    "message": "VPS stop initiated",
    "data": {
        "id": "9f1c8a2e-...",
        "hostname": "vps-web-01.cliente.com.br",
        "power_state": "stopped",
        "is_online": false
    }
}

Reiniciar VPS

POST /api/vps/{id}/restart

Reinicia a VPS. Retorna 409 se ela estiver desligada (use ligar).

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS.

Exemplo de resposta

{
    "message": "VPS restart initiated",
    "data": {
        "id": "9f1c8a2e-...",
        "hostname": "vps-web-01.cliente.com.br",
        "power_state": "running"
    }
}

Forçar desligamento

POST /api/vps/{id}/force-stop

Força o desligamento imediato (hard shutdown). Retorna 409 se já estiver desligada.

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS.

Exemplo de resposta

{
    "message": "VPS force stop initiated",
    "data": {
        "id": "9f1c8a2e-...",
        "hostname": "vps-web-01.cliente.com.br",
        "power_state": "stopped",
        "is_online": false
    }
}

Status da VPS

GET /api/vps/{id}/status

Estado de energia atual, uptime e timestamps. uptime é null quando a VPS não está rodando.

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS.

Exemplo de resposta

{
    "data": {
        "id": "9f1c8a2e-...",
        "power_state": "running",
        "is_online": true,
        "uptime": "2d 4h 15m",
        "timestamps": {
            "last_started_at": "2026-06-26T09:50:00+00:00",
            "last_ping_at": "2026-06-28T14:00:00+00:00"
        }
    }
}

Métricas da VPS

GET /api/vps/{id}/metrics

Tráfego, rede, monitoramento, backup, uso de disco e séries temporais (RRD do Proxmox).

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS.

Query string

Campo Tipo Descrição
timeframe hour|day|week|month|year Janela do gráfico. Padrão: hour.
Unidades dos pontos: time em segundos Unix; cpu fração 0..1; memória e disco em bytes; netin/netout/diskread/diskwrite em bytes por segundo. Sem provisionamento ou nó inacessível, charts.points vem [] com HTTP 200.

Exemplo de resposta

{
    "data": {
        "id": "9f1c8a2e-...",
        "traffic": {
            "used": 5368709120,
            "limit": 1099511627776,
            "percentage": 0.49,
            "exceeded": false
        },
        "disk": {
            "used": 12884901888,
            "total": 85899345920,
            "percentage": 15,
            "source": "storage-allocation"
        },
        "charts": {
            "timeframe": "hour",
            "points": [
                {
                    "time": 1782658800,
                    "cpu": 0.0423,
                    "mem": 1610612736,
                    "maxmem": 4294967296,
                    "netin": 10485,
                    "netout": 8192
                }
            ]
        }
    }
}

Trocar senha

POST /api/vps/{id}/password

Troca a senha do usuário no SO da VPS (via guest agent, na hora). A VPS precisa estar ligada e com o guest agent disponível. Não altera o cloud-init.

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS.

Corpo (JSON)

Campo Tipo Descrição
username root|administrator Usuário alvo. Padrão: root.
password obrigatório string (8–72) Nova senha.
password_confirmation obrigatório string Confirmação da senha (igual a password).
VPS desligada → 409. Guest agent indisponível → 409. Sucesso → 200.

Templates de SO da VPS

GET /api/vps/{id}/os-templates

Lista os templates de SO disponíveis no datacenter desta VPS — use um id daqui no reset (troca de SO).

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS.

Exemplo de resposta

{
    "data": [
        {
            "id": "5e1b0c9a-...",
            "display_name": "Ubuntu 22.04 LTS",
            "os_family": "linux",
            "os_type": "ubuntu",
            "additional_price": 0,
            "min_requirements": {
                "cpu_cores": 1,
                "ram_gb": 1,
                "storage_gb": 10
            }
        }
    ]
}

Resetar (reinstalar)

POST /api/vps/{id}/reset

Reseta a VPS para uma instalação limpa do SO (enfileirado). Destrutivo: apaga todos os dados da VPS. Pode trocar o SO por outro template do mesmo datacenter (ver templates da VPS). Responde 202.

Parâmetros de rota

Campo Tipo Descrição
id obrigatório uuid ID da VPS.

Corpo (JSON)

Campo Tipo Descrição
os_template_id obrigatório uuid Template de SO (deve ser do datacenter da VPS).
confirm obrigatório boolean Deve ser true — confirma a operação destrutiva.
keep_password boolean Manter a senha atual. Padrão: true.
new_password string (8–72) Nova senha (obrigatória se keep_password=false).
keep_ssh_keys boolean Manter as chaves SSH atuais. Padrão: true.
ssh_key_ids uuid[] Chaves a aplicar quando keep_ssh_keys=false.
Pré-condições: VPS provisionada, com IP, serviço ativo e não em reset — senão 409. Template de outro datacenter → 422.