Automatizar a faturação com o ISPConfig

O ISPConfig tem um comando para cada momento em que o dinheiro e as máquinas se tocam: criar a conta, suspendê-la, mudá-la para outro pacote, removê-la. O que não tem é seja o que for que decida quando os executar.

Ligar as duas metades é sobretudo trabalho corrente. Duas coisas no ISPConfig não são correntes, e ambas quebram silenciosamente uma primeira tentativa: o código de estado de uma chamada não lhe diz absolutamente nada, e uma conta não é um cliente.

O código de estado não diz nada

Tudo volta como HTTP 200. Erros de validação, «isso não existe», uma palavra-passe errada, um método que o utilizador remoto não tem autorização para chamar: todos eles, 200. O veredicto é um campo code dentro do corpo JSON.

Classifique pelo code e pelo texto, nunca pelo estado. A razão pela qual isto importa mais a uma integração de faturação do que a qualquer outra coisa é a sondagem: um cliente que trate 200 como êxito lê uma falha de autenticação como um inventário vazio bem-sucedido e, a seguir, marca todas as contas desse cliente como desaparecidas. Uma sessão expirada, e a sua reconciliação elimina um negócio de alojamento.

O campo message vem em dois sabores, e a diferença é útil. Os erros de validação da própria camada de formulários do painel são uma lista de chaves de tradução separada por <br>, não frases: domain_error_unique para um domínio que já está alojado. As verificações na biblioteca remota são frases em inglês corrente: Invalid client_id 99999. Faça correspondência com as chaves, cite as frases.

Uma conta é um site, não um cliente

O ISPConfig separa duas coisas que a maioria dos painéis de controlo funde. Um cliente é um identificador de acesso ao painel com limites para toda a conta. Um web_domain é um site alojado. Um cliente pode ser dono de vários sites.

Uma conta de alojamento do Provibr é um site, identificada pelo seu domínio. Criar uma precisa por isso de um dono, pelo que o agente cria um cliente novo e um site por baixo dele, e deriva o identificador de acesso do cliente a partir do domínio para conseguir sempre voltar a encontrar o dono.

Essa escolha é o que torna seguro o caminho da eliminação, e o caminho da eliminação é onde esta integração quase correu mal. Mais sobre isso abaixo.

O ciclo de vida, em correspondência

Suspender é idempotente nos dois sentidos

A suspensão alterna o indicador active do site entre y e n. Não há máscaras de bits nem estados parciais: um site está ligado ou está desligado.

Uma segunda suspensão num site já suspenso responde code: ok com uma resposta de 0, ou seja, zero linhas alteradas. Isso não é um erro, e um ciclo de cobrança que suspende tudo o que está vencido, incluindo o que suspendeu ontem, não tem de pedir desculpa por nada. Vale a pena apreciar como isso é raro: como se lê em Automatizar a faturação com o HestiaCP, ali a mesma segunda suspensão é um HTTP 401, indistinguível de um segredo errado, num painel que bane o seu endereço após cinco autenticações recusadas.

Uma coisa a conhecer, ainda que a integração não a use: o ISPConfig tem também um bloqueio ao nível do cliente, e ativá-lo passa todos os sites desse cliente a inativos de uma só vez. Um cliente que se tranca a si próprio no painel, ou um bloqueio de revendedor acima dele, aparece por isso na sondagem como suspenso. Isso está correto, e não é algo que o seu sistema de faturação tenha feito.

Mudar de pacote é aqui uma verdadeira ação

Um pacote do ISPConfig é um modelo de cliente: um conjunto de limites com nome, construído por um administrador no painel. A API remota não consegue criar um, o que não faz mal, porque um plano deve referir-se a um pacote em vez de o inventar. O Provibr passa o nome do pacote e o agente procura o identificador do modelo.

Isso faz do ISPConfig um dos painéis de controlo onde uma mudança de plano é genuinamente uma mudança de plano. O CloudPanel e o CyberPanel têm de a recusar por completo; aqui acontece e os limites mudam de imediato.

Duas cautelas medidas, se escrever isto por si próprio. Envie uma atualização mínima, transportando apenas o novo modelo: uma atualização com o registo completo do cliente voltou como remote_fault sem mensagem aproveitável, e o mesmo aconteceu com uma que combinava um modelo explícito com limites explícitos. E saiba que o modelo prevalece sobre os limites que envie ao mesmo tempo, o que é o sentido certo mas surpreende as pessoas à primeira vez.

