API InovHost — Controle de VPS

1 URL base

Toda chamada é um POST para essa URL, com o parâmetro action na query string:

https://cliente.inovhost.com/modules/addons/vmware/center.php

POST https://cliente.inovhost.com/modules/addons/vmware/center.php?action=vm_power_on

2 Autenticação

Envie o token no header Authorization:

Authorization: Bearer rvps_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Para integrações que não conseguem enviar headers customizados, o token também pode ser enviado como campo do corpo do POST:

api_token=rvps_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3 Formato de resposta

Por padrão a API responde em um formato legado, baseado em tags, mantido por compatibilidade com o WHMCS. Para integrações externas, solicite JSON — envie um dos dois:

• Header Accept: application/json
• Parâmetro ?format=json na URL (ou format=json no corpo do POST)

Exemplo de resposta JSON:

{
  "result": "success",
  "msg": "Sucesso! O comando foi executado!",
  "success": true
}

success é a fonte de verdade da resposta: true quando result é exatamente "success", false em qualquer outro caso, incluindo os códigos de erro da seção 6. O texto de result/msg pode variar entre versões — a validação de sucesso deve sempre usar o campo success.

4 Ações disponíveis

Todas exigem ip (o IP dedicado da VPS) exceto conn, vm_create e vm_list (que não têm uma VPS específica associada) e vm_status (aceita ip ou service_api — veja a seção 4.1). O IP pode ser enviado com ou sem porta (191.101.x.x ou 191.101.x.x:5900) — a porta é ignorada.

Campos usados em mais de uma ação

• product — nome exato do produto conforme cadastrado no WHMCS (ex: "VPS CA 2 GB").
• service_api — identificador definido e controlado pelo sistema cliente (não é gerado pela InovHost), enviado no vm_create. Vincula a VPS ao registro interno correspondente do lado da integração e fica associado ao serviço em nossa base — é esse vínculo que permite ao vm_status localizar a VPS antes de existir um IP atribuído. Fora do vm_status, esse campo não é utilizado por nenhuma outra ação.
• source_url — opcional. URL do sistema de origem (WHMCS, WordPress, painel próprio, etc.), armazenada como metadado do pedido para fins de suporte. Só é utilizada de fato pelo AdminServicesTabFields, para montar o link de console/detalhe do domínio de origem. Quando omitida, a API reaproveita o valor salvo no momento da criação da VPS.
• billingcycle — ciclo de cobrança do pedido (ex: monthly, quarterly, annually), correspondente a um ciclo válido do produto no WHMCS.
• guest_os_version — precisa corresponder exatamente a um valor da lista de sistemas operacionais suportados, mantida pela InovHost. A lista de produtos e sistemas operacionais disponíveis é fornecida pela equipe de integração no momento do onboarding.

4.1 Exemplos

Ligar uma VPS

# liga a VPS informada
curl -X POST "https://cliente.inovhost.com/modules/addons/vmware/center.php?action=vm_power_on&format=json" \
  -H "Authorization: Bearer rvps_SEU_TOKEN_AQUI" \
  -d "ip=191.101.20.15"

Resposta:

{ "result": "success", "msg": "Sucesso! O comando foi executado!", "success": true }

Criar uma VPS nova

curl -X POST "https://cliente.inovhost.com/modules/addons/vmware/center.php?action=vm_create&format=json" \
  -H "Authorization: Bearer rvps_SEU_TOKEN_AQUI" \
  -d "product=VPS CA 2 GB" \
  -d "service_api=meu-id-interno-123" \
  -d "billingcycle=monthly" \
  -d "guest_os_version=Ubuntu 20.04"

Consultar se a VPS já ficou pronta (vm_status)

A criação (vm_create) é assíncrona: o pedido é aceito imediatamente, mas o provisionamento acontece em uma fila interna.

vm_status aceita dois identificadores, com prioridade para ip: utilize ip ao consultar uma VPS já existente; utilize service_api enquanto a VPS ainda está em provisionamento e não possui IP atribuído. Quando ip é enviado e localizado, ele é usado; service_api funciona como fallback, aplicado apenas se ip não for enviado ou não corresponder a nenhuma VPS.

Consultando por ip (VPS que já existe):

curl -X POST "https://cliente.inovhost.com/modules/addons/vmware/center.php?action=vm_status&format=json" \
  -H "Authorization: Bearer rvps_SEU_TOKEN_AQUI" \
  -d "ip=191.101.20.15"

Consultando por service_api (logo após um vm_create, ainda sem IP) — faça polling a cada 5 minutos até ready retornar true:

curl -X POST "https://cliente.inovhost.com/modules/addons/vmware/center.php?action=vm_status&format=json" \
  -H "Authorization: Bearer rvps_SEU_TOKEN_AQUI" \
  -d "service_api=meu-id-interno-123"

{
  "result": "success",
  "domain_status": "Pending",
  "ip": "",
  "ready": "0",
  "msg": "Status consultado com sucesso!",
  "success": true
}

{
  "result": "success",
  "domain_status": "Active",
  "ip": "191.101.20.15",
  "ready": "1",
  "msg": "Status consultado com sucesso!",
  "success": true
}

domain_status segue os valores padrão do WHMCS (Pending, Active, Suspended, Terminated, Cancelled). Use o campo ready como sinal definitivo de "pronta para uso" — só vem "1" quando o status é Active e já existe um IP atribuído.

Listar todas as VPS do revendedor (vm_list)

Não requer nenhum campo além do token — a busca já é restrita ao revendedor dono do token (client_id). Essa ação sempre responde em JSON, independente de header Accept ou do parâmetro format: o formato legado de tags não se aplica a listas, já que é um recurso voltado exclusivamente a integrações externas.

curl -X POST "https://cliente.inovhost.com/modules/addons/vmware/center.php?action=vm_list" \
  -H "Authorization: Bearer rvps_SEU_TOKEN_AQUI"

Resposta:

{
  "result": "success",
  "msg": "Lista consultada com sucesso!",
  "success": true,
  "count": 2,
  "vms": [
    {
      "sid": 481,
      "ip": "191.101.20.15",
      "product": "VPS CA 2 GB",
      "domain_status": "Active",
      "service_api": "meu-id-interno-123",
      "billingcycle": "Monthly",
      "regdate": "2026-05-10",
      "ready": true
    },
    {
      "sid": 502,
      "ip": "",
      "product": "VPS CA 4 GB",
      "domain_status": "Pending",
      "service_api": "meu-id-interno-456",
      "billingcycle": "Monthly",
      "regdate": "2026-07-01",
      "ready": false
    }
  ]
}

5 Avisos importantes

Comportamentos e limitações que precisam ser considerados antes de integrar.

6 Erros

Resposta de erro (formato JSON):

{ "result": "error12", "msg": "Erro! Não foi possível autenticá-lo", "success": false }