Blueprint de integração

WHMCS + CastlePanel

Um módulo de provisionamento para transformar eventos comerciais do WHMCS em operações seguras e auditadas no CastlePanel.

Arquitetura definida Desenvolvimento futuro API base disponível

Provisioning Moduleligado ao produto de hospedagem

Client Arearecursos técnicos no serviço

Single Sign-Oncliente e administrador

Service PropertiesIDs técnicos persistentes

Tipo de módulo

Provisionamento como núcleo

O módulo principal deve acompanhar o produto contratado. Um addon administrativo é opcional para configurações globais e diagnósticos.

Obrigatório

Provisioning Module

Cria e administra cada serviço de hospedagem, recebe os eventos de ciclo de vida e exibe ações na área do cliente.

/modules/servers/castlepanel/

Opcional

Addon Module

Centraliza teste de conexão, estado geral, logs filtrados, documentação e manutenção da integração.

/modules/addons/castlepanel/

Estrutura

Arquivos do módulo

O cliente HTTP e as regras de assinatura ficam isolados das funções exigidas pelo WHMCS.

/modules/servers/castlepanel/

castlepanel.php
lib/
  ApiClient.php
  ApiException.php
  OperationPoller.php
  SsoRelay.php
templates/
  clientarea.tpl
lang/
  portuguese-br.php
hooks.php

Ciclo do produto

Mapeamento das funções WHMCS

Função WHMCS	Operação CastlePanel	Regra
CreateAccount	Criar ou vincular cliente, serviço e site	Salvar IDs e operation ID antes de retornar
SuspendAccount	Alterar cliente ou serviço para suspended	Não excluir dados
UnsuspendAccount	Alterar estado para active	Consultar a operação até estado terminal
TerminateAccount	Cancelar cliente ou serviço	Purge definitivo continua sendo uma ação separada
ChangePackage	Atualizar o plano do serviço	CastlePanel valida consumo antes de reduzir limites
Renew	Sincronizar vigência quando necessário	Não reprovisionar recursos existentes
ServiceSingleSignOn	Solicitar ticket customer	Encaminhar por relay local e POST
AdminSingleSignOn	Solicitar ticket admin	Exigir permissão e mapeamento administrativo
ClientArea	Consultar recursos delegados	Nunca aceitar customer ID livre do navegador

Persistência

Service Properties recomendadas

Os identificadores técnicos devem acompanhar a instância do serviço, não depender de domínio ou e-mail mutáveis.

CastlePanel Customer IDcliente técnico proprietário do serviço

CastlePanel Service IDserviço e limites do plano

CastlePanel Site IDsite principal do produto

CastlePanel Operation IDúltima operação assíncrona

CastlePanel Last Syncmomento da última leitura confirmada

Área do cliente

Recursos úteis sem reproduzir o painel inteiro

O WHMCS deve oferecer ações frequentes. A administração completa continua no CastlePanel.

Resumo

Domínio, plano, estado técnico, SSL e última operação.

E-mails

Listar, criar, suspender, reativar, excluir e abrir webmail.

Bancos

Listar, criar, suspender, reativar, excluir e abrir o gerenciador.

SFTP

Contas por domínio ou pasta, com senha temporária exibida uma vez.

SSL

Estado, checagem DNS, emissão e renovação.

Operações

Acompanhamento visual do CastleAgent sem bloquear a página.

SSO no WHMCS

Redirect compatível sem ticket secreto na URL

O WHMCS espera uma URL de redirecionamento. O módulo usa um relay local para preservar o consumo por POST do CastlePanel.

SolicitarO backend do módulo pede um ticket customer ou admin à API do CastlePanel.
GuardarO ticket fica temporariamente na sessão do WHMCS, nunca na URL retornada.
RedirecionarServiceSingleSignOn retorna uma rota local do próprio módulo.
EntregarA rota local gera um formulário e envia o ticket por POST para o CastlePanel.
ConsumirO CastlePanel invalida o ticket, cria a sessão e registra o ator.

Importante: o ticket é de uso único, dura poucos segundos e não deve aparecer em query string, logs do módulo ou histórico do navegador.

Segurança

Credencial e chamadas da API

Servidor a servidor

Token e segredo HMAC ficam na configuração criptografada do servidor WHMCS.

Escopo mínimo

Credenciais separadas para provisionamento, cliente, SSO e administração.

Contexto delegado

O backend calcula o customer ID a partir do serviço autenticado.

Logs filtrados

Usar o log de módulo ocultando token, segredo, ticket, senha e payload sensível.

Idempotência

Repetições do WHMCS não podem criar o mesmo cliente, site ou recurso duas vezes.

Timeout controlado

A função comercial registra a operação; o acompanhamento continua sem requisição longa.

Plano de construção

Entrega em cinco fases

ConexãoConfiguração de servidor, teste da API e cliente HTTP assinado.
ProvisionamentoCreate, suspend, unsuspend, terminate e change package.
Área do clienteResumo, e-mails, bancos, SFTP, SSL e operações.
SSOService e Admin Single Sign-On usando relay local.
QualidadeIdempotência, testes de falha, upgrade, tradução e pacote versionado.

Referências

Documentação oficial usada no blueprint

Provisioning ModulesVisão geral oficial do módulo de produto/servidor. Supported FunctionsFunções de ciclo, área do cliente, métricas e ações. Single Sign-OnContrato oficial para acesso de serviço e administrador.

Blueprint pronto

Quando o WHMCS entrar no roadmap, a base já está definida.

O desenvolvimento poderá começar pelo módulo de provisionamento sem redesenhar segurança, API ou SSO.

Ver todas as integrações Consultar OpenAPI