Praktik Terbaik

Gunakan pola-pola ini agar integrasi mitra tetap dapat diprediksi, dapat dipantau, dan aman bagi fasilitas.

Identifikasi fasilitas secara konsisten

Pilih metode penautan yang dikonfigurasi untuk akun mitra Anda dan gunakan secara konsisten:

Direct Link - gunakan facility_id Performance Hub yang dikembalikan oleh endpoint facilities.
Linking Identifier - gunakan pengidentifikasi lokasi Anda sendiri, seperti ID cabang, kode lokasi, atau nomor toko.

Jangan mengirimkan kedua pengidentifikasi dalam permintaan yang sama. Performance Hub memproses permintaan menggunakan metode penautan yang dikonfigurasi untuk akun mitra Anda.

Lihat Metode Penautan Mitra untuk panduan penyiapan.

Lakukan penulisan batch dengan hati-hati

Partner API menerima isi permintaan JSON dan dirancang untuk alur kerja sinkronisasi berbasis batch jika didokumentasikan. Jaga agar batch tetap terbatas dan dapat dicoba ulang.

Panduan default:

Gunakan hingga 1000 item per permintaan batch untuk kinerja optimal.
Jaga payload tetap di bawah 10MB.
Tetap dalam batas 5 permintaan per detik per endpoint.

Batas laju dapat disesuaikan dan dikonfigurasi kasus per kasus oleh manajer akun mitra Performance Hub Anda. Jika Anda memperkirakan impor bervolume tinggi, lalu lintas peluncuran, atau pengisian ulang (backfill) pelaporan, sepakati throughput yang diperlukan sebelum jendela perubahan.

Jika Anda perlu menyinkronkan kumpulan data yang besar, bagi menjadi potongan-potongan yang deterministik dan catat ID setiap potongan di sisi Anda. Ini memudahkan penelusuran percobaan ulang yang gagal.

Coba ulang dengan aman

Gunakan exponential backoff untuk kegagalan sementara seperti 429, 500, 502, 503, dan 504.

Hindari loop percobaan ulang yang rapat. Titik awal yang baik adalah:

Coba ulang setelah 1 detik.
Coba ulang setelah 2 detik.
Coba ulang setelah 4 detik.
Hentikan dan kirim peringatan jika operasi masih gagal.

Untuk kegagalan validasi seperti 400 atau 422, perbaiki permintaan sebelum mencoba ulang.

Gunakan idempotensi jika didukung

Endpoint unlock Door/Gate Controller mendukung idempotency_key opsional. Menggunakan kembali kunci yang sama untuk mitra, fasilitas, dan pintu yang sama akan mengembalikan hasil yang sudah ada jika tersedia.

Gunakan kunci yang stabil untuk tindakan yang dilakukan, misalnya ID check-in atau ID peristiwa akses dari sistem Anda.

Jangan berasumsi bahwa setiap endpoint tulis mendukung idempotensi kecuali hal itu didokumentasikan untuk endpoint tersebut.

Jaga data sumber tetap bersih

Kirimkan nilai yang stabil dan dinormalisasi jika memungkinkan:

Gunakan ID anggota, paket, fasilitas, dan check-in yang konsisten dari sistem sumber Anda.
Gunakan stempel waktu ISO 8601 untuk tanggal dan waktu.
Kirimkan nomor telepon dalam format internasional jika tersedia.
Kirimkan mata uang menggunakan bidang yang didokumentasikan untuk setiap endpoint.
Hindari membebani bidang teks bebas dengan data yang seharusnya berada di bidang terstruktur.

Rancang untuk sinkronisasi inkremental dan penuh

Sebagian besar integrasi mitra membutuhkan keduanya:

Sinkronisasi inkremental untuk perubahan sehari-hari.
Sinkronisasi rekonsiliasi penuh untuk memperbaiki peristiwa yang terlewat, impor historis, atau penyimpangan data.

Integrasi Anda harus dapat mengirim ulang status terkini untuk anggota, paket keanggotaan, atau snapshot laporan tanpa bergantung pada keberhasilan permintaan sebelumnya.

Publikasikan Access Time Windows dengan aman

Perlakukan nilai access_time_windows setiap anggota sebagai snapshot lengkap dengan revisi yang independen:

Koordinasikan satu aliran access_time_windows_revision yang terus meningkat secara monoton di seluruh worker inkremental dan rekonsiliasi.
Coba ulang pengiriman yang tidak pasti atau sementara gagal dengan revisi dan payload ternormalisasi yang sama.
Hilangkan access_time_windows jika Anda tidak memperbaruinya.
Kirim [] hanya setelah pengambilan dari sumber otoritatif yang berhasil membuktikan bahwa tidak ada jendela yang tersisa. Jangan pernah mengubah batas waktu upstream, hasil parsial, atau kegagalan parsing menjadi pencabutan.
Jaga agar external_id dan scope_key tetap stabil, dan sertifikasi setiap pemetaan cakupan sebelum produksi.
Pantau usia data sumber terhadap kebijakan kesegaran yang disepakati untuk integrasi tersebut.

Lihat panduan produsen Access Time Windows yang otoritatif untuk snapshot lengkap, zona waktu, DST, pembatalan, dan vektor uji.

Perlakukan kontrol akses sebagai hal yang kritis bagi keselamatan

Untuk pembukaan kunci Door/Gate Controller:

Sistem Anda harus memutuskan apakah orang tersebut diizinkan masuk sebelum memanggil Performance Hub.
Performance Hub mengembalikan 200 hanya setelah pengontrol di lokasi mengonfirmasi bahwa relai secara fisik telah membuka kunci.
Sebagian besar konfirmasi selesai dalam 3-5 detik.
Batas waktu adalah buka kunci yang gagal secara eksplisit, bukan keberhasilan di latar belakang.
Coba ulang hanya sesuai dengan aturan akses dan keselamatan Anda sendiri.

Selalu catat event_id dan command_id yang dikembalikan oleh endpoint unlock.

Pantau integrasi Anda

Gunakan log permintaan Partner Console selama pengembangan dan peluncuran. Di produksi, kelola juga log Anda sendiri yang berisi:

Stempel waktu permintaan.
Endpoint.
ID rekaman sumber.
Pengidentifikasi fasilitas.
Kode status HTTP.
Isi respons atau pesan kesalahan Performance Hub.

Bidang-bidang ini membuat dukungan dan rekonsiliasi jauh lebih cepat saat pelanggan menanyakan apa yang terjadi.