Usa l'API di Smoobu: crea una chiave API, configura i webhook e firma le richieste

Smoobu ha un'API con cui uno strumento o il tuo codice può leggere e scrivere i tuoi dati di prenotazione, più i webhook che avvisano il tuo sistema nel momento in cui qualcosa cambia. Gestisci tutto in Avanzate > Chiavi API. Usala quando uno strumento per la gestione degli alloggi ha bisogno di accedere alle tue prenotazioni o quando stai costruendo la tua integrazione. È riservato solo agli utenti esperti: l'assistenza clienti può aiutare solo con problemi di integrazione legati ai partner del Marketplace. Il nostro team di assistenza non può aiutare con sviluppi su misura.

Prima di iniziare

Ti servono queste cose prima di poter usare l'API:

Un account Smoobu a pagamento. Le chiavi non si generano su una prova gratuita. Se sei in prova e ti serve l'accesso all'API, contatta l'assistenza Smoobu per farlo attivare.
La consapevolezza che ogni chiave dà pieno accesso a tutto il tuo account. Tratta una chiave come una password.

Crea una chiave API

In Smoobu, apri Avanzate, poi Chiavi API.
Clicca su Generate API Key.
Copia la chiave e conservala subito in un posto sicuro, per esempio un gestore di password. Smoobu mostra la chiave una volta sola, quindi se lasci la pagina senza salvarla dovrai generarne una nuova.
Incolla la chiave nello strumento o nel codice che ha bisogno di accedere.

Ogni chiave dà pieno accesso a tutto il tuo account, e oggi non c'è modo di limitare una chiave solo a una parte dei tuoi dati. Se usi più di un'integrazione, genera una chiave separata per ciascuna, così puoi revocarne una senza rompere le altre. Per ritirare una chiave, eliminala in questa pagina e lo strumento che la usa perde subito l'accesso.

Tieni al sicuro la tua chiave

Una chiave è una password per tutto il tuo account, quindi trattala come tratteresti una password:

Non scrivere mai una chiave direttamente nel tuo codice. Vale per chiavi API, password e token allo stesso modo: chiunque può vedere il codice può vedere la chiave.
Conserva le credenziali in variabili d'ambiente, per esempio in un file .env che il tuo codice legge all'avvio.
Tieni il file .env fuori dal controllo di versione. Aggiungi .env e ogni altro file di configurazione che contiene segreti al tuo .gitignore, così non finiscono mai su GitHub.
Rendi privati i tuoi repository. Se il codice della tua integrazione è su GitHub, imposta subito la visibilità del repository su Private, soprattutto quando il codice è un tuo lavoro proprietario.

Se una chiave viene comunque esposta, eliminala nella pagina Chiavi API e generane una nuova; la chiave esposta smette subito di funzionare.

Configura un webhook

Un webhook avvisa il tuo sistema quando qualcosa cambia in Smoobu, così il tuo sistema non deve continuare a chiedere.

Nella pagina Chiavi API, trova il campo Webhook URLs.
Inserisci l'indirizzo del tuo server che deve ricevere gli aggiornamenti.
Clicca su Salva. Puoi aggiungere più di un webhook.

Smoobu invia un webhook per questi eventi:

una nuova prenotazione
una prenotazione aggiornata
una prenotazione cancellata
l'invio di un check-in online
un elemento di prezzo creato
un elemento di prezzo aggiornato
un elemento di prezzo eliminato
un nuovo messaggio

Questa lista è l'insieme completo. Non c'è alcun webhook per le recensioni, e non ci sono eventi nascosti o non documentati.

Per i dati esatti che Smoobu invia con ogni evento, apri la documentazione per sviluppatori (docs.smoobu.com): nella pagina Chiavi API, clicca su Clicca qui per documentazione API. Gli stessi documenti contengono il riferimento completo degli endpoint e gli esempi di codice.

Collega invece uno strumento del Marketplace

Se lo strumento che vuoi è già un partner del Marketplace di Smoobu, per esempio uno strumento di pricing o di check-in, non consegni alcuna chiave. Segui semplicemente le guide nel Marketplace di Smoobu. Puoi scollegare i partner del Marketplace in qualsiasi momento, il che taglia subito l'accesso del partner. Questo però potrebbe non chiudere il tuo abbonamento al relativo servizio. Usa questa strada quando esiste, e genera una tua chiave solo per uno strumento o uno script che non è un partner in elenco.

