Venda a hospedagem Zinn® pelo WHMCS

O módulo da Zinn Digital® converte os botões do próprio WHMCS em ações reais na nossa plataforma. Um pedido provisiona a hospedagem do seu cliente. A automação de fatura vencida do WHMCS a suspende. Marcar a fatura como paga a libera. Cancelar agenda a exclusão. E o seu cliente recebe um botão Entrar no painel de hospedagem na área do cliente que o conecta diretamente.

Ele é gratuito, licenciado sob GPL-2.0-or-later e não possui nenhum caminho privilegiado para a nossa plataforma: cada chamada que ele faz é um endpoint documentado que você mesmo poderia fazer com sua própria chave de API.

Antes de começar

Você precisa de duas coisas, e a segunda pega muita gente de surpresa.

1. Uma conta de revendedor da Zinn® com um programa ativo. Inscreva-se em zinndigital.com e ative a revenda.
2. Um plano de revendedor com limite de sites. Os sites que seus clientes pedem contam para o seu plano, então você precisa de um que tenha espaço disponível.

⚠️ O teste de conexão não consegue dizer se um pedido será bem-sucedido. Ele lê seu programa e não provisiona nada, portanto, ele relata uma conta active saudável 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 — compre ou estenda 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 da Zinn®, abra API keys e crie uma com exatamente estas onze permissões:

| Permissão | Por que é necessária | | -------------------- | ----------------------------------------------------------- | | org.create | Abre a conta do seu cliente na Zinn® no primeiro pedido. | | org.read | Lê as contas dos seus clientes. | | sites.create | Provisiona o site. | | sites.view | Lê um serviço e seu uso. | | sites.delete | Encerra. | | reseller.view | Lista o que você vendeu e lê o disco e a largura de banda. | | reseller.provision | Suspende, libera, conecta um cliente, define o plano dele e altera o pacote dele. | | billing.view | Lê quanto custaria um upgrade antes de realizá-lo. | | sites.manage | Limpa o cache e faz um backup a partir dos botões. | | sites.panel_access | Altera a senha do administrador do WordPress. | | hosting.php.manage | Alterna a versão do PHP em um upgrade ou downgrade. |

⛔ Não conceda reseller.manage. Uma chave colada em um painel de faturamento deve ser capaz de reter um cliente por falta de pagamento e conectá-lo. Ela não deve ser capaz de ler e reescrever as credenciais do seu próprio gateway de pagamento. A permissão reseller.provision existe para que você não precise conceder a mais abrangente. ⛔ org.create não é opcional. Sem ela, o módulo pode ler suas contas, mas não pode abrir uma, de modo que o teste de conexão passa e o primeiro pedido retorna 403. ⛔⛔ Conceda toda a tabela e observe que o teste de conexão não consegue dizer se você não o fez. Ele lê seu programa de revendedor e não provisiona nada, portanto, ele fica verde para uma chave que esteja perdendo qualquer uma delas. O que você recebe em troca é um 403 na única operação que a permissão ausente cobre, 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 a sua instalação do WHMCS para que o arquivo do módulo fique em modules/servers/zinn/zinn.php.

⛔ O diretório deve se chamar zinn. O WHMCS deriva os nomes das funções de um módulo de provisionamento do nome do diretório dele, portanto, renomeá-lo para zinn-whmcs ou zinndigital produz um módulo que o WHMCS lista, permite que você selecione e nunca chama — sem nenhum erro em lugar nenhum. O arquivo zip já é descompactado com o nome correto; apenas não o renomeie.

3. Adicionar o servidor

No WHMCS: Configurações → Configurações do Sistema → Servidores → Adicionar Novo Servidor.

• Nome: qualquer um, por exemplo, Zinn Digital®
• Nome do host: api.zinndigital.com
• Tipo: Zinn Digital®
• Senha: sua chave de API da etapa 1

⛔ A chave vai no campo Senha, que o WHMCS armazena criptografado. Não a coloque em uma opção de configuração de produto — elas ficam em texto simples no banco de dados e são visíveis para todos os administradores, e essa credencial pode criar e destruir a hospedagem dos seus clientes.

