Μετάβαση στο περιεχόμενο
Ιστολόγιο

Ενσωμάτωση API κράτησης πτήσεων: όσα δεν λέει η τεκμηρίωση

Σύνταξη Tekravel
Γράφτηκε με τη βοήθεια τεχνητής νοημοσύνης

Το ticket στον πίνακά σας λέει «προσθέστε πτήσεις». Έχετε ήδη παραδώσει μια ενσωμάτωση πληρωμών, μια για κόστη αποστολής, ίσως και μια για χάρτες, και το νοητικό μοντέλο που φέρνετε μαζί σας είναι το προφανές: αναζήτηση, εμφάνιση αποτελεσμάτων, χρέωση κάρτας, τέλος. Μετά η πρώτη πραγματική κράτηση επιστρέφει με διαφορετική τιμή από αυτήν της σελίδας αποτελεσμάτων, η δεύτερη πέφτει σε timeout και κανείς δεν μπορεί να σας πει αν ο πελάτης έχει θέση, και κάποιος από το operations ρωτάει γιατί υπάρχει κράτηση αλλά όχι εισιτήριο. Μια ενσωμάτωση API κράτησης πτήσεων μοιάζει απ' έξω με checkout ηλεκτρονικού καταστήματος. Από κάτω είναι μια κατανεμημένη συναλλαγή με συστήματα που σχεδιάστηκαν πολύ πριν από το REST, και οι περισσότερες εκπλήξεις γεννιούνται ακριβώς σε αυτό το κενό.

Το κείμενο απευθύνεται στον developer που δεν έχει δει ποτέ PNR. Δεν αφορά τα endpoints ενός συγκεκριμένου προμηθευτή· τα ονόματα αλλάζουν από πάροχο σε πάροχο, το σχήμα όχι.

Η αλληλουχία κλήσεων πίσω από μια ενσωμάτωση API κράτησης πτήσεων

Σχεδόν κάθε API πτήσεων, όπως κι αν ονομάζει τις μεθόδους του, περνάει από τα ίδια τέσσερα βήματα. Το να τραβήξετε σωστά τα όρια ανάμεσά τους είναι το μεγαλύτερο μέρος της δουλειάς.

ΒήμαΤι σας δίνειΤι πρέπει να αποθηκεύσετεΤι πάει στραβά
ΑναζήτησηΔρομολόγια με τιμή και ένα αδιαφανές κλειδί προσφοράς ή ναύλουΤίποτα μόνιμο — τα αποτελέσματα παλιώνουν γρήγοραΘεωρείτε την τιμή οριστική· το κλειδί λήγει πριν από το checkout
Τιμολόγηση / επαλήθευσηΤην επιβεβαιωμένη τιμή, τους κανόνες ναύλου, τις αποσκευές, ενίοτε τα υποχρεωτικά πεδία επιβάτηΤην επαληθευμένη προσφορά και τη λήξη τηςΗ τιμή άλλαξε· η κλάση εξαντλήθηκε· οι κανόνες διαφέρουν από όσα δείξατε
ΚράτησηΜια κράτηση — το PNR — με record locator και προθεσμία έκδοσηςΤη δική σας αναφορά, τον locator, την προθεσμία, τα ακριβή στοιχεία επιβατών που στείλατεTimeout χωρίς απάντηση· διπλά PNR· απόρριψη ονομάτων
ΈκδοσηΕκδοθέντες αριθμούς e-ticket· εδώ δεσμεύονται πραγματικά τα χρήματαΚάθε αριθμό εισιτηρίου, αντιστοιχισμένο σε επιβάτη και τμήμαΜερική έκδοση· ακύρωση της κράτησης από την αεροπορική επειδή πέρασε η προθεσμία

Η γραμμή που αμφισβητούν οι περισσότεροι είναι η τρίτη, επειδή πολλά API σάς επιτρέπουν κράτηση και έκδοση σε μία κλήση. Χρησιμοποιήστε την αν θέλετε. Τα δύο πράγματα παραμένουν ξεχωριστά στον κόσμο της αεροπορικής: ένα PNR μπορεί να υπάρχει χωρίς εισιτήριο, και μια έκδοση μπορεί να αποτύχει αφού δημιουργήθηκε το PNR. Ένα συνδυασμένο endpoint απλώς κρύβει τη στιγμή όπου το ένα πέτυχε και το άλλο όχι, οπότε το μοντέλο δεδομένων σας πρέπει να έχει θέση και για αυτήν την κατάσταση.

Προσέξτε επίσης τι δεν επιστρέφει η αναζήτηση: μια υπόσχεση. Είναι διαφήμιση. Το βήμα της τιμολόγησης είναι η προσφορά, και μόνο το εισιτήριο είναι η πώληση.

