Automatizar a faturação e o aprovisionamento Plesk

Um produto de alojamento automatizado tem três momentos em que o dinheiro e as máquinas se tocam:

1. 01A encomenda é paga: tem de existir uma subscrição, no plano de serviço certo, em segundos.
2. 02A fatura está vencida: a subscrição tem de se apagar e voltar assim que for paga.
3. 03A subscrição termina: tem de ser removida, a sério, incluindo os seus dados.

O Plesk tem chamadas para os três. O que não tem é algo que decida quando as executar, e é essa a metade que está a construir. Esta página trata de ligar as duas, e de quatro comportamentos que são inofensivos quando se acionam à mão e perigosos quando um agendador os executa às três da manhã.

Tudo aqui foi medido num servidor Plesk Obsidian 18.0.80 em funcionamento, em agosto de 2026.

Os três momentos e as chamadas que os sustentam

Dois desses números moldam o desenho. Uma subscrição demora quatro segundos e meio a criar e quase oito a eliminar. É tempo suficiente para que um formulário de encomenda tenha de assinalar que algo está a acontecer, suficiente para que um orçamento de tempo-limite escrito para uma API rápida corte a meio uma chamada que funciona, e suficiente para que duas encomendas que chegam juntas sejam realmente concorrentes, e não apenas em teoria.

Repare também na linha de leitura. Uma única chamada XML devolve todas as subscrições com o seu plano, estado, quota e utilização num terço de segundo, independentemente de quantas sejam. E um sistema de faturação reconcilia-se constantemente com o painel.

A armadilha da suspensão é um erro de faturação, não um detalhe de API

O Plesk oferece duas formas de suspender, e cada uma escreve campos diferentes. Num produto de alojamento, isto deixa de ser uma curiosidade.

Medido, na mesma subscrição:

Um ciclo de cobrança que suspende via REST escreve um campo que a leitura em bloco não consulta, pelo que a sua plataforma continua a reportar a conta como ativa. Eis porque isto prejudica a faturação em particular: quando a fatura é finalmente paga, a sua automatização olha para o seu próprio estado, vê uma conta que nunca foi suspensa e não a reativa. O cliente pagou e continua apagado, e nada registou um erro.

A regra cabe numa linha: suspenda através do campo que lê. O Provibr escreve <webspace><set><gen_setup><status>, após o que as duas vistas concordam.

gen_info.status é uma máscara de bits; medimos 0 para ativo, 1 para webspace desligado e 16 para desativado pelo administrador. Trate tudo o que não seja zero como suspenso, a única leitura que sobrevive a um valor que ainda ninguém viu.

Uma reserva honesta: não medimos a suspensão de uma subscrição já suspensa. No HestiaCP esse caso não é idempotente e devolve um erro com o aspeto de um erro de autenticação (exatamente aquilo em que um ciclo de cobrança tropeça todos os dias), por isso confirme-o no seu próprio servidor antes de depender dele.

Uma chave expirada parece exatamente um servidor vazio

Esta é a falha que pode causar danos a sério, e descreve-se numa frase.

A API XML devolve HTTP 200 para uma chave errada. O erro está dentro do documento, como código 11003. Um cliente que verifica o código de estado lê, por isso, uma falha de autenticação como uma ronda bem-sucedida que não encontrou subscrições.

Ponha agora isto dentro de uma tarefa de reconciliação noturna. Uma ronda bem-sucedida que nada encontrou significa, para qualquer plataforma de alojamento, que todas as contas que ali estavam ontem foram eliminadas. Uma única chave expirada e, de um dia para o outro, o seu sistema marca toda a sua base de clientes como desaparecida.

Daí saem duas regras, e aplicam-se a qualquer painel que reporte a falha com um 200, o que, dos painéis que integrámos, é o caso da maioria:

• Na API XML, o código de estado não transporta qualquer informação, nem sequer sobre a autenticação. Analise o documento.
• Uma resposta ilegível é desconhecida, nunca vazia. Um servidor vazio existe de facto, e produz um único resultado vazio em vez de um erro: esses dois casos são realmente diferentes, e distingui-los é todo o trabalho.

O REST falha de outra forma ainda: uma chave inutilizável regressa em HTTP 401 com um corpo completamente vazio. Por isso, um teste de ligação tem de sondar ambas as superfícies e reportá-las em separado. Um resultado REST a verde com uma API XML muda significa que a lista de contas, a lista de planos e cada mudança de plano ficarão vazias, e a conclusão tentadora é que o cliente não tem contas.

O código de erro não diz o que correu mal

Os erros REST do Plesk transportam um código numérico, e dá vontade de o usar como critério de decisão. Medido, ele não classifica:

• 1007 abrange tanto «esse domínio já existe» como «esse nome de utilizador de cliente já existe».
• 1013 abrange tanto «não existe esse plano de serviço» (REST) como «o domínio não existe» (XML).
• 0 significa sem código, não sem erro.

Para uma integração de faturação, o dano cai na lógica de repetição. «O domínio já existe» depois de uma encomenda paga pode significar que a tentativa anterior teve êxito parcial e que se deve verificar antes de tentar de novo; «não existe esse plano de serviço» significa que a encomenda nunca terá êxito e pertence à frente de um humano. Partilham uma família de códigos. Por isso é o texto que classifica, e essa correspondência deve estar num único lugar do seu código, em vez de ser deduzida de novo em cada ponto de chamada.

