Vender alojamento web com Plesk

O Plesk faz correr sem problemas uma centena de subscrições por si. O que não faz é receber uma encomenda, cobrar o dinheiro, reparar que uma fatura ficou por pagar, ou suspender a conta correspondente. É nessa distância entre «um painel que aloja sites» e «um negócio de alojamento» que está o trabalho, e esta página explica como percorrê-la sem cair nos quatro sítios onde é fácil cair.

O que o Plesk já lhe dá

Uma subscrição é a unidade que se vende: um domínio principal, um plano de serviço, limites de disco e de tráfego, e tudo o que está por baixo. Um plano de serviço é a descrição que o próprio painel faz desse pacote: quota, tráfego mensal, quantos domínios e caixas de correio, que serviços estão ativos. Ambos os conceitos já existem, por isso não se inventa um modelo de produto, apenas se dá nome a um que já lá está.

A API é boa num aspeto que conta particularmente para um produto de alojamento: uma única chamada lê todas as subscrições do servidor, com o respetivo plano, estado, quota e utilização. Medimo-la em 0,33 segundos, independentemente de quantas existam. Três chamadas de leitura dão o quadro completo de um servidor (subscrições, clientes, planos) e esse número não cresce com o número de clientes. Construir o mesmo quadro através de REST exigiria uma chamada mais três por subscrição.

Uma só chave abre duas APIs, e são precisas as duas

O Plesk dispõe de uma API REST v2 moderna e de uma API XML/RPC mais antiga. Nenhuma delas é completa por si só, e isto não é uma questão de preferência.

A REST v2 não tem subscrições nem planos de serviço. Enumerámos os seus 43 caminhos a partir do próprio documento OpenAPI; /subscriptions e /service-plans não constam deles, e pedi-los devolve um 404 apresentado como página HTML em vez de JSON. Como o plano de serviço é o pacote de alojamento, todo o lado dos pacotes tem de passar por XML.

O que salva a situação é a credencial. A chave emitida por POST /api/v2/auth/keys funciona sem alterações em ambas: como X-API-Key no REST e como KEY no ponto de acesso XML. Medido, a mesma chave, as duas APIs. Por isso pede-se ao operador um único valor, não dois.

O que isto custa são dois vocabulários de falha. O REST responde a uma chave inutilizável com um HTTP 401 e um corpo totalmente vazio. O XML responde à mesma chave com um HTTP 200 e um código de erro dentro do documento. O que nos leva ao fio da navalha.

Uma falha de autenticação que parece um servidor vazio

Como a API XML devolve um HTTP 200 para uma chave errada, um cliente que verifica o código de estado lê uma falha de autenticação como uma ronda bem-sucedida que não encontrou nada. E uma ronda bem-sucedida que não encontrou nada tem um significado em qualquer plataforma de alojamento: todas as contas que ali estavam ontem desapareceram.

A consequência não é um painel de controlo avariado. É um sistema que marca cada um dos seus clientes como eliminado porque uma chave expirou. A regra que daqui decorre é absoluta: na API XML o código de estado não transporta qualquer informação, nem sequer sobre autenticação. Analise o documento e trate uma resposta ilegível como desconhecida em vez de como vazia.

Um servidor vazio também não produz um erro: produz um único resultado vazio, que é a resposta certa quando não há mesmo nenhuma. Distinguir esses dois casos é todo o trabalho.

A armadilha da suspensão: escrever e ler o mesmo campo

Há duas formas de suspender uma subscrição no Plesk, e não escrevem o mesmo campo.

Releia a segunda linha. Suspender através de REST deixa a zero o campo que a sondagem em bloco lê. Assim, um produto de alojamento que suspende através de REST e sonda através de XML mostrará a conta como ativa quando ela está, na verdade, suspensa. Nada falha. Nada fica vermelho. O painel e o servidor simplesmente discordam, e a primeira pessoa a dar por isso é um cliente que não consegue aceder a um site que se julga em funcionamento.

A regra: suspender e reativar pelo mesmo campo que se lê. O Provibr usa XML <webspace><set><gen_setup><status>, e depois disso as duas vistas movem-se em conjunto: o campo XML indica 16 e o REST indica suspenso.

gen_info.status é uma máscara de bits, e os valores que medimos são 0 para ativo, 1 para webspace-off e 16 para desativado pelo administrador. Tudo o que não seja zero conta como suspenso, o que é a única leitura que sobrevive a um valor que ainda não vimos.

Dois conjuntos de dados que nunca pedimos ao painel

A API XML do Plesk foi concebida para administração, pelo que dois dos seus conjuntos de dados devolvem material de credenciais a quem os pedir:

• <webspace><get> com o conjunto de dados hosting devolve a palavra-passe FTP da conta em texto simples, com um campo que a marca explicitamente como tal.
• <customer><get> com o conjunto de dados gen_info devolve o hash da palavra-passe do cliente (bcrypt) juntamente com o tipo de hash.

Isto é razoável para uma API de administração. Não é algo que uma plataforma de alojamento deva puxar pela rede de forma periódica.

Uma camada de ocultação é a resposta errada para isto. A resposta certa é não pedir. A sondagem do Provibr pede exatamente quatro conjuntos de dados (informações gerais, limites, estatísticas e subscrições) e percorremo-los campo a campo para confirmar que nenhum transporta um segredo. A lista de clientes vem do REST, que não tem qualquer campo de palavra-passe.

Há uma consequência de conceção que vale a pena referir. O utilizador FTP ou de sistema de uma subscrição daria um identificador curto atraente, mas vive apenas no conjunto de dados hosting, pelo que usá-lo como identidade significaria obter a palavra-passe de cada cliente em cada ciclo de sondagem. Daí o domínio, em vez disso.

