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

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 vedi | Che cosa sai | Che cosa fare | Che cosa non fare |
|---|---|---|---|
| Il fornitore risponde «tariffa modificata» | Nulla è stato prenotato | Mostra il nuovo totale, chiedi accettazione, rilancia la creazione | Rilanciare con il vecchio prezzo sperando che passi |
| Successo, ma il totale differisce da quello accettato | Esiste una prenotazione al nuovo prezzo | Trattieni il pagamento, chiedi al cliente, annulla la prenotazione se rifiuta | Incassare il vecchio importo e assorbire la differenza |
| Pagamento incassato, la chiamata di emissione dà errore | Esiste un PNR, stato del biglietto ignoto | Rileggi la prenotazione, riprova l'emissione entro il limite, rimborsa dopo | Segnare la prenotazione come fallita e dimenticare il PNR |
| Timeout sulla creazione | Esito sconosciuto | Cerca con il tuo riferimento, poi prosegui o riprova una volta | Riprovare subito alla cieca |
| Timeout sulla cancellazione | Potresti essere ancora responsabile del segmento | Rileggi lo stato prima di dire qualcosa al cliente | Mostrare «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.