Vai al contenuto
Blog

Gestione degli errori dell'API del motore di prenotazione: tre guasti che costano soldi

Redazione Tekravel
Scritto con l'aiuto dell'IA

Il ticket di assistenza arriva un giovedì sera. Un cliente ha pagato, la pagina ha girato a vuoto e poi ha mostrato un errore generico. La carta è stata addebitata. I tuoi log mostrano una POST al fornitore che non ha mai ricevuto risposta. La compagnia aerea ha bloccato un posto? Nessuno sa dirtelo, e il cliente aspetta. Una buona gestione degli errori dell'API del motore di prenotazione è in gran parte il lavoro di non trovarsi mai in quella posizione, o almeno di sapere esattamente che cosa fare quando ci si trova.

La maggior parte delle guide all'integrazione tratta gli errori come un catalogo di codici di stato. Nelle prenotazioni i codici sono la parte facile. Ciò che costa denaro è un piccolo insieme di situazioni in cui la richiesta sembra fallita ma il mondo è cambiato lo stesso, oppure sembra riuscita e il mondo non è cambiato. Tre contano più delle altre.

Primo guasto: il prezzo è cambiato tra ricerca e prenotazione

I risultati di ricerca sono un preventivo, non un contratto. Le tariffe sono in cache, la disponibilità è condivisa tra tutti i canali di vendita del fornitore, e il numero che hai mostrato alle 14:02 può essere vecchio dopo pochi minuti. Il fornitore te lo dice al passaggio di creazione della prenotazione: a volte con una chiara risposta «tariffa modificata», a volte restituendo in silenzio un totale diverso dentro una risposta altrimenti riuscita.

La seconda variante è quella pericolosa. Se il tuo codice legge la conferma, salva la prenotazione e addebita al cliente l'importo che ha visto, la differenza esce dal tuo margine o, più tardi, da un ADM. La regola è semplice: confronta il totale confermato dal fornitore con quello accettato dal cliente, ogni volta, nel codice, prima di incassare il pagamento.

Che cosa fare quando differiscono dipende dall'entità dello scarto e da chi lo sostiene. Pochi centesimi di arrotondamento tra valute sono una tolleranza che fissi una volta. Qualsiasi cosa di più torna al cliente come nuovo prezzo con un pulsante di accettazione esplicito. Mai assorbirlo in automatico, mai addebitarlo in automatico.

Secondo guasto: prenotato, ma non emesso

Un PNR esistente non equivale a un biglietto esistente. Molti flussi creano prima la prenotazione ed emettono l'e-ticket in un passaggio separato, con un limite di tempo in mezzo. Se il pagamento riesce e l'emissione fallisce, hai i soldi di un cliente e una prenotazione che scadrà con i suoi tempi.

Il guasto è raramente rumoroso. La chiamata di emissione restituisce un errore o un timeout, e la prenotazione resta in uno stato che il tuo database chiama «pagato» mentre il fornitore dice ancora «in attesa». Intanto il limite di emissione corre, e a differenza della tua coda di assistenza, la compagnia non aspetta.

Trattalo come uno stato a sé, non come una variante di successo o fallimento. Una prenotazione ha bisogno almeno di questi stati: creata, in attesa, pagamento incassato, in emissione, emessa, fallita-e-rimborsabile. «Pagamento incassato, in emissione» è lo stato che richiede un timer: quando una prenotazione ci resta troppo a lungo, un job deve rileggere la prenotazione dal fornitore e decidere, senza aspettare che un umano se ne accorga. La decisione costa poco quando conosci il limite di tempo del fornitore, perché ti dice per quanto puoi riprovare in sicurezza prima di dover rimborsare.

Terzo guasto: il timeout con esito sconosciuto

È il ticket del giovedì sera. La richiesta è partita; nessuna risposta è tornata; la connessione è caduta o il gateway ha rinunciato. Il fornitore può aver elaborato tutto, una parte o niente.

La tentazione è riprovare. Non riprovare alla cieca una chiamata di creazione, perché il secondo tentativo può produrre una seconda prenotazione, e un duplicato è un costo reale: due posti bloccati, forse due biglietti emessi, una disputa di rimborso su uno dei due.

