Vai al contenuto
Blog

API di disponibilità alberghiera e fornitori lenti

Redazione Tekravel
Scritto con l'aiuto dell'IA

Il ticket di solito arriva con un'aria del tutto innocua. «Aggiungere la ricerca hotel alla pagina di prenotazione: il fornitore ci ha dato una API di disponibilità alberghiera, c'è una sandbox, dovrebbe bastare uno sprint.» Leggi la documentazione, invii una richiesta per due adulti a Dubai per tre notti e la risposta arriva. Poi invii la stessa richiesta per una città con più strutture, e per un tempo lungo e imbarazzante non torna nulla. Quando finalmente torna, è un documento così voluminoso che il tuo parser JSON comincia a interrogarsi sulle proprie scelte di vita.

È lì che il lavoro cambia natura. La disponibilità alberghiera non è una semplice lettura: è un fan-out. Una sola domanda dell'utente diventa tante domande a tanti fornitori, e ognuno risponde con i suoi tempi, con il suo vocabolario, con la sua idea di cosa sia una «camera». Il client che costruisci deve restare utile mentre quel fan-out è ancora in corso. Questo articolo parla di come progettarlo, ed è scritto per uno sviluppatore che conosce bene REST e JSON ma non ha mai dovuto spiegare a un hotel perché una tariffa non rimborsabile è stata mostrata all'ospite come cancellabile gratuitamente.

Perché una API di disponibilità alberghiera è più lenta degli endpoint a cui sei abituato

Vista da fuori, una ricerca voli somiglia molto a una ricerca hotel: parte una query, tornano opzioni con un prezzo. Sotto la superficie, però, i due problemi non coincidono. Se hai letto le nostre note su cosa comporta davvero integrare una API di prenotazione voli, sai già che il prezzo trovato in ricerca non è sempre quello che prenoti. Gli hotel aggiungono una seconda difficoltà sopra la prima: il volume.

Una sola città può contare centinaia di strutture. Ogni struttura vende diverse tipologie di camera. Ogni tipologia è venduta con diversi piani tariffari (rate plan): con colazione o senza, rimborsabile o no, tariffa riservata ai membri, tariffa pacchetto. E ogni piano tariffario può arrivare da più di un fornitore: un bedbank, un channel manager, un contratto diretto, un wholesaler con cui hai firmato perché in quell'hotel aveva un allotment migliore di chiunque altro. Moltiplica tutto e la ricerca «semplice» diventa un albero enorme, assemblato da fonti che non concordano né sui nomi né sugli ID.

Quindi la parte lenta raramente è il tuo codice. È il fornitore più lento che hai deciso di aspettare.

Risultati progressivi o risposta completa: una scelta da fare consapevolmente

Esistono due modi onesti di restituire i risultati di una ricerca hotel, e la maggior parte delle integrazioni finisce in una via di mezzo che non soddisfa nessuno.

Aspettare tutto. Il backend fa partire il fan-out, attende che ogni fornitore risponda o vada in timeout, poi unisce, deduplica, ordina e restituisce un unico elenco completo. Il risultato è pulito: una richiesta, una risposta, prezzi confrontabili perché sono tutti sul tavolo. Il prezzo da pagare è che l'utente fissa uno spinner per tutto il tempo che impiega il fornitore più lento, ogni singola volta.

Mandare quello che c'è. Il backend avvia il fan-out e restituisce subito un handle della ricerca. Il client interroga l'handle a intervalli, oppure tiene aperto uno stream, e riceve i risultati a blocchi man mano che i fornitori rispondono. I primi hotel compaiono in fretta. Il costo si sposta altrove, sotto forma di complessità: l'elenco si riordina mentre l'utente lo sta leggendo, il badge «più economico» può spostarsi, e un hotel comparso grazie a un fornitore può ricevere più tardi una tariffa più bassa da un altro.

Se la tua interfaccia è una pagina di ricerca davanti a una persona, il progressivo è quasi sempre la scelta giusta: chi cerca sta sfogliando, non sta lanciando un job batch, e una pagina che lavora in modo visibile batte una pagina che riflette in silenzio. Se invece a consumare i dati è un'altra macchina, per esempio un job di confronto tariffe o uno strumento di prenotazione aziendale che ha bisogno di una risposta definitiva, aspettare è spesso più semplice e corretto.

