Vendi l'hosting Zinn® da WHMCS

Il modulo Zinn Digital® trasforma i pulsanti di WHMCS in azioni reali sulla nostra piattaforma. Un ordine esegue il provisioning dell'hosting del Suo cliente. L'automazione delle fatture scadute di WHMCS lo sospende. Contrassegnare la fattura come pagata lo riattiva. L'annullamento ne programma l'eliminazione. E il Suo cliente riceve un pulsante Accedi al pannello di hosting nella propria area clienti che lo autentica immediatamente.

È gratuito, con licenza GPL-2.0-or-later e non possiede alcuna via privilegiata per l'accesso alla nostra piattaforma: ogni chiamata effettuata è un endpoint documentato che Lei stesso potrebbe eseguire utilizzando la Sua chiave API.

Prima di iniziare

Sono necessarie due cose, e la seconda spesso coglie impreparati.

1. Un account rivenditore Zinn® con un programma attivo. Si registri su zinndigital.com e attivi la rivendita.
2. Un piano rivenditore con disponibilità di siti. I siti ordinati dai Suoi clienti vengono scalati dal Suo piano, quindi Le ne serve uno con spazio disponibile.

⚠️ Il test di connessione non è in grado di determinare se un ordine andrà a buon fine. Legge il Suo programma e non esegue alcun provisioning, pertanto segnala un account active sano ma che non può ancora vendere nulla. Se il Suo primo ordine non va a buon fine con "This organization has no hosting plan, so it cannot host a site yet", significa che si è verificato questo problema: acquisti o estenda il Suo piano rivenditore ed effettui nuovamente l'ordine. Non c'è alcun problema con il modulo.

1. Creare la chiave API

Nel Suo pannello di controllo Zinn®, apra API keys e ne crei una con esattamente questi undici permessi:

| Permesso | Motivo per cui è necessario | | -------------------- | --------------------------------------------------------------- | | org.create | Apre l'account Zinn® del Suo cliente al primo ordine. | | org.read | Legge gli account dei Suoi clienti. | | sites.create | Esegue il provisioning del sito. | | sites.view | Legge un servizio e il relativo utilizzo. | | sites.delete | Termina il servizio. | | reseller.view | Elenca ciò che ha venduto e legge lo spazio disco e la larghezza di banda. | | reseller.provision | Sospende, riattiva, autentica un cliente, imposta il relativo piano e modifica il pacchetto. | | billing.view | Legge il costo di un aggiornamento prima di eseguirlo. | | sites.manage | Elimina la cache ed esegue un backup tramite i pulsanti. | | sites.panel_access | Modifica la password dell'amministratore di WordPress. | | hosting.php.manage | Cambia la versione di PHP in occasione di un aggiornamento o di una riduzione di livello. |

⛔ Non conceda reseller.manage. Una chiave inserita in un pannello di fatturazione deve essere in grado di bloccare un cliente per mancato pagamento e di autenticarlo. Non deve essere in grado di leggere e sovrascrivere le credenziali del Suo gateway di pagamento. reseller.provision esiste proprio per evitare di dover concedere il permesso più esteso. ⛔ org.create non è facoltativo. Senza di esso il modulo può leggere i Suoi account ma non può aprirne uno, pertanto il test di connessione viene superato e il primo ordine restituisce 403. ⛔⛔ Conceda l'intera tabella e tenga presente che il test di connessione non può segnalar se non lo ha fatto. Legge il Suo programma rivenditore e non esegue alcun provisioning, quindi risulta verde anche per una chiave priva di uno qualsiasi di questi elementi. Quello che otterrà invece sarà un errore 403 sull'unica operazione coperta dal permesso mancante, mesi dopo, da parte di un cliente.

2. Installare il modulo

1. Scaricare il modulo e decomprimerlo.
2. Caricare la directory zinn all'interno della Sua installazione di WHMCS in modo che il file del modulo si collochi in modules/servers/zinn/zinn.php.

⛔ La directory deve chiamarsi zinn. WHMCS ricava i nomi delle funzioni di un modulo di provisioning dal nome della sua directory, quindi rinominarlo in zinn-whmcs o zinndigital genera un modulo che WHMCS elenca, consente di selezionare e poi non richiama mai, senza alcun errore visibile. Il file zip viene già estratto con il nome corretto; si limiti a non rinominarlo.

3. Aggiungere il server

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

• Name: un nome a scelta, ad es. Zinn Digital®
• Hostname: api.zinndigital.com
• Type: Zinn Digital®
• Password: la Sua chiave API ottenuta al passaggio 1

⛔ La chiave va inserita nel campo Password, che WHMCS memorizza in forma crittografata. Non la inserisca in un'opzione di configurazione del prodotto: queste ultime sono in chiaro nel database e visibili a qualsiasi amministratore, e questa credenziale può creare e distruggere l'hosting dei Suoi clienti.