Γιατί η τιμή που αναζητήσατε δεν είναι η τιμή που κλείνετε

Οι web developers περιμένουν κατάλογο. Το απόθεμα των αεροπορικών δεν είναι κατάλογος. Μια πτήση πωλείται σε κλάσεις κράτησης, καθεμία ένας κουβάς θέσεων σε έναν ναύλο, και η αεροπορική ανοίγει και κλείνει αυτούς τους κουβάδες συνεχώς καθώς γεμίζει η πτήση. Τα αποτελέσματα αναζήτησης συναρμολογούνται γρήγορα από διαθεσιμότητα που μπορεί ήδη να είναι λίγο πίσω· μέχρι ο χρήστης να πληκτρολογήσει δύο διαβατήρια, ο φθηνότερος κουβάς σε εκείνη την πτήση μπορεί να έχει κλείσει. Όταν τρέχει το βήμα τιμολόγησης, ρωτάει ξανά, και η ειλικρινής απάντηση είναι μερικές φορές υψηλότερη.

Οι φόροι προσθέτουν τη δική τους απόκλιση. Υπολογίζονται εκ νέου στην τιμολόγηση για τους συγκεκριμένους επιβάτες και τη διαδρομή, και ένα παιδί ή ένα βρέφος τιμολογείται διαφορετικά από τον ενήλικα που υπέθεσε η αναζήτηση. Η μετατροπή νομίσματος, αν η βιτρίνα σας δείχνει ευρώ ενώ ο προμηθευτής κοστολογεί σε άλλο νόμισμα, είναι ακόμη ένα σημείο όπου ο αριθμός μετακινείται.

Η σχεδιαστική συνέπεια είναι απλή και συχνά παραλείπεται: ποτέ μη χρεώνετε την τιμή της αναζήτησης. Τρέξτε το βήμα τιμολόγησης πριν από την πληρωμή, συγκρίνετε, και αν το ποσό άλλαξε, δείξτε τον νέο αριθμό και ρωτήστε. Όποια προσαύξηση εφαρμόζετε πρέπει να υπολογιστεί ξανά πάνω στον επανατιμολογημένο ναύλο, όχι να μεταφερθεί από τη σελίδα αποτελεσμάτων — η λογική είναι η ίδια που δουλεύει ένα γραφείο όταν ορίζει στρατηγική προσαύξησης online, και σπάει με τον ίδιο τρόπο όταν η βάση μετακινείται από κάτω της.

Idempotency, και τι σημαίνει ένα timeout κατά την κράτηση

Αυτή είναι η ενότητα που αξίζει να διαβάσετε δύο φορές.

Όταν μια κλήση κράτησης πέφτει σε timeout, δεν ξέρετε τι έγινε. Το αίτημα μπορεί να μην έφτασε ποτέ. Μπορεί να έφτασε και να απέτυχε. Ή — η περίπτωση που πονάει — έφτασε, ο προμηθευτής δημιούργησε το PNR στην αεροπορική, και η απάντηση χάθηκε στον δρόμο της επιστροφής. Για τον κώδικά σας, και τα τρία μοιάζουν ολόιδια. Για την αεροπορική, το τρίτο είναι μια ζωντανή κράτηση που δεσμεύει θέσεις στο όνομα του πελάτη σας.

Το αντανακλαστικό από άλλες ενσωματώσεις είναι να ξαναπροσπαθήσετε. Εδώ, μια τυφλή επανάληψη μπορεί να παράγει δεύτερο PNR για τους ίδιους επιβάτες στην ίδια πτήση. Οι αεροπορικές αντιμετωπίζουν τις διπλές κρατήσεις ως παραβίαση πολιτικής· ανάλογα με τον μεταφορέα και τις συμφωνίες του γραφείου, η συνέπεια κυμαίνεται από αυτόματη ακύρωση της μίας ή και των δύο κρατήσεων μέχρι χρεωστικό σημείωμα — ένα ADM — προς όποιον τις εξέδωσε. Το γραφείο που θα το παραλάβει θα θέλει να μάθει γιατί το σύστημά σας έκλεισε δύο φορές.

