Prenotazioni Hotel

Il webservice per le prenotazioni alberghiere consente ai client di interrogare la disponibilità della struttura passando come parametri il numero di persone e le date di arrivo e partenza. Attraverso i vari step percorribili si potrà scegliere, tra la lista delle camere disponibili, il trattamento desiderato. Al termine del processo il server fornirà i parametri necessari per la generazione di un form di pagamento o pre-autorizzazione su Paypal. La procedura prevede l’utilizzo dei metodi del webservice in ordine prestabilito. Ciascun webservice fornisce infatti uno o più token indispensabili per procedere con lo step successivo. Andiamo ad analizzare uno ad uno i diversi step del processo di prenotazione tramite webservice.

Url webservice

http://www.overplace.com/wsdl/prenotazioni_hotel ^[1]

Metodo 1

checkHotel

Ritorna la lista delle informazioni di base della struttura ricettiva

Parametri

• ws_auth_token: Client token ottenuto dal Client Login Webservice ^[2] (string).
• idapp: Application id delle vetrina Overplace sulla quale il client vuole operare (es. CJ50)(string).
• response type : formato della risposta, i parametri accettati sono “xml” o “json”(string).

Esempio Request lato Client

 Esempio Response lato Client

Response in formato Json

 

Metodo 2

checkDisponibilita

Ritorna la lista delle camere disponibili sulla base dei parametri passati, per ciascuna camera specifica i trattamenti disponibili e i relativi prezzi e le condizioni di prenotazione.

Parametri

• ws_auth_token: Client token ottenuto dal Client Login Webservice ^[2] (string).
• idapp: Application id delle vetrina Overplace sulla quale il client vuole operare (es. CJ50)(string).
• id_hotel: Id Hotel ottenuto da metodo precedente (int).
• data_inizio_prenotazione : Data di arrivo in formato (YYYY-mm-dd)(string).
• data_fine_prenotazione : Data di partenza in formato (YYYY-mm-dd)(string).
• numero_adulti : Numero di persone per cui si sta prenotando(int).
• ws_token : Token identificativo del processo di prenotazione, parametro ritornato dal metodo precedente(string).
• response type : formato della risposta, i parametri accettati sono “xml” o “json”(string).

Esempio Request lato Client

 Esempio Response lato Client

Response in formato Json

 

Metodo 3

userRegistrationHotel

Se non si dispone di uno user_token per proseguire è necessario registrare un nuovo utente in Overplace, fornendo tutte le informazioni necessarie al funzionamento dello script di prenotazione alberghiera. Il metodo ritorna lo user token della nuova utenza.

Parametri

• ws_auth_token: Client token ottenuto dal Client Login Webservice ^[2] (string).
• idapp: Application id delle vetrina Overplace sulla quale il client vuole operare (es. CJ50)(string).
• nickname: Nickname del nuovo utente(string).
• email : Indirizzo email del nuovo utente(string).
• password : Password del nuovo utente, lunghezza minima 6 caratteri(string).
• cellular_phone : Numero di telefono cellulare completo di prefisso internazionale completo (es.003933312312345)(numeric).
• nome : Nome del nuovo utente(string).
• cognome : Cognome del nuovo utente(string).
• citta : Città del nuovo utente(string).
• indirizzo : Indirizzo del nuovo utente(string).
• cap : Zip code / Cap del nuovo utente(numeric).
• nazione : Nazione del nuovo utente(string).
• response type : formato della risposta, i parametri accettati sono “xml” o “json”(string).

Esempio Request lato Client

 Esempio Response lato Client

Response in formato Json

 

Metodo 4

riepilogoPrenotazione

Ritorna i dati riepilogativi della prenotazione in base ai parametri inseriti negli step precedenti. Se il profilo utente associato allo user token è completo, il servizio torna il riepilogo della prenotazione all’interno del tag “info_prenotazione”, altrimenti ritorna i campi del profilo utente presenti e quelli mancanti suddividendoli negli indici (“campi_profilo_miss” e “campi_profilo”). Tra le informazioni presenti all’interno del riepilogo sono presenti anche l’id della modalità di pagamento, l’eventuale flag indicante la richiesta di carta di credito a garanzia e la policy applicata dall’albergatore.

Parametri

• ws_auth_token: Client token ottenuto dal Client Login Webservice ^[2] (string).
• idapp: Application id delle vetrina Overplace sulla quale il client vuole operare (es. CJ50)(string).
• id_hotel: Id Hotel ottenuto dai servizi precedenti(int).
• id_hotel_camera : Id hotel camera, associato alla camera presente nella lista ritoranta dal servizio checkDisponibilita(int).
• id_hotel_trattamento : Id del trattamento selezionato, associato alla camera scelta(string).
• data_inizio_hotel_camera : Valore del campo data_inizio corrispondente alla camera scelta(string).
• token_hotel_camera : Valore del campo token corrispondente alla camera scelta(string).
• prezzo : Valore del campo prezzo corrispondente alla camera scelta(numeric / double string).
• ws_token : Token identificativo del processo di prenotazione, parametro ritornato dal metodo precedente(string).
• user_token : Token identificativo di un utente Overplace, si ottiene attraverso i metodi per il login di un utente esterno ^[3]
• response type : formato della risposta, i parametri accettati sono “xml” o “json”(string).