Prema Test Connection. Verrà eseguita una chiamata effettiva e riportato quanto restituito dalla nostra piattaforma, anziché limitarsi a verificare che i campi siano compilati.

4. Creare il prodotto

Configuration → System Settings → Products/Services, quindi imposti Module Settings sul server appena aggiunto. I campi sono:

| Campo | Obbligatorio | Informazione | | ---------------- | ------------ | -------------------------------------------------------------------------- | | Product line | sì | La linea Zinn® che sta vendendo: mainstream (WordPress gestito), footprint_free, wordpress, linux, cloud, agency, app_hosting, ai_hosting, lms_hosting, managed_database, vector_hosting, zinn_compute, fleet_linux, fleet_enterprise, mail o reseller. | | Stack | sì | Ciò che viene creato: wordpress (predefinito), woocommerce, php, static, node, one_click, headless_cms, nextcloud o owncloud. | | Application | no | Solo per gli stack one_click e headless_cms: quale applicazione installare. La specificazione di un'applicazione su qualsiasi altro stack viene rifiutata, poiché tale stack determina già cosa viene installato. | | PHP version | no | ad es. 8.3. Lasciare vuoto per la versione predefinita della linea. Una versione non offerta dalla linea viene rifiutata insieme all'elenco di quelle disponibili. | | Plan code | sì | Il piano Zinn® venduto da questo prodotto. GET /v1/reseller/prices elenca i Suoi piani. Un ordine privo di questo codice viene rifiutato — consulti l'avviso sottostante. | | Billing interval | no | monthly (predefinito) o annual: l'intervallo con cui viene addebitata la Sua linea all'ingrosso per questo cliente. L'importo addebitato al Suo cliente è configurato sul prodotto WHMCS e rimane invariato. |

⛔⛔ Il codice del piano è obbligatorio e un ordine che ne è sprovvisto viene rifiutato intenzionalmente. Fino al 2026-09-01 il campo era puramente decorativo e non veniva letto da alcun componente, pertanto il modulo ordinava un hosting che non disponeva di alcun piano e qualsiasi conseguenza di ciò passava inosservata. Il Suo rendiconto all'ingrosso viene generato a partire dagli abbonamenti attivi dei Suoi clienti, di conseguenza non vi era alcuna riga per il servizio e non Le è stato fatturato nulla per tutta la sua durata; il Suo cliente non ha ereditato alcuna disponibilità, quindi non è stata applicata alcuna quota di spazio disco o file al suo sito; e la modifica del pacchetto non aveva alcun effetto, impedendo l'esecuzione di un aggiornamento venduto. Il sito è stato comunque sottoposto a provisioning e ha funzionato perfettamente.

Il modulo ora rifiuta l'ordine in alternativa, poiché non esiste un piano sicuro che possa essere ipotizzato: un'ipotesi comporterebbe il provisioning di un hosting su un piano che Lei non ha scelto e che potrebbe non aver prezzato, e, a differenza di un rifiuto che Lei legge immediatamente, tale situazione emergerebbe solo all'arrivo di un rendiconto, ammesso che ciò avvenga.

Imposti Auto Setup sull'opzione che preferisce: il modulo è idempotente rispetto all'ID del servizio WHMCS, pertanto un tentativo di provisioning ripetuto restituisce lo stesso sito anziché addebitarne un secondo.

Cosa fa ciascuna azione di WHMCS

| Azione di WHMCS | Cosa accade dalla nostra parte | | --------------------------- | ---------------------------------------------------------------------------------------- | | Create | Crea l'account Zinn® del cliente (o riutilizza quello di cui dispone già) ed effettua il provisioning del suo sito. | | Suspend | Mette il sito in stato di blocco per mancato pagamento. Il contenuto viene conservato; nulla viene eliminato. | | Unsuspend | Rimuove il blocco imposto da Lei. | | Terminate | Programma l'eliminazione del sito, prevedendo un periodo di tolleranza. La data viene visualizzata nell'area clienti. | | Usage update | Aggiorna lo spazio disco e la larghezza di banda su ogni servizio, una volta al giorno. | | Log in to hosting panel | Apre un collegamento di accesso monouso che conduce direttamente al pannello del Suo cliente. | | Change Package | Esegue l'aggiornamento o la riduzione di livello del servizio. Sposta il pacchetto e la versione di PHP se il nuovo prodotto ne specifica una. | | Change Password | Imposta la password dell'amministratore di WordPress. Il riquadro non viene visualizzato per gli stack che non dispongono di tale account. | | Renew | Conferma che il servizio esiste ancora. L'hosting Zinn® è continuo, pertanto non vi è alcuna scadenza remota da estendere. | | Sync Usage / Purge Cache / Take Backup | Pulsanti presenti nella pagina di gestione del servizio per l'amministratore. Il Suo cliente dispone di Purge Cache e Take Backup nella propria area clienti. | | Service tab | Stato, piano, spazio disco, larghezza di banda, eventuale eliminazione programmata e chi ha applicato la sospensione. | | Import | ListAccounts legge ogni pagina, in modo che un'importazione non possa interrompersi silenziosamente alla prima. |

