API do Virtualizor para revendedores: primeiros passos

Este é o ponto de partida da documentação da API do Virtualizor para quem tem revenda de VPS na Vitt Host — a conta Cloud do painel. Com a API, o seu sistema (a sua loja, a sua área do cliente, um script) faz o que você faria clicando no painel: criar o cliente, criar a VPS dele dentro da sua cota, ligar, suspender, reinstalar, fazer backup.

O que você precisa

• O endereço do seu painel. As chamadas vão para a porta 4083, com HTTPS.
• Uma chave de API: o par apikey e apipass.
• Um servidor seu de onde as chamadas partem. A chave dá controle sobre todas as VPS da conta: ela não pode ir para o navegador do cliente.

1. Gere a chave de API no painel

Entre no painel com a sua conta de revenda e abra a área de credenciais de API (API Credentials, no menu da conta). Gere uma chave e guarde o apikey e o apipass num lugar seguro.

Daí em diante, dá para criar, listar e revogar chaves pela própria API (artigo API do Virtualizor: chaves SSH, firewall e chaves de API). Uma chave por sistema que acessa facilita revogar só a que vazou.

2. O formato de toda chamada

Toda chamada é para o mesmo endereço, e o que muda é a ação:

https://SEU-PAINEL:4083/index.php?act=ACAO&api=json&apikey=SUA_APIKEY&apipass=SUA_APIPASS

• act diz o que fazer: listvs lista VPS, create cria, start liga…
• api=json pede a resposta em JSON. Sem ele, a resposta não vem em JSON.
• O id da VPS vai na URL, quase sempre como svs.
• Quem só lê usa GET. Quem altera manda os campos no corpo de um POST (application/x-www-form-urlencoded).
• Quase toda alteração exige um campo de confirmação (addvs=1, changepass=1, do=1…). Sem ele, a chamada só devolve os dados da tela, sem mudar nada — os artigos dizem qual é o de cada ação.

3. A resposta

Vem em JSON. Além dos dados da ação, toda resposta traz informações da conta (uid, username, preferences…), que você pode ignorar.

• Deu certo: nas alterações, vem o campo done.
• Deu errado: vem o campo error, com as mensagens. Confira sempre — a resposta HTTP pode ser 200 mesmo com erro.

4. Teste com curl

# Uma vez por terminal:
export VIRT_HOST='endereco-do-seu-painel'
export VIRT_KEY='sua-apikey'
export VIRT_PASS='sua-apipass'

# Teste: a cota da sua conta Cloud.
curl -sS "https://$VIRT_HOST:4083/index.php?act=cloudres&api=json&apikey=$VIRT_KEY&apipass=$VIRT_PASS"

5. As funções usadas nos exemplos

Todos os artigos mostram cada chamada em curl, PHP, Python e Node.js. Os exemplos em PHP, Python e Node usam uma função virt_api (no Node, virtApi), que monta a URL, manda os campos e confere o error. Copie a da sua linguagem:

PHP

<?php
// virt_api.php — chamada à API do Virtualizor (usuário final / Cloud).
// Credenciais por variável de ambiente, nunca no código:
//   VIRT_HOST (endereço do painel), VIRT_KEY (apikey), VIRT_PASS (apipass)
function virt_api(string $act, array $get = [], array $post = []): array
{
    $query = ['act' => $act] + $get + [
        'api'     => 'json',
        'apikey'  => getenv('VIRT_KEY'),
        'apipass' => getenv('VIRT_PASS'),
    ];
    $url = 'https://' . getenv('VIRT_HOST') . ':4083/index.php?' . http_build_query($query);

    $ch = curl_init($url);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 120]);
    if ($post) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post));
    }
    $corpo = curl_exec($ch);
    if ($corpo === false) {
        throw new RuntimeException('Falha de conexão: ' . curl_error($ch));
    }

    $dados = json_decode($corpo, true);
    if (!is_array($dados)) {
        throw new RuntimeException('Resposta que não é JSON: ' . substr($corpo, 0, 200));
    }
    if (!empty($dados['error'])) {
        throw new RuntimeException('Erro da API: ' . json_encode($dados['error']));
    }
    return $dados;
}

Python

# virt_api.py — chamada à API do Virtualizor (usuário final / Cloud).
# pip install requests
# Credenciais por variável de ambiente: VIRT_HOST, VIRT_KEY, VIRT_PASS
import os
import requests

def virt_api(act, get=None, post=None):
    params = {
        "act": act,
        **(get or {}),
        "api": "json",
        "apikey": os.environ["VIRT_KEY"],
        "apipass": os.environ["VIRT_PASS"],
    }
    url = f"https://{os.environ['VIRT_HOST']}:4083/index.php"
    if post:
        r = requests.post(url, params=params, data=post, timeout=120)
    else:
        r = requests.get(url, params=params, timeout=120)
    r.raise_for_status()
    dados = r.json()
    if dados.get("error"):
        raise RuntimeError(f"Erro da API: {dados['error']}")
    return dados

Node.js