Há ainda uma quinta forma de falha: peça ao REST uma rota que não existe e ele responde com uma página HTML, não JSON.

Uma encomenda falhada pode bloquear a repetição

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

Num fluxo de faturação, isso lê-se assim: o cliente pagou, o aprovisionamento falhou, e a repetição falha agora de forma diferente, porque o domínio está a ser usado por uma conta que ele nunca recebeu. A segunda falha parece uma encomenda duplicada, que é uma das coisas mais confusas de depurar a partir de um pedido de suporte.

Daí decorrem duas medidas baratas. Resolva o plano antes de criar seja o que for: já tem a lista de planos, por isso procure o nome localmente e faça a encomenda falhar antes de tocar no painel, o que elimina esta falha em vez de a gerir. E faça a limpeza após uma criação falhada, porque deixar os destroços transforma uma encomenda falhada num nome de domínio bloqueado para sempre.

Por contraste, um erro de validação de campo como um nome de utilizador de cliente duplicado devolve HTTP 400 e não deixa nada para trás. Essa verificação corre antes da criação; só a procura do plano acontece tarde demais para o salvar.

Duas chamadas que têm, cada uma, um meio

Remover uma subscrição significa DELETE /domains/{id} e depois DELETE /clients/{id}. Se a primeira tiver êxito e a segunda não, fica com um registo de cliente que não possui nada: invisível na maioria das vistas, e um erro de identificador duplicado da próxima vez que esse cliente voltar. Aos 7,7 segundos, a eliminação também é longa o suficiente para uma rede a interromper, por isso o cancelamento merece o mesmo tratamento que o aprovisionamento: releia o painel a seguir e reconcilie com a leitura em bloco, não com a resposta que obteve.

As subidas e descidas de plano têm o seu próprio recanto. <webspace><switch-subscription> não aceita um nome de plano, apenas o GUID ou o ID externo do plano, ao passo que em todo o resto do Plesk um pacote é referenciado pelo nome. O Provibr mantém o nome como aquilo que os humanos veem e faz internamente a tradução de nome para GUID a partir da lista de planos que a sondagem já obtém. Guardar antes um GUID no seu sistema de faturação funciona até ao momento em que alguém reconstrói um plano.

Onde vive a fatura

Os três momentos acima são apenas metade de um produto de alojamento. A outra metade é o aspeto da sua própria fatura.

Paga por capacidade, por tipo de recurso, e uma conta de alojamento é um deles. Cada subscrição conta, esteja em funcionamento ou não; só uma subscrição suspensa não conta. É o sentido certo para a cobrança: suspender um cliente em atraso liberta o lugar enquanto os seus dados ficam intactos, e reativá-lo volta a ocupá-lo.

Ultrapassar o seu limite não é bloqueado no momento em que acontece. É detetado, é-lhe dito qual o tipo de recurso e em quanto, e tem um dia útil para o corrigir. Se esse prazo expirar, os servidores mais recentes acima do limite são desligados, os mais recentes primeiro, para que o que construiu mais cedo sobreviva. Um segundo excesso na mesma semana recebe uma hora em vez de um dia, porque de outro modo o período de graça poderia ser renovado para sempre ao descer abaixo do limite e voltar a ultrapassá-lo. Nada é reiniciado por si quando fica resolvido: ligar uma máquina é uma decisão, e a plataforma não a toma enquanto ninguém está a ver.

Cada período dá origem a uma proforma que pode ler e imprimir, chegando a fatura definitiva da contabilidade sob a forma de ficheiro. Uma linha de fatura regista o nome do pacote tal como estava no momento da faturação, pelo que renomear um plano mais tarde não reescreve o histórico.

O que o Provibr faz, e o que deliberadamente não faz

O Provibr coloca-se entre a sua faturação e o seu servidor Plesk. Uma subscrição é uma linha comum: encomende-a, suspenda-a, reative-a, mude o seu plano de serviço, elimine-a. A suspensão passa pelo campo que a sondagem lê. O plano é resolvido antes da criação, e uma criação falhada é limpa. Cada mutação termina relendo a subscrição, pelo que o que fica guardado é o que foi observado, e não o que foi pedido. O agente liga-se para o exterior a partir da sua própria rede, pelo que a porta 8443 não tem de estar exposta à internet.

O que não faz: gerir o próprio servidor Plesk, nem entrar dentro de uma subscrição. Também nunca pede ao Plesk os conjuntos de dados que contêm a palavra-passe FTP ou o hash da palavra-passe do cliente, ambos entregues pelo painel em texto simples se os pedir.

A ler a seguir

• Como vender alojamento web com Plesk: o modelo de produto, as duas APIs e o que nunca pedimos ao painel.
• Faturação e licença: capacidade, preço por escalão, crédito, proformas e o que acontece acima do limite.
• 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 as respostas registadas como fixtures. A suspensão repetida, as chaves limitadas a revendedor e o comportamento sob carga de tráfego real não foram medidos, e estão assinalados como tal acima.