Τι δουλεύει, περίπου με αυτή τη σειρά:

  • Δημιουργήστε τη δική σας αναφορά κράτησης πριν καλέσετε προς τα έξω, αποθηκεύστε την και στείλτε την με το αίτημα όπου το API δέχεται client reference. Αν το API υποστηρίζει idempotency key, χρησιμοποιήστε το· αν όχι, η αναφορά σας είναι πάλι αυτό που σας επιτρέπει να αναζητήσετε την κράτηση μετά.
  • Μοντελοποιήστε ρητά την άγνωστη κατάσταση. Εκκρεμής, επιβεβαιωμένη, αποτυχημένη — και άγνωστη. Ένα timeout μεταφέρει την κράτηση σε άγνωστη, όχι σε αποτυχημένη.
  • Λύστε το άγνωστο ρωτώντας, όχι επαναλαμβάνοντας. Ανακτήστε με την αναφορά σας, ή ζητήστε τις πρόσφατες κρατήσεις για αυτούς τους επιβάτες, πριν αποφασίσετε αν θα ξαναπροσπαθήσετε.
  • Τρέξτε μια εργασία συμφωνίας που σαρώνει ό,τι παραμένει άγνωστο και το συγκρίνει με όσα αναφέρει ο προμηθευτής, και στέλνει ό,τι δεν μπορεί να διευθετήσει σε ουρά για άνθρωπο αντί να μαντεύει.

Τα timeout στην έκδοση είναι το ίδιο πρόβλημα με χρήματα επάνω του. Αν δεσμεύσετε την κάρτα πριν από την έκδοση και η έκδοση κολλήσει, έχετε πελάτη που πλήρωσε και ίσως κανένα εισιτήριο. Αν εκδώσετε πριν από τη δέσμευση και η δέσμευση αποτύχει, έχετε εκδώσει έγγραφο που κάποιος πρέπει να πληρώσει στην αεροπορική. Πρώτα έγκριση της κάρτας, μετά έκδοση, μετά δέσμευση σε επιτυχία είναι το συνηθισμένο σχήμα — το ζητούμενο είναι να το αποφασίσετε συνειδητά, όχι να το ανακαλύψετε στην παραγωγή.

Οι έννοιες του κλάδου που αιφνιδιάζουν τους web developers

Καμία από αυτές δεν είναι δύσκολη. Καθεμία έχει κοστίσει σε κάποιον μια εβδομάδα επειδή δεν ήξερε ότι υπάρχει.

Ένα PNR δεν είναι εισιτήριο

Το PNR είναι το αρχείο κράτησης: επιβάτες, τμήματα, επαφές, μια προθεσμία. Το εισιτήριο είναι το πληρωμένο έγγραφο που δίνει στον επιβάτη το δικαίωμα να πετάξει. Ένα PNR χωρίς εισιτήριο λήγει στην προθεσμία έκδοσής του και οι θέσεις επιστρέφουν προς πώληση, μερικές φορές σιωπηλά από τη δική σας σκοπιά.

Τα ονόματα είναι σχεδόν αμετάβλητα

Μετά την έκδοση, οι περισσότεροι ναύλοι δεν επιτρέπουν αλλαγή ονόματος πέρα από μικρή διόρθωση, και το τι θεωρείται μικρό διαφέρει ανά αεροπορική. Το όνομα πρέπει να ταιριάζει με το ταξιδιωτικό έγγραφο. Συλλέξτε επώνυμο και όνομα ξεχωριστά, μην αφήσετε έναν ελεύθερο τίτλο να διαρρεύσει σε πεδίο ονόματος, και επικυρώστε πριν από την κλήση κράτησης, όχι μετά.

Οι τύποι επιβατών τιμολογούνται, δεν είναι διακοσμητικοί

Ενήλικας, παιδί και βρέφος είναι τύποι ναύλου, και η ηλικία που αποφασίζει ποιος ισχύει είναι συνήθως η ηλικία κατά την ημερομηνία ταξιδιού, όχι κατά την κράτηση. Ένα βρέφος σε αγκαλιά συνήθως δεν καταλαμβάνει θέση και μπορεί να ταξιδέψει μόνο με ενήλικα. Λάθος τύπος σημαίνει ότι η τιμολόγηση είτε αποτυγχάνει είτε δίνει λάθος ναύλο.

Οι ώρες είναι τοπικές, και τα τμήματα δεν είναι σκέλη

Οι ώρες αναχώρησης και άφιξης δίνονται στην τοπική ώρα κάθε αεροδρομίου. Μην τις μετατρέπετε στη ζώνη ώρας του χρήστη για εμφάνιση, και μην υπολογίζετε διάρκειες αφαιρώντας τες χωρίς τις αποκλίσεις. Ένα ταξίδι περιέχει τμήματα· ένα τμήμα με τεχνική στάση περιέχει περισσότερα από ένα σκέλη. Το UI και τα δεδομένα σας πρέπει να συμφωνούν ποιο από τα δύο είναι μια «στάση».

Πράγματα συμβαίνουν μετά την πώληση

