Vai al contenuto
Blog

Integrazione API prenotazione voli: ciò che la doc non dice

Redazione Tekravel
Scritto con l'aiuto dell'IA

Il ticket sulla board dice soltanto «aggiungere i voli». Hai già integrato un sistema di pagamento, il calcolo delle spedizioni, magari le mappe, e il modello mentale che ti porti dietro è quello ovvio: ricerca, risultati, addebito sulla carta, fatto. Poi la prima prenotazione vera torna con un prezzo diverso da quello mostrato nei risultati, la seconda va in timeout e nessuno sa dirti se il cliente ha il posto, e qualcuno delle operations chiede perché esiste una prenotazione ma non un biglietto. Vista da fuori, un'integrazione API prenotazione voli sembra il checkout di un e-commerce. Sotto, è una transazione distribuita verso sistemi progettati molto prima di REST, e quasi tutte le sorprese nascono da questa distanza.

Queste pagine sono per lo sviluppatore che non ha mai visto un PNR. Non parlano degli endpoint di un fornitore in particolare: i nomi cambiano da un provider all'altro, la struttura no.

La sequenza di chiamate dietro un'integrazione API prenotazione voli

Quasi ogni API voli, comunque chiami i suoi metodi, percorre gli stessi quattro passaggi. Tracciare bene i confini tra l'uno e l'altro è la maggior parte del lavoro.

PassaggioCosa ti restituisceCosa devi salvareCosa va storto
RicercaItinerari con un prezzo e una chiave d'offerta o di tariffa opacaNiente di durevole: i risultati invecchiano in frettaTratti il prezzo come definitivo; la chiave scade prima del checkout
Prezzo / verificaIl prezzo confermato, le regole tariffarie, il bagaglio, a volte i campi passeggero obbligatoriL'offerta verificata e la sua scadenzaIl prezzo è cambiato; la classe è esaurita; le regole non sono quelle che hai mostrato
PrenotazioneUna prenotazione, il PNR, con un record locator e una scadenza di emissioneIl tuo riferimento, il locator, la scadenza, i dati passeggero esatti che hai inviatoTimeout senza risposta; PNR duplicati; nomi rifiutati
EmissioneI numeri di e-ticket emessi: è qui che il denaro viene impegnato davveroOgni numero di biglietto, collegato al passeggero e al segmento a cui appartieneEmissione parziale; prenotazione cancellata dalla compagnia perché la scadenza è passata

La riga su cui si discute è la terza, perché molte API permettono di prenotare ed emettere con una sola chiamata. Usala pure, se ti fa comodo. Nel mondo della compagnia aerea, però, le due cose restano separate: un PNR può esistere senza biglietto, e un'emissione può fallire dopo che il PNR è stato creato. Un endpoint combinato nasconde soltanto il momento in cui una delle due è riuscita e l'altra no, quindi il tuo modello dati deve comunque prevedere quello stato.

Nota anche cosa la ricerca non restituisce: una promessa. È una vetrina. Il passaggio del prezzo è il preventivo, e solo l'emissione è la vendita.

Perché il prezzo trovato non è il prezzo prenotato

Chi sviluppa per il web si aspetta un catalogo. L'inventario aereo non lo è. Un volo si vende per classi di prenotazione, ciascuna un gruppo di posti a una certa tariffa, e la compagnia apre e chiude questi gruppi di continuo, man mano che il volo si riempie. I risultati di ricerca vengono assemblati in fretta da una disponibilità che può essere già leggermente indietro; nel tempo in cui l'utente digita due passaporti, la classe più economica di quel volo può essersi chiusa. Quando parte il passaggio del prezzo, la domanda viene rifatta, e la risposta onesta a volte è più alta.

Le tasse aggiungono la loro deriva. Vengono ricalcolate al momento del pricing per i passeggeri e la rotta esatti, e un bambino o un neonato hanno un prezzo diverso dall'adulto che la ricerca dava per scontato. Anche la conversione di valuta, se la tua vetrina mostra una valuta diversa da quella in cui quota il fornitore, è un altro punto in cui il numero si muove.

