Lewati ke konten
Blog

API ketersediaan hotel: merancang untuk supplier yang lambat

Redaksi Tekravel
Ditulis dengan bantuan AI

Tiketnya biasanya terlihat tidak berbahaya. "Tambahkan pencarian hotel ke halaman booking — supplier sudah memberi kita API ketersediaan hotel, ada sandbox-nya, harusnya cukup satu sprint." Anda membaca dokumentasinya, mengirim permintaan untuk dua orang dewasa di Bali selama tiga malam, dan respons datang. Lalu Anda mengirim permintaan yang sama untuk kota dengan lebih banyak properti, dan tidak ada apa-apa yang kembali untuk waktu yang lama dan canggung. Ketika akhirnya datang, ukurannya cukup besar untuk membuat parser JSON Anda merenungkan pilihan hidupnya.

Di titik itulah bentuk pekerjaannya berubah. Ketersediaan hotel bukan lookup. Ini fan-out: satu pertanyaan dari pengguna Anda menjadi banyak pertanyaan ke banyak supplier, masing-masing menjawab dengan kecepatannya sendiri, dengan kosakatanya sendiri, dengan gagasannya sendiri tentang apa itu "kamar". Klien yang Anda bangun harus tetap berguna selama fan-out itu belum selesai. Tulisan ini membahas cara merancang klien tersebut — untuk developer yang paham REST dan JSON tetapi belum pernah harus menjelaskan kepada hotel mengapa tarif non-refundable seorang tamu ditampilkan sebagai pembatalan gratis.

Mengapa API ketersediaan hotel lebih lambat dari endpoint yang biasa Anda pakai

Dari luar, pencarian penerbangan dan pencarian hotel tampak mirip: kueri dikirim, opsi berharga kembali. Di dalamnya, masalahnya tidak sama. Jika Anda sudah membaca catatan kami tentang apa yang sebenarnya dibutuhkan integrasi API pemesanan penerbangan, Anda tahu harga yang Anda cari tidak selalu harga yang Anda pesan. Hotel menambahkan kesulitan kedua di atasnya: volume.

Satu kota bisa memiliki ratusan properti. Setiap properti menjual beberapa tipe kamar. Setiap tipe kamar dijual dengan beberapa rate plan — dengan sarapan, tanpa sarapan, refundable, non-refundable, tarif member, tarif paket. Setiap rate plan bisa datang dari lebih dari satu sumber: bedbank, channel manager, kontrak langsung, wholesaler yang Anda ajak kerja sama karena allotment-nya di satu hotel lebih baik dari yang lain. Kalikan semuanya dan pencarian "sederhana" menjadi pohon besar, dirakit dari beberapa sumber yang tidak sepakat soal nama maupun ID.

Jadi bagian yang lambat jarang sekali kode Anda. Yang lambat adalah supplier paling lambat yang Anda putuskan untuk ditunggu.

Hasil progresif atau jawaban lengkap: pilih dengan sengaja

Ada dua cara jujur untuk mengembalikan hasil pencarian hotel, dan kebanyakan integrasi berakhir di tengah-tengah yang tidak nyaman.

Tunggu semuanya. Backend Anda menyebar permintaan, menunggu setiap supplier menjawab atau timeout, menggabungkan, menghapus duplikat, mengurutkan, lalu mengembalikan satu daftar lengkap. Hasilnya rapi: satu permintaan, satu respons, harga yang bisa dibandingkan karena semuanya sudah di meja. Harganya, pengguna Anda menatap spinner selama supplier paling lambat Anda butuhkan, setiap kali.

Kirim apa yang sudah ada. Backend Anda memulai fan-out dan langsung mengembalikan search handle. Klien melakukan polling ke handle itu, atau menahan stream tetap terbuka, dan menerima hasil per batch saat supplier menjawab. Hotel pertama muncul cepat. Harganya adalah kompleksitas di tempat lain: daftar berubah urutan saat pengguna sedang membacanya, label "termurah" bisa berpindah, dan hotel yang muncul dari satu supplier belakangan bisa mendapat tarif lebih murah dari supplier lain.

Jika antarmuka Anda adalah halaman pencarian di depan manusia, progresif hampir selalu benar — orang itu sedang menjelajah, bukan menjalankan batch job, dan halaman yang terlihat bekerja lebih baik daripada halaman yang diam-diam berpikir. Jika konsumen Anda adalah mesin lain — job perbandingan tarif, alat booking korporat yang butuh satu jawaban pasti — menunggu sering kali lebih sederhana dan benar.

