LRV Cloud Manager — Infraestrutura Cloud

Introdução

A API pública do LRV Cloud Manager permite gerenciar VPS, domínios, tickets, assinaturas e muito mais de forma programática. Use API Keys ou Bearer Tokens para autenticar.

Base URL: https://cloud.lrvweb.com.br/api/v1/

Formato: todas as respostas são JSON. Envie Content-Type: application/json no body de POST/PUT.

# Listar seus servidores VPS
curl -H "X-API-Key: lrv_live_sua_chave" \
     https://cloud.lrvweb.com.br/api/v1/hosting

// PHP com cURL
$ch = curl_init('https://cloud.lrvweb.com.br/api/v1/hosting');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['X-API-Key: lrv_live_sua_chave'],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response['data']);

// JavaScript (fetch API)
const response = await fetch('https://cloud.lrvweb.com.br/api/v1/hosting', {
    headers: { 'X-API-Key': 'lrv_live_sua_chave' }
});
const { data } = await response.json();
console.log(data);

# Python com requests
import requests

response = requests.get(
    'https://cloud.lrvweb.com.br/api/v1/hosting',
    headers={'X-API-Key': 'lrv_live_sua_chave'}
)
data = response.json()['data']
print(data)

Autenticação

Existem duas formas de autenticar: via API Key direta no header ou usando Bearer Token obtido a partir da API Key.

1. API Key (recomendado para servidores)

Envie sua chave no header X-API-Key em cada requisição. Simples e direto.

curl -H "X-API-Key: lrv_live_abc123..." \
     https://cloud.lrvweb.com.br/api/v1/tickets

$headers = ['X-API-Key: lrv_live_abc123...'];

$ch = curl_init('https://cloud.lrvweb.com.br/api/v1/tickets');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);

const res = await fetch('https://cloud.lrvweb.com.br/api/v1/tickets', {
    headers: { 'X-API-Key': 'lrv_live_abc123...' }
});

import requests
res = requests.get(
    'https://cloud.lrvweb.com.br/api/v1/tickets',
    headers={'X-API-Key': 'lrv_live_abc123...'}
)

2. Bearer Token (recomendado para apps client-side)

Troque sua API Key por um token de curta duração (1h). Ideal para aplicações que não devem expor a API Key diretamente.

# Passo 1: Obter token
curl -X POST https://cloud.lrvweb.com.br/api/v1/auth/token \
     -H "Content-Type: application/json" \
     -d '{"api_key": "lrv_live_abc123..."}'

# Resposta:
# {"success":true,"data":{"access_token":"eyJ...","refresh_token":"rft...","expires_in":3600}}

# Passo 2: Usar o token
curl -H "Authorization: Bearer eyJ..." \
     https://cloud.lrvweb.com.br/api/v1/hosting

# Passo 3: Renovar quando expirar
curl -X POST https://cloud.lrvweb.com.br/api/v1/auth/refresh \
     -H "Content-Type: application/json" \
     -d '{"refresh_token": "rft..."}'

// Passo 1: Obter token
$ch = curl_init('https://cloud.lrvweb.com.br/api/v1/auth/token');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['api_key' => 'lrv_live_abc123...']),
    CURLOPT_RETURNTRANSFER => true,
]);
$tokens = json_decode(curl_exec($ch), true)['data'];

// Passo 2: Usar o token
$ch = curl_init('https://cloud.lrvweb.com.br/api/v1/hosting');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $tokens['access_token']]);

// Passo 1: Obter token
const { data: tokens } = await fetch('https://cloud.lrvweb.com.br/api/v1/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ api_key: 'lrv_live_abc123...' })
}).then(r => r.json());

// Passo 2: Usar o token
const vps = await fetch('https://cloud.lrvweb.com.br/api/v1/hosting', {
    headers: { 'Authorization': `Bearer ${tokens.access_token}` }
}).then(r => r.json());

import requests

# Passo 1: Obter token
tokens = requests.post(
    'https://cloud.lrvweb.com.br/api/v1/auth/token',
    json={'api_key': 'lrv_live_abc123...'}
).json()['data']

# Passo 2: Usar o token
vps = requests.get(
    'https://cloud.lrvweb.com.br/api/v1/hosting',
    headers={'Authorization': f'Bearer {tokens["access_token"]}'}
).json()

Escopos (Permissions)

