Partner API: gestire chiavi e webhook
Con la Partner API colleghi siti di prenotazione, app e integrazioni propri con STRYK. Crei chiavi con esattamente i permessi necessari e configuri i webhook.
Contents
Prima di iniziare
- Ti serve il permesso Gestisci i canali. Solo così vedi la riga API nella pagina Canali.
- Chiarisci quali aree l’integrazione deve leggere o scrivere. Una chiave riceve solo questi permessi.
- Un’integrazione chiama la Partner API dal proprio server. La chiave non la inserisci mai nel codice del browser o in un’app. Endpoint, parametri ed esempi li trovi nella Documentazione per sviluppatori. Lì la sezione Autenticazione e scope spiega che cosa permette ogni permesso.
- I webhook richiedono un destinatario con un indirizzo che inizia con https://.
Apri API
In STRYKCanali
- Scegli in Collegamenti propri la riga API con l’aggiunta “Chiavi API e webhook”. Si apre la finestra API.
- Scegli la scheda Chiavi API o Webhook. Con Documentazione per sviluppatori nell’intestazione della finestra apri il portale per sviluppatori.
- Schede Chiavi API e Webhook
- Chiave con permessi
- Azioni della chiave
Crea chiave API
In STRYKCanaliAPIChiavi API
- Scegli Crea chiave API. Si apre la finestra Crea chiave API.
- Inserisci il Nome, per esempio “Pagina di prenotazione”.
- Scegli in Permessi uno schema: Solo lettura (leggi tutte le aree), Lettura e scrittura (scrivi dove possibile) oppure Personalizzato. Con Personalizzato scegli per ogni area Nessun accesso, Lettura o Scrittura. Le aree sono Hotel e camere, Disponibilità, Prezzi e tariffe, Prenotazioni, Ospiti, Pagamenti e Fatture. Scrittura comprende Lettura. Le fatture sono documenti fiscali dell’hotel e tramite API si possono solo leggere.
- Facoltativo: apri Avanzato. Scegli la Scadenza: Nessuna scadenza, 30 giorni, 90 giorni, 1 anno oppure Data (da domani, al massimo tra tre anni). In Limitazione IP inserisci per riga un indirizzo o una rete CIDR, al massimo 20. Se è vuoto, sono consentiti tutti gli indirizzi. In Nota annoti un promemoria interno.
- Scegli Crea. STRYK mostra Chiave API creata con la chiave e l’avviso Visibile solo ora.
- Copia la chiave e salvala per esempio nel gestore delle password. Scegli Fatto.
Gestisci le chiavi
In STRYKCanaliAPIChiavi API
La lista mostra per ogni chiave Nome, l’inizio della chiave, i Permessi, Creato, Ultimo usato, Scadenza e lo stato: Attivo, In scadenza, Revocato o Scaduto. Scegli una chiave per vedere Permessi, Scadenza, Indirizzi IP consentiti, Limite di richieste (richieste al minuto), Utilizzo, Richieste recenti e la Cronologia.
- Apri nella riga il menu Opzioni.
- Scegli Rigenera se l’integrazione deve ricevere una nuova chiave con gli stessi permessi. Sotto Chiave attuale scegli Vecchia chiave valida ancora 24 h, così puoi passare l’integrazione, oppure Revoca subito. Conferma con Rigenera. STRYK mostra la nuova chiave una volta.
- Scegli Revoca e conferma Revocare la chiave API? per bloccare subito una chiave. Le richieste con questa chiave vengono allora rifiutate da STRYK.
Configura i webhook
In STRYKCanaliAPIWebhook
Un webhook invia gli eventi scelti firmati tramite HTTPS ai tuoi sistemi.
- Scegli Crea webhook. Si apre la finestra Nuovo webhook.
- Inserisci l’URL di destinazione, per esempio https://crm.nordlicht.invalid/hooks/stryk. L’indirizzo deve iniziare con https://.
- Facoltativo: inserisci una Descrizione, per esempio “Prenotazioni al nostro CRM”.
- Scegli in Eventi almeno uno: Prenotazione creata, Prenotazione modificata, Prenotazione annullata, Ospite modificato, Disponibilità modificata, Prezzo modificato, Pagamento modificato oppure Stato camera modificato. Con Seleziona tutto e Annulla selezione scegli tutti o nessuno.
- Scegli Crea webhook. STRYK mostra Il vostro segreto di firma una volta.
- Conserva il segreto nel tuo destinatario. Come il destinatario verifica la firma lo descrive la documentazione per sviluppatori alla voce Webhook e verifica della firma.
- Scegli il webhook e poi Invia evento di prova. STRYK segnala “L’evento di prova viene consegnato.”
Gestisci i webhook
Ort: Canali > API > Webhook, seleziona il webhook
- Con l’interruttore Consegna attiva metti in pausa o attivi il webhook. I webhook in pausa non ricevono eventi. Dopo l’attivazione la consegna riparte con i nuovi eventi.
- Ultimi 7 giorni, Ultimo successo e Ultimo errore mostrano lo stato. Sotto Consegne vedi ogni consegna con Stato HTTP e Tentativi. Con Invia di nuovo ripeti una consegna.
- Rinnova segreto crea un nuovo segreto. Il precedente resta valido ancora 24 ore, così puoi passare il destinatario.
- Con Modifica cambi indirizzo ed eventi, con Elimina e la conferma Eliminare il webhook? lo rimuovi. Il registro delle consegne resta conservato per 30 giorni.
Verifica il risultato
- Sulla chiave compare Ultimo usato con la data, appena l’integrazione la usa. Richieste 24 h conta le richieste.
- Sul webhook Ultimi 7 giorni mostra “{Zahl} consegnati, {Zahl} non riusciti”, e l’evento di prova compare sotto Consegne.
Se qualcosa non funziona
| Cosa vedi | Causa | Come risolvere |
|---|---|---|
| “Scegli almeno un permesso.” | Nessuna area ha un permesso. | Scegli uno schema oppure assegna ad almeno un’area Lettura o Scrittura. |
| “Inserisci un nome.” | Il Nome manca. | Inserisci un nome. |
| “Controlla:” seguito da un indirizzo | Un indirizzo in Limitazione IP non è valido. | Correggi l’indirizzo o la rete CIDR. Sono consentite al massimo 20 voci. |
| “Scegli una data da domani, al massimo tra tre anni.” | La data di scadenza è fuori dall’intervallo. | Scegli una data da domani, non più lontana di tre anni. |
| “L’indirizzo deve iniziare con https://.” | L’URL di destinazione non è un indirizzo HTTPS. | Inserisci un indirizzo che inizia con https://. |
| “Scegli almeno un evento.” | Il webhook non ha alcun evento. | Scegli almeno uno tra gli Eventi. |
| In pausa per errori ripetuti | Il destinatario non risponde con uno stato 2xx. | Verifica che il destinatario sia raggiungibile e scegli Riattiva. |
| “Attiva il webhook per inviare un evento di prova.” | Il webhook è in pausa. | Attiva Consegna attiva e invia l’evento di prova. |
| “Non è stato possibile caricare la selezione. Chiudi la finestra e riaprila.” | L’elenco dei permessi e degli eventi non è stato caricato. | Chiudi la finestra e riaprila. |