Come si configura l'autenticazione API HMAC?

A partire dal 25 settembre 2026, tutte le richieste API di Smoobu dovranno essere autenticate tramite firme HMAC-SHA256. Questa guida spiega in che modo questo cambiamento ti riguarda e fornisce istruzioni dettagliate per aggiornare la tua integrazione.

Cos'è l'autenticazione HMAC?

HMAC (Hash-based Message Authentication Code) è uno standard di sicurezza che garantisce che ogni richiesta API sia autentica e non sia stata manomessa.

Invece di inviare solo la tua chiave API, ogni richiesta viene firmata con un segreto, in modo simile a come le banche verificano le transazioni.

Questo mi riguarda?

• No: non sei interessato se utilizzi solo integrazioni di partner ufficiali collegate tramite lo Smoobu Marketplace (ad es. PriceLabs, Chekin). Questi partner gestiscono la migrazione automaticamente dalla loro parte.
• Sì:
  • Se utilizzi l'API di Smoobu direttamente tramite i tuoi script o integrazioni personalizzate di cui controlli il codice, segui i passaggi riportati di seguito.
  • Se hai incollato la tua chiave API Smoobu in uno strumento di terze parti che non controlli (ad esempio, uno strumento per la determinazione dei prezzi o un channel manager che non si trova nel Smoobu Marketplace). Non puoi effettuare questa migrazione da solo, perché il fornitore dello strumento deve implementare la nuova firma da parte sua. Vedi “Usi uno strumento di terze parti?” qui sotto.

Usi uno strumento di terze parti?

Se la tua chiave API è utilizzata da uno strumento di terze parti che non controlli, non cancellare la chiave né provare a migrarla da solo: ciò comprometterebbe l'integrazione.

Contatta invece il nostro team di assistenza e comunicaci quale strumento stai utilizzando. Contatteremo direttamente il fornitore e configureremo il nuovo metodo di firma. La tua chiave API esistente rimarrà la stessa e l'integrazione continuerà a funzionare durante tutto il periodo di migrazione, mentre noi ci occuperemo di questo.

Passo dopo passo

1) Apri il tuo account Smoobu e vai su Avanzate > Chiavi API

2) Clicca su “Crea nuovo”, poi assegna alla tua chiave un nome descrittivo (ad es. “La mia integrazione Smoobu” o “Script di sincronizzazione canale”) in modo da poterla identificare facilmente in seguito. Clicca su “Submit”.

3) Dopo aver cliccato su “Submit”, il tuo segreto verrà visualizzato una sola volta: copialo subito e conservalo in un posto sicuro (come un gestore di password o le variabili d'ambiente della tua applicazione).

💡 Suggerimento: se perdi il tuo segreto, puoi rigenerarlo su questa pagina. Tieni presente che la rigenerazione invaliderà immediatamente il segreto esistente, quindi assicurati di aggiornare prima la tua integrazione.

4) Aggiorna la tua integrazione per firmare le richieste. La guida tecnica completa con esempi di codice è disponibile qui: docs.smoobu.com/#hmac-authentication

Ogni richiesta API ora richiede queste intestazioni:

5) Durante il periodo di migrazione (da ora fino al 25 settembre 2026), Smoobu accetta sia le richieste firmate che quelle non firmate. Puoi implementare la tua integrazione aggiornata e verificare che funzioni senza compromettere la tua configurazione attuale.

💡Suggerimento: invia alcune richieste con le nuove intestazioni e verifica di ricevere risposte positive. Se vedi il codice di errore 401 Unauthorized, ricontrolla il tuo timestamp (deve essere entro 5 minuti dall'ora del server) e assicurati che il tuo nonce non sia stato riutilizzato

6) Elimina la tua vecchia chiave API (facoltativo, ma consigliato). Se hai una chiave API in “Chiavi API legacy”, puoi eliminarla una volta configurata la nuova chiave. Durante il periodo di migrazione funzionano sia la vecchia che la nuova chiave, quindi puoi farlo dopo aver completato i test.

💡 Suggerimento: non eliminare la tua vecchia chiave finché la tua nuova integrazione firmata non funziona. Entrambe possono coesistere durante il periodo di migrazione.

Domande frequenti

A chi si applicano queste modifiche?

Questo vale se utilizzi direttamente l'API di Smoobu, ad esempio con:

• I tuoi script
• Integrazioni personalizzate
• Strumenti di terze parti in cui hai inserito manualmente la tua chiave API

Se utilizzi un'integrazione di un partner tramite il Smoobu Marketplace (come Pricelabs, Chekin o integrazioni simili), non è richiesta alcuna azione da parte tua. Il tuo partner di integrazione si occuperà dell'aggiornamento.

Inoltre, anche le connessioni API con i portali di prenotazione (Airbnb, Booking.com, ecc.) non sono interessate da questa modifica.

Cosa rimane invariato?

• Il valore della tua chiave API non cambia
• Tutti gli endpoint API Smoobu esistenti funzionano esattamente come prima
• Si applicano gli stessi formati di dati e le stesse risposte

Cosa c'è di nuovo?

• Ogni richiesta include un timestamp, un nonce univoco e una firma
• Generi un segreto dalla tua dashboard Smoobu per creare quella firma

Ricevo l'errore 401 Non autorizzato — cosa dovrei controllare?

Cause comuni:

• Sfasamento dell'orologio — l'ora di sistema presenta uno scostamento superiore a 5 minuti. Assicurati che il tuo server utilizzi NTP.
• Nonce riutilizzato — ogni richiesta deve avere un X-Nonceunivoco. Usa UUID v4 o byte casuali.
• Hash del corpo errato — per le richieste GET/DELETE, esegui l'hash di una stringa vuota (non null o undefined).
• Ordine della stringa di query — i parametri devono essere ordinati alfabeticamente quando si costruisce la stringa canonica.
• Discrepanza di codifica — firma il corpo JSON grezzo esattamente come viene inviato (stessi spazi e stessa codifica).

La mia vecchia chiave API ha smesso di funzionare — cosa è successo?

Se hai superato la scadenza del 25 settembre 2026 e non hai aggiunto la firma HMAC, le richieste non firmate restituiscono un errore 401.

Per risolvere il problema:

1. Vai su Avanzate > Chiavi API
2. Crea una nuova chiave e genera un segreto
3. Aggiorna la tua integrazione per firmare le richieste

Posso ancora usare il mio vecchio valore della chiave API?

Sì. Il valore della tua chiave API rimane lo stesso.

Devi solo aggiungere queste intestazioni accanto al tuo X-API-Key esistente:

• X-Timestamp
• X-Nonce
• X-Signature

Cosa succede se perdo il mio segreto?

1. Vai su: Avanzate > Chiavi API
2. Trova la tua chiave e clicca su Rigenera segreto.
3. Il vecchio segreto smette di funzionare immediatamente, quindi aggiorna subito la tua integrazione.

Qual è il calendario della migrazione?

Guida tecnica completa

Per la guida tecnica completa — inclusi esempi di codice dettagliati in cURL, PHP e Node.js — visita la documentazione dell'API Smoobu:

https://docs.smoobu.com/#hmac-authentication

Questa pagina contiene tutto ciò di cui hai bisogno per implementare la firma HMAC nella tua integrazione.