Venda hospedagem Zinn® a partir do WHMCS

O módulo do Zinn Digital® transforma os botões do próprio WHMCS em ações reais em nossa plataforma. Um pedido provisiona a hospedagem do seu cliente. A automação de faturas vencidas do WHMCS a suspende. Marcar a fatura como paga a reativa. O cancelamento agenda a exclusão. E o seu cliente ganha um botão Log in to hosting panel na área do cliente dele, que faz o login diretamente.

Ele é gratuito, licenciado sob a GPL-2.0-or-later e não possui caminhos privilegiados em nossa plataforma: cada chamada feita é um endpoint documentado que você mesmo poderia chamar com sua própria chave de API.

Antes de começar

Você precisa de duas coisas, e a segunda costuma pegar as pessoas de surpresa.

1. Uma conta de revendedor Zinn® com um programa ativo. Cadastre-se em zinndigital.com e ative a revenda.
2. Um plano de revendedor com limite de sites disponível. Os sites que seus clientes solicitam são contabilizados no seu plano; portanto, você precisa de um plano com espaço livre.

⚠️ O Test Connection não é capaz de informar se um pedido será bem-sucedido. Ele apenas lê o seu programa e não provisiona nada, reportando, assim, uma conta active em perfeito estado que ainda não pode vender nada. Se o seu primeiro pedido falhar com "This organization has no hosting plan, so it cannot host a site yet", foi isso o que aconteceu — adquira ou amplie seu plano de revendedor e faça o pedido novamente. Não há nada de errado com o módulo.

1. Criar a chave de API

No seu painel Zinn®, abra API keys e crie uma com exatamente estas onze permissões:

⛔ Não conceda reseller.manage. Uma chave colada em um painel financeiro deve ser capaz de reter um cliente por falta de pagamento e conectá-lo ao painel. Ela não deve ter permissão para ler e regravar as credenciais do seu próprio gateway de pagamento. A permissão reseller.provision existe exatamente para que você não precise conceder essa permissão mais abrangente. ⛔ org.create não é opcional. Sem ela, o módulo consegue ler suas contas, mas não consegue abrir uma nova; assim, o Test Connection é aprovado e o primeiro pedido retorna 403. ⛔⛔ Conceda todas as permissões da tabela e note que o Test Connection não é capaz de informar se você deixou de incluir alguma. Ele lê o seu programa de revendedor e não provisiona nada, ficando verde mesmo para uma chave que não possua qualquer uma delas. O que você receberá, em vez disso, é um 403 na operação exata coberta pela permissão ausente, meses depois, vindo de um cliente.

2. Instalar o módulo

1. Baixe o módulo e descompacte-o.
2. Envie o diretório zinn para dentro da sua instalação do WHMCS, de modo que o arquivo do módulo fique localizado em modules/servers/zinn/zinn.php.

⛔ O diretório deve se chamar obrigatoriamente zinn. O WHMCS deduz os nomes das funções de um módulo de provisionamento a partir do nome do seu diretório; portanto, renomeá-lo para zinn-whmcs ou zinndigital fará com que o WHMCS liste o módulo, permita selecioná-lo e, em seguida, nunca o chame — sem exibir erro algum. O arquivo zip já é descompactado com o nome correto; basta não renomeá-lo.

3. Adicionar o servidor

No WHMCS: Configuration → System Settings → Servers → Add New Server.

• Name: qualquer um, por exemplo, Zinn Digital®
• Hostname: api.zinndigital.com
• Type: Zinn Digital®
• Password: sua chave de API da etapa 1

⛔ A chave deve ser inserida no campo Password, que o WHMCS armazena de forma criptografada. Não a insira em uma opção de configuração de produto — elas ficam em texto simples no banco de dados e visíveis para qualquer administrador, e essa credencial tem permissão para criar e destruir a hospedagem dos seus clientes.

Clique em Test Connection. Ele realiza uma chamada real e retorna o que a nossa plataforma respondeu, em vez de apenas verificar se os campos foram preenchidos.

4. Criar o produto

Configuration → System Settings → Products/Services, e então defina Module Settings para o servidor que acabou de adicionar. Os campos são:

⛔⛔ Plan code é obrigatório, e qualquer pedido sem ele é recusado propositalmente. Até 01/09/2026, esse campo era apenas decorativo e nada o lia, de modo que o módulo realizava pedidos de hospedagem que não continham plano algum — e todas as consequências disso aconteciam de forma silenciosa. Seu faturamento por atacado é construído a partir das assinaturas ativas dos seus clientes; portanto, não havia item na fatura para o serviço e nada era faturado de você durante todo o período em que ele rodou; seu cliente não herdava limites, portanto nenhuma cota de disco ou arquivos era aplicada ao site dele; e o comando Change Package não tinha nada para alterar, de forma que um upgrade vendido não podia ser executado. O site era provisionado e funcionava perfeitamente durante todo o tempo.

