Automatizar a faturação e o aprovisionamento HestiaCP

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

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

O HestiaCP tem um comando para cada um deles. O que não tem é algo que decida quando os executar. Esta página trata de ligar as duas metades, e dos sítios concretos onde a API do HestiaCP responde de uma forma que quebra silenciosamente uma primeira tentativa.

Os três momentos, e os comandos por baixo

Repare na coluna das respostas. Uma mutação bem-sucedida no HestiaCP é HTTP 204 com nada no corpo. Não 200. Um cliente escrito sob o pressuposto de que o êxito vale 200 rejeita cada chamada que funcionou e, depois, normalmente tenta de novo. E é assim que uma integração que funciona se torna uma integração bloqueada (ver mais abaixo).

A verdadeira resposta vive num cabeçalho de resposta, Hestia-Exit-Code, que transporta um número saído de uma tabela fixa. O estado HTTP deriva dele e reduz cerca de vinte códigos a quatro estados. Leia o cabeçalho; trate o estado como uma pista.

A suspensão não é simétrica, e aqui isso conta mais do que em qualquer outro lado

Esta é a armadilha que atinge especificamente uma integração de faturação, porque uma integração de faturação é a única coisa que suspende a mesma conta duas vezes.

Medido, na mesma conta:

v-suspend-user   numa conta ativa      → 204, saída 0
v-suspend-user   numa conta suspensa   → 401, saída 5   ("user X is suspended")
v-unsuspend-user numa conta suspensa   → 204, saída 0
v-unsuspend-user numa conta ativa      → 204, saída 0

Reativar é idempotente. Suspender não é. E a falha que produz é um HTTP 401, o mesmo estado que se obtém para um segredo errado, uma chave fora do seu âmbito e um endereço bloqueado.

Assim, um ciclo de cobrança que suspende tudo o que está vencido, incluindo o que já suspendeu ontem, reportará falhas de autenticação para contas que estão exatamente no estado pretendido. O código de saída 5 em v-suspend-user significa «já estava assim» e tem de ser lido como êxito.

Nunca repetir após um erro de autenticação

O HestiaCP bane um endereço após cinco autenticações recusadas, com o fail2ban, maxretry = 5 e um DROP do iptables. Uma vez disparado, as chamadas deixam de exceder o tempo-limite ao nível da aplicação e passam a excedê-lo ao nível da rede: a sua monitorização diz que o painel está inacessível, e nada nos seus registos aponta para um problema de credenciais.

Para uma integração de faturação, isto conta mais do que para qualquer outra coisa, porque uma integração de faturação é o que corre sem supervisão durante a noite. Duas consequências:

• Os códigos de saída 9, 10 e 21 nunca devem despoletar uma repetição automática. São, respetivamente, segredo errado, permissão recusada e API desativada. Nenhum deles é uma falha passageira, e os três contam para o banimento.
• Um comando fora das permissões da chave também conta como uma autenticação falhada. Não é óbvio: a mesma linha de registo é escrita para um segredo errado e para uma chave válida que estende a mão a um comando que não tem autorização para executar. Uma chave limitada ao conjunto de permissões billing fornecido de origem no HestiaCP não tem v-list-user-packages nem v-list-web-domains, pelo que um ciclo de sondagem que lê pacotes e domínios esgota o contador de banimento conforme previsto. Use uma chave sem âmbito restrito, a do administrador.

Levantar um banimento exige um terminal no anfitrião do painel: v-delete-firewall-ban <endereço> HESTIA. Se o software que constrói não souber dizer essa frase, quem estiver de piquete às três da manhã passará a noite no problema errado.

Uma encomenda paga custa dois comandos, por isso precisa de uma reversão

O HestiaCP não tem nenhum comando que crie um utilizador e lhe associe um domínio de uma só vez. Isso deixa uma janela:

v-add-user       provibrtest1 …                         → 204, saída 0
v-add-web-domain provibrtest1 "não é um domínio válido" → 422, saída 2
v-list-user      provibrtest1                           → a conta existe, com zero domínios