Mana pun yang Anda pilih, tiga aturan menjaga klien progresif tetap waras:

  • Setiap batch membawa status penyelesaian untuk pencarian secara keseluruhan, agar klien tahu bedanya "belum ada hasil lagi" dan "tidak akan ada hasil lagi".
  • Hasil digabungkan dengan kunci hotel yang stabil di server, bukan ditempelkan di belakang. Klien tidak boleh harus menebak bahwa dua kartu adalah gedung yang sama.
  • Urutan berdasarkan harga bersifat sementara sampai pencarian selesai, dan antarmuka mengatakannya. Pengguna memaafkan daftar yang perlahan tenang; mereka tidak memaafkan label "harga terendah" yang ternyata salah.

Memodelkan kamar dan rate plan agar tidak runtuh

Di sinilah sebagian besar integrasi hotel gagal tanpa suara, dan kegagalannya muncul berbulan-bulan kemudian sebagai tiket support, bukan laporan bug.

Model yang menggoda adalah model datar: hotel punya daftar penawaran, setiap penawaran punya nama kamar dan harga. Tampilannya bagus. Lalu satu supplier mengembalikan "Deluxe King" dan "Deluxe Room, 1 King Bed" untuk kamar yang jelas sama, supplier lain mengembalikan nama yang sama untuk dua kamar yang benar-benar berbeda (satu dengan pemandangan kota, satu tidak), dan supplier ketiga mengembalikan tarif per malam sementara yang lain per masa inap. Daftar datar tidak bisa memberi tahu Anda sedang melihat yang mana. Ia hanya menampilkannya.

Model yang bertahan menghadapi supplier sungguhan punya setidaknya empat tingkat, dan menjaganya tetap terpisah:

TingkatIsinyaKesalahan yang harus dihindari
HotelID stabil milik Anda sendiri, dipetakan ke kode setiap supplierMemakai ID hotel dari supplier sebagai primary key
KamarOkupansi, konfigurasi tempat tidur, teks kamar asli dari supplier tanpa diubah"Merapikan" nama kamar sampai dua kamar berbeda melebur jadi satu
Rate planBoard basis, refundability, jenis pembayaran, supplier asalnyaMemperlakukan sarapan atau refundability sebagai bagian nama kamar
HargaTotal untuk seluruh masa inap, mata uang, pajak dan biaya yang sudah termasuk serta yang dibayar di hotelMenampilkan angka per malam di samping angka per masa inap, atau menyembunyikan biaya saat check-in

Anda boleh tidak setuju di mana garisnya ditarik — sebagian tim memisahkan okupansi menjadi tingkat tersendiri, dan itu masuk akal begitu Anda menjual booking multi-kamar. Yang tidak boleh adalah menggabungkan tingkat hanya karena antarmuka cuma menampilkan dua di antaranya. Antarmuka boleh meratakan saat render. Data tidak boleh.

Satu detail layak mendapat kalimatnya sendiri: simpan deskripsi kamar mentah dari supplier di samping versi yang sudah dinormalkan. Ketika tamu tiba dan diberi kamar yang berbeda dari voucher-nya, pertanyaan pertama semua orang adalah apa yang sebenarnya dikirim supplier.

Kebijakan pembatalan adalah data, bukan paragraf

Banyak supplier mengembalikan ketentuan pembatalan sebagai teks bebas: "Pembatalan gratis hingga 3 hari sebelum kedatangan, setelah itu denda 1 malam." Sangat menggoda untuk menampilkan string itu dan lanjut.

Jangan. Teks tidak bisa dibandingkan, diurutkan, difilter, atau ditegakkan. Pengguna Anda ingin memfilter tarif refundable. Tim keuangan Anda ingin tahu booking mana yang menjadi non-refundable besok agar agen bisa menghubungi klien sebelum tenggatnya lewat. Alur pasca-booking Anda harus memberi tahu pelanggan, tepat saat mereka menekan tombol batal, berapa persisnya yang akan ditagih. Semua itu tidak bisa berjalan di atas sebuah kalimat.

Modelkan setiap kebijakan sebagai daftar berurutan dari jendela denda: dari saat ini, sampai saat itu, dendanya sebesar ini (atau sebagian dari masa inap, atau sekian malam). Batasnya adalah timestamp dengan zona waktu — zona waktu hotel, bukan server Anda dan bukan pengguna — karena "3 hari sebelum kedatangan" berarti momen yang berbeda tergantung tengah malam siapa yang Anda hitung. Simpan teks asli supplier di samping versi terstruktur, tampilkan versi terstruktur, dan perlakukan ketidakcocokan keduanya sebagai sesuatu untuk diselidiki, bukan disembunyikan.