Cada API Key tem escopos que definem o que ela pode acessar. Se tentar acessar um recurso sem o escopo necessário, receberá HTTP 403.

Escopos disponíveis: hosting.read hosting.write tickets.read tickets.write domains.read domains.write billing.read billing.write backups.read backups.write monitoring.read databases.read databases.write applications.read applications.write emails.read emails.write webhooks.read webhooks.write

Primeiros Passos

Integrar com a API leva menos de 5 minutos:

Crie uma API Key no painel: Painel → API Keys → Criar
Escolha os escopos que sua integração precisa (ex: hosting.read, tickets.write)
Faça sua primeira chamada usando o exemplo abaixo
Teste no Sandbox primeiro com chave lrv_test_ (writes são simulados, reads retornam dados reais)
Troque para Production mudando para chave lrv_live_

Exemplo completo: Criar um ticket via API

curl -X POST https://cloud.lrvweb.com.br/api/v1/tickets \
     -H "X-API-Key: lrv_live_sua_chave" \
     -H "Content-Type: application/json" \
     -d '{
       "subject": "Problema no servidor",
       "message": "O site está lento desde as 14h.",
       "priority": "high",
       "department": "suporte"
     }'

# Resposta (201 Created):
{
  "success": true,
  "message": "Ticket created successfully.",
  "data": {
    "id": 42,
    "subject": "Problema no servidor",
    "status": "open",
    "priority": "high"
  }
}

$apiKey = 'lrv_live_sua_chave';

$ch = curl_init('https://cloud.lrvweb.com.br/api/v1/tickets');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'subject'  => 'Problema no servidor',
        'message'  => 'O site está lento desde as 14h.',
        'priority' => 'high',
        'department' => 'suporte',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['success']) {
    echo "Ticket #" . $response['data']['id'] . " criado!";
}

const apiKey = 'lrv_live_sua_chave';

const response = await fetch('https://cloud.lrvweb.com.br/api/v1/tickets', {
    method: 'POST',
    headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        subject: 'Problema no servidor',
        message: 'O site está lento desde as 14h.',
        priority: 'high',
        department: 'suporte',
    }),
});

const { success, data } = await response.json();
if (success) {
    console.log(`Ticket #${data.id} criado!`);
}

import requests

api_key = 'lrv_live_sua_chave'

response = requests.post(
    'https://cloud.lrvweb.com.br/api/v1/tickets',
    headers={'X-API-Key': api_key},
    json={
        'subject': 'Problema no servidor',
        'message': 'O site está lento desde as 14h.',
        'priority': 'high',
        'department': 'suporte',
    }
)

result = response.json()
if result['success']:
    print(f"Ticket #{result['data']['id']} criado!")

Endpoints

Todos os endpoints seguem REST. Recursos disponíveis:

Hosting (VPS)

Escopo: hosting.read / hosting.write

GET /api/v1/hosting
GET /api/v1/hosting/show?id=
POST /api/v1/hosting/restart?id=
GET /api/v1/hosting/metrics?id=

Tickets

Escopo: tickets.read / tickets.write

GET /api/v1/tickets
GET /api/v1/tickets/show?id=
POST /api/v1/tickets
POST /api/v1/tickets/reply
POST /api/v1/tickets/close?id=

Domínios

Escopo: domains.read / domains.write

GET /api/v1/domains
GET /api/v1/domains/show?id=
POST /api/v1/domains
POST /api/v1/domains/remove?id=

Assinaturas

Escopo: billing.read

GET /api/v1/subscriptions
GET /api/v1/subscriptions/show?id=
GET /api/v1/subscriptions/invoices?subscription_id=

Bancos de Dados

Escopo: databases.read / databases.write

GET /api/v1/databases
POST /api/v1/databases
POST /api/v1/databases/remove?id=

Backups

Escopo: backups.read / backups.write

GET /api/v1/backups
POST /api/v1/backups
POST /api/v1/backups/restore

Ver todos os endpoints no API Explorer →

Paginação

Endpoints de listagem retornam dados paginados. Use ?page= e ?per_page= (máx 100).

Parâmetros

page — Número da página (padrão: 1)
per_page — Itens por página (padrão: 25, máx: 100)
search — Busca textual (quando disponível)
status — Filtrar por status
sort — Ordenação: asc ou desc

Resposta paginada