L'ordine sicuro è: fermarsi, poi leggere, poi decidere. Ferma il flusso lato cliente con uno stato onesto, «stiamo confermando la tua prenotazione». Leggi il lato del fornitore cercando la prenotazione con il riferimento che hai generato prima della chiamata (per questo crei un tuo riferimento cliente per primo e lo invii se il fornitore lo accetta). Solo allora decidi: trovata significa proseguire dallo stato reale; non trovata dopo la finestra di elaborazione del fornitore significa che puoi riprovare una volta.

Se il fornitore non permette la ricerca per il tuo riferimento, cerca per nome del passeggero, rotta e data in una finestra stretta, e considera una corrispondenza come trovata. Brutto, ma molto più economico di un duplicato.

Una tabella decisionale con cui puoi non essere d'accordo

Che cosa vediChe cosa saiChe cosa fareChe cosa non fare
Il fornitore risponde «tariffa modificata»Nulla è stato prenotatoMostra il nuovo totale, chiedi accettazione, rilancia la creazioneRilanciare con il vecchio prezzo sperando che passi
Successo, ma il totale differisce da quello accettatoEsiste una prenotazione al nuovo prezzoTrattieni il pagamento, chiedi al cliente, annulla la prenotazione se rifiutaIncassare il vecchio importo e assorbire la differenza
Pagamento incassato, la chiamata di emissione dà erroreEsiste un PNR, stato del biglietto ignotoRileggi la prenotazione, riprova l'emissione entro il limite, rimborsa dopoSegnare la prenotazione come fallita e dimenticare il PNR
Timeout sulla creazioneEsito sconosciutoCerca con il tuo riferimento, poi prosegui o riprova una voltaRiprovare subito alla cieca
Timeout sulla cancellazionePotresti essere ancora responsabile del segmentoRileggi lo stato prima di dire qualcosa al clienteMostrare «annullato» perché il clic è avvenuto

Una riga che puoi contestare: alcuni team rimborsano al primo errore di emissione per tenere calmo il cliente. È difendibile per biglietti economici e una cattiva abitudine per quelli costosi, perché puoi perdere una tariffa che un minuto dopo avresti salvato.

Quanto costa sbagliare

Ogni guasto ha un conto diverso. Un cambio di prezzo non rilevato è margine perso su ogni prenotazione toccata, spesso notato solo alla riconciliazione. Un caso prenotato-non-emesso è un cliente che arriva in aeroporto con una prenotazione scaduta e un addebito sulla carta: un chargeback e un problema di reputazione insieme. Un nuovo tentativo cieco dopo un timeout è una prenotazione duplicata, e le compagnie controllano i duplicati; una serie di essi è il genere di cosa che finisce in un ADM.

Niente di tutto questo è esotico. È l'idraulica poco appariscente che separa una demo da qualcosa che puoi lasciare in funzione per un fine settimana.

Costruisci il job di riconciliazione prima di averne bisogno

Tutti e tre i guasti finiscono allo stesso modo: il tuo database e quello del fornitore non concordano. Scrivi quindi il job che li confronta prima del primo incidente, non dopo. Un'esecuzione notturna è il minimo; ogni pochi minuti per ciò che è in uno stato transitorio è meglio. Elenca le prenotazioni bloccate in attesa, in emissione o sconosciute, chiede al fornitore che cosa ne pensa, e ripara il record oppure apre un ticket con le prove allegate.

Conserva ogni richiesta e risposta delle chiamate di prenotazione, timeout compresi, con il riferimento che hai inviato. Quando un cliente contesta un addebito, quel log è il tuo argomento. Tiene anche onesta la discussione sulla latenza: vedi che cosa puoi e non puoi correggere nella latenza delle API per capire perché i timeout sono un dato di fatto e non un bug da eliminare.

Se stai ancora decidendo come cablare la connessione al fornitore, la guida in integrazione API di prenotazione voli copre l'ordine delle chiamate che questo articolo presuppone. E se vuoi parlare di come questi stati si mappano sulle nostre API voli e hotel, l'accesso parte da una conversazione: vedi la pagina delle API di viaggio.

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.