O sinal de pronto é global ao servidor

Criar um site responde em milissegundos, e essa resposta significa aceite, não feito. A linha da base de dados existe; o anfitrião virtual e a raiz de documentos são assentes de forma assíncrona pelo daemon do servidor.

O sinal pelo qual esperar é a contagem da fila de trabalhos desse servidor, que foi medida a descer de três para zero em cerca de oito segundos numa máquina sossegada, e em cerca de vinte e três segundos numa execução anterior. É um contador global, não um contador por comando. Num servidor multi-inquilino movimentado pode ficar acima de zero por causa dos trabalhos de outros clientes, ou chegar a zero enquanto o seu trabalho ainda está pendente.

Por isso, a regra é um tempo-limite com uma mensagem verdadeira em vez de uma espera infinita: sondar até a fila estar vazia ou até esgotar o orçamento de criação de 180 segundos, e depois reportar a conta como criada, porque está. «O site ainda está a ser configurado» é melhor coisa para dizer a um cliente que paga do que um indicador de espera que nunca para.

Eliminar é uma questão de privacidade, não uma questão de limpeza

Esta é a parte do artigo a guardar se não guardar mais nada, e na verdade não é sobre o ISPConfig.

O caminho da eliminação tinha um defeito que nenhuma fixture conseguia ver: comparava dois campos que nunca são de facto iguais, pelo que o ramo que removia o cliente dono era código morto. Cada eliminação deixava para trás um identificador de acesso ao painel com o nome do cliente, o seu endereço de correio, os seus contactos e a sua palavra-passe. O comando respondia ok, o site desaparecia, o contador ia a zero, e os dados pessoais de uma pessoa que tinha pedido para sair ficavam no nó.

Nada acima do painel consegue ver isso. Um trabalhador de expurgo e uma exportação de dados do titular limpam o nosso lado; não têm qualquer vista do que sobra no seu nó de alojamento. A regra que daí saiu vale a pena roubar:

> Meça um caminho de eliminação contra a própria base de dados do painel, e nunca contra «o comando respondeu ok».

No ISPConfig isso são quatro contagens, e as quatro têm de estar a zero: sites, clientes, identificadores de acesso ao sistema e o diretório do cliente no disco. E meça com o painel em vez de o fazer com o auxiliar de limpeza do seu próprio teste, porque o auxiliar pode transportar o mesmo mal-entendido e então a máquina parece limpa enquanto a integração deixa fugir dados.

A regra de eliminação segura em si é uma linha: remova o site; remova o cliente dono apenas se ele não tiver mais sites. O ISPConfig tem uma chamada que elimina um cliente e tudo o que está por baixo dele e, numa conta importada, isso levaria consigo os outros sites do cliente. Nunca elimine mais do que foi pedido.

Nada é instantâneo

O seu painel só é alcançável através do agente que está dentro da sua própria rede, e esse agente liga para o exterior, pelo que 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 até que o seu estado seja definitivo: concluído, falhado, expirado ou cancelado. A leitura nunca funciona assim, porque um inventário ou uma fatura 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. Tudo o que cria algo aceita também uma chave de idempotência da sua própria autoria, pelo que um webhook reenviado e um duplo clique não lhe custam nada.

Onde vive a fatura

O Provibr não fatura os seus clientes, 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 reserva: quantas contas de alojamento pode ter em funcionamento em simultâneo, a um preço unitário que desce por escalões à medida que a contagem sobe. Para uma conta de alojamento não existe «parado»: há ativo e suspenso, e uma conta suspensa não conta. Assim, a ação de cobrança que já queria por razões comerciais é também a que liberta o lugar que está a pagar.

O que não é automatizado

O Provibr gere contas, não o painel. Não instala o ISPConfig, não o atualiza, e não toca em caixas de correio, bases de dados ou DNS: um cliente que elimina a sua própria caixa de correio fá-lo sem que nada acima do painel o saiba ou se importe. Não há consola para uma conta de alojamento, não há reinstalação, e não há suspensão parcial.

Se está numa fase anterior a esta e ainda não chegou à parte da faturação, a peça companheira é Vender alojamento web com ISPConfig, que cobre o utilizador remoto, a delimitação de permissões e o modelo de um painel para vários servidores. As credenciais, o certificado e o ecrã dos pacotes estão documentados na página de documentação do ISPConfig.