Dan periksa ulang kebijakannya saat booking, bukan hanya saat pencarian. Kebijakan berubah di antara dua panggilan itu lebih sering dari yang diperkirakan siapa pun.

Berapa sebenarnya harga sebuah kesalahan

Pencarian yang lambat membuat Anda kehilangan konversi — buruk, tapi terlihat; seseorang pasti mengeluh. Kegagalan yang mahal adalah yang sunyi.

Tarif yang ditampilkan refundable padahal supplier menganggapnya non-refundable berarti sengketa dengan pelanggan yang memegang screenshot, dan biasanya agensi sendiri yang akhirnya membayar dendanya. Harga per malam yang ditampilkan sebagai total masa inap menjual kamar di bawah modal sampai seseorang di bagian akuntansi menyadarinya. Kamar yang digabung dengan kamar lain mengirim keluarga berempat ke kamar untuk dua orang. Biaya yang dibayar di hotel tapi tak pernah ditampilkan mengubah ulasan bintang lima menjadi chargeback. Masing-masing adalah keputusan pemodelan yang dibuat di sprint pertama, biasanya dengan label "nanti kita rapikan".

Caching: apa yang boleh disimpan dan apa yang tidak

Setiap tim yang mengintegrasikan API hotel pada akhirnya bertanya apakah hasil boleh di-cache agar pencarian lebih cepat dan lebih murah. Jawabannya ya, untuk sebagian hal, dan garis pemisahnya lebih penting daripada angka performa apa pun.

Konten statis — nama hotel, alamat, koordinat, foto, daftar fasilitas, deskripsi kamar — jarang berubah dan justru itulah yang harus Anda cache secara agresif di penyimpanan Anda sendiri. Periksa ketentuan supplier tentang cara menyimpan dan menampilkannya; sebagian lisensi membatasinya. Mengambilnya secara live di setiap pencarian lambat tanpa manfaat.

Tarif dan ketersediaan live adalah soal lain. Harga yang di-cache adalah tebakan tentang berapa yang akan ditagih supplier, dan supplier tidak menghormati tebakan Anda. Cache singkat untuk hasil pencarian bisa diterima untuk menampilkan halaman — selama setiap jalur booking melakukan re-pricing ke supplier sebelum mengambil uang, dan antarmuka memperlakukan perubahan harga sebagai hasil normal, bukan error. Sebagian supplier juga membatasi rasio pencarian terhadap booking; caching agresif yang menyembunyikan lalu lintas Anda yang sebenarnya dari mereka bukan celah yang layak diandalkan.

Yang tidak boleh pernah di-cache adalah apa pun yang mewakili komitmen: token harga yang ditahan, kode booking, kutipan biaya pembatalan. Semua itu milik satu pengguna dan satu momen.

Sebelum Anda menyebutnya selesai

Pemeriksaan singkat yang layak dijalankan pada integrasi Anda sebelum menangani booking sungguhan:

  • Pencarian mengembalikan status penyelesaian, dan klien berperilaku berbeda sebelum dan sesudahnya.
  • Hotel dikunci dengan ID milik Anda sendiri, dengan kode setiap supplier dipetakan ke sana.
  • Kamar, rate plan, dan harga adalah objek terpisah di data Anda, apa pun yang ditampilkan layar.
  • Setiap harga menyatakan apakah per malam atau per masa inap, dan apa yang dibayar saat kedatangan.
  • Kebijakan pembatalan disimpan sebagai jendela denda berwaktu dalam zona waktu hotel, dengan teks aslinya tetap disimpan.
  • Jalur booking melakukan re-pricing dan membaca ulang kebijakan sebelum menagih siapa pun.
  • Tidak ada yang mewakili komitmen yang pernah disajikan dari cache.

Jika Anda sedang menimbang apakah membangun semua ini langsung ke masing-masing supplier atau memulai dari platform yang sudah menghadapi masalah-masalah ini, sisi kontrak sama pentingnya dengan kode — tulisan kami tentang kontrak hotel consolidator dan tarif bedbank membahas apa yang perlu diminta. API penerbangan dan hotel kami dibuka lewat percakapan, bukan lewat kunci self-service; jika itu jalur yang ingin Anda jajaki, mulai percakapannya di halaman travel APIs.

Fan-out tidak pernah hilang. Klien yang baik hanya berhenti berpura-pura bahwa fan-out itu tidak ada.

Redaksi Tekravel

Meja teknologi perjalanan

Meja teknologi perjalanan Tekravel menulis untuk pelaku industri: pemilik agen, konsolidator, dan para pengembang yang mengintegrasikan mereka. Setiap artikel diperiksa pada platform yang dijelaskannya sebelum diterbitkan.