Pressione Testar Conexão. Ela faz uma chamada real e relata o que nossa plataforma disse, em vez de apenas verificar se os campos estão preenchidos.

4. Criar o produto

Configurações → Configurações do Sistema → Produtos/Serviços, depois defina Configurações do Módulo para o servidor que você acabou de adicionar. Os campos são:

| Campo | Obrigatório | O que é | | ---------------- | ----------- | -------------------------------------------------------------------------- | | Product line | sim | A linha da Zinn® que você está vendendo — mainstream (WordPress gerenciado), footprint_free, wordpress, linux, cloud, agency, app_hosting, ai_hosting, lms_hosting, managed_database, vector_hosting, zinn_compute, fleet_linux, fleet_enterprise, mail ou reseller. | | Stack | sim | O que é construído: wordpress (padrão), woocommerce, php, static, node, one_click, headless_cms, nextcloud ou owncloud. | | Application | não | Apenas para as stacks one_click e headless_cms — qual aplicativo instalar. Nomear um em qualquer outra stack é recusado, porque essa stack já decide o que é instalado. | | PHP version | não | por exemplo, 8.3. Deixe em vazio para o padrão da linha. Uma versão que a linha não oferece é recusada com a lista daquelas que ela oferece. | | Plan code | sim | O plano da Zinn® que este produto vende. GET /v1/reseller/prices lista os seus. Um pedido sem ele é recusado — veja o aviso abaixo. | | Billing interval | não | monthly (padrão) ou annual — o intervalo em que a sua linha de atacado para este cliente é cobrada. O que você cobra do seu próprio cliente é definido no produto WHMCS e não é afetado. |

⛔⛔ O código do plano é obrigatório, e um pedido sem ele é recusado propositalmente. Até 01/09/2026, o campo era decorativo e nada o lia, de modo que o módulo solicitava hospedagem que não carregava nenhum plano — e todas as consequências disso eram silenciosas. Seu extrato de atacado é gerado a partir das assinaturas ativas dos seus clientes, portanto, não havia linha para o serviço e você não era faturado por nada enquanto ele estivesse rodando; seu cliente não herdava nenhum benefício, portanto, nenhuma cota de disco ou arquivo era aplicada ao seu site; e Alterar Pacote não tinha nada para alterar, de modo que um upgrade que você vendeu não podia ser realizado. O site foi provisionado e funcionou perfeitamente o tempo todo.

Agora o módulo recusa o pedido em vez disso, porque não há um plano seguro para ele adivinhar: um palpite provisionaria hospedagem em um plano que você não escolheu e pode não ter precificado, e — ao contrário de uma recusa, que você lê imediatamente — isso só viria à tona quando um extrato chegasse, se é que chegasse.

Defina Auto Setup para o que você preferir — o módulo é idempotente em relação ao ID do serviço no WHMCS, portanto, um provisionamento repetido retorna o mesmo site em vez de cobrar você por um segundo.

O que cada ação do WHMCS faz

| Ação do WHMCS | O que acontece do nosso lado | | --------------------------- | ---------------------------------------------------------------------------------------- | | Criar | Cria a conta do cliente na Zinn® (ou reutiliza a que ele já tem) e provisiona o site dele. | | Suspender | Coloca o site em retenção por falta de pagamento. O conteúdo é retido; nada é excluído. | | Remover suspensão | Libera a sua retenção. | | Encerrar | Agenda a exclusão do site, com um período de carência. A data aparece na área do cliente. | | Atualização de uso | Atualiza o disco e a largura de banda em cada serviço, uma vez por dia. | | Entrar no painel de hospedagem | Abre um link de login de uso único direto para o painel do seu cliente. | | Alterar Pacote | Faz upgrade ou downgrade do serviço. Move o pacote e a versão do PHP se o novo produto especificar uma. | | Alterar Senha | Define a senha do administrador do WordPress. A caixa não aparece em stacks que não possuem essa conta. | | Renovar | Confirma que o serviço ainda existe. A hospedagem na Zinn® é contínua, portanto, não há prazo remoto a ser estendido. | | Sincronizar Uso / Limpar Cache / Fazer Backup | Botões na página de serviço do administrador. Seu cliente recebe Limpar Cache e Fazer Backup na área do cliente. | | Aba de serviço | Status, plano, disco, largura de banda, qualquer exclusão agendada e quem aplicou uma suspensão. | | Importar | ListAccounts lê todas as páginas, de modo que uma importação não pode parar silenciosamente na primeira. |

Upgrades: quem cobra de quem

Seu cliente nunca é faturado pela Zinn®, seja em um pedido ou em um upgrade. Você cobra deles pelo WHMCS; nós cobramos de você, no seu extrato de atacado. Portanto, Alterar Pacote move os direitos do seu cliente e a linha no seu próximo extrato, e não mexe em nenhum cartão — o WHMCS já recebeu o dinheiro do seu cliente e calculou a própria proporcionalidade.

O segundo serviço de um cliente. No mesmo plano, é outro site sob a franquia de sites desse próprio plano, e nada mais é concedido. Em um plano diferente, é recusado: substituir o plano ativo deixaria um dos dois serviços sem faturamento. Venda ambos no mesmo plano ou configure o cliente como um registro de cliente separado no WHMCS.

Alterar Senha existe apenas para o WordPress. A hospedagem na Zinn® não tem uma única "senha de serviço" — seu cliente acessa o painel com o botão de login — e um site php ou static não tem conta de aplicativo para alterar. O WHMCS oculta a caixa inteiramente em vez de mostrar uma que não pode funcionar.

Três respostas que você não deve nivelar em duas

• Remover suspensão pode responder com uma recusa. Isso significa que o site foi suspenso pela nossa equipe de abuso, e não por você, e nenhum painel de faturamento pode liberá-lo. A mensagem diz isso; mostre-a ao seu administrador em vez de tentar novamente.
• Encerrar agenda uma exclusão, não a executa. A data retorna como pending_deletion_at e a área do cliente a exibe. Dizer a um cliente que os dados dele já se foram quando não se foram é pior do que não lhe dizer nada.
• Disco e largura de banda podem ser desconhecidos, e desconhecido não é zero. Quando não conseguimos fazer uma leitura, o módulo deixa o valor como está em vez de escrever 0 — caso contrário, o WHMCS mostraria ao seu cliente uma barra de uso vazia e tranquilizadora para um site do qual não temos nenhuma leitura.

Solução de problemas

O teste de conexão passa e o primeiro pedido falha com um erro de permissão. A chave de API está sem a permissão org.create. O módulo precisa abrir a conta do cliente antes de poder criar o site dele.

Um pedido falha dizendo que a organização não tem plano de hospedagem. Seu plano de revendedor não tem mais limite de sites disponível ou você ainda não possui um. Veja Antes de começar acima.

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

Os cancelamentos estão falhando. Certifique-se de estar usando a versão 1.0.0 do módulo ou posterior. Versões anteriores não enviavam confirmação de exclusão e cada encerramento era recusado, o que deixava o serviço em execução e gerando cobrança.

Uma recusa que nomeia um campo. Nossos erros de validação nomeiam o campo e o motivo entre colchetes após a mensagem, por exemplo, (php_version: 7.2 is not offered on this product line). Essa é a metade acionável — a frase na frente dela é propositalmente genérica.

Verificar seu download

Cada arquivo compactado é fornecido via TLS a partir do nosso próprio nome de host e nunca redirecionado para um host de terceiros. Sua soma de verificação SHA-256 é impressa ao lado do link de download na página de downloads. Compare-a após baixar:

• 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 o WHMCS?

Há um módulo para o HostBill e um cliente PHP de arquivo único para qualquer outra coisa, ambos gratuitos e ambos na mesma página de downloads. Cada endpoint que os módulos usam está na referência da API.