{
  "success": true,
  "data": [
    { "id": 1, "hostname": "vps-01.lrv.cloud", ... },
    { "id": 2, "hostname": "vps-02.lrv.cloud", ... }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 48,
    "last_page": 2
  },
  "links": {
    "self": "/api/v1/hosting?page=1&per_page=25",
    "first": "/api/v1/hosting?page=1&per_page=25",
    "last": "/api/v1/hosting?page=2&per_page=25",
    "next": "/api/v1/hosting?page=2&per_page=25"
  }
}

Rate Limiting

Cada API Key tem um limite configurável de requisições por minuto. Quando excedido, a API retorna HTTP 429 com o header Retry-After.

Headers de Rate Limit

X-RateLimit-Limit: 60        ← Requisições permitidas por janela
X-RateLimit-Remaining: 58    ← Requisições restantes
X-RateLimit-Reset: 1720540860 ← Timestamp (epoch) de reset

Quando exceder o limite (HTTP 429)

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 42 seconds."
  }
}

Webhooks

Configure URLs para receber notificações em tempo real quando eventos ocorrem. Todos os payloads são assinados com HMAC SHA-256.

Eventos disponíveis

ticket.created ticket.replied ticket.closed hosting.created hosting.suspended hosting.restarted payment.received payment.overdue subscription.created subscription.cancelled backup.created domain.added application.installed monitoring.alert

Payload recebido

POST https://seu-servidor.com/webhook
Headers:
  Content-Type: application/json
  X-Webhook-Event: ticket.created
  X-Webhook-Signature: sha256=a1b2c3d4e5...
  X-Webhook-Timestamp: 1720540800

Body:
{
  "event": "ticket.created",
  "timestamp": "2026-07-09T20:00:00-03:00",
  "data": {
    "id": 42,
    "subject": "Problema no servidor",
    "status": "open",
    "priority": "high"
  }
}

Validar assinatura (HMAC SHA-256)

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = 'seu_webhook_secret';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
$valid = hash_equals($expected, $signature);

if (!$valid) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
// Processar evento...

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(signature)
    );
}

// No Express:
app.post('/webhook', (req, res) => {
    const sig = req.headers['x-webhook-signature'];
    if (!verifyWebhook(req.rawBody, sig, 'seu_secret')) {
        return res.status(401).send('Invalid');
    }
    // Processar evento...
});

import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# No Flask:
@app.route('/webhook', methods=['POST'])
def webhook():
    sig = request.headers.get('X-Webhook-Signature', '')
    if not verify_webhook(request.data, sig, 'seu_secret'):
        return 'Invalid', 401
    # Processar evento...

Tratamento de Erros

Todas as respostas de erro seguem o mesmo formato:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": [
      { "field": "domain", "message": "Invalid domain format." }
    ]
  }
}

Códigos HTTP

Código	Significado	Quando ocorre
`200`	OK	Requisição processada com sucesso
`201`	Created	Recurso criado (ticket, domínio, etc.)
`202`	Accepted	Ação enfileirada (restart, backup)
`400`	Bad Request	Parâmetros faltando ou inválidos
`401`	Unauthorized	API Key inválida ou ausente
`403`	Forbidden	Escopo insuficiente
`404`	Not Found	Recurso não encontrado
`409`	Conflict	Recurso já existe ou conflito de estado
`422`	Validation Error	Dados inválidos (com detalhes por campo)
`429`	Rate Limited	Limite de requisições excedido
`500`	Server Error	Erro interno (reporte ao suporte)

Códigos de erro comuns

UNAUTHORIZED FORBIDDEN NOT_FOUND VALIDATION_ERROR RATE_LIMIT_EXCEEDED MISSING_ID DOMAIN_ALREADY_EXISTS VPS_NOT_RUNNING TICKET_CLOSED INVALID_API_KEY INVALID_SCOPES ENVIRONMENT_MISMATCH

SDKs e Ferramentas

Baixe as coleções e especificações para começar a integrar rapidamente.

PHP

composer require lrv/cloud-manager-sdk

JavaScript / TypeScript

npm install @lrv/cloud-manager

Python

pip install lrv-cloud-manager

Downloads

OpenAPI YAML Postman Bruno Insomnia API Explorer

Infraestrutura

Aplicações

Dev & Ops

Comunicação

Performance

Segurança

Monitoramento

Experiência

Documentação da API