Οι αεροπορικές αλλάζουν δρομολόγια αφού εκδοθούν τα εισιτήρια. Μια κράτηση που ήταν σωστή στην έκδοση μπορεί εβδομάδες αργότερα να δείχνει νέα ώρα, νέο αριθμό πτήσης ή σπασμένη ανταπόκριση, και ανάλογα με τον προμηθευτή το μαθαίνετε μέσω ειδοποίησης, ουράς ή ανακτώντας ξανά την κράτηση. Σχεδιάστε με την παραδοχή ότι η κράτηση θα αλλάξει αφού έχετε σταματήσει να την κοιτάτε.

Το void δεν είναι επιστροφή χρημάτων

Λίγο μετά την έκδοση υπάρχει συνήθως ένα παράθυρο στο οποίο ένα εισιτήριο μπορεί να ακυρωθεί (void) σαν να μην υπήρξε ποτέ. Μετά από αυτό το παράθυρο, μόνο επιστροφή χρημάτων βάσει των κανόνων ναύλου είναι δυνατή, και μπορεί να κοστίσει ποινή ή να μην επιστρέψει τίποτα. Το παράθυρο και οι κανόνες του ανήκουν στον προμηθευτή και στη συμφωνία έκδοσης· διαβάστε τα πριν φτιάξετε κουμπί «ακύρωση».

Τι κοστίζει το λάθος

Οι αποτυχίες σε μια ενσωμάτωση πτήσεων είναι ακριβές με συγκεκριμένο τρόπο: πέφτουν σε ανθρώπους, όχι σε logs. Μια διπλή κράτηση γίνεται τηλεφώνημα στην αεροπορική και πιθανώς σημείωμα εις βάρος του λογαριασμού του γραφείου. Ένας χρεωμένος πελάτης χωρίς εισιτήριο γίνεται επιστροφή χρημάτων, παράπονο και κίνδυνος chargeback. Ένα εισιτήριο που εκδόθηκε χωρίς επιτυχημένη πληρωμή γίνεται χρέος προς την αεροπορική που κάποιος πρέπει να τακτοποιήσει. Μια αλλαγή δρομολογίου που κανείς δεν επεξεργάστηκε γίνεται ταξιδιώτης στο αεροδρόμιο για πτήση που έφυγε νωρίτερα.

Τίποτα από αυτά δεν εμφανίζεται σε δοκιμή της ευτυχισμένης διαδρομής. Γράψτε πρώτα τις δυσάρεστες διαδρομές: το timeout στην κράτηση, την τιμή που ανέβηκε, την έκδοση που απέτυχε μετά το PNR, το void μετά από επιτυχημένη πληρωμή. Αν αυτά αντιμετωπίζονται, η ευτυχισμένη διαδρομή είναι το εύκολο κομμάτι.

Δοκιμές απέναντι σε ένα API πτήσεων

Τα περιβάλλοντα δοκιμών των προμηθευτών είναι χρήσιμα και ελλιπή. Τείνουν να είναι πιο ήσυχα από την παραγωγή, οπότε εξαντλημένες κλάσεις και αλλαγές τιμής είναι σπανιότερες, και κάποια δεν προσομοιώνουν καθόλου timeout. Χρησιμοποιήστε τα για το σχήμα των κλήσεων και τα σφάλματα επικύρωσης, και μετά προγραμματίστε μια ελεγχόμενη εκτέλεση στην παραγωγή με πραγματικές κρατήσεις που ακυρώνετε (void) μέσα στο παράθυρο — με το operations ενήμερο ότι το κάνετε.

Το αν θα ενσωματώσετε καθόλου είναι ξεχωριστό ερώτημα. Αν αυτό που πραγματικά χρειάζεστε είναι βιτρίνα και όχι ακατέργαστο απόθεμα μέσα στο δικό σας σύστημα, η αντιστάθμιση περιγράφεται στο white label ή δική σας μηχανή κρατήσεων, και η ίδια συλλογιστική ισχύει για μια B2B πύλη για υποπράκτορες. Αν θέλετε όντως το απόθεμα μέσα στον δικό σας κώδικα, η πλατφόρμα εκθέτει API πτήσεων και ξενοδοχείων, και η πρόσβαση ξεκινά με μια συζήτηση για την περίπτωση χρήσης σας και όχι με αυτοεξυπηρετούμενο κλειδί — που είναι και η σωστή στιγμή να θέσετε καθεμία από τις παραπάνω ερωτήσεις.

Σύνταξη Tekravel

Τμήμα τεχνολογιών ταξιδιού

Το τμήμα τεχνολογιών ταξιδιού της Tekravel γράφει για τον κλάδο: ιδιοκτήτες πρακτορείων, κονσολιντέιτορ και τους προγραμματιστές που τους ενσωματώνουν. Κάθε άρθρο ελέγχεται πάνω στην πλατφόρμα που περιγράφει πριν δημοσιευτεί.