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.
- Il login dell'account principale. Solo l'account principale ha chiavi API. Il login di un membro del team non ha la pagina Chiavi API. Non puoi quindi limitare un'integrazione ad alcuni dei tuoi alloggi dandole l'accesso di un membro del team.
- La consapevolezza che una chiave dà accesso a tutto il tuo account. Tratta una chiave come una password. L'unica cosa che una chiave non può leggere senza il tuo permesso sono i dati personali dei tuoi ospiti.
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. Se lo strumento ha bisogno di nomi, indirizzi e-mail o numeri di telefono dei tuoi ospiti, spunta Consenti l'accesso ai dati personali degli ospiti. Se non ne ha bisogno, lascia la casella senza spunta. 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à accesso a tutto il tuo account. L'unica parte che puoi escludere sono i dati personali dei tuoi ospiti: nomi, indirizzi e-mail, numeri di telefono, note e messaggi. La colonna Dati degli ospiti nell'elenco delle chiavi mostra quali chiavi possono leggerli. 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.
Chiavi create prima del 26 ottobre 2026
Le chiavi che esistevano prima dell'introduzione dell'accesso ai dati degli ospiti possono ancora leggere i dati personali dei tuoi ospiti fino al 30 novembre 2026. Dopo quella data, una chiave restituisce i dati degli ospiti solo se le hai consentito l'accesso. Se uno strumento ha bisogno dei dati degli ospiti, consenti l'accesso per la sua chiave nella pagina Chiavi API prima del 30 novembre. Così lo strumento continua a funzionare. Se uno strumento non ne ha bisogno, non fare nulla: dal 1° dicembre la sua chiave smette di leggere i dati degli ospiti.
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
.envche il tuo codice legge all'avvio. -
Tieni il file
.envfuori dal controllo di versione. Aggiungi.enve 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 ogni aggiornamento una sola volta e non riprova. Se il tuo server non risponde entro 60 secondi, quell'aggiornamento va perso. Usa l'API per recuperare gli eventi che potresti aver perso. Per vedere cosa invia Smoobu prima di farci affidamento, inserisci un indirizzo temporaneo di un servizio come webhook.site e fai una prenotazione di prova.
Smoobu invia un webhook per questi eventi:
- una nuova prenotazione
- una prenotazione aggiornata
- una prenotazione cancellata
- una prenotazione eliminata
- una modifica a prezzi, soggiorno minimo o disponibilità
- l'invio di un check-in online
- un nuovo messaggio
Questa lista è l'insieme completo. Non c'è alcun webhook per le recensioni, e non ci sono eventi nascosti o non documentati. Le modifiche alle voci di prezzo di una prenotazione (elementi di prezzo) vengono inviate solo ai partner di integrazione configurati da Smoobu, mai agli indirizzi che inserisci qui.
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:
- X-API-Key (la tua chiave),
-
X-Timestamp (l'ora attuale in formato UTC ISO 8601 (esempio:
2026-04-01T12:00:00Z)), - X-Nonce (un valore unico che non riutilizzi mai: usa UUID v4),
- 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. I nomi e i dati di contatto degli ospiti arrivano solo se la chiave può leggere i dati degli ospiti. 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.
La mia chiave API non funziona più
Smoobu disattiva ogni chiave che non viene usata da più di 90 giorni. Non ricevi alcun avviso prima, e una chiave disattivata non si può riattivare. Crea una nuova chiave come descritto sopra e aggiungila, con il suo secret, al tuo strumento o al tuo codice.
Se annulli il tuo piano a pagamento, le tue chiavi vengono sospese. Tornano a funzionare se ti abboni di nuovo entro 90 giorni.
I nomi e i dati degli ospiti arrivano vuoti
La chiave non ha accesso ai dati personali dei tuoi ospiti. In questo caso nomi, indirizzi e-mail, numeri di telefono e note degli ospiti arrivano vuoti. Le richieste di dati degli ospiti o di dati del check-in online vengono rifiutate con 403 Forbidden. Consenti l'accesso ai dati degli ospiti per quella chiave nella pagina Chiavi API. In alternativa, crea una nuova chiave con Consenti l'accesso ai dati personali degli ospiti spuntato e usala nel tuo strumento. Date, prezzi, proprietà e pagamenti non sono interessati.
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.
Il mio server perde dei webhook
Smoobu invia ogni webhook una sola volta, senza nuovi tentativi. Un aggiornamento non arriva al tuo sistema quando:
- il tuo server non risponde entro 60 secondi. Smoobu scarta l'aggiornamento.
- il tuo server risponde con HTTP 400. Il tuo server ha rifiutato i dati inviati da Smoobu. Controlla i log del tuo server per capire perché.
Usa l'API per recuperare le prenotazioni e le modifiche che potresti aver perso. Per controllare cosa arriva, inserisci nel campo dei webhook un indirizzo temporaneo di un servizio come webhook.site, fai una prenotazione di prova e guarda cosa arriva. Se il tuo indirizzo continua a rispondere con errori, Smoobu lo disattiva e ti invia un'e-mail (vedi la sezione successiva).
Ho ricevuto un'e-mail che dice che il mio URL webhook è stato disattivato
Smoobu disattiva un indirizzo webhook quando continua a rispondere con errori, e ti invia questa e-mail. Finché è disattivato, quell'indirizzo non riceve aggiornamenti da Smoobu.
- Controlla il sistema dietro l'indirizzo: il tuo server o lo strumento per cui l'hai inserito. Deve essere raggiungibile e accettare gli aggiornamenti senza errori. Se l'indirizzo appartiene a uno strumento, contatta l'azienda che lo offre.
- Nella pagina Chiavi API, inserisci di nuovo lo stesso indirizzo nel campo dei webhook e clicca su Salva.
Se l'indirizzo continua a rispondere con errori, Smoobu lo disattiva di nuovo. Se non usi più quell'indirizzo, non devi fare nulla.
Le richieste vengono bloccate con 429
Le tue richieste falliscono con HTTP 429 e il messaggio «Requests limit exceeded»: la tua integrazione invia più richieste di quante Smoobu ne consenta. Il blocco resta finché la tua integrazione continua a chiamare. Per passare:
- Chiama meno spesso. Distribuisci le richieste nel tempo.
- Fai una pausa, poi riprova. Quando ricevi un 429, aspetta prima di inviare la richiesta successiva, invece di riprovare subito.
- Raggruppa le richieste dove puoi, invece di inviarne tante piccole.
Il limite esatto è nella documentazione per sviluppatori (docs.smoobu.com).
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.
Articoli correlati
- Raggruppa un alloggio e le sue unità secondarie per evitare le doppie prenotazioni
- Smoobu per gestire più alloggi, team e account
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.
Commenti
0 commenti
Accedi per aggiungere un commento.