Qualunque strada tu scelga, tre regole tengono in piedi un client progressivo:

  • Ogni blocco porta con sé uno stato di completamento della ricerca nel suo insieme, così il client distingue tra «per ora nessun altro risultato» e «nessun altro risultato, punto».
  • I risultati vengono uniti sul server tramite una chiave hotel stabile, non accodati. Il client non dovrebbe mai dover capire da solo che due schede sono lo stesso edificio.
  • L'ordinamento per prezzo è provvisorio finché la ricerca non è completa, e l'interfaccia lo dichiara. Gli utenti perdonano un elenco che si assesta; non perdonano un'etichetta «prezzo più basso» che si rivela sbagliata.

Modellare camere e piani tariffari senza che collassino

È qui che la maggior parte delle integrazioni alberghiere fallisce senza far rumore, e il fallimento si presenta mesi dopo come ticket di assistenza, non come bug report.

Il modello più allettante è piatto: un hotel ha un elenco di offerte, ogni offerta ha un nome camera e un prezzo. A video rende benissimo. Poi un fornitore restituisce «Deluxe King» e «Deluxe Room, 1 King Bed» per quella che è ovviamente la stessa camera, un altro usa lo stesso nome per due camere davvero diverse (una con vista città, una senza), e un terzo manda un prezzo per notte mentre tutti gli altri lo mandano per soggiorno. Un elenco piatto non sa dirti quale di questi casi hai davanti. Si limita a mostrarli.

Un modello che regge il contatto con i fornitori reali ha almeno quattro livelli, e li tiene separati:

LivelloCosa contieneL'errore da evitare
HotelUn tuo ID stabile, mappato sul codice di ciascun fornitoreUsare l'ID hotel di un fornitore come chiave primaria
CameraOccupazione, configurazione dei letti, il testo originale del fornitore conservato così com'è«Ripulire» i nomi delle camere finché due camere diverse si fondono in una
Piano tariffarioTrattamento, rimborsabilità, modalità di pagamento, il fornitore di provenienzaConsiderare la colazione o la rimborsabilità parte del nome della camera
PrezzoTotale del soggiorno, valuta, quali tasse e supplementi sono inclusi e quali si pagano in hotelMostrare un importo per notte accanto a importi per soggiorno, o nascondere i costi da pagare all'arrivo

Puoi non essere d'accordo su dove passano i confini: alcuni team danno all'occupazione un livello tutto suo, il che ha senso quando si vendono prenotazioni multi-camera. Quello che non puoi fare è fondere i livelli solo perché l'interfaccia ne mostra due. L'interfaccia può appiattire al momento del rendering. I dati no.

Un dettaglio merita una frase a parte: conserva la descrizione grezza della camera inviata dal fornitore accanto a qualsiasi versione normalizzata. Quando un ospite arriva e riceve una camera diversa da quella del voucher, la prima cosa che tutti chiederanno è che cosa ha mandato davvero il fornitore.

Le politiche di cancellazione sono dati, non un paragrafo

Molti fornitori restituiscono le condizioni di cancellazione come testo libero: «Cancellazione gratuita fino a 3 giorni prima dell'arrivo, poi penale di 1 notte». La tentazione di mostrare quella stringa e passare oltre è fortissima.

Resisti. Un testo non si può confrontare, ordinare, filtrare né far rispettare. L'utente vuole filtrare solo le tariffe rimborsabili. L'amministrazione vuole sapere quali prenotazioni diventano non rimborsabili domani, così l'agenzia può sollecitare il cliente prima che scada il termine. Il flusso post-prenotazione deve dire al cliente, nel momento in cui preme «cancella», esattamente quanto gli verrà addebitato. Niente di tutto questo funziona su una frase.

Modella ogni politica come un elenco ordinato di finestre di penale: da questo istante a quell'istante, l'addebito è questo importo (oppure questa quota del soggiorno, oppure questo numero di notti). I confini sono timestamp con fuso orario, e il fuso è quello dell'hotel, non del tuo server né dell'utente, perché «3 giorni prima dell'arrivo» indica un momento diverso a seconda di quale mezzanotte prendi come riferimento. Salva il testo originale del fornitore accanto alla versione strutturata, mostra quella strutturata e tratta ogni discrepanza tra le due come qualcosa da indagare, non da nascondere.

