Venda l'hosting Zinn® da WHMCS

Il modulo Zinn Digital® trasforma i pulsanti nativi di WHMCS in azioni reali sulla nostra piattaforma. Un ordine effettua il provisioning dell'hosting per il Suo cliente. L'automazione delle fatture insolute di WHMCS lo sospende. Contrassegnare la fattura come pagata lo riattiva. L'annullamento ne pianifica l'eliminazione. Inoltre, il Suo cliente dispone di un pulsante Accedi al pannello di hosting nella propria area clienti che gli consente di effettuare direttamente il login.

È gratuito, rilasciato con licenza GPL-2.0-or-later e non possiede percorsi privilegiati verso la nostra piattaforma: ogni chiamata che esegue corrisponde a un endpoint documentato che Lei stesso potrebbe invocare con la Sua chiave API.

Prima di iniziare

Sono necessari due requisiti, e il secondo coglie spesso di sorpresa.

1. Un account rivenditore Zinn® con un programma attivo. Si registri su zinndigital.com e attivi l'opzione rivenditore.
2. Un piano rivenditore con quota di siti disponibile. I siti ordinati dai Suoi clienti vengono conteggiati a valere sul Suo piano, pertanto Le occorre un piano con spazio residuo.

⚠️ Verifica connessione non può segnalare se un ordine andrà a buon fine. Legge il Suo programma e non effettua alcun provisioning, segnalando di conseguenza un account active operativo che tuttavia non è ancora in grado di vendere nulla. Se il Suo primo ordine non va a buon fine restituendo l'errore "Questa organizzazione non ha un piano di hosting, quindi non può ancora ospitare un sito", il motivo è proprio questo: acquisti o estenda il Suo piano rivenditore e ripeta l'ordine. Il modulo funziona correttamente.

1. Creare la chiave API

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

⛔ Non concedere reseller.manage. Una chiave inserita in un pannello di fatturazione deve essere in grado di sospendere un cliente per mancato pagamento e consentirgli il login. Non deve poter leggere e modificare le credenziali del Suo gateway di pagamento. Il permesso reseller.provision esiste proprio per evitarLe di dover concedere quello più esteso. ⛔ org.create non è facoltativo. In sua assenza, il modulo può visualizzare i Suoi account ma non può aprirne di nuovi; di conseguenza Verifica connessione ha esito positivo e il primo ordine restituisce l'errore 403. ⛔⛔ Conceda tutti i permessi della tabella e tenga presente che Verifica connessione non può rilevare eventuali mancanze. Esegue solo una lettura del Suo programma rivenditore senza effettuare alcun provisioning, risultando quindi positiva anche per una chiave priva di uno qualsiasi di questi permessi. In caso contrario, riceverà invece un errore 403 sull'unica operazione coperta dal permesso mancante, mesi dopo, da parte di un cliente.

2. Installare il modulo

1. Scarichi il modulo ed estragga l'archivio.
2. Carichi la cartella zinn all'interno della Sua installazione di WHMCS, in modo che il file del modulo sia posizionato in modules/servers/zinn/zinn.php.

⛔ La cartella deve chiamarsi tassativamente zinn. WHMCS ricava i nomi delle funzioni di un modulo di provisioning dal nome della sua directory; pertanto, rinominarla in zinn-whmcs o zinndigital genera un modulo che WHMCS elenca, consente di selezionare, ma non invoca mai — senza visualizzare alcun errore. Il file zip si estrae già con il nome corretto: è sufficiente non rinominarlo.

3. Aggiungere il server

In WHMCS: Configurazione → Impostazioni di sistema → Server → Aggiungi nuovo server.

• Nome: a scelta, ad es. Zinn Digital®
• Hostname: api.zinndigital.com
• Tipo: Zinn Digital®
• Password: la Sua chiave API generata al punto 1

⛔ La chiave va inserita nel campo Password, che WHMCS memorizza in formato crittografato. Non la inserisca in un'opzione di configurazione del prodotto: queste ultime sono memorizzate in testo non cifrato nel database e visibili a qualsiasi amministratore, e questa credenziale consente di creare ed eliminare i servizi di hosting dei Suoi clienti.

Prema Verifica connessione. Il sistema effettua una chiamata reale e restituisce la risposta della nostra piattaforma, anziché limitarsi a verificare la presenza di dati nei campi.

4. Creare il prodotto

Configurazione → Impostazioni di sistema → Prodotti/Servizi, quindi imposti Impostazioni modulo sul server appena aggiunto. I campi sono:

⛔⛔ Il campo Plan code è obbligatorio, e un ordine che ne è privo viene intenzionalmente rifiutato. Fino al 2026-09-01 il campo era puramente indicativo e non veniva letto; pertanto il modulo ordinava hosting privi di qualsiasi piano — e ogni conseguenza di ciò si verificava in modo silente. L'estratto conto all'ingrosso viene generato in base agli abbonamenti attivi dei Suoi clienti, di conseguenza non figurava alcuna voce per il servizio e non Le è stato fatturato nulla per tutta la sua durata; il Suo cliente non ereditava alcuna soglia, quindi al suo sito non veniva applicata alcuna quota per disco o file; inoltre, la funzione Modifica pacchetto non aveva alcun elemento da variare, rendendo impossibile eseguire un upgrade da Lei venduto. Durante l'intero periodo il sito è stato regolarmente erogato e funzionante.