La conseguenza progettuale è semplice e spesso saltata: non addebitare mai sul prezzo della ricerca. Esegui il passaggio del prezzo prima del pagamento, confronta e, se l'importo è cambiato, mostra il nuovo valore e chiedi conferma. Qualunque ricarico applichi va ricalcolato sulla tariffa riprezzata, non trascinato dalla pagina dei risultati: è la stessa logica che un'agenzia affronta quando definisce una strategia di ricarico online, e si rompe allo stesso modo quando la base le si sposta sotto i piedi.

Idempotenza, e cosa significa un timeout in prenotazione

Questa è la sezione da leggere due volte.

Quando una chiamata di prenotazione va in timeout, non sai cosa è successo. La richiesta potrebbe non essere mai arrivata. Potrebbe essere arrivata e fallita. Oppure, ed è il caso che fa male, è arrivata, il fornitore ha creato il PNR presso la compagnia e la risposta si è persa sulla via del ritorno. Per il tuo codice i tre casi sono identici. Per la compagnia aerea il terzo è una prenotazione attiva che tiene bloccati dei posti a nome del tuo cliente.

Il riflesso che viene da altre integrazioni è riprovare. Qui un retry alla cieca può generare un secondo PNR per gli stessi passeggeri sullo stesso volo. Le compagnie considerano le prenotazioni duplicate una violazione delle loro regole; a seconda del vettore e degli accordi dell'agenzia, la conseguenza va dalla cancellazione automatica di una o di entrambe le prenotazioni fino a una nota di addebito, un ADM, inviata a chi le ha emesse. L'agenzia che la riceve vorrà sapere perché il tuo sistema ha prenotato due volte.

Cosa funziona, più o meno in quest'ordine:

  • Crea il tuo riferimento di prenotazione prima di chiamare l'esterno, salvalo e invialo con la richiesta ovunque l'API accetti un riferimento del client. Se l'API supporta una chiave di idempotenza (idempotency key), usala; se non la supporta, il tuo riferimento resta ciò che ti permette di ritrovare la prenotazione in seguito.
  • Modella in modo esplicito lo stato sconosciuto. In attesa, confermata, fallita e sconosciuta. Un timeout porta la prenotazione a sconosciuta, non a fallita.
  • Risolvi lo stato sconosciuto chiedendo, non ripetendo. Recupera la prenotazione tramite il tuo riferimento, o elenca le prenotazioni recenti per quei passeggeri, prima di decidere se riprovare.
  • Esegui un job di riconciliazione che passi in rassegna tutto ciò che è ancora sconosciuto e lo confronti con quanto riporta il fornitore, e manda ciò che non riesce a chiarire a una coda gestita da una persona invece di tirare a indovinare.

I timeout in emissione sono lo stesso problema, con il denaro di mezzo. Se incassi dalla carta prima di emettere e l'emissione si blocca, hai un cliente che ha pagato e forse nessun biglietto. Se emetti prima dell'incasso e l'incasso fallisce, hai emesso un documento che qualcuno dovrà pagare alla compagnia. Autorizzare la carta, emettere e poi incassare in caso di successo è lo schema più comune: il punto è sceglierlo consapevolmente, non scoprirlo in produzione.

I concetti del trasporto aereo che spiazzano chi sviluppa per il web

Nessuno di questi è difficile. Ognuno è costato a qualcuno una settimana, solo perché non sapeva che esistesse.

Un PNR non è un biglietto

Il PNR è il record della prenotazione: passeggeri, segmenti, contatti, una scadenza. Il biglietto è il documento pagato che dà al passeggero il diritto di volare. Un PNR non emesso scade alla sua scadenza di emissione e i posti tornano in vendita, a volte senza che dalla tua parte arrivi alcun segnale.

I nomi sono quasi immutabili

