Quando un nuovo cliente si iscrive ai tuoi servizi, il tempo che intercorre tra la firma del contratto e la creazione di un sito WordPress è importante. MyKinsta rende semplice la creazione e la gestione dei siti WordPress, ma le agenzie che gestiscono molti progetti di clienti cercano spesso un modo per automatizzare le attività di configurazione ripetitive.
L’API di Kinsta permette di automatizzare parte di questo processo. In questo tutorial, collegheremo un modulo di iscrizione del client HubSpot all’API di Kinsta attraverso un’applicazione middleware Node.js. Quando un contatto invia il modulo, il middleware riceve i dati, chiama l’API Kinsta e crea automaticamente un sito WordPress.
Perché le agenzie dovrebbero automatizzare il provisioning del sito
La configurazione manuale di un sito comporta dei ritardi nel momento in cui il rapporto con il cliente è più importante. Le nuove iscrizioni richiedono che qualcuno crei un ambiente di hosting, configuri WordPress, generi le credenziali e le comunichi al cliente.
MyKinsta rende queste operazioni semplici, ma quando il processo dipende dalla disponibilità di un membro del team per completare ogni fase, possono verificarsi dei ritardi.
Straight out Digital (Sod), un’agenzia digitale che gestisce centinaia di siti di clienti su Kinsta, utilizza l’API di Kinsta per costruire strumenti interni personalizzati che trasformano il provisioning e la manutenzione in flussi di lavoro automatizzati. Invece di ripetere gli stessi passaggi di configurazione per ogni nuovo sito, Sod attiva il processo in modo programmatico. Il risultato, come descrive il team, è che “quella che poteva essere un’operazione che richiedeva molto tempo è stata resa semplice”.
Collegando HubSpot all’API di Kinsta si ottiene un risultato simile. Quando un cliente invia il modulo di iscrizione, HubSpot invia un webhook, il middleware riceve i dati del contatto e l’API di Kinsta avvia il processo di creazione del sito.
In questo modo, il passaggio dal lead all’ambiente WordPress viene effettuato automaticamente, riducendo il lavoro manuale necessario per l’onboarding dei nuovi clienti.
Come iniziare
Per seguire questo tutorial, servono:
- Almeno un sito esistente nel tuo account Kinsta. Questo assicura che l’accesso all’API sia disponibile.
- Un account HubSpot con un modulo impostato per acquisire le iscrizioni dei clienti. Nota che i flussi webhook sono disponibili solo su alcuni piani HubSpot premium.
- Node.js 18 o una versione successiva installata localmente.
Puoi generare una chiave API Kinsta all’interno della dashboard MyKinsta. Vai su Impostazioni Azienda > Chiavi API e clicca su Crea chiave API.
Imposta una scadenza, dai un nome alla chiave e clicca su Genera. Poiché MyKinsta mostra la nuova chiave API solo una volta, conservala in un luogo sicuro.
Ti servirà anche l’ID dell’azienda. Puoi recuperarlo dall’URL di MyKinsta una volta effettuato l’accesso o facendo una richiesta all’endpoint /sites quando la tua chiave API sarà attiva.
Memorizza entrambi i valori in un file .env nella root del tuo progetto:
KINSTA_API_KEY=your_api_key_here
KINSTA_COMPANY_ID=your_company_id_hereCome integrare HubSpot con Kinsta utilizzando l’API di Kinsta
Analogamente all’utilizzo dell’API di Kinsta e di Slack, puoi impostare un’integrazione in cui l’invio di un modulo HubSpot attiva un webhook, un’applicazione Node.js riceve i dati dei contatti, chiama l’API di Kinsta per creare un sito WordPress e interroga l’API finché il sito non è attivo.
Il progetto si articola in cinque fasi: configurazione di HubSpot, configurazione del middleware, autenticazione dell’API, creazione del sito e monitoraggio delle operazioni.
1. Configurare il modulo e il flusso di lavoro di HubSpot
All’interno della dashboard di HubSpot, crea o seleziona il modulo che acquisisce le iscrizioni dei nuovi clienti in Marketing > Forms.
Come minimo, il modulo necessita di campi per il nome, l’indirizzo e-mail e il nome dell’azienda. Questi valori corrispondono ai parametri che passerai successivamente all’API di Kinsta.
Con il modulo pronto, vai su Automation > Workflows nel menu di navigazione di HubSpot e clicca su Create workflow nell’angolo in alto a destra.
Successivamente, seleziona Start from scratch. Si aprirà l’editor del flusso di lavoro. Clicca sul trigger e scegli Form submission come trigger di iscrizione.
Quindi seleziona il tuo modulo dal menu a tendina Form submission e completa la configurazione. Ora HubSpot aggiungerà un contatto nel flusso di lavoro ogni volta che qualcuno invierà il modulo.
Con l’attivazione del trigger, il canvas del flusso di lavoro mostra una nuova azione. Clicca su Data Ops > Send a webhook, imposta il metodo su POST e inserisci per ora un URL segnaposto. Una volta distribuita l’applicazione Node.js, aggiorna l’URL al tuo endpoint live.
HubSpot invia un payload JSON all’URL del webhook quando il flusso di lavoro viene eseguito. Il payload include le proprietà del contatto, con i valori dei campi modulo che appaiono con i loro nomi interni di proprietà HubSpot. Puoi confermare il nome interno di qualsiasi campo in HubSpot in Settings > Properties, esaminando il pannello dei dettagli della proprietà.
2. Creare l’endpoint del middleware
HubSpot può inviare un webhook a un URL quando un contatto invia tuo modulo, ma non ha modo di parlare direttamente con l’API di Kinsta. Invece, un livello middleware riceve il payload di HubSpot, estrae i dati dei contatti necessari, li riformatta e li passa all’API di Kinsta.
Express.js è un framework web Node.js minimale che rende veloce la creazione di un server HTTP come questo. Gestisce le richieste in entrata, permette di definire i percorsi e dà accesso al corpo della richiesta con una configurazione minima. Si installa dopo aver inizializzato un nuovo progetto Node.js:
npm init -y
npm install express dotenv
express fornisce il server e il livello di routing, mentre dotenv carica il file .env in process.env in modo che la tua chiave API e il tuo ID aziendale siano disponibili per l’applicazione in fase di esecuzione.
Il server si trova in un file app.js. Avvia Express, gli dice di eseguire il parse dei corpi delle richieste in arrivo come JSON, definisce una route che ascolta le richieste POST di HubSpot e avvia il server su una porta locale.
Questo esempio presuppone Node.js 18 o una versione successiva, che include il supporto nativo per il fetch.
// app.js
const express = require('express');
require('dotenv').config();
const app = express();
app.use(express.json());
const KinstaAPIUrl = 'https://api.kinsta.com/v2';
const headers = {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.KINSTA_API_KEY}`
};
app.post('/new-site', async (req, res) => {
const event = Array.isArray(req.body) ? req.body[0] : req.body;
const displayName = event?.properties?.company;
const adminEmail = event?.properties?.email;
if (!displayName || !adminEmail) {
return res.status(400).json({ message: 'Missing required fields' });
}
// Kinsta API call goes here
res.status(200).json({ message: 'Received' });
});
app.listen(3000, () => console.log('Server running on port 3000'));
La riga app.use(express.json()) indica a Express di analizzare i corpi delle richieste in arrivo come JSON. Senza di essa, req.body restituisce un valore undefined.
La route legge i dati del contatto dal payload del webhook, estrae il nome dell’azienda e l’email dell’amministratore e convalida che entrambi i valori siano presenti prima di continuare.
L’operatore di concatenamento opzionale ?. gestisce i casi in cui la struttura del payload differisce da quella prevista. Invece di lanciare un errore che potrebbe mandare in crash il server, restituisce in modo sicuro undefined se una proprietà è mancante.
3. Autenticazione con l’API di Kinsta
L’API di Kinsta utilizza l’autenticazione con token Bearer. Ogni richiesta inviata include la tua chiave API nell’intestazione Authorization. L’API utilizza questa chiave per identificare il tuo account e verificare il tuo livello di accesso.
La chiamata require('dotenv').config() all’inizio di app.js carica il file .env all’avvio dell’applicazione. In questo modo process.env.KINSTA_API_KEY si risolve nella chiave API effettiva in fase di esecuzione.
Definisci l’URL di base e le intestazioni come costanti all’inizio di app.js dopo la configurazione di dotenv:
const KinstaAPIUrl = 'https://api.kinsta.com/v2';
const headers = {
content-Type": "application/json",
Authorization: `Bearer ${process.env.KINSTA_API_KEY}`
};
Definendo le intestazioni come una costante, il codice è coerente con tutte le chiamate API dell’applicazione e la rotazione delle chiavi è semplice. Aggiornando il valore nel file .env e riavviando il server, non dovrai andare a caccia di chiavi in ogni punto del codice.
L’ID azienda non viene inserito nell’intestazione dell’Authorization. Sarà necessario invece includerlo nel corpo della richiesta quando crei un sito.
4. Creare il sito WordPress tramite l’API di Kinsta
Una volta effettuata l’autenticazione, potrai effettuare la richiesta di creazione del sito. L’endpoint /sites dell’API di Kinsta accetta una richiesta POST con i dettagli del sito che vuoi creare e la mette in coda per il provisioning. Invece di aspettare che il sito sia pronto prima di rispondere, l’API restituisce immediatamente un riferimento da utilizzare per monitorare l’operazione.
All’interno della rotta /new-site, sostituisci il commento segnaposto con il seguente:
const response = await fetch(`${KinstaAPIUrl}/sites`, {
metodo: 'POST',
headers,
body: JSON.stringify({
azienda: process.env.KINSTA_COMPANY_ID,
display_name: displayName,
regione: 'us-central1',
install_mode: 'new',
admin_email: adminEmail,
admin_password: process.env.WP_ADMIN_PASSWORD,
admin_user: 'admin',
site_title: displayName
})
});
const data = await response.json();I parametri richiesti sono company, display_name, region, install_mode, admin_email, admin_password, admin_user e site_title. Impostando install_mode su "new", l’API creerà una nuova installazione. Il valore region corrisponde all’identificativo della regione di un data center Kinsta.
Se fornisci siti con WooCommerce o Yoast SEO preinstallati, l’API supporta parametri opzionali per entrambi. Una volta aggiunto woocommerce: true o wordpressseo: true al corpo della richiesta, l’API installa questi plugin come parte del processo di creazione del sito. Il sito viene fornito con la tua serie di plugin standard già installati.
Una richiesta andata a buon fine restituisce un codice di stato 202 e non 200. Il 202 indica che l’API ha accettato la richiesta e ha messo in coda l’operazione, ma non significa che il sito sia pronto. La creazione di un sito Kinsta avviene in modo asincrono, quindi il corpo della risposta contiene un operation_id che puoi utilizzare per controllare l’avanzamento del provisioning piuttosto che restituire i dettagli del sito finito.
5. Monitorare lo stato dell’operazione
Poiché la creazione di un sito avviene in modo asincrono, devi interrogare l’endpoint /operations/{operation_id} per verificare quando il sito è pronto. L’API restituisce lo stato attuale dell’operazione ogni volta che la chiami. Quando lo stato cambia in completed, la risposta include i dettagli del nuovo sito.
Prendi l’operation_id dalla risposta di creazione del sito e passalo a una funzione di polling:
const pollOperation = (operationId) => {
const interval = setInterval(async () => {
const resp = await fetch(
`${KinstaAPIUrl}/operations/${operationId}`,
{ method: 'GET', headers }
);
const result = await resp.json();
if (result.status === 'completed') {
clearInterval(interval);
console.log('Site ready:', result);
}
}, 30000);
};La funzione esegue il polling ogni 30 secondi. L’API di Kinsta consente fino a 120 richieste al minuto, con un limite inferiore di 5 richieste al minuto per gli endpoint di creazione di risorse come la creazione di un sito. Il polling dell’endpoint delle operazioni ogni 30 secondi rimane entro questi limiti e controlla i progressi con un intervallo ragionevole.
Devi anche estrarre il valore operation_id e passarlo a pollOperation(). Aggiungi quanto segue alla fine della rotta app.post:
const operationId = data.operation_id;
pollOperation(operationId);Una volta completata l’operazione, la risposta contiene i dettagli del nuovo sito. Puoi testare l’applicazione in locale eseguendo node app.js nel tuo terminale. Dopo aver distribuito l’applicazione, sostituisci l’URL del webhook segnaposto nel tuo flusso di lavoro HubSpot con il tuo endpoint live.
Automatizzare l’onboarding dei clienti della tua agenzia con HubSpot e Kinsta
Con l’integrazione in corso, un nuovo ambiente WordPress inizia il provisioning non appena un cliente invia il modulo di iscrizione a HubSpot. Il middleware riceve i dati dei contatti, li passa all’API di Kinsta e controlla l’operazione fino a quando il sito non è pronto. Questo approccio aiuta ad automatizzare la fase iniziale di configurazione del sito mentre il tuo team continua a gestire i siti attraverso MyKinsta.
Per rendere il middleware accessibile a HubSpot, distribuisci l’applicazione in modo che abbia un endpoint pubblico. Piattaforme come Sevalla (un prodotto di Kinsta) possono ospitare applicazioni Node.js di questo tipo. Quando l’applicazione sarà attiva, aggiorna l’URL del webhook nel flusso di lavoro di HubSpot in modo che punti all’endpoint distribuito.
Per l’hosting WordPress gestito di Kinsta, l’accesso alle API è disponibile su tutti gli account una volta generata una chiave API in MyKinsta.
