• X-INTEGRATION-NAME

• X-INTEGRATION-TOKEN

3. Endpoint IAPI e Swagger
   

1. Una volta ricevute le credenziali, ti consigliamo di provare l’API utilizzando il nostro Swagger disponibile all’URL seguente per familiarizzare con l’API:
   

https://app.swaggerhub.com/apis/PriceLabs/price-labs_connector/1.0.0

2. L'URL di base per tutte le chiamate API è disponibile sullo swagger summenzionato.

3. Sicurezza
   

1. Richieste del PMS a PriceLabs:
   

Ci sono due intestazioni di sicurezza richieste: X-INTEGRATION-TOKEN è inizialmente fornito da PriceLabs e può essere rigenerato utilizzando l'endpoint dal PMS, e X-INTEGRATION-NAME che è fornito da PriceLabs ed è costante.

2. Richieste di PriceLabs al PMS:

I seguenti componenti saranno combinati in due firme: una serie di intestazioni, una stringa di versione e il corpo della stringa json. Saranno firmati utilizzando il token di integrazione.

Valori di esempio:

version = “v1”

headers["X-SOURCE"] = “request_source”

headers["X-PL-TIMESTAMP"] = “request_timestamp”

headers["X-PL-REQUESTID"] = “request_id”

body = "{\"test\":\"body\"}"

Questi valori di esempio verrebbero combinati come segue nello pseudo-codice:

api_token = "26eea40c-f297-4b68-aeb8-bb626fe4b5e5"

header_components = "v1:request_source:request_timestamp:request_id"

signed_headers = "v1." + sha256_sign( header_components, api_token )

body_components = signed_headers + "{\"test\":\"body\"}"

signed_body = sha256_sign( body_components, api_token )

And these will be provided as the following headers:

headers["X-PL-SIGNED-HEADERS"] = signed_headers

headers["X-PL-SIGNED-BODY"] = signed_body

Dopo aver calcolato la firma di ciò che ricevi, puoi confrontarla con le intestazioni di firma fornite nella richiesta.

Per verificare l'implementazione, vengono fornite le firme degli esempi:

headers["X-PL-SIGNED-HEADERS"]="v1.567425e5a91b576652d591cabea78e9e1fe017d1c67e2d812ae2859c355965ff"

headers["X-PL-SIGNED-BODY"]="5011b348ff6691bb9cbe93f85ffb836ef0e3fec45a4ce924f5940cb1aa4071b8"

La versione può essere identificata nell'header suddividendola sul primo ‘.’, nella stringa prima del numero della versione, come v1 nell'header firmato sopra.

5. Configurazione degli URL del PMS

Il PMS dovrà impostare i seguenti 3 URL per ricevere le informazioni sui prezzi. Si prega di prendere nota di quelli obbligatori:

1. Sinccronizza URL (obbligatorio)

1. Questo endpoint deve essere creato e controllato dal PMS.

2. Il PMS deve fornire questo endpoint a PriceLabs utilizzando l’endpoint /integration

3. PriceLabs chiamerà questo endpoint e inserirà gli alloggi insieme ai prezzi associati e come indicato nelle Funzionalità di determinazione dei prezzi in questo documento.

4. Se l'attivazione dell'URL di sincronizzazione non riesce, lo tentiamo 10 volte in quel giorno di calendario.

2. URL trigger del calendario (obbligatorio)

1. Questo endpoint deve essere creato e controllato dal PMS.

2. Il PMS deve fornire questo endpoint a PriceLabs utilizzando l’endpoint /integration

3. Questo endpoint riceverà listing_ids che necessitano di un aggiornamento completo delle loro informazioni.

4. Una volta attivato questo endpoint da PriceLabs, il PMS deve inviare un calendario completo che includa i prezzi e la disponibilità più recenti utilizzando l’endpoint /calendar.

3. Hook URL

1. Questo endpoint è facoltativo per il PMS, che, tuttavia, se vuole implementarlo lo deve creare e controllare.

2. Il PMS deve fornire questo endpoint a PriceLabs utilizzando l’endpoint /integration

3. Se questo URL è configurato, PriceLabs può chiamare questo endpoint per inviare notifiche al PMS con informazioni specifiche rilevanti per un alloggio.  

4. Questo endpoint può anche essere utilizzato per notificare al PMS eventuali errori o dati mancanti per un alloggio.

6. Caratteristiche dei prezzi

Come parte della nostra soluzione di determinazione dinamica dei prezzi, possiamo supportare le seguenti funzionalità di determinazione dei prezzi tramite la nostra API. Si consiglia di supportare almeno quelli contrassegnati come obbligatori* poiché questi sono i requisiti minimi per la nostra integrazione. Il supporto per le altre funzionalità crea un'integrazione più solida che consente ai clienti di sfruttare appieno le funzionalità di PriceLabs.

1. Prezzi*

2. Soggiorno minimo*

3. Restrizioni per il check-in e il check-out

4. Prezzo della durata del soggiorno (LOS)

5. Multi-unità: una proprietà/un alloggio che contiene più unità

6. Sconti settimanali e mensili

7. Viene applicata una tariffa per persona extra e un trigger per persona extra (dopo quanti ospiti vengono applicate le tariffe per persona extra)

7. Chiamate API

La comunicazione tra PriceLabs e il PMS è una comunicazione bidirezionale, in cui alcune API sono ospitate da PriceLabs e altre devono essere implementate e ospitate dal PMS. 

Le chiamate API sono fornite da PriceLabs. Alcune di queste chiamate API sono obbligatorie, mentre altre sono facoltative.

1. Integrazione

1. Endpoint: /integration

2. Obbligatorio: Sì

3. Prerequisito: Il PMS dovrebbe ricevere le credenziali API da PriceLabs. Si tratta di una chiamata API autonoma.

4. Descrizione:

• Questo endpoint sarà utilizzato per aggiornare e mantenere l’integrazione con il PMS. Principalmente questo endpoint viene utilizzato per aggiornare le seguenti informazioni critiche:

• Per aggiornare sync_url, calendar_trigger_url e hook_url

• Per aggiornare il token API

• Per controllare quali “caratteristiche” di prezzo sono esposte agli utenti, come soggiorno minimo, restrizioni di check-in/out, sconti settimanali/mensili, tariffe per persone extra, ecc.  

2. Alloggi

1. Endpoint: /listings

2. Obbligatorio: Sì

3. Prerequisito: 

1. Il cliente crea/aggiorna gli alloggi e i relativi attributi nel PMS.

2. Il cliente deve essere registrato presso PriceLabs e deve consentire al PMS di inviare attributi e prezzi dell’alloggio a PriceLabs.

4. Descrizione:

• Per ricevere raccomandazioni sui prezzi, questa chiamata API deve essere effettuata per un alloggio appena creato o per inviare aggiornamenti a un alloggio esistente. È fondamentale che questa chiamata sia fatta per eventuali nuovi alloggi da aggiungere in PriceLabs, altrimenti PriceLabs non sarà in grado di fornire consigli sui prezzi per l'alloggio appena creato all'interno del PMS.

• Durante questa chiamata, è obbligatorio fornire l'ID e-mail registrato del cliente nel parametro user_token della richiesta. Questo è lo stesso ID e-mail con cui il cliente è registrato presso PriceLabs.

• 
  

• 

• 
  

• Importante: il listing_id che viene inviato a PriceLabs deve essere univoco sul PMS. Per unicità intendiamo che un listing_id XYZ non può appartenere a due o più utenti nel tuo PMS ed è esclusivo per un particolare utente. Ad esempio, il listing_id "L2001" viene utilizzato per due proprietà diverse appartenenti a utenti diversi. Tali casi creerebbero ambiguità.

3. Calendario

1. Endpoint: /calendar

2. Obbligatorio: Sì

3. Prerequisito: /listings

4. Descrizione:

• Questo endpoint sarà utilizzato per aggiornare il calendario di un alloggio con il prezzo giornaliero e disponibilità. Senza questa chiamata, PriceLabs non sarà in grado di derivare i prezzi dinamici per l'alloggio specificato.

• La richiesta di calendario per un alloggio appena aggiunto deve contenere un minimo di 730 giorni di tariffe e disponibilità. Una volta inviato un calendario completo a PriceLabs, le chiamate successive possono essere utilizzate per inviare aggiornamenti all'intero calendario o un intervallo specifico di date.  

• Si consiglia di utilizzare questa API per inviare eventuali aggiornamenti che si verificano nelle tariffe di un alloggio e disponibilità per una durata di calendario specificata per mantenere aggiornato PriceLabs, in modo che il PMS possa infine inviare solo aggiornamenti nel calendario (solo delta, non il calendario completo).

• Come minimo, il prezzo e la disponibilità devono essere aggiornati per ogni data. Le altre impostazioni non sono necessarie, tuttavia, per ricevere un diff invece delle impostazioni complete con ogni sincronizzazione è necessario mantenerle tutte aggiornate.

4. Ottieni prezzi

1. Endpoint: /get_prices

2. Obbligatorio: No, ma si raccomanda di implementarlo

3. Prerequisito: Questa API può essere chiamata dopo che PriceLabs ha attivato l'URL di sincronizzazione

4. Descrizione:

• Dopo la configurazione degli alloggi insieme ai prezzi e alla disponibilità utilizzando gli endpoint /listings e /calendar, PriceLabs attiverà l'URL di sincronizzazione fornito dal PMS non appena saranno pronti i nuovi prezzi.

• Una volta che il PMS riceve l’attivazione dell’URL di sincronizzazione, può consumare i prezzi nel corpo del trigger dell’URL di sincronizzazione, o chiamare /get_prices per recuperare gli ultimi prezzi dinamici per gli alloggi.  

• Di solito questa chiamata deve essere effettuata una volta al giorno, quando viene attivato l'URL di sincronizzazione. In alcuni casi, potrebbe essere più di una volta al giorno, se il cliente desidera pubblicare gli ultimi prezzi dinamici affinché siano lanciati prima.

• È importante notare che il PMS non deve impostare un lavoro CRON per chiamare questo endpoint, ma piuttosto chiamarlo solo dopo l'attivazione dell'URL di sincronizzazione.

• Questa chiamata è facoltativa, poiché i prezzi vengono inseriti anche nel messaggio pubblicato nell’URL di sincronizzazione. PMS può consumare i prezzi dall’URL di sincronizzazione se non desidera chiamare get_prices.

• Come procedura standard, in caso di attivazione URL di sincronizzazione non riuscita, tentiamo nuovamente l'URL di sincronizzazione 10 volte in un giorno solare.

5. Prenotazioni

1. Endpoint: /reservations

2. Obbligatorio: Sì. Questa API abilita gli strumenti di Portfolio Analytics per i clienti.

3. Prerequisito: L'alloggio per il quale vengono pubblicate le prenotazioni deve essere configurato correttamente su PriceLabs.

4. Descrizione:

• Questo endpoint viene utilizzato per aggiungere una nuova prenotazione o aggiornare una prenotazione esistente per un alloggio.  

• Si consiglia di chiamare questo endpoint ogni volta che ci sono nuove prenotazioni o aggiornamenti o cancellazioni di una prenotazione esistente in quanto queste informazioni vengono utilizzate all'interno del prodotto Portfolio Analytics che i clienti utilizzano per vedere varie tendenze e confrontare le prestazioni degli alloggi con il mercato.

• Una nota importante da menzionare è che il campo total_cost nella richiesta di prenotazione deve includere la somma di tutti i costi associati, comprese le commissioni e le tasse.  

• Per calcoli accurati dell’occupazione, è importante fornire anche blocchi di calendario (blocchi del proprietario, blocchi di manutenzione, ecc.) come prenotazioni con un costo di $0 e uno stato BLOCCATO.

6. Stato

1. Endpoint: /status

2. Obbligatorio: No

3. Prerequisito: Gli alloggi devono essere configurati in PriceLabs

4. Descrizione:

• Questo endpoint viene utilizzato per estrarre informazioni da PriceLabs sullo stato attuale dei dati associati.  

• Le informazioni possono essere recuperate per prenotazioni, alloggi e calendari di alloggi.

• Ciò non avrebbe un impatto diretto sui dati o sull’esperienza dell’utente, ma può essere utilizzato dal PMS per convalidare le informazioni, eseguire il debug durante la creazione dell'integrazione o fornire supporto agli utenti dell'integrazione stabilita.

                  7. Piani tariffari

8. Example Integration Flow

A scopo dimostrativo, utilizzeremo un nome ad hoc “Fancy Rentals” come PMS che desidera integrarsi con PriceLabs. Una volta che Fancy Rentals riceve il token e il nome dell'integrazione da PriceLabs, può effettuare chiamate API come spiegato nella sezione precedente.

1. Innanzitutto, Fancy Rentals deve chiamare l’endpoint /integration per aggiornare gli URL del PMS (sezione 5) e per recuperare il token di integrazione. Se gli URL del PMS non sono impostati, le altre chiamate API che seguono potrebbero non funzionare come previsto. Fancy Rentals deve memorizzare il token di integrazione alla fine per effettuare chiamate API a PriceLabs. Se hanno bisogno di un nuovo token, possono richiamare questo endpoint per ottenerlo.  

2. Ogni volta che un utente crea un nuovo alloggio in Fancy Rentals e aggiunge le proprie tariffe e disponibilità, Fancy Rentals deve chiamare gli endpoint /listings per i nuovi alloggi seguiti da /calendar per inviare tariffe e disponibilità per un minimo di 12 mesi e fino a 2 anni. 

3. Ogni volta che un utente aggiorna le tariffe e la disponibilità dei propri alloggi in Fancy Rentals, deve chiamare /calendar per aggiornare lo stesso in PriceLabs

4. Ogni volta che PriceLabs chiama l'URL di attivazione del calendario con gli ID dell'alloggio, Fancy Rentals deve chiamare /calendar con un aggiornamento completo delle tariffe e della disponibilità per gli alloggi inviati da PriceLabs.

5. Quando l’utente imposta le personalizzazioni dei prezzi e attiva la sincronizzazione degli alloggi o avvia una sincronizzazione manuale in PriceLabs, PriceLabs chiamerà l’URL di sincronizzazione fornito da Fancy Rentals con gli ID degli alloggi insieme ai loro prezzi dinamici e ad altre impostazioni. Fancy Rentals può chiamare /get_prices per recuperare lo stesso, se necessario.

6. Quando Fancy Rentals riceve prenotazioni dall'utente o da altri canali, deve chiamare gli endpoint /reservations per inviare i dettagli della prenotazione a PriceLabs. Poiché anche le nuove prenotazioni/cancellazioni cambiano disponibilità, si consiglia che il PMS chiami successivamente /calendar per aggiornare le ultime disponibilità e tariffe.

9. Certificazione
   

Dopo che il PMS ha completato lo sviluppo, gli chiediamo di informare PriceLabs in modo da poter effettuare la certificazione. Assisteremo il team del PMS in ogni fase di questo processo di certificazione. Si prega di notare che il PMS sarà generalmente visibile a tutti i clienti nel menu a discesa dei PMS solo dopo il completamento della certificazione.

1. Di seguito è riportato il link alla nostra checklist per la certificazione, con cui il PMS deve verificare la sua integrazione.

https://docs.google.com/spreadsheets/d/18mMq8Qwv_LIalrxgiud_qHeRk4SPjeHtcC8wEYHcxOo/edit#gid=0

2. Chiediamo inoltre al team del PMS di condividere alcune informazioni relative all’integrazione insieme alle informazioni di marketing. I dettagli sono disponibili nella stessa checklist della certificazione.

3. La checklist consiste anche nei test di verifica che dobbiamo eseguire per assicurarci che il flusso API sia implementato correttamente.  

1. Questi possono essere eseguiti da PriceLabs utilizzando un account di test sul PMS e un utente di prova in PriceLabs OPPURE  

2. Se non è possibile creare o condividere un account di prova sul PMS, il team del PMS e il team di PriceLabs possono eseguire questi test durante una chiamata pre-programmata.

10. Attivazione

Una volta completata la certificazione, il PMS è pronto per essere attivato su PriceLabs.

1. Il PMS deve configurare i propri URL di produzione in PriceLabs: URL di sincronizzazione, URL di trigger del calendario e URL di collegamento e recuperare il token di integrazione più recente.

2. Il PMS e PriceLabs, insieme, devono identificare i potenziali clienti con cui entrare in contatto. Idealmente, un insieme di tali clienti deve essere selezionato in modo che l'integrazione possa essere controllata per essere pienamente funzionale nel modo corretto. PriceLabs abiliterà l'integrazione per i clienti selezionati.

3. Una volta che l’integrazione è identificata come funzionante senza problemi per i clienti selezionati, può essere abilitata per tutti i clienti in PriceLabs in accordo con il PMS.