API e Webhook

Cosa sono l'API e i webhook di Salonnare, a cosa servono e come creare chiavi API e webhook.

API e Webhook

Con l'API e i webhook di Salonnare colleghi il tuo salone ad altri software: il tuo programma di contabilità, il tuo sito web, un servizio di newsletter o una dashboard personalizzata. Non devi essere uno sviluppatore per capire cosa fanno, questa pagina lo spiega con calma.

Non ancora disponibile

Questa funzione è ancora indicata come Presto nell'app: al momento non puoi creare chiavi API o webhook. Se apri Impostazioni > API e Webhook, vedi solo un avviso che la funzione è in arrivo. Questa pagina descrive come funzionerà una volta disponibile.

Cos'è un'API?

Un'API (Application Programming Interface) è un accordo che permette a due programmi di comunicare tra loro. Dove tu clicchi su un pulsante nell'app per caricare un appuntamento, un altro programma può richiedere gli stessi dati tramite l'API, automaticamente e senza passaggi manuali.

Esempi pratici per un salone:

  • Il tuo software di contabilità recupera automaticamente il tuo fatturato ogni notte.
  • Il tuo sito web mostra i tuoi trattamenti e i tuoi prezzi direttamente da Salonnare.
  • Un partner di integrazione sincronizza la tua lista clienti.

L'accesso all'API funziona tramite una chiave API: un codice segreto che dimostra che la richiesta proviene da te. Trattala come una password.

Creare una chiave API

  1. Vai su Impostazioni -> API e Webhook.
  2. Nella scheda Chiavi API, clicca su Nuova chiave.
  3. Dai alla chiave un nome riconoscibile (ad esempio "Contabilità") e scegli i permessi: Solo lettura, Lettura + scrittura o Accesso completo. Al momento, una chiave API può solo recuperare dati, indipendentemente dal livello di permesso scelto; una chiave di sola lettura non può comunque fare di più.
  4. Copia subito la chiave e conservala in modo sicuro. Per motivi di sicurezza Salonnare mostra la chiave completa solo una volta.

Sospetti che una chiave sia stata compromessa? Eliminala subito, ogni integrazione che usa quella chiave si interrompe immediatamente.

Cos'è un webhook?

Un webhook è l'opposto dell'API. Invece di essere tu a recuperare i dati, Salonnare invia automaticamente un messaggio a un indirizzo (URL) tuo nel momento in cui succede qualcosa. L'altro software non deve più chiedere continuamente "c'è qualcosa di nuovo?", riceve un segnale da sé.

Salonnare può inviare questi sei eventi:

  • booking.created - un collaboratore crea un appuntamento nell'app
  • booking.updated - un collaboratore modifica un appuntamento nell'app (incluso un cambio di stato a completato o no-show)
  • booking.cancelled - un collaboratore annulla un appuntamento nell'app
  • payment.received - un collaboratore completa un pagamento in cassa
  • client.created - un collaboratore crea un cliente nell'app
  • client.updated - un collaboratore modifica i dati di un cliente nell'app
Solo ciò che accade nell'app

Ogni evento deriva da un'azione di un collaboratore nell'app. Una prenotazione online tramite la tua pagina di prenotazione o Google, un cliente che annulla da solo, una conversione dalla lista d'attesa, una serie ricorrente, un percorso e un cliente che si registra da solo sulla pagina di prenotazione non inviano (ancora) una notifica. Segnalalo al tuo partner di integrazione: può recuperare gli appuntamenti mancati richiedendo periodicamente l'elenco degli appuntamenti.

Configurare un webhook

  1. Vai su Impostazioni -> API e Webhook e apri la scheda Webhook.
  2. Clicca su Nuovo webhook.
  3. Inserisci l'URL a cui Salonnare deve inviare le notifiche (te lo fornisce il tuo partner di integrazione o sviluppatore).
  4. Scegli gli eventi a cui vuoi reagire.
  5. Salva. Puoi poi controllare i registri di invio per verificare se le notifiche arrivano correttamente.

Il segreto che Salonnare usa per firmare i messaggi viene mostrato nel momento in cui salvi il webhook, conservalo subito in modo sicuro, come una chiave API, perché Salonnare non lo mostrerà di nuovo. Se lo perdi, clicca sull'icona di aggiornamento vicino al webhook (Richiedi un nuovo secret); vedrai quindi un nuovo segreto una sola volta. Il vecchio segreto smette di funzionare da quel momento, quindi anche il lato ricevente deve essere aggiornato.

Ogni notifica webhook porta una firma che il destinatario può usare per verificare che il messaggio provenga davvero da Salonnare.

Lavorare in sicurezza

  • Non condividere mai le chiavi API pubblicamente (non in email, screenshot o codice pubblicato online).
  • Dai a un'integrazione solo i permessi di cui ha davvero bisogno, scegli sola lettura dove possibile.
  • Elimina le chiavi e i webhook che non usi più.

Poiché Salonnare elabora i tuoi dati nell'UE e sei tu a decidere quali integrazioni ottengono l'accesso, mantieni il pieno controllo sui tuoi dati. Hai bisogno di aiuto con un'integrazione? Non esitare a contattarci tramite la pagina di supporto.

Sei uno sviluppatore in cerca dei dettagli tecnici (autenticazione, endpoint, campi, codici di errore, verifica della firma)? Consulta la Documentazione API.

Articoli correlati

ImpostazioniPrenotazioni onlineNotifiche