Documentação da API — RastrePanel

INTRODUÇÃO

Visão geral

A API REST do RastrePanel foi criada para integrações de provisionamento, cobrança e automação. Todas as respostas usam JSON e incluem um identificador de requisição para suporte e auditoria.

v1

Versionada

Endpoints estáveis sob o prefixo /api/v1.

↻

Idempotente

Repetições seguras em operações mutáveis.

⌁

Auditável

Cada resposta inclui um X-Request-ID.

Use somente HTTPS.

Nunca coloque o token em query strings, logs, aplicações frontend ou código-fonte.

ACESSO

Autenticação

Todas as chamadas usam um Bearer Token. Envie também Accept: application/json para receber o formato padronizado da API.

HTTP

Authorization: Bearer rp_live_SEU_TOKEN
Accept: application/json

O token nunca amplia os poderes da conta vinculada. Se a conta for suspensa, expirar ou perder acesso ao recurso, o token também deixa de autorizar a operação.

CREDENCIAIS

Gerenciar tokens

Crie os tokens diretamente no servidor e conceda somente os escopos necessários. O segredo completo é exibido uma única vez.

BASH · CRIAR TOKEN

cd /opt/rastrepanel/app
sudo -u rastrepanel php8.4 artisan rastrepanel:api-token-create admin@exemplo.com \
  --name="ERP de cobrança" \
  --expires=365 \
  --ability=sites:read \
  --ability=sites:create \
  --ability=sites:suspend \
  --ability=sites:release \
  --ability=sites:delete \
  --ability=statistics:read

LISTAR

sudo -u rastrepanel php8.4 artisan \
  rastrepanel:api-token-list

REVOGAR

sudo -u rastrepanel php8.4 artisan \
  rastrepanel:api-token-revoke 12

PERMISSÕES

Escopos disponíveis

Escopo	Autoriza
`sites:read`	Listar e consultar sites
`sites:create`	Criar e provisionar sites
`sites:suspend`	Suspender sites
`sites:release`	Liberar ou reativar sites
`sites:delete`	Remover sites e serviços relacionados
`statistics:read`	Consultar estatísticas de acesso
`clients:read`	Listar e consultar clientes da revenda
`clients:create`	Criar clientes da revenda
`clients:update`	Atualizar clientes, cotas, permissões e sites
`clients:suspend`	Suspender o acesso de clientes
`clients:release`	Liberar o acesso de clientes
`clients:delete`	Remover contas de clientes

Escopos clients:* exigem um token vinculado a uma conta de Revenda.

REFERÊNCIA

Endpoints

GET/sitesListar sites GET/sites/{id}Consultar site POST/sitesCriar site POST/sites/{id}/suspendSuspender POST/sites/{id}/releaseLiberar DELETE/sites/{id}Remover GET/statisticsEstatísticas gerais GET/sites/{id}/statisticsEstatísticas do site GET/clientsListar clientes POST/clientsCriar cliente PUT/clients/{id}Atualizar cliente DELETE/clients/{id}Remover cliente

Identificadores opacos

O parâmetro {id} usa o identificador de dez caracteres devolvido pela API. Não use o ID numérico interno do banco.

RECURSO

Sites

GET/sites

Listar sites

Retorna os sites visíveis para a conta autenticada, com paginação.

CURL

curl --fail-with-body \
  -H "Authorization: Bearer ${RASTREPANEL_API_TOKEN}" \
  -H "Accept: application/json" \
  "https://seu-painel:3083/api/v1/sites?per_page=25&page=1"

Ver exemplo de resposta +

{
  "data": {
    "sites": [{
      "id": "00aB3dE91x",
      "domain": "cliente.exemplo.com.br",
      "site_type": "laravel",
      "php_version": "8.4",
      "active": true,
      "status": "active"
    }]
  },
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 1
  }
}

GET/sites/{id}

Consultar um site

Retorna os dados do site, seu estado operacional e os eventos recentes de provisionamento.

POST/sites

Criar um site

Provisiona o site e retorna HTTP 201. O DNS inicial é preparado automaticamente.

JSON · CORPO

{
  "domain": "cliente.exemplo.com.br",
  "site_type": "laravel",
  "php_version": "8.4",
  "php_max_children": 20,
  "php_memory_limit": 512,
  "bind_ip": null,
  "issue_ssl": false,
  "client_id": "00aB3dE91x"
}

Campo	Regra
`site_type`	`laravel`, `php` ou `static`. Padrão: `laravel`.
`php_version`	`8.2`, `8.3` ou `8.4`. Padrão: `8.4`.
`php_max_children`	Entre 2 e 100. Padrão: 20.
`php_memory_limit`	Entre 128 e 2048 MB. Padrão: 512.
`issue_ssl`	Quando verdadeiro, `ssl_email` é obrigatório.
`client_id`	Opcional para revendas; atribui o site a um cliente do mesmo tenant.