Agora, o módulo recusa o pedido, pois não existe um plano seguro para ele presumir: uma suposição provisionaria a hospedagem em um plano que você não escolheu e pode não ter precificado e, diferentemente de uma recusa — que você visualiza imediatamente —, isso só seria notado quando a fatura chegasse, se chegasse.

Defina o Auto Setup como preferir — o módulo é idempotente em relação ao ID de serviço do WHMCS, de modo que uma nova tentativa de provisionamento retorna o mesmo site em vez de cobrar você por um segundo.

O que cada ação do WHMCS faz

Upgrades: quem cobra de quem

O seu cliente nunca recebe faturas da Zinn®, seja em um pedido ou em um upgrade. Você o cobra por meio do WHMCS; nós cobramos você, em sua fatura de atacado. Portanto, um Change Package altera os direitos do seu cliente e a linha na sua próxima fatura, sem realizar cobranças em nenhum cartão — o WHMCS já cobrou o valor do cliente e calculou a sua própria divisão proporcional.

Um segundo serviço para o cliente. No mesmo plano, trata-se de outro site sob o limite de sites do próprio plano, e nenhum recurso adicional é concedido. Em um plano diferente, a operação é recusada: substituir o plano ativo deixaria um dos dois serviços sem cobrança. Venda ambos no mesmo plano ou cadastre o cliente em um registro de cliente separado no WHMCS.

Change Password existe apenas para o WordPress. A hospedagem Zinn® não possui uma "senha de serviço" única — seu cliente acessa o painel por meio do botão de login —, e um site php ou static não tem conta de aplicativo para alterar. O WHMCS oculta totalmente a caixa em vez de exibir um recurso que não funciona.

Três respostas que não devem ser tratadas de forma igual

• Unsuspend pode responder com uma recusa. Isso significa que o site foi suspenso pela nossa equipe de combate a abusos, e não por você, e nenhum painel de faturamento pode liberá-lo. A mensagem detalha essa situação; mostre-a ao seu administrador em vez de tentar novamente.
• Terminate agenda uma exclusão, ele não a executa de imediato. A data é retornada como pending_deletion_at e a área do cliente a exibe. Dizer a um cliente que os dados dele já foram apagados quando isso não aconteceu é pior do que não dizer nada.
• Disco e largura de banda podem constar como desconhecidos, e desconhecido não é zero. Quando não conseguimos fazer uma leitura, o módulo mantém o valor inalterado em vez de gravar 0 — caso contrário, o WHMCS exibiria ao seu cliente uma barra de uso vazia e enganosamente reconfortante para um site do qual não temos nenhuma leitura.

Solução de problemas

O Test Connection é aprovado, mas o primeiro pedido falha com um erro de permissão. Falta a permissão org.create na chave de API. O módulo precisa abrir a conta do cliente antes de poder criar o site dele.

Um pedido falha informando que a organização não possui plano de hospedagem. O seu plano de revendedor esgotou o limite de sites disponível, ou você ainda não possui um plano ativo. Consulte a seção Antes de começar acima.

Um pedido falha mencionando uma stack. O campo Stack no produto está vazio ou indica algo que não compilamos. Defina-o como wordpress, a menos que esteja vendendo outra coisa.

Cancelamentos estão falhando. Certifique-se de estar usando a versão 1.0.0 do módulo ou superior. Versões anteriores não enviavam confirmação de exclusão e todo encerramento era recusado, fazendo com que o serviço continuasse ativo e gerando cobranças.

Uma recusa que cita um campo. Nossos erros de validação trazem o campo e a justificativa entre colchetes após a mensagem, por exemplo: (php_version: 7.2 is not offered on this product line). Essa é a parte que exige ação — a frase anterior a ela é deliberadamente genérica.

Verifique seu download

Cada arquivo é distribuído via TLS a partir de nosso próprio hostname e nunca é redirecionado para um servidor de terceiros. Seu checksum SHA-256 está indicado ao lado do link de download na página de downloads. Compare-o após baixar o arquivo:

• macOS ou Linux: shasum -a 256 zinn-whmcs-1.0.0.zip
• Windows: certutil -hashfile zinn-whmcs-1.0.0.zip SHA256

Não usa WHMCS?

Disponibilizamos um módulo para HostBill e um cliente PHP em arquivo único para quaisquer outros sistemas, ambos gratuitos e disponíveis na mesma página de downloads. Cada endpoint utilizado pelos módulos está documentado na referência da API.