A identidade de uma subscrição é um nome de domínio

No Plesk, uma subscrição tem o nome do seu domínio principal. É o que o painel mostra, é aquilo por que a sua API filtra, e é o que qualquer integração tem de guardar.

Esta é uma diferença real face ao cPanel e ao DirectAdmin, onde uma conta tem um nome de utilizador curto e um domínio em separado, e tem uma consequência prática: o domínio não pode ser alterado depois. Aquilo que o sistema de faturação guarda como identificador de uma subscrição Plesk é um nome de domínio, e um cliente que queira mudar o nome do seu site está a pedir uma nova subscrição em vez de uma edição.

Duas coisas mais modestas medidas pelo caminho. A própria especificação do Plesk diz que uma palavra-passe de cliente tem entre 5 e 14 caracteres; uma palavra-passe de 22 caracteres foi aceite sem queixas, pelo que o limite documentado não é o que está a ser aplicado. E o Plesk escolhe ele próprio o endereço IP a partir do seu próprio pool, razão pela qual uma conta de alojamento no Provibr tem um campo de endereço vazio até o painel indicar um.

Uma encomenda falhada pode deixar meia subscrição para trás

Medido: criar um domínio com um plano de serviço que não existe responde com um HTTP 404 e uma mensagem clara, e mesmo assim o objeto de domínio existe a seguir, sem tipo de alojamento e com uma raiz de documentos vazia. O Plesk cria primeiro o objeto e aplica o plano depois, e não reverte quando o segundo passo falha.

O cliente pagou, a encomenda falhou, e a tentativa seguinte falha agora de forma diferente, porque o domínio já está em uso, por uma conta que ele nunca recebeu. Por isso, procure o plano antes de criar seja o que for, na lista de planos já obtida, e faça a limpeza depois de qualquer criação falhada. Em contraste, um erro de validação de campo, como um nome de utilizador em duplicado, regressa em HTTP 400 e não deixa nada para trás: essa verificação corre antes da criação, e só a procura do plano acontece demasiado tarde.

Sem latência, o que é mais raro do que deveria

A listagem de utilização do DirectAdmin fica cerca de três segundos atrasada face à realidade em ambos os sentidos, o que obriga a uma segunda chamada com autoridade. O Plesk não. Medimos uma criação e uma eliminação face à leitura em bloco:

    0 ms  create
 4519 ms  create returns 201
 4957 ms  bulk read sees the subscription      <- immediately
 4957 ms  delete
12622 ms  delete returns 200
13001 ms  bulk read no longer sees it          <- immediately

O Plesk é transacional: assim que a chamada responde, a alteração fica visível na leitura em bloco. Uma única fonte com autoridade, sem segunda chamada, sem esperas.

Os próprios tempos merecem ser referidos. Criar uma subscrição demora 4,1 a 4,5 segundos e eliminar uma 7,7 segundos, tempo suficiente para que um cliente a observar um formulário de encomenda tenha de ser informado de que algo está a acontecer. Mudar de plano demora 1,5 segundos e suspender 0,78.

O que o Provibr faz com tudo isto

O Provibr coloca-se entre a faturação e o servidor Plesk. Liga-se o servidor com uma única chave de API e, depois disso, uma subscrição é uma linha vulgar: encomendá-la, suspendê-la, reativá-la, movê-la para outro plano de serviço, eliminá-la.

• Uma só chave, porque a mesma chave abre as duas APIs.
• A suspensão passa pelo campo que a sondagem lê, para que painel e servidor não possam divergir.
• A sondagem nunca pede um conjunto de dados que contenha uma palavra-passe, para que nenhum segredo de cliente chegue à plataforma.
• O plano é resolvido antes da criação, e uma criação falhada é limpa em vez de ficar para trás.
• Nada é aceite pela sua própria palavra. Cada mutação termina relendo a subscrição.
• O agente liga-se para o exterior a partir da sua rede, pelo que a porta 8443 não fica exposta à internet e nada é instalado no servidor Plesk.
• As subscrições que não foram encomendadas através do Provibr ficam intactas até serem importadas, o que torna adotável um servidor com duzentos clientes existentes, em vez de uma reconstrução.

O que não faz

Gere as subscrições num servidor Plesk que o operador explora, não o servidor em si: os serviços, as zonas DNS, o encaminhamento de correio e as próprias definições do painel ficam onde estão. Não há consola, porque uma conta de alojamento não é uma máquina. As caixas de correio, as bases de dados e o DNS dentro de uma subscrição pertencem ao Plesk e ao cliente.

Uma ressalva honesta: tudo isto foi medido com uma chave de administrador. Se uma chave limitada a revendedor ou a cliente consegue sequer usar a API XML não foi testado, pelo que a integração faz uma sondagem no momento da ligação e recusa credenciais que só conseguem ver parte de um painel, em vez de gerir metade dele em silêncio.

A ler a seguir

• Automatizar a faturação e o aprovisionamento no Plesk: os três momentos em que o dinheiro e as máquinas se tocam, e as armadilhas de cada um.
• Alternativas ao cPanel para fornecedores de alojamento: seis painéis quanto ao modelo de licença, ao esforço de migração e ao comportamento de API medido.
• Configurar o Plesk: a chave de API, os planos de serviço, os planos web e a importação de subscrições.

Medido no Plesk Obsidian 18.0.80 em agosto de 2026, com todas as respostas registadas como fixtures. O comportamento com uma chave limitada a revendedor, com mais de uma subscrição por cliente e sob uma carga de tráfego real não foi medido, e está assinalado como tal acima.