Um verdadeiro utilizador unix, com um diretório pessoal, sem site, e uma linha em cada contagem. Se o domínio do cliente já estava ocupado no seu painel (o que acontece, porque os clientes se mudam), a encomenda falha e fica com meia conta na mão que ninguém alguma vez notará.

A regra é simples e tem de estar embutida: se o segundo passo falhar, elimine o utilizador e reporte o erro original. Um domínio recusado nunca deve deixar meia conta para trás.

O Provibr faz exatamente isso, e o erro que o cliente vê é o que o HestiaCP deu para o domínio, não um erro secundário sobre uma limpeza.

Onde vive realmente a fatura

Vale a pena ser explícito, porque é o mal-entendido mais comum: o Provibr não fatura os seus clientes. Não lhes envia qualquer fatura, não anda atrás deles para cobrar, e não sabe o que lhes cobra. Essa relação é sua.

O que o Provibr fatura é a capacidade que o próprio reserva: quantas contas de alojamento pode ter em funcionamento em simultâneo, por mês, a um preço unitário escalonado. O que cobra aos seus próprios clientes por uma conta HestiaCP, e como, fica inteiramente dentro do seu próprio sistema de faturação.

Há duas formas de ligar as duas metades:

Um módulo WHMCS. Se já usa o WHMCS, instale o módulo de aprovisionamento do Provibr e faça um produto do WHMCS apontar para um plano web do Provibr. Uma encomenda paga cria a conta; uma suspensão no WHMCS suspende-a; uma rescisão remove-a. O seu cliente mantém uma conta, uma fatura e um identificador de acesso. O módulo é um simples zip que instala por si próprio, e corre dentro do seu WHMCS. Não há nada a ativar do nosso lado.

A API REST. Se usa o FOSSBilling, o Blesta, algo interno, ou uma folha de cálculo e uma tarefa cron, comande-a diretamente. Uma chave, um URL de base, e exatamente as permissões que o membro por trás da chave já tem.

A única regra para o comandar a partir do seu próprio código

Tudo o que toca numa máquina é assíncrono, e tem de ser. A sua infraestrutura só é alcançável através do agente que está dentro da sua própria rede, e esse agente liga para o exterior. Por isso, um ponto de acesso que altera uma conta não pode responder com o resultado. Responde que a encomenda foi aceite e entrega-lhe um comando para seguir, que lê até que o seu estado seja definitivo: concluído, falhado, expirado ou cancelado. Um comando falhado transporta o próprio código de erro do agente, com os seus argumentos, o mesmo que o painel apresenta no ecrã.

A leitura nunca funciona assim. Um inventário, um endereço ou uma fatura responde imediatamente, porque essa resposta vem de uma base de dados e não do seu anfitrião.

A consequência prática para um gancho de faturação: não marque a encomenda como concluída com base na resposta de aceitação. No HestiaCP, v-add-user demora cerca de um segundo e v-delete-user cerca de três, pelo que a espera é curta, mas a primeira resposta que obtém diz «enviámos», não «funcionou».

Suspender é também controlar os seus próprios custos

Uma ligação fácil de não notar. No Provibr, um servidor suspenso não conta para a sua capacidade, e para uma conta de alojamento não existe «parado»: há ativo e suspenso.

Assim, a ação de cobrança que já queria executar por razões comerciais é também a que liberta o lugar que está a pagar. Suspenda uma conta em atraso e ela deixa imediatamente de contar; elimine-a e também deixa de contar; deixe-a a correr por pagar e está a pagá-la.

O que isto não automatiza

O Provibr gere contas, não o painel. Não instala o HestiaCP, não o atualiza, não altera definições do servidor, e não toca no DNS, nas caixas de correio ou nas bases de dados. Um cliente que elimina a sua própria caixa de correio através do HestiaCP fá-lo sem que nada acima disso o saiba ou se importe. Não há consola para uma conta de alojamento. E não há suspensão parcial: uma conta está ativa ou não está.

Se também vende VPS, servidores de jogos ou contas cPanel, os mesmos três momentos aplicam-se a todos eles, e podem viver num único inventário. O Provibr faz correr hoje os seus painéis de controlo, os seus hipervisores e os seus painéis de jogo lado a lado, com um único conjunto de permissões e um único registo de atividade para o conjunto.