E ricontrolla la politica al momento della prenotazione, non solo in fase di ricerca. Tra le due chiamate le politiche cambiano più spesso di quanto chiunque si aspetti.

Quanto costa davvero sbagliare

Una ricerca lenta ti costa conversioni: brutto, ma visibile, perché prima o poi qualcuno si lamenta. I guasti costosi sono quelli silenziosi.

Una tariffa mostrata come rimborsabile che il fornitore considera non rimborsabile diventa una contestazione con un cliente che ha lo screenshot, e di solito la penale finisce per pagarla l'agenzia. Un prezzo per notte presentato come totale del soggiorno vende camere sottocosto finché qualcuno in contabilità non se ne accorge. Una camera fusa con un'altra manda una famiglia di quattro persone in una stanza pensata per due. Supplementi da pagare in hotel mai mostrati trasformano una recensione a cinque stelle in un chargeback. Ognuno di questi è una decisione di modellazione presa nel primo sprint, di solito sotto l'etichetta «sistemiamo dopo».

Cache: cosa puoi conservare e cosa no

Ogni team che integra una API alberghiera prima o poi si chiede se può mettere in cache i risultati per rendere la ricerca più veloce ed economica. La risposta è sì, per alcune cose, e il confine tra le due categorie conta più di qualsiasi numero sulle prestazioni.

Il contenuto statico (nomi degli hotel, indirizzi, coordinate, foto, elenchi dei servizi, descrizioni delle camere) cambia di rado ed è esattamente ciò che conviene mettere in cache, senza timidezze, in un archivio tuo. Verifica nei termini del fornitore come puoi conservarlo e mostrarlo: alcune licenze pongono dei limiti. Recuperarlo in tempo reale a ogni ricerca è lento e non porta alcun beneficio.

Tariffe e disponibilità in tempo reale sono un'altra storia. Un prezzo in cache è un'ipotesi su quanto addebiterà il fornitore, e i fornitori non onorano le tue ipotesi. Una cache di breve durata sui risultati di ricerca può andare bene per mostrare una pagina, a patto che ogni percorso di prenotazione riprezzi presso il fornitore prima di incassare e che l'interfaccia tratti un prezzo cambiato come un esito normale, non come un errore. Alcuni fornitori limitano anche quante ricerche puoi fare rispetto alle prenotazioni effettive; una cache aggressiva che nasconde loro il tuo traffico reale non è una scappatoia su cui valga la pena contare.

Ciò che non devi mai mettere in cache è qualunque cosa rappresenti un impegno: un token di prezzo bloccato, un riferimento di prenotazione, un preventivo di cancellazione. Appartengono a un solo utente e a un solo momento.

Prima di dichiararlo finito

Un breve controllo da fare sulla tua integrazione prima che gestisca prenotazioni vere:

  • La ricerca restituisce uno stato di completamento, e il client si comporta in modo diverso prima e dopo.
  • Gli hotel sono identificati da un tuo ID, con il codice di ciascun fornitore mappato su di esso.
  • Camera, piano tariffario e prezzo sono oggetti separati nei tuoi dati, qualunque cosa mostri lo schermo.
  • Ogni prezzo dichiara se è per notte o per soggiorno, e cosa si paga all'arrivo.
  • Le politiche di cancellazione sono salvate come finestre di penale temporizzate nel fuso orario dell'hotel, con il testo originale conservato.
  • Il percorso di prenotazione riprezza e rilegge la politica prima di addebitare qualcosa a chiunque.
  • Nulla che rappresenti un impegno viene mai servito da una cache.

Se stai valutando se costruire tutto questo fornitore per fornitore oppure partire da una piattaforma che questi problemi li ha già affrontati, il lato contrattuale pesa quanto il codice: il nostro articolo su contratti da consolidatore alberghiero e tariffe bedbank spiega cosa chiedere. Le nostre API voli e hotel si aprono con una conversazione, non con una chiave self-service; se è la strada che vuoi esplorare, avvia quella conversazione dalla pagina delle travel API.

Il fan-out non sparisce mai. Un buon client semplicemente smette di fingere che non ci sia.

Redazione Tekravel

Desk tecnologie per il turismo

Il desk tecnologie per il turismo di Tekravel scrive per gli operatori: titolari di agenzie, consolidatori e gli sviluppatori che li integrano. Ogni articolo viene verificato sulla piattaforma che descrive prima della pubblicazione.