Aggiornamenti: chi fattura a chi

Al Suo cliente non viene mai fatturato nulla da Zinn®, né in caso di ordine né di aggiornamento. Lei fattura al cliente tramite WHMCS; noi fatturiamo a Lei nel Suo rendiconto all'ingrosso. Pertanto, un'azione di modifica del pacchetto trasferisce i diritti del Suo cliente e la relativa voce nel Suo prossimo rendiconto, senza toccare alcuna carta di credito: WHMCS ha già incassato il denaro del Suo cliente e calcolato il proprio rateo.

Un secondo servizio per un cliente. Sul medesimo piano, si tratta di un ulteriore sito che rientra nella disponibilità di siti di quel piano e non viene concesso nient'altro. Su un piano differente, l'operazione viene rifiutata: la sostituzione del piano attivo lascerebbe uno dei due servizi non fatturati. È possibile vendere entrambi sullo stesso piano oppure configurare il cliente come un record cliente separato in WHMCS.

Change Password esiste esclusivamente per WordPress. L'hosting Zinn® non prevede un'unica "password di servizio" (il Suo cliente accede al proprio pannello tramite il pulsante di accesso), e un sito di tipo php o static non possiede alcun account applicativo da modificare. WHMCS nasconde completamente il riquadro anziché mostrarne uno non funzionante.

Tre risposte che non devono essere sintetizzate in due

• Unsuspend può restituire un rifiuto. Ciò significa che il sito è stato sospeso dal nostro team di gestione degli abusi e non da Lei, e nessun pannello di fatturazione può rimuovere tale sospensione. Il messaggio lo specifica chiaramente; lo mostri al Suo amministratore invece di effettuare un nuovo tentativo.
• Terminate programma un'eliminazione, non la esegue immediatamente. La data viene restituita come pending_deletion_at e viene visualizzata nell'area clienti. Dire a un cliente che i suoi dati sono già stati eliminati quando non è così è peggio che non dirgli nulla.
• Lo spazio disco e la larghezza di banda possono risultare sconosciuti, e uno stato sconosciuto non equivale a zero. Quando non è stato possibile effettuare una rilevazione, il modulo lascia immutato il valore anziché scrivere 0, altrimenti WHMCS mostrerebbe al Suo cliente una barra di utilizzo vuota e rassicurante per un sito di cui non disponiamo di alcuna lettura.

Risoluzione dei problemi

Il test di connessione viene superato e il primo ordine fallisce restituendo un errore di permesso. Manca il permesso org.create sulla chiave API. Il modulo deve aprire l'account del cliente prima di poter creare il suo sito.

Un ordine fallisce indicando che l'organizzazione non ha un piano di hosting. Il Suo piano rivenditore ha esaurito la disponibilità di siti o non ne possiede ancora uno. Consulti la sezione Prima di iniziare in alto.

Un ordine fallisce menzionando uno stack. Il campo Stack sul prodotto è vuoto o specifica uno stack che non siamo in grado di creare. Impostarlo su wordpress a meno che non si stia vendendo qualcos'altro.

Gli annullamenti non vanno a buon fine. Si assicura di utilizzare la versione del modulo 1.0.0 o successiva. Le versioni precedenti non inviavano alcuna conferma di eliminazione e qualsiasi risoluzione del contratto veniva rifiutata, lasciando il servizio attivo e fatturabile.

Un rifiuto che menziona un campo

I nostri errori di validazione specificano il campo e il motivo racchiusi tra parentesi dopo il messaggio, ad es. (php_version: 7.2 is not offered on this product line). Questa è la parte su cui è possibile agire: la frase che la precede è deliberatamente generica.

Verificare il download

Ogni archivio viene distribuito tramite protocollo TLS dal nostro hostname e non viene mai reindirizzato verso un host di terze parti. Il relativo codice di controllo SHA-256 viene stampato accanto al collegamento di download nella pagina dei download. Lo confronti dopo il download:

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

Non state utilizzando WHMCS?

È disponibile un modulo HostBill e un client PHP a file singolo per qualsiasi altra esigenza, entrambi gratuiti e reperibili nella stessa pagina dei download. Ogni endpoint utilizzato dai moduli è descritto nella documentazione di riferimento delle API.