Integrasi API pemesanan tiket pesawat: yang tidak ada di dokumentasi

Tiket di board Anda bertuliskan "tambahkan penerbangan". Anda pernah memasang payment gateway, kalkulator ongkir, mungkin juga peta, dan model yang Anda bawa adalah yang paling jelas: cari, tampilkan hasil, tagih kartu, selesai. Lalu pemesanan sungguhan pertama kembali dengan harga yang berbeda dari halaman hasil, yang kedua timeout dan tak ada yang bisa memastikan pelanggan dapat kursi atau tidak, dan seseorang dari tim operasional bertanya kenapa ada reservasi tapi tidak ada tiket. Integrasi API pemesanan tiket pesawat dari luar tampak seperti checkout e-commerce. Di baliknya, ini transaksi terdistribusi ke sistem yang dirancang jauh sebelum REST, dan sebagian besar kejutan datang dari celah itu.
Tulisan ini untuk developer yang belum pernah melihat PNR. Ini bukan soal endpoint satu pemasok tertentu; nama-namanya berubah antar penyedia, bentuknya tidak.
Urutan panggilan dalam integrasi API pemesanan tiket pesawat
Hampir semua API penerbangan, apa pun nama metodenya, melewati empat langkah yang sama. Menetapkan batas antar langkah dengan benar adalah sebagian besar pekerjaannya.
| Langkah | Yang Anda dapat | Yang harus disimpan | Yang bisa salah |
|---|---|---|---|
| Pencarian | Itinerary dengan harga dan kunci penawaran atau tarif yang buram | Tidak ada yang permanen — hasil cepat basi | Harga dianggap final; kunci kedaluwarsa sebelum checkout |
| Cek harga / verifikasi | Harga terkonfirmasi, aturan tarif, bagasi, kadang data penumpang wajib | Penawaran yang terverifikasi dan masa berlakunya | Harga berubah; kelas habis; aturan berbeda dari yang ditampilkan |
| Pemesanan | Reservasi — PNR — dengan kode booking dan batas waktu penerbitan tiket | Referensi Anda sendiri, kode booking, batas waktu, data penumpang persis seperti yang dikirim | Timeout tanpa jawaban; PNR ganda; nama ditolak |
| Penerbitan tiket | Nomor e-ticket; di sinilah uang benar-benar terikat | Setiap nomor tiket, terkait penumpang dan segmennya | Penerbitan sebagian; reservasi dibatalkan maskapai karena lewat batas waktu |
Baris yang paling sering diperdebatkan adalah yang ketiga, karena banyak API membolehkan pesan dan terbitkan tiket dalam satu panggilan. Silakan dipakai. Tapi di dunia maskapai keduanya tetap terpisah: PNR bisa ada tanpa tiket, dan penerbitan bisa gagal setelah PNR terbentuk. Endpoint gabungan hanya menyembunyikan momen ketika yang satu berhasil dan yang lain tidak, jadi model data Anda tetap perlu tempat untuk keadaan itu.
Perhatikan juga apa yang tidak dikembalikan pencarian: janji. Itu iklan. Langkah cek harga adalah penawaran, dan baru tiket yang merupakan penjualan.
Mengapa harga pencarian bukan harga yang Anda pesan
Developer web mengharapkan katalog. Inventaris maskapai bukan katalog. Satu penerbangan dijual dalam kelas pemesanan, masing-masing ember kursi dengan satu tarif, dan maskapai terus membuka-tutup ember itu seiring pesawat terisi. Hasil pencarian dirakit cepat dari ketersediaan yang mungkin sudah sedikit tertinggal; saat pengguna selesai mengetik dua paspor, kelas termurah di penerbangan itu bisa saja sudah tutup. Langkah cek harga bertanya ulang, dan jawaban jujurnya kadang lebih mahal.
Pajak menambah pergeserannya sendiri. Pajak dihitung ulang saat cek harga untuk penumpang dan rute yang persis, dan anak atau bayi berbeda harganya dari dewasa yang diasumsikan pencarian. Jika toko Anda menampilkan mata uang lain, misalnya rupiah, sementara pemasok mengutip dalam dolar, konversi kurs adalah satu lagi tempat angka bergerak.
Konsekuensi desainnya sederhana dan sering dilewatkan: jangan pernah menagih berdasarkan harga pencarian. Jalankan cek harga sebelum pembayaran, bandingkan, dan jika jumlahnya berubah, tunjukkan angka baru lalu minta persetujuan. Markup apa pun harus dihitung ulang dari tarif baru, bukan dibawa dari halaman hasil — logikanya sama dengan yang dipikirkan agen saat menyusun strategi markup online, dan rusaknya pun sama ketika dasarnya bergeser.
Idempotensi, dan arti timeout saat pemesanan
Bagian ini perlu dibaca dua kali.
Saat panggilan pemesanan timeout, Anda tidak tahu apa yang terjadi. Permintaan mungkin tak pernah sampai. Mungkin sampai lalu gagal. Atau — kasus yang menyakitkan — sampai, pemasok membuat PNR di maskapai, dan responsnya hilang di jalan pulang. Bagi kode Anda, ketiganya terlihat sama. Bagi maskapai, yang ketiga adalah reservasi hidup yang menahan kursi atas nama pelanggan Anda.
Refleks dari integrasi lain adalah mengulang. Di sini, pengulangan buta bisa menghasilkan PNR kedua untuk penumpang yang sama di penerbangan yang sama. Maskapai menganggap booking ganda sebagai pelanggaran kebijakan; tergantung maskapai dan perjanjian agen, akibatnya bisa berupa pembatalan otomatis salah satu atau kedua reservasi hingga memo debit — ADM — yang dikirim ke pihak penerbit. Agen yang menerimanya akan ingin tahu mengapa sistem Anda memesan dua kali.
Yang berhasil, kira-kira dengan urutan ini:
- Buat referensi booking sendiri sebelum memanggil keluar, simpan, dan kirim bersama permintaan di mana pun API menerima referensi klien. Jika API mendukung idempotency key, pakai; jika tidak, referensi Anda tetap alat untuk mencari booking itu sesudahnya.
- Modelkan status "tidak diketahui" secara eksplisit. Tertunda, terkonfirmasi, gagal — dan tidak diketahui. Timeout memindahkan booking ke tidak diketahui, bukan ke gagal.
- Selesaikan status tak diketahui dengan bertanya, bukan mengulang. Ambil booking berdasarkan referensi Anda, atau daftar booking terbaru untuk penumpang tersebut, sebelum memutuskan mencoba lagi.
- Jalankan job rekonsiliasi yang menyapu semua yang masih tak diketahui, membandingkannya dengan laporan pemasok, dan mengirim yang tak bisa diselesaikan ke antrean manusia alih-alih menebak.
Timeout saat penerbitan tiket adalah masalah yang sama dengan uang di dalamnya. Jika Anda menagih kartu sebelum penerbitan lalu penerbitan macet, Anda punya pelanggan yang sudah bayar dan mungkin tanpa tiket. Jika Anda menerbitkan sebelum penagihan dan penagihan gagal, Anda sudah mengeluarkan dokumen yang harus dibayar seseorang ke maskapai. Pola umumnya: otorisasi kartu dulu, terbitkan tiket, lalu capture jika berhasil — intinya putuskan dengan sengaja, jangan baru ketahuan di produksi.
Konsep penerbangan yang mengejutkan developer web
Tak satu pun sulit. Masing-masing pernah menghabiskan seminggu seseorang karena ia tidak tahu konsep itu ada.
PNR bukan tiket
PNR adalah catatan reservasi: penumpang, segmen, kontak, batas waktu. Tiket adalah dokumen berbayar yang memberi hak terbang. PNR tanpa tiket kedaluwarsa pada batas waktunya dan kursinya kembali dijual, kadang tanpa kabar dari sisi Anda.
Nama nyaris tidak bisa diubah
Setelah tiket terbit, kebanyakan tarif tidak mengizinkan ganti nama selain koreksi kecil, dan apa yang dianggap kecil berbeda tiap maskapai. Nama harus sama dengan dokumen perjalanan. Kumpulkan nama keluarga dan nama depan secara terpisah — hati-hati dengan nama tunggal yang umum di Indonesia, karena aturan pemasok untuk kasus itu berbeda-beda — jangan biarkan gelar dari teks bebas masuk ke kolom nama, dan validasi sebelum panggilan pemesanan, bukan sesudahnya.
Tipe penumpang punya harga, bukan hiasan
Dewasa, anak dan bayi adalah tipe tarif, dan usia yang menentukan biasanya usia pada tanggal terbang, bukan tanggal pemesanan. Bayi di pangkuan umumnya tidak menempati kursi dan hanya boleh terbang bersama orang dewasa. Salah tipe, maka cek harga gagal atau mengutip tarif yang keliru.
Waktu bersifat lokal, dan segmen bukan leg
Jam berangkat dan tiba diberikan dalam waktu lokal tiap bandara. Jangan dikonversi ke zona waktu pengguna untuk tampilan, dan jangan hitung durasi dengan mengurangkannya tanpa offset. Perjalanan berisi segmen; segmen dengan transit teknis berisi lebih dari satu leg. UI dan data Anda harus sepakat mana yang disebut "transit".
Banyak hal terjadi setelah penjualan
Maskapai mengubah jadwal setelah tiket terbit. Booking yang benar saat penerbitan bisa beberapa minggu kemudian menunjukkan jam baru, nomor penerbangan baru, atau sambungan yang putus, dan tergantung pemasoknya Anda mengetahuinya lewat notifikasi, antrean, atau dengan mengambil ulang booking. Rencanakan bahwa booking akan berubah setelah Anda berhenti memperhatikannya.
Void bukan refund
Sesaat setelah penerbitan biasanya ada jendela waktu di mana tiket bisa di-void seolah tak pernah ada. Setelah itu hanya refund sesuai aturan tarif yang mungkin, dan bisa kena penalti atau tidak mengembalikan apa pun. Jendela dan aturannya milik pemasok dan perjanjian penerbitan; baca dulu sebelum membuat tombol "batal".
Harga sebuah kesalahan
Kegagalan dalam integrasi penerbangan mahal dengan cara yang khas: jatuhnya ke manusia, bukan ke log. Booking ganda berarti telepon ke maskapai dan mungkin memo terhadap akun agen. Pelanggan yang sudah ditagih tanpa tiket berarti refund, komplain, dan risiko chargeback. Tiket yang terbit tanpa pembayaran sukses berarti utang ke maskapai yang harus dilunasi seseorang. Perubahan jadwal yang tak diproses berarti penumpang di bandara untuk penerbangan yang sudah berangkat lebih awal.
Tak satu pun muncul di tes jalur bahagia. Tulis jalur yang tidak bahagia lebih dulu: timeout saat pemesanan, harga yang naik, tiket yang gagal setelah PNR terbentuk, void setelah pembayaran sukses. Jika semua itu tertangani, jalur bahagia adalah bagian yang mudah.
Menguji terhadap API penerbangan
Lingkungan uji pemasok berguna tetapi tidak lengkap. Biasanya lebih sepi daripada produksi, jadi kelas habis dan perubahan harga lebih jarang, dan sebagian sama sekali tidak mensimulasikan timeout. Gunakan untuk bentuk panggilan dan error validasi, lalu rencanakan uji terkendali di produksi dengan booking sungguhan yang Anda void di dalam jendela waktunya — dengan tim operasional yang tahu Anda sedang melakukannya.
Perlu integrasi atau tidak adalah pertanyaan tersendiri. Jika yang sebenarnya Anda butuhkan adalah toko online, bukan inventaris mentah di sistem sendiri, pertimbangannya diuraikan dalam white label atau membangun booking engine sendiri, dan penalaran yang sama berlaku untuk portal B2B untuk subagen. Jika Anda memang ingin inventarisnya ada di kode sendiri, platform ini menyediakan API penerbangan dan hotel, dan akses dimulai dari percakapan tentang kebutuhan Anda, bukan kunci swalayan — momen yang tepat pula untuk menanyakan setiap pertanyaan di atas.