Il modulo ora provvede invece a rifiutare l'ordine, poiché non esiste un piano predefinito sicuro da dedurre: una deduzione automatica attiverebbe l'hosting su un piano da Lei non selezionato e potenzialmente non prezzato, e — diversamente da un rifiuto, visibile nell'immediato — emergerebbe unicamente al recapito di un estratto conto, se non del tutto inosservato.

Imposti Attivazione automatica secondo la Sua preferenza — il modulo garantisce l'idempotenza basandosi sull'ID del servizio WHMCS, pertanto un nuovo tentativo di provisioning restituisce il medesimo sito anziché addebitargliene un secondo.

Funzionamento delle azioni di WHMCS

Upgrade: a chi spettano gli addebiti

Zinn® non fattura mai nulla al Suo cliente, né per un ordine né per un upgrade. La fatturazione verso il cliente è gestita da Lei tramite WHMCS; noi emettiamo la fattura a Suo carico, all'interno del Suo estratto conto all'ingrosso. Di conseguenza, l'operazione Modifica pacchetto aggiorna le assegnazioni del Suo cliente e la riga del Suo successivo estratto conto, senza richiedere transazioni su carta di credito — WHMCS ha già riscosso l'importo dal Suo cliente e calcolato il relativo rateo pro-rata.

Secondo servizio di un cliente. Qualora sia associato al medesimo piano, costituisce un ulteriore sito compreso nella quota siti del piano stesso, senza ulteriori assegnazioni. Su un piano diverso l'operazione viene respinta: la sostituzione del piano attivo determinerebbe la mancata fatturazione di uno dei due servizi. Venda entrambi i servizi con lo stesso piano, oppure registri il cliente come anagrafica distinta all'interno di WHMCS.

La funzione Modifica password è disponibile unicamente per WordPress. L'hosting Zinn® non adotta un'unica "password del servizio" — il Suo cliente accede al pannello mediante l'apposito pulsante di autenticazione — e un sito php o static non dispone di un account applicativo da modificare. WHMCS evita di mostrare un campo non utilizzabile, nascondendolo del tutto.

Tre risposte che non devono essere assimilate in due sole casistiche

• La riattivazione può rispondere con un rifiuto. Ciò si verifica se il sito è stato sospeso dal nostro team abusi e non da Lei, circostanza in cui nessun pannello di fatturazione è autorizzato a procedere alla revoca. Il messaggio notifica tale stato; lo sottoponga al Suo amministratore anziché reiterare i tentativi.
• La cessazione pianifica un'eliminazione, non la esegue all'istante. La data viene restituita con il parametro pending_deletion_at ed è consultabile nell'area clienti. Comunicare a un cliente che i suoi dati sono già andati perduti, quando non corrisponde al vero, è peggiore che non notificare alcunché.
• Spazio su disco e traffico possono risultare sconosciuti, e uno stato sconosciuto non corrisponde a zero. Nei casi in cui non sia stato possibile effettuare una misurazione, il modulo non altera il valore astenendosi dall'inserire 0 — in caso contrario WHMCS mostrerebbe al Suo cliente una rassicurante barra di utilizzo vuota per un sito di cui non si dispone di alcuna rilevazione.

Risoluzione dei problemi

Verifica connessione ha esito positivo e il primo ordine fallisce con un errore di permessi. Alla chiave API manca il permesso org.create. Il modulo necessita di creare l'account del cliente prima di poterne generare il sito.

Un ordine fallisce segnalando che l'organizzazione non dispone di un piano di hosting. Il Suo piano rivenditore ha esaurito la quota di siti a disposizione, oppure non ne possiede ancora uno. Faccia riferimento alla sezione Prima di iniziare riportata sopra.

Un ordine fallisce indicando un errore relativo allo stack. Il campo Stack all'interno del prodotto è vuoto o riporta un elemento non gestito. Imposti il valore su wordpress, a meno che non stia vendendo una soluzione diversa.

Le richieste di annullamento falliscono. Verifichi di impiegare la versione 1.0.0 o successiva del modulo. Le versioni precedenti non inviavano la conferma di eliminazione provocando il rifiuto di ogni cessazione, lasciando il servizio operativo e soggetto a fatturazione.

Un rifiuto che riporta l'indicazione di un campo. I nostri errori di validazione indicano tra parentesi quadre o tonde il campo e la motivazione a seguito del messaggio, ad es. (php_version: 7.2 is not offered on this product line). Tale dicitura rappresenta l'indicazione utile su cui intervenire — la frase che la precede è formulata deliberatamente in termini generici.

Verificare il download

Ciascun archivio viene erogato tramite protocollo TLS dal nostro hostname proprietario ed è privo di reindirizzamenti verso host terzi. Il relativo checksum SHA-256 è riportato a fianco del collegamento di download nella pagina dei download. Esegua il confronto 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 utilizza WHMCS?

Sono disponibili un modulo per HostBill e un client PHP a singolo file per qualsiasi altro sistema, entrambi gratuiti e reperibili nella medesima pagina dei download. Ciascun endpoint impiegato dai moduli è consultabile nella documentazione API.