// virt_api.mjs — chamada à API do Virtualizor (usuário final / Cloud).
// Node.js 18 ou mais novo (fetch nativo). Rode como módulo (.mjs).
// Credenciais por variável de ambiente: VIRT_HOST, VIRT_KEY, VIRT_PASS
export async function virtApi(act, get = {}, post = null) {
  const url = new URL(`https://${process.env.VIRT_HOST}:4083/index.php`);
  url.search = new URLSearchParams({
    act,
    ...get,
    api: 'json',
    apikey: process.env.VIRT_KEY,
    apipass: process.env.VIRT_PASS,
  });

  const corpo = new URLSearchParams();
  for (const [nome, valor] of Object.entries(post ?? {})) {
    // Lista vira o campo repetido com [] (ssh_keys[], sel_serv[]...).
    if (Array.isArray(valor)) valor.forEach((v) => corpo.append(`${nome}[]`, v));
    else corpo.append(nome, valor);
  }

  const resp = await fetch(url, post ? { method: 'POST', body: corpo } : {});
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const dados = await resp.json();
  if (dados.error && Object.keys(dados.error).length) {
    throw new Error(`Erro da API: ${JSON.stringify(dados.error)}`);
  }
  return dados;
}

6. O fluxo de revenda de ponta a ponta

Do pedido do seu cliente à VPS no ar, em PHP com a função acima. Cada passo está detalhado no artigo dele.

<?php
require 'virt_api.php';

// 1. Cabe? A cota livre é a contratada (resources) menos o usado (usage).
$cota = virt_api('cloudres');
$livreRam = $cota['resources']['ram'] - ($cota['usage']['ram'] ?? 0);

// 2. O cliente: crie o usuário e descubra o id dele pelo e-mail.
virt_api('adduser', [], [
    'adduser' => 1,
    'user_email' => 'cliente@exemplo.com.br',
    'user_password' => 'Senha-Do-Cliente-2026',
]);
$uid = null;
foreach (virt_api('users')['user_list'] as $id => $u) {
    if ($u['email'] === 'cliente@exemplo.com.br') $uid = $id;
}

// 3. A VPS dele. O osid sai de ostemplates, na resposta de act=create.
$vps = virt_api('create', [], [
    'addvs' => 1, 'virt' => 'kvm', 'uid' => $uid,
    'hostname' => 'vps1.exemplo.com.br', 'rootpass' => 'Senha-Root-Forte-2026',
    'osid' => 'ID_DO_SISTEMA', 'space' => 20, 'ram' => 2048,
    'cores' => 2, 'ips' => 1, 'bandwidth' => 0,
]);
$vpsid = $vps['vpsid'];

// 4. O botão "Gerenciar servidor" da sua área do cliente: link sem senha.
$sso = virt_api('sso', ['svs' => $vpsid]);

Na inadimplência, suspenda a VPS (act=listvs&suspend=ID) em vez de apagar; no cancelamento, apague (act=listvs&delvs=ID) depois do backup, se o cliente quiser os dados. As duas estão no artigo de energia e suspensão e no de VPS.

Segurança

• A chave fica no servidor. Nunca em JavaScript de página, aplicativo de celular ou repositório de código. Use variável de ambiente ou cofre de segredos.
• A chave vai na URL, e URL aparece em log de servidor e de proxy. Não registre a URL completa das chamadas no seu sistema.
• Não desligue a verificação do certificado. A documentação oficial usa curl -k, que aceita qualquer certificado — inclusive o de quem estiver interceptando a conexão. Os exemplos daqui não usam.
• Senhas viajam no corpo de várias chamadas (root, cliente, VNC). Não registre o corpo em log.
• Vazou? Crie uma chave nova e apague a antiga (artigo de segurança).

Todos os artigos

1. API do Virtualizor: conta Cloud, cota e cobrança — 6 endpoints
2. API do Virtualizor: clientes da revenda e login único (SSO) — 5 endpoints
3. API do Virtualizor: criar, editar e apagar VPS — 6 endpoints
4. API do Virtualizor: ligar, desligar, reiniciar e suspender VPS — 10 endpoints
5. API do Virtualizor: hostname, senha root, reinstalação e receitas — 8 endpoints
6. API do Virtualizor: VNC, modo de resgate e ISO — 7 endpoints
7. API do Virtualizor: IPs, sub-redes, DNS reverso e redirecionamento — 9 endpoints
8. API do Virtualizor: servidores e registros de DNS — 7 endpoints
9. API do Virtualizor: chaves SSH, firewall e chaves de API — 13 endpoints
10. API do Virtualizor: backups e volumes — 8 endpoints
11. API do Virtualizor: estatísticas, logs, processos e serviços — 14 endpoints

Para achar um endpoint pelo nome ou pela ação, e montar o comando com os seus valores, use a busca da API do Virtualizor no site.

Sobre esta documentação

Escrita pela Vitt Host a partir da documentação oficial da Virtualizor, lida em 07/10/2026. Ela cobre os 93 endpoints da API do usuário final. A documentação oficial se contradiz em vários pontos — a tabela de parâmetros diz uma coisa e o exemplo, outra. Nesses casos, os artigos seguem os exemplos oficiais, que trazem a chamada completa, e apontam a diferença em Cuidados. Referência original: Enduser API.