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 Crea nuova in alto a destra.
Nella finestra Crea un token API, scrivi un nome breve in Etichetta (facoltativo) per riconoscere la chiave in seguito e clicca su Submit.
Smoobu mostra Token creato con la tua nuova chiave nel campo Etichetta e il tuo Segreto sotto. Copia entrambi con i pulsanti di copia e conservali subito in un posto sicuro, per esempio un gestore di password: Smoobu mostra il segreto una volta sola. Spunta Ho copiato il mio segreto e clicca su Chiuso.
La nuova chiave compare nell'elenco con la sua etichetta, e puoi copiarla di nuovo in qualsiasi momento dalla colonna Chiave. Il segreto non può essere mostrato di nuovo: se lo perdi, revoca la chiave e creane una nuova. Incolla la chiave e il segreto 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, clicca su Revoca accanto a essa: qualsiasi richiesta che la usa ancora smette subito di funzionare.

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, revocala nella pagina Chiavi API e creane 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.

Quel campo contiene solo i webhook che aggiungi tu. Alcuni partner del Marketplace registrano i propri tramite l'API di Smoobu quando li colleghi, quindi non devi mai inserire l'indirizzo di un partner in questo campo.

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 31 ottobre 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: segui i passaggi 1 e 2 qui sotto per attivare la firma. Poi contatta l'azienda esterna e condividi con lei la tua nuova chiave API e il tuo secret, così può collegarsi a Smoobu.

Per configurare la firma:

Crea una chiave come descritto sopra in Crea una chiave API. Ogni chiave che crei lì arriva con un segreto, mostrato una volta sola nella finestra Token creato.
Conserva il segreto in modo sicuro. Se lo perdi, crea una nuova chiave e aggiorna la tua integrazione con la nuova chiave e il nuovo segreto prima di revocare quella vecchia, così la tua integrazione non si ferma mai nel frattempo.
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

Porta le tue prenotazioni nel tuo sistema

Puoi portare i dati delle tue prenotazioni nel tuo sito web o nel tuo sistema tramite l'API. A chi lo gestisce serviranno la documentazione API di Smoobu e l'endpoint delle prenotazioni, GET /api/reservations, da usare con la chiave API del tuo account. Una cosa da riferire al tuo sviluppatore: tra i parametri di data di quell'endpoint, al momento funzionano solo from e to.

Problemi comuni

Crea nuova 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.

Uno strumento partner riceve gli aggiornamenti delle prenotazioni, ma in Smoobu non compare nessun webhook

Non c'è nulla di rotto e non devi correggere niente. Quando un partner del Marketplace registra un webhook per te, Smoobu lo conserva separatamente dai tuoi e non compare in quel campo. I tuoi webhook restano invariati. Se in seguito scolleghi il partner, Smoobu rimuove i suoi webhook al posto tuo.

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