Dopo l'emissione, la maggior parte delle tariffe non ammette un cambio nome oltre a una piccola correzione, e cosa conti come piccola varia da compagnia a compagnia. Il nome deve corrispondere al documento di viaggio. Raccogli cognome e nomi separatamente, non lasciare che un titolo scritto a testo libero finisca in un campo del nome, e valida prima della chiamata di prenotazione, non dopo.

I tipi di passeggero hanno un prezzo, non sono decorativi

Adulto, bambino e neonato sono tipi tariffari, e l'età che decide quale si applica è di solito quella alla data del viaggio, non alla data della prenotazione. Un neonato in braccio di norma non occupa un posto e può viaggiare solo con un adulto. Se sbagli il tipo, il passaggio del prezzo fallisce oppure quota la tariffa sbagliata.

Gli orari sono locali, e i segmenti non sono tratte

Gli orari di partenza e di arrivo sono espressi nell'ora locale di ciascun aeroporto. Non convertirli nel fuso dell'utente per mostrarli, e non calcolare le durate sottraendoli senza gli offset. Un viaggio contiene segmenti; un segmento con uno scalo tecnico contiene più di una tratta. La tua interfaccia e i tuoi dati devono essere d'accordo su quale di queste sia uno «scalo».

Le cose cambiano dopo la vendita

Le compagnie modificano gli operativi dopo l'emissione dei biglietti. Una prenotazione corretta al momento dell'emissione può mostrare settimane dopo un nuovo orario, un nuovo numero di volo o una coincidenza saltata, e a seconda del fornitore lo scopri tramite una notifica, una coda o recuperando di nuovo la prenotazione. Metti in conto che la prenotazione cambi quando hai già smesso di guardarla.

Void non è rimborso

Subito dopo l'emissione c'è di solito una finestra in cui il biglietto può essere annullato (void) come se non fosse mai esistito. Passata quella finestra resta solo il rimborso secondo le regole tariffarie, che può comportare una penale o non restituire nulla. La finestra e le sue regole dipendono dal fornitore e dall'accordo di emissione: leggile prima di costruire un pulsante «annulla».

Quanto costa sbagliare

Gli errori in un'integrazione voli costano in un modo particolare: ricadono sulle persone, non sui log. Una prenotazione duplicata diventa una telefonata alla compagnia e magari una nota di addebito sul conto dell'agenzia. Un cliente addebitato senza biglietto diventa un rimborso, un reclamo e un rischio di chargeback. Un biglietto emesso senza un pagamento andato a buon fine diventa un debito verso la compagnia che qualcuno dovrà saldare. Una variazione operativa che nessuno ha gestito diventa un viaggiatore in aeroporto per un volo partito prima.

Nessuno di questi casi emerge in un test del percorso felice. Scrivi prima i percorsi infelici: il timeout in prenotazione, il prezzo salito, l'emissione fallita dopo il PNR, il void dopo un pagamento riuscito. Se quelli sono gestiti, il percorso felice è la parte facile.

Fare test su un'API voli

Gli ambienti di test dei fornitori sono utili e incompleti. Tendono a essere più tranquilli della produzione, quindi classi esaurite e variazioni di prezzo sono più rare, e alcuni non simulano affatto i timeout. Usali per la forma delle chiamate e per gli errori di validazione, poi pianifica un giro controllato in produzione con prenotazioni reali da annullare (void) entro la finestra, con le operations informate di quello che stai facendo.

Se integrare o no è un'altra domanda. Se ciò che ti serve davvero è una vetrina più che l'inventario grezzo nel tuo sistema, il compromesso è spiegato in white label o booking engine proprio, e lo stesso ragionamento vale per un portale B2B per subagenti. Se invece vuoi l'inventario nel tuo codice, questa piattaforma espone API voli e hotel, e l'accesso parte da una conversazione sul tuo caso d'uso, non da una chiave self-service: che è anche il momento giusto per fare ciascuna delle domande qui sopra.

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.