Vendendo a hospedagem Zinn® a partir de seus próprios sistemas

Você revende nossa hospedagem. Seus clientes são seus: seus preços, suas faturas, seu provedor de pagamento. É assim que você opera nossa plataforma a partir do que você já utiliza — um painel de faturamento, seu próprio site WordPress ou um script.

O que seus clientes realmente veem

Antes da mecânica: seus clientes nunca precisam nos ver. Três superfícies, e você escolhe qual usar.

| Superfície | De quem é | |---|---| | O painel de hospedagem, no seu próprio domínio | Defina um domínio de painel em Revenda → Sua marca e seus clientes farão login em panel.yourcompany.com com seu logotipo e suas cores. O mesmo painel, o seu endereço. | | Seu próprio site | O plugin do WordPress coloca a busca de domínios e um link de login com um clique no seu site, e processa o pedido pelo seu próprio checkout do WooCommerce. | | Seu painel de faturamento | O WHMCS ou HostBill continua sendo a porta de entrada; o módulo faz o provisionamento por trás dele e o botão da área do cliente os direciona direto para a hospedagem deles. |

⛔ Seja qual for a sua escolha, você é o comerciante oficial (merchant of record) para os seus clientes: seus preços, suas faturas, seu número de IVA/CNPJ, seu provedor de pagamento. Nós cobramos de você, uma vez por mês, por atacado.

Assim que tiver definido o domínio do painel, coloque-o no campo Endereço do painel do plugin do WordPress e em nenhum outro lugar — os links de login gerados por esta API seguem esse endereço automaticamente.

As quatro formas de integração

Existem quatro formas de entrada, e todas fazem a mesma coisa por trás:

| | Para | |---|---| | O módulo WHMCS | Uma loja WHMCS | | O módulo HostBill | Uma loja HostBill | | O plugin do WordPress | Vender a partir do seu próprio site WordPress ou WooCommerce | | A API | Qualquer outra coisa — Blesta, um sistema interno, um script cron |

1. Obtenha uma chave de API

No seu painel, vá para Chaves de API e crie uma. Conceda a ela apenas o que for necessário:

| Permissão | Por quê | |---|---| | org.read | Ler as contas dos seus clientes | | sites.create | Provisionar um site | | sites.view | Ler um serviço | | sites.delete | Encerrar | | reseller.view | Listar seus serviços e ler o uso | | reseller.provision | Suspender, liberar e fazer login de um cliente |

⛔ Não dê a uma integração a permissão reseller.manage. Essa permissão edita sua tabela de preços e suas próprias credenciais do gateway de pagamento. A permissão reseller.provision existe justamente para que uma chave colada em um painel de faturamento ou site não precise disso.

A chave é exibida apenas uma vez. Armazene-a onde você guarda suas outras credenciais — nunca em um arquivo servido pelo seu servidor Web.

2. Faça sua primeira chamada

curl https://api.zinndigital.com/v1/reseller/services \
  -H "Authorization: Bearer zdk_live_…"

Isso retorna todos os serviços que você provisionou, uma linha por site, com o cliente ao qual ele pertence, seu status e o que você cobra por ele. Em uma nova conta, será uma lista vazia — o que é a resposta correta, e não um erro.

3. A integração completa, em seis chamadas

QUANDO                CHAMADA
um pedido é pago     POST   /v1/orgs                                   uma vez por CLIENTE
                     POST   /v1/sites                                  uma vez por SERVIÇO
eles não pagaram     POST   /v1/reseller/services/{siteId}/suspend
eles pagam           POST   /v1/reseller/services/{siteId}/unsuspend
eles cancelam        DELETE /v1/sites/{siteId}
"fazer login na h."  POST   /v1/reseller/services/{siteId}/sso

O provisionamento consiste em duas chamadas, e as chaves são importantes:

# 1. a conta do cliente — baseada no SEU ID de cliente
curl -X POST https://api.zinndigital.com/v1/orgs \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-4211" \
  -d '{"type":"customer","name":"Acme Ltd"}'

# 2. o site deles — baseado no SEU ID de serviço
curl -X POST https://api.zinndigital.com/v1/sites \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: service-9915" \
  -d '{"org_id":"<from step 1>","product_line":"mainstream","primary_domain":"acme.com"}'

Duas regras que custam dinheiro quando você erra

Baseie a conta no seu CLIENTE e o site no seu SERVIÇO. O segundo pedido de um cliente deve cair na conta que ele já possui. Se você basear ambos no serviço, um cliente acabará com três contas não relacionadas e três painéis separados.
Envie um Idempotency-Key em cada POST, construído a partir do seu próprio ID para o item. Todo sistema de faturamento realiza novas tentativas — o retorno de um gateway chega duas vezes, um administrador reexecuta um provisionamento com falha, um cliente clica duas vezes. Sem a chave, a segunda tentativa criará um segundo site e você será cobrado por ele.

Três respostas que você não deve simplificar para duas

unsuspend pode retornar 409. Isso significa que nossa equipe de abuso está retendo o site, e não você. Mostre a mensagem; não tente novamente.
**Encerrar agenda uma exclusão, não a executa imediatamente.** A data retorna como pending_deletion_at. Dizer a um cliente que os dados dele já se foram quando não foram é pior do que não dizer nada.
disk_used_bytes pode ser null, e null não é zero. Significa que não pudemos medir, não que nada foi usado. Ignore — não grave 0 nos seus próprios registros, ou você mostrará ao cliente uma barra de uso verde para um site do qual não tem nenhuma leitura.

4. Faça o login de um cliente

POST /v1/reseller/services/{siteId}/sso retorna uma URL de uso único que direciona seu cliente diretamente para a própria conta dele, já conectado.

⛔ Gere a chave quando ele clicar, nunca ao renderizar a página. O link é de uso único e expira em poucos minutos, portanto, um link gravado diretamente em uma página é consumido na primeira visualização e deixado em todos os caches entre você e o navegador.

5. Instale um módulo em vez disso

WHMCS — copie o módulo para modules/servers/zinn/, adicione um servidor cuja Senha seja sua chave de API e defina a linha de produtos no produto. Pressione Testar Conexão: ele faz uma chamada real e informa o que a plataforma respondeu.
HostBill — copie para includes/modules/Hosting/zinn/ e conecte da mesma maneira.
WordPress — o Zinn® Reseller Toolkit: busca de domínios, um link de login para a hospedagem dos seus clientes e provisionamento do WooCommerce quando um pedido é pago. Código aberto em <https://github.com/Zinn-Digital/zinn-reseller-toolkit>, ou baixe-o em Plugins no seu painel.

6. Coloque em produção

Verifique estes itens antes de aceitar um pedido real:

O teste de conexão do módulo passa, ou sua primeira chamada curl retorna uma lista.
Sua tabela de preços está definida (Revenda → Seus preços).
Seu gateway de pagamento está conectado (Revenda → Gateways de pagamento) — seus clientes pagam a você, através da sua própria conta.
Os detalhes da sua empresa foram preenchidos (Revenda → Sua empresa) para que as faturas dos seus clientes levem a sua entidade jurídica e número de IVA/CNPJ, e não o nosso.
Você fez um pedido real de ponta a ponta e viu o site aparecer.

Onde está todo o resto

A referência completa da API — cada endpoint, gerado a partir de nossa especificação, com a permissão que cada um precisa — está em <https://zinndigital.com/developers/api>.