Venda de 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ê comanda nossa plataforma a partir do que já utiliza — um painel de faturamento, seu próprio site WordPress ou um script.

O que seus clientes realmente veem

Antes dos detalhes operacionais: seus clientes nunca precisam nos ver. Três superfícies, e você escolhe qual utilizar.

⛔ Independentemente da sua escolha, você é o comerciante de registro para seus clientes: seus preços, suas faturas, seu número de identificação fiscal, seu provedor de pagamento. Nós faturamos você, uma vez por mês, a preço de atacado.

Depois de definir o hostname do painel, insira-o no campo Endereço do painel do plugin do WordPress e em nenhum outro lugar — os links de login gerados por esta API o seguirão automaticamente.

As quatro formas de integração

Existem quatro formas de integração, e todas realizam o mesmo processo nos bastidores:

1. Obtenha uma chave de API

No seu painel de controle, acesse Chaves de API e crie uma. Conceda apenas as permissões necessárias:

⛔ Não conceda a permissão reseller.manage a uma integração. Essa permissão altera sua tabela de preços e as credenciais do seu próprio gateway de pagamento. A permissão reseller.provision existe exatamente para que uma chave colada em um painel de faturamento ou em um site não precise desse acesso.

A chave é exibida apenas uma vez. Armazene-a onde você guarda suas outras credenciais — nunca em um arquivo servido publicamente 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 pertence, seu status e o valor cobrado por ele. Em uma conta nova, o retorno é uma lista vazia — o que é a resposta correta, não um erro.

3. Toda a integração, em seis chamadas

QUANDO               CHAMADA
um pedido é pago     POST   /v1/orgs                                   uma vez por CLIENTE
                     POST   /v1/sites                                  uma vez por SERVIÇO
está inadimplente    POST   /v1/reseller/services/{siteId}/suspend
ele paga             POST   /v1/reseller/services/{siteId}/unsuspend
ele cancela          DELETE /v1/sites/{siteId}
"entrar na hosp."    POST   /v1/reseller/services/{siteId}/sso

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

# 1. a conta do cliente — vinculada ao 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 dele — vinculado ao 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 cujo erro custa dinheiro

1. Vincule a conta ao seu CLIENTE e o site ao seu SERVIÇO. O segundo pedido de um cliente deve ser incluído na conta que ele já possui. Se vincular ambos ao serviço, um único cliente acabará com três contas não relacionadas e três painéis separados.
2. Envie um Idempotency-Key em cada POST, estruturado a partir do seu próprio id para o item. Todo sistema de faturamento realiza novas tentativas — um callback de gateway chega duas vezes, um administrador reexecuta um provisionamento com falha, um cliente clica duas vezes. Sem a chave, a segunda tentativa cria um segundo site e ele será cobrado de você.

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

• unsuspend pode retornar 409. Isso significa que a nossa equipe de abusos bloqueou o site, não você. Exiba a mensagem; não repita a tentativa.
• **O encerramento agenda uma exclusão, ele não a executa de imediato.** A data é retornada como pending_deletion_at. Dizer a um cliente que os dados dele já foram apagados quando isso ainda não aconteceu é pior do que não dizer nada.
• disk_used_bytes pode ser null, e nulo não é zero. Isso significa que não foi possível medir, e não que nada foi utilizado. Ignore esse valor — não registre 0 nos seus relatórios, ou você exibirá para o cliente uma barra de uso verde referente a um site do qual não obteve leitura.

4. Faça o login de um cliente

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

⛔ Gere a URL quando ele clicar, nunca ao renderizar a página. O link é de uso único e expira em poucos minutos; portanto, um link inserido no código de uma página é inutilizado na primeira visualização e armazenado em todos os caches intermediários até o navegador.

5. Como alternativa, instale um módulo

• 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 item. Clique em Testar Conexão: isso fará uma chamada real e informará a resposta da plataforma.
• HostBill — copie para includes/modules/Hosting/zinn/ e conecte-o da mesma forma.
• WordPress — o Zinn® Reseller Toolkit: busca de domínios, link de login na hospedagem dos seus clientes e provisionamento via WooCommerce após o pagamento de um pedido. Código aberto em <https://github.com/Zinn-Digital/zinn-reseller-toolkit>, ou baixe em Plugins no seu painel.

6. Entre em produção

Verifique estes itens antes de processar um pedido real:

• O teste de conexão foi bem-sucedido no módulo, ou seu primeiro curl retornou uma lista.
• Sua tabela de preços está configurada (Revenda → Seus preços).
• Seu gateway de pagamento está conectado (Revenda → Gateways de pagamento) — seus clientes pagam você, por meio da sua própria conta.
• Os dados da sua empresa foram preenchidos (Revenda → Sua empresa) para que as faturas dos seus clientes exibam sua entidade legal e identificação fiscal, e não as nossas.
• Você realizou um pedido real do início ao fim e confirmou a criação do site.

Onde encontrar todo o restante

A referência completa da API — cada endpoint gerado a partir da nossa especificação, com as respectivas permissões necessárias — está disponível em <https://zinndigital.com/developers/api>.