Esempio Request lato Client

 Esempio Response lato Client

Response in formato Json

 

Metodo 5

completaProfiloHotel

Se il metodo precedente non dovesse ritornare il riepilogo prenotazione, ma l’elenco delle informazioni mancanti relative all’utenza, è necessario utilizzare questo servizio per aggiornare il profilo utente completandolo con le informazioni mancanti. Al termine del processo di aggiornamento, Overplace tornerà un messaggio di status; se il messaggio è positivo (“profilo_ok”), si può richiamare il serivizio “riepilogoPrenotazione” che tornerà il riepilogo completo in base ai parametri impostati in precedenza.

Parametri

• ws_auth_token: Client token ottenuto dal Client Login Webservice ^[2] (string).
• idapp: Application id delle vetrina Overplace sulla quale il client vuole operare (es. CJ50)(string).
• id_hotel: Id Hotel ottenuto dai servizi precedenti(int).
• nome : Id hotel camera, associato alla camera presente nella lista ritoranta dal servizio checkDisponibilita(int).
• cognome : Id del trattamento selezionato, associato alla camera scelta(string).
• indirizzo : Valore del campo data_inizio corrispondente alla camera scelta(string).
• cap : Valore del campo token corrispondente alla camera scelta(string).
• citta : Valore del campo prezzo corrispondente alla camera scelta(numeric / double string).
• nazione : Token identificativo del processo di prenotazione, parametro ritornato dal metodo precedente(string).
• cellulare : formato della risposta, i parametri accettati sono “xml” o “json”(string).
• ws_token : Token identificativo del processo di prenotazione, parametro ritornato dal metodo precedente(string).
• user_token : Token identificativo di un utente Overplace, si ottiene attraverso i metodi per il login di un utente esterno ^[3]
• response type : formato della risposta, i parametri accettati sono “xml” o “json”(string).

Esempio Request lato Client

 Esempio Response lato Client

Response in formato Json

Metodo 6

inserisciPrenotazione

Metodo che inserisce una prenotazione nel sistema Overplace, tutti i dati relativi al booking sono contenuti nel ws_token. La risposta contiene sempre l’id della prenotazione inserita, il resto varia in base alla tipologia di pagamento richiesta dall’albergatore e alla policy configurata per la singola camera. Se l’albergatore richiede un autorizzazione di pagamento o un pagamento diretto, nella response è presente un tag “paypal_values” contenendo la lista delle variabili da postare a paypal per configurare il pagamento. Tali variabili possono essere ciclate per generare un form funzionale. Nel caso in cui sia richiesto il pagamento totale in loco, senza carta di credito a garanzia, il servizio tornerà il tag “esito” con il valore “prenotazione_confermata” (in tal caso il processo di prenotazione è completo).

In seguito al submit del form paypal e in base all’esito del pagamento, il client si dovrà occupare di gestire la comunicazione con payapl, le request ipn ed eventuali transazioni fallite o tentativi di frode. Tutta la procedura è totale responsabilità del client. Per la gestione del flusso di comunicazioni con paypal consultare il sito di riferimento https://developer.paypal.com ^[4]

Parametri

• ws_auth_token: Client token ottenuto dal Client Login Webservice ^[2] (string).
• idapp: Application id delle vetrina Overplace sulla quale il client vuole operare (es. CJ50)(string).
• ws_token : Token identificativo del processo di prenotazione, parametro ritornato dal metodo precedente(string).
• user_token : Token identificativo di un utente Overplace, si ottiene attraverso i metodi per il login di un utente esterno ^[3]
• response type : formato della risposta, i parametri accettati sono “xml” o “json”(string).

Esempio Request lato Client

 Esempio Response lato Client

Response in formato Json

 Script php di esempio per generare form di pagamento paypal

 

Metodo 7

checkIpnResponse

In seguito alla conferma di pagamento ricevuta dal circuito paypal, per rendere effettiva la prenotazione sul circuito Overplace, sarà necessario comunicare l’id transazione paypal (parametro txn_id) e l’item_number, equivalente all’id_prenotazione ottenuto come primo parametro del metodo precedente. La validità del parametro txn_id, come sopra specificato, dovrà essere verificata dal client al momento della ricezione della instant payment notification di paypal https://developer.paypal.com/‎ ^[4]

Parametri

• ws_auth_token: Client token ottenuto dal Client Login Webservice ^[2] (string).
• idapp: Application id delle vetrina Overplace sulla quale il client vuole operare (es. CJ50)(string).
• id_hotel_prenotazione : Id prenotazione ottenuto con il metodo precedente(string).
• ipn: txn_id ottenuto da paypal in seguito a response ipn(string).
• response type : formato della risposta, i parametri accettati sono “xml” o “json”(string).

Esempio Request lato Client

 Esempio Response lato Client

Response in formato Json