Firma le tue richieste con HMAC

Smoobu sta spostando l'accesso diretto all'API verso richieste firmate (HMAC), così ogni chiamata dimostra di essere autentica e non alterata. Se hai costruito una tua integrazione, devi aggiungere la firma entro il 25 settembre 2026; dopo quella data, le richieste non firmate vengono rifiutate. Durante il passaggio funzionano sia le richieste firmate sia quelle non firmate, così puoi migrare e fare prove senza rompere il tuo sistema attivo.

Chi deve fare qualcosa:

Partner del Marketplace (strumenti di pricing, strumenti di check-in e simili): niente da fare, ci pensa il partner.
Collegamenti ai portali (Airbnb, Booking.com e altri portali): non interessati.
Il tuo script o la tua integrazione che gestisci tu: aggiungi la firma con i passaggi qui sotto.
Uno strumento che non gestisci ma in cui hai incollato la tua chiave: non eliminare la chiave e non migrarla da solo, perché romperesti lo strumento. Contatta il team Smoobu, indica quale strumento usi, e Smoobu configura il partner. La tua chiave continua a funzionare durante il passaggio.

Per configurare la firma:

Vai su Avanzate, poi Chiavi API.
Clicca su Crea nuova, dai alla chiave un'etichetta chiara e clicca su Invia.
Copia subito il segreto e conservalo in modo sicuro. Smoobu lo mostra una volta sola. Se lo perdi, usa Rigenera segreto in questa pagina, ma la rigenerazione annulla subito il vecchio segreto, quindi aggiorna prima la tua integrazione.
Aggiorna la tua integrazione per firmare ogni richiesta. Insieme alla tua chiave, ogni richiesta invia quattro header aggiuntivi:
1. X-API-Key (la tua chiave),
2. X-Timestamp (l'ora attuale in formato UTC ISO 8601 (esempio: 2026-04-01T12:00:00Z)),
3. X-Nonce (un valore unico che non riutilizzi mai: usa UUID v4),
4. e X-Signature (la firma HMAC-SHA256). Come costruire la firma, e il formato esatto di ogni header, è nella documentazione per sviluppatori: la guida tecnica completa con esempi di codice è disponibile qui: docs.smoobu.com/#hmac-authentication

Problemi comuni

Generate API Key manca o non fa nulla

La generazione delle chiavi è disattivata sugli account in prova gratuita. Se sei in prova e ti serve l'accesso all'API, contatta l'assistenza Smoobu per farla attivare.

Le mie richieste firmate falliscono con 401 Unauthorized

La causa abituale è la firma o il timestamp. Altre cause comuni:

Sfasamento dell'orologio: l'ora del tuo sistema è sbagliata di più di 5 minuti. Assicurati che il tuo server usi NTP.
Nonce riutilizzato: ogni richiesta deve avere un X-Nonce unico (usa UUID v4 o byte casuali).
Hash del corpo sbagliato: per le richieste GET e DELETE, calcola l'hash di una stringa vuota, non di null o undefined.
Ordine della query string: ordina i parametri in ordine alfabetico quando costruisci la stringa canonica.
Codifica non corrispondente: firma il corpo JSON grezzo esattamente come viene inviato, con gli stessi spazi e la stessa codifica.

Durante il passaggio puoi tornare alle richieste non firmate mentre lo sistemi.

Ancora bloccato?

Se questi passaggi non hanno risolto, contatta il team Smoobu: apri il menu Aiuto per aprire un ticket o prenotare uno slot per una chiamata, oppure usa la bolla della chat in basso a destra. Per ottenere la risposta più rapida, indica:

Il tuo Smoobu User ID (nel menu dell'icona del profilo, in alto a destra).
Il nome o l'ID dell'alloggio, se riguarda un alloggio preciso.
Il Booking ID, se riguarda una prenotazione precisa (Prenotazioni, poi Visualizza altro).
Il nome del portale, se riguarda la sincronizzazione di un portale (Booking.com, Airbnb, Vrbo, e così via).
Un breve passo per passo: cosa hai fatto, cosa ti aspettavi e cosa è successo.
Screenshot o una breve registrazione dello schermo del problema.
Il tuo browser e sistema operativo, se qualcosa si vede male a schermo.

Articoli in questa sezione