POST/sites/{id}/suspend

POST/sites/{id}/release

Suspender e liberar

Altera a disponibilidade do site. Solicitar novamente o estado atual não reinicia o serviço desnecessariamente.

DELETE/sites/{id}

Remover um site

Remove arquivos, usuário Linux, bancos relacionados, workers, backups locais, configuração web, SSL e a zona DNS exata. O domínio deve ser confirmado no corpo.

JSON · CONFIRMAÇÃO

{"confirmation":"cliente.exemplo.com.br"}

MÉTRICAS

Estatísticas

GET/statistics?days=30

GET/sites/{id}/statistics?days=30

Os períodos aceitos são 7, 30 ou 90 dias. As métricas incluem requisições, visitantes únicos, bytes transferidos, bots, grupos de status HTTP, série diária, páginas e referenciadores mais frequentes.

Cache de cinco minutos

As estatísticas são armazenadas temporariamente para reduzir o custo de leitura dos logs.

REVENDA

Clientes de revenda

Tokens vinculados a revendas podem criar e administrar clientes dentro do próprio tenant. Não existem sub-revendas.

GET/clientsListar clientes

GET/clients/{id}Consultar cliente

POST/clientsCriar cliente

PUT/clients/{id}Atualizar conta, cotas e sites

POST/clients/{id}/suspendSuspender acesso

POST/clients/{id}/releaseLiberar acesso

DELETE/clients/{id}Remover conta

Criar cliente

JSON · CORPO

{
  "name": "Cliente Exemplo",
  "email": "cliente@exemplo.com.br",
  "password": "SenhaTemporariaForte123",
  "role": "admin",
  "active": true,
  "max_sites": 5,
  "max_databases": 10,
  "max_backups": 10,
  "max_cron_jobs": 20,
  "site_ids": []
}

Para o perfil Usuário, envie tecnicamente role: "operator" e uma combinação de permissões: sites, databases, git, backups, terminal, files, php_site, cron, mail e laravel.

Suspensão de conta

Suspender um cliente interrompe login e tokens, mas não retira automaticamente seus sites do ar. Use o endpoint de suspensão do site quando necessário.

CONFIABILIDADE

Idempotência

Chamadas POST e DELETE exigem uma chave única. Ela deve ter entre 8 e 128 caracteres formados por letras, números, ponto, sublinhado, dois-pontos e hífen.

HTTP

Idempotency-Key: pedido-84721-criacao
Content-Type: application/json

1Primeira chamada

A resposta é processada e armazenada.

2Repetição idêntica

A API devolve a resposta original.

3Corpo diferente

A mesma chave retorna conflito HTTP 409.

Se o resultado ficar incerto, repita a mesma requisição com a mesma chave. Não gere outra chave.

RESPOSTAS

Erros

Erros seguem uma estrutura consistente e incluem o identificador da requisição.

JSON · 422

{
  "error": {
    "code": "validation_failed",
    "message": "Os dados enviados não são válidos.",
    "details": {
      "domain": ["O campo domínio já está sendo utilizado."]
    },
    "request_id": "a60a25d1-c1ea-4ab4-a6a0-a5df433ca019"
  }
}

400JSON malformado

401Token inválido ou expirado

403Escopo insuficiente

404Recurso não encontrado

409Conflito de idempotência

413Corpo acima do limite

415Tipo de conteúdo inválido

422Falha de validação

429Limite de chamadas excedido

502Falha na operação do servidor

503Estatísticas indisponíveis

PRODUÇÃO

Limites e operação

Os limites abaixo podem ser ajustados no arquivo de ambiente do painel:

DOTENV

API_RATE_LIMIT_PER_MINUTE=60
API_AUTH_RATE_LIMIT_PER_MINUTE=120
API_IDEMPOTENCY_TTL_HOURS=24
API_IDEMPOTENCY_PROCESSING_TIMEOUT_MINUTES=15
API_MAX_REQUEST_BYTES=65536

Use um token diferente para cada sistema consumidor.
Conceda somente os escopos realmente necessários.
Faça rotação periódica e revogue tokens sob suspeita.
Registre o X-Request-ID ao investigar falhas.

Integre seu sistemaao RastrePanel.

Visão geral

Autenticação

Gerenciar tokens

Escopos disponíveis

Endpoints

Sites

Listar sites

Consultar um site

Criar um site

Suspender e liberar

Remover um site

Estatísticas

Clientes de revenda

Criar cliente

Idempotência

Erros

Limites e operação

Integre seu sistema
ao RastrePanel.