Pemecahan Masalah Keycard Encoder

Perbaikan Cepat

Periksa jaringan dan daya terlebih dahulu, lalu coba ulang encoding satu kartu. Ini memakan waktu sekitar 2 menit.

Panduan ini membantu Anda menyelesaikan masalah umum pada keycard encoder.

Referensi Cepat

Yang Anda lihat	Mengapa ini terjadi	Lakukan ini
Encoder tidak merespons	Masalah daya atau jaringan	Periksa konektivitas
Kartu tidak ter-encode	Masalah jenis kartu atau device	Verifikasi kartu dan device
Kegagalan keycard dengan bahasa biasa	AVA menormalkan error vendor, room, atau session	Baca pesannya
"UserCredentialsNotProvided.NotApplicable"	Kredensial Saflok hilang atau belum lengkap	Tambahkan kredensial Saflok
Encoding Saflok/Ambiance gagal atau time out	Windows Agent, service encoder Ambiance, atau device offline	Restart encoder Saflok/Ambiance
"Please create a new keycard first, then use Duplicate for any extra cards."	Saflok tidak dapat menemukan registrasi aktif yang ada untuk reservasi	Perbaiki keycard pertama yang hilang
Multi-room Saflok/Ambiance memerlukan room-level ID	Room yang dipilih belum punya sub-reservation sendiri	Periksa room yang dipilih
"The keycard encoder is temporarily offline. Please approach the Front Desk for assistance."	Encoder tidak punya session aktif	Periksa session encoder
Teks mentah DoorLock generate fail atau internal error muncul	Payload teknis room-access lolos ke modal	Gunakan jalur retry generik
Perubahan jenis encoder tidak bertahan	Save sebelumnya meninggalkan state encoder campuran	Simpan ulang jenis encoder
"Test Connection" gagal (Be-Tech) atau agent tetap offline	Masalah Base URL, adapter, atau service	Perbaiki koneksi Be-Tech
"Make sure the Be-Tech client program is running on the encoder computer."	Windows Agent mengembalikan respons vendor-unavailable 502	Periksa program client Be-Tech
"Test Connection" gagal (GreatLocks)	Detail server GreatLocks yang tersimpan hilang atau usang	Perbaiki koneksi GreatLocks
Inventaris GreatLocks tidak dimuat	Tunnel agent, record server, atau sumber inventaris bermasalah	Periksa sinkron inventaris GreatLocks
"Service URL is required" (LockSDK)	Mode direct memerlukan Service URL per encoder	Tambahkan Service URL LockSDK
Agent LockSDK menampilkan Not registered	Belum ada device agent per-encoder	Daftarkan agent LockSDK
Heartbeat Monitor mati setelah save	Save tidak tersimpan di session hotel Anda saat ini	Simpan ulang Heartbeat Monitor
Heartbeat menampilkan unreachable	Agent offline atau tunnel bermasalah	Periksa status agent
Encoder tetap unavailable	Daftar dinamis masih melihat agent sebagai disconnected	Periksa status live encoder
Windows Agent menampilkan Not connected	Agent tidak berjalan atau instalasi belum selesai	Sambungkan ulang agent
Windows meminta izin	Kontrol service lewat tray membutuhkan elevasi	Setujui prompt UAC

Encoder tidak merespons

Yang Anda lihat: Encoder tampil offline atau tidak merespons di AVA.

Perbaikan:

1. Periksa daya dan kabel encoder.
2. Verifikasi konektivitas jaringan antara kiosk dan encoder (hanya Direct Connection).
3. Pastikan IP dan port server sudah benar.
4. Restart software encoder.

Kartu tidak ter-encode

Yang Anda lihat: Penulisan keycard gagal atau menghasilkan kartu kosong.

Perbaikan:

1. Pastikan jenis kartu cocok dengan encoder Anda.
2. Masukkan ulang kartu lalu coba lagi.
3. Uji dengan kartu kosong baru.
4. Jika Enable guest selection mati, pastikan kiosk diarahkan ke encoder yang benar.
5. Jika Enable guest selection aktif, pastikan tamu memilih encoder online di kiosk.

Kegagalan encode yang dinormalisasi

Yang Anda lihat: Modal reservasi menampilkan pesan singkat dengan bahasa biasa, bukan string vendor mentah.

Mengapa ini terjadi: AVA kini mempertahankan kegagalan Saflok, Be-Tech, Opera, dan session internal yang sudah dinormalisasi sebelum menampilkannya. AVA memprioritaskan pesan terstruktur terlebih dahulu, lalu baru kembali ke parsing string vendor lama jika diperlukan.

Perbaikan:

1. Baca pesan singkatnya terlebih dahulu.
2. Cari userMessage, errorCode, nama vendor, dan detail aman di tampilan support.
3. Gunakan detail itu saat Anda menghubungi support.
4. Cocokkan pesan dengan perbaikan yang paling mungkin di bawah ini:
   • Occupied room: Segarkan reservasi, lalu coba lagi.
   • Encoder offline: Periksa daya, jaringan, atau status agent.
   • Failed detect/write: Masukkan ulang kartu atau pakai kartu kosong baru.
   • No active session: Sambungkan ulang session encoder.
   • Missing mapping: Pastikan room mapping benar.
   • Invalid room or date: Verifikasi tanggal stay dan penugasan room.
   • Vendor auth, gateway, or timeout: Periksa akses vendor atau coba lagi nanti.
   • Invalid request: Buka ulang reservasi yang benar lalu coba lagi.

Fallback lama tetap aktif

Respons lama masih bisa menampilkan string vendor lawas. AVA mempertahankan jalur parsing itu agar log historis dan integrasi lama tetap terbaca benar.

Encoding Saflok/Ambiance tidak berfungsi

Yang Anda lihat: Encoding keycard gagal, time out, atau kiosk melaporkan tidak ada respons dari encoder Saflok/Ambiance.

Perbaikan: Lakukan tiga pemeriksaan berikut secara berurutan. Masing-masing mengesampingkan penyebab umum sebelum Anda lanjut ke berikutnya.

Pemulihan otomatis Saflok

Jika Saflok PMSI mulai lambat atau restart nanti, AVA memeriksa ulang kesiapan setiap 10 detik. Tunggu sebentar, lalu segarkan sebelum menginstal ulang agent.

1. Periksa Windows Agent tersambung di AVA

1. Buka Settings → Room Access → Keycard Encoding.

2. Temukan kartu Windows Agent untuk encoder ini.

3. Pastikan status menampilkan Connected dan waktu Last Seen masih baru.

   

4. Jika agent Not connected, ikuti Windows Agent not connected sebelum lanjut. Jika Saflok PMSI masih mulai, tunggu 10 detik dan segarkan sekali sebelum menginstal ulang apa pun.

2. Periksa encoder online di Ambiance

Jika agent tersambung tetapi encoding masih gagal, masuk ke server Ambiance dan verifikasi device encoder.

1. Buka Ambiance lalu pergi ke Device Management → Encoders.

2. Temukan encoder untuk kiosk ini, misalnya encoder Vouch.

3. Pastikan Status menunjukkan Online.

   

4. Jika encoder menampilkan Offline, lanjut ke langkah 3 untuk restart service encoder.

3. Restart Ambiance Encoder Service

Jika encoder offline di Ambiance, restart service encoder di komputer tempat server Ambiance terpasang.

1. Di komputer yang menjalankan server Ambiance, tekan tombol Windows atau klik menu Start.

2. Ketik services manager lalu buka Ambiance Services Manager dari hasil pencarian.

3. Di daftar services, pilih Ambiance Encoder Service.

   

4. Klik tombol Stop (kotak merah).

5. Tunggu beberapa detik sampai status service berubah menjadi Stopped.

6. Klik tombol Start (segitiga merah).

7. Pastikan status State kembali ke Running.

8. Kembali ke Device Management → Encoders di Ambiance dan pastikan encoder Online.

9. Coba encode test card dari kiosk.

Mengapa restart berhasil

Service encoder bisa kehilangan koneksi ke encoder fisik setelah gangguan jaringan atau periode idle yang lama. Menghentikan lalu memulai ulang service memaksanya membangun ulang koneksi.

Saflok duplicate keycard needs a first keycard

Yang Anda lihat: AVA menampilkan "Please create a new keycard first, then use Duplicate for any extra cards."

Mengapa ini terjadi: Saflok tidak dapat menemukan registrasi aktif atau record keycard untuk reservasi itu. Duplicate card memerlukan satu keycard pertama yang berhasil sebelum AVA bisa menambah kartu lain.

Perbaikan:

1. Buat keycard pertama untuk reservasi.
2. Tunggu sampai encoding pertama selesai dengan sukses.
3. Pilih Duplicate hanya setelah keycard pertama ada.
4. Jika error muncul lagi, pastikan reservasi masih memiliki registrasi aktif di Ambiance.
5. Coba request duplicate lagi.

Yang seharusnya tidak Anda lihat

Anda seharusnya tidak melihat ReservationNotFound mentah atau detail SOAP fault di pesan.

Saflok/Ambiance multi-room keycards need a room-level reservation ID

Yang Anda lihat: Anda mencoba encode kartu untuk satu room dalam masa inap multi-room, lalu AVA menghentikan alurnya.

Mengapa ini terjadi: Duplicate card Saflok/Ambiance memakai sub-reservation ID milik room yang dipilih. Jika room itu belum memiliki ID sendiri, Anda akan melihat error fail-fast.

Perbaikan:

1. Buka reservasi dan pilih baris room yang tepat.
2. Tunggu sinkron PMS jika room baru saja di-split atau dipindah.
3. Pastikan room itu ada sebagai sub-reservation tersendiri di PMS Anda.
4. Coba Encode Keycard lagi.

Encoder tidak punya session aktif

Yang Anda lihat: AVA menampilkan "The keycard encoder is temporarily offline. Please approach the Front Desk for assistance."

Mengapa ini terjadi: Encoder saat ini tidak punya session aktif. AVA memperlakukannya sebagai masalah kesiapan offline.

Perbaikan:

1. Pastikan encoder menyala dan terhubung.
2. Segarkan Settings → Room Access → Keycard Encoding.
3. Periksa apakah encoder menampilkan Online atau Connected.
4. Coba encode lagi setelah session tersambung kembali.
5. Jika masih gagal, gunakan encoder lain atau hubungi support.

Payload room-access mentah tampil di modal

Yang Anda lihat: Modal menampilkan teks mentah seperti DoorLock generate fail! atau internal error.

Mengapa ini terjadi: AVA menangkap blob teknis room-access. AVA kini kembali ke pesan retry generik alih-alih menampilkan payload mentah.

Perbaikan:

1. Tutup modal.
2. Tunggu beberapa detik.
3. Coba encode keycard lagi.
4. Jika pesan yang sama muncul lagi, pastikan encoder online.
5. Jika masih gagal, pindah ke encoder lain atau hubungi support.

Kredensial Saflok belum disediakan

Yang Anda lihat: "UserCredentialsNotProvided.NotApplicable" muncul saat encoding keycard.

Perbaikan:

1. Buka Settings → Room Access → Keycard Encoding.
2. Atur Encoder Type ke Saflok.
3. Masukkan Username dan Password di Encoder Credentials.
4. Jika direct communication aktif, masukkan PMSI Server URL.
5. Klik Save.
6. Klik Test Connection, lalu encode satu test card.

Perubahan jenis encoder tidak bertahan

Yang Anda lihat: Anda memilih satu jenis encoder, tetapi encoder lain tetap aktif.

Perbaikan:

1. Buka Settings → Room Access → Keycard Encoding.
2. Di Keycard Encoder Settings, pilih jenis encoder yang Anda inginkan.
3. Klik Save sekali dan tunggu pesan sukses.
4. Segarkan halaman dan pastikan hanya jenis encoder itu yang aktif.
5. Jika masalah berulang, ganti jenis, simpan, lalu ganti kembali dan simpan lagi.

Be-Tech test connection gagal

Yang Anda lihat: Test Connection menampilkan kegagalan atau tombol tetap nonaktif.

Gunakan ini ketika Anda memang mengonfigurasi Base URL langsung atau melihat kegagalan request Be-Tech umum. Jika Anda melihat pesan program client, gunakan Be-Tech client program unavailable.

Perbaikan:

1. Pastikan Base URL dimulai dengan http:// atau https://.
2. Pastikan layanan Be-Tech berjalan di workstation encoder.
3. Periksa apakah workstation dan kiosk berada di jaringan yang sama.
4. Jika Anda memakai Windows Agent, pastikan kartu agent berstatus Connected.
5. Masukkan ulang Hotel Name, Chain No, Workstation, dan Reader No.
6. Klik Test Connection lagi.

Program client Be-Tech tidak tersedia

Yang Anda lihat: AVA menampilkan "Make sure the Be-Tech client program is running on the encoder computer."

Mengapa ini terjadi: Windows Agent mengembalikan respons 502 vendor-unavailable milik Be-Tech. AVA kini menampilkan pesan langsung untuk kasus itu.

Perbaikan:

1. Buka komputer encoder.
2. Pastikan program client Be-Tech sedang berjalan.
3. Restart program client jika berhenti.
4. Restart Windows Agent jika program client sudah berjalan.
5. Klik Test Connection lagi.

Kegagalan Be-Tech lainnya

Jika Anda melihat Be-Tech request failed, ikuti Be-Tech test connection fails. Pesan langsung program client hanya berlaku untuk respons 502 vendor-unavailable.

GreatLocks test connection gagal

Yang Anda lihat: Test Connection gagal setelah Anda mengedit detail server GreatLocks.

Perbaikan:

1. Buka Settings → Room Access → Keycard Encoding.
2. Pastikan server GreatLocks memiliki XHLSI Server IP Address dan TCP Port.
3. Klik Save lagi.
4. Jika Anda memperbarui penyiapan lama, pertahankan record server yang sudah ada.
5. Klik Test Connection lagi.

Inventaris GreatLocks tidak dimuat

Yang Anda lihat: Inventaris building, floor, atau room tetap kosong untuk GreatLocks.

Mengapa ini terjadi: Tunnel GreatLocks offline, atau sumber inventaris tidak dapat dijangkau.

Perbaikan:

1. Buka Settings → Room Access → Keycard Encoding.
2. Pastikan record server GreatLocks sudah disimpan.
3. Periksa apakah tunnel agent menampilkan koneksi yang sehat.
4. Klik Test Connection lagi.
5. Segarkan halaman setelah koneksi kembali.

Service URL LockSDK wajib diisi

Yang Anda lihat: Save diblokir atau form encoder menampilkan "Service URL is required."

Perbaikan:

1. Buka Settings → Room Access → Keycard Encoding.
2. Pilih LockSDK.
3. Buka Physical Encoder Devices dan edit encoder.
4. Masukkan Service URL yang valid, misalnya http://127.0.0.1:8092.
5. Klik Save, lalu jalankan Test Connection.

Agent LockSDK belum terdaftar

Yang Anda lihat: Kartu encoder LockSDK menampilkan Not registered di Windows Agent.

Perbaikan:

1. Pastikan encoder LockSDK ada di Physical Encoder Devices.
2. Buka Windows Agent dan temukan kartu encoder.
3. Klik Download Windows Agent jika kartunya baru, atau Reinstall jika sudah ada.
4. Ekstrak paket dan jalankan file .bat di PC Windows yang terhubung.
5. Segarkan status dan pastikan kartu berubah dari Not registered menjadi Connected atau Not connected.
6. Gunakan Advanced options hanya untuk View Logs, Rotate Secret, atau Delete. Rotate Secret membuka dialog konfirmasi sebelum AVA memutus agent saat ini.

Heartbeat Monitor mati setelah save

Yang Anda lihat: Anda mengaktifkan Heartbeat Monitor, klik Save, lalu pengaturannya mati lagi.

Perbaikan:

1. Buka Settings → Room Access → Keycard Encoding.
2. Buka Encoding Options → Advanced options.
3. Aktifkan Heartbeat Monitor.
4. Klik Save sekali dan tunggu pesan sukses.
5. Segarkan halaman dan pastikan Heartbeat Monitor tetap aktif.
6. Jika tetap mati, ikuti Settings Not Saving After Switching Hotels.

Kegagalan Heartbeat

Yang Anda lihat: Heartbeat Monitor menampilkan unreachable.

Perbaikan:

1. Pastikan agent berjalan di kiosk/PC.
2. Periksa Registered Agents untuk status online dan keterjangkauan tunnel.
3. Tinjau log agent untuk error.
4. Instal ulang agent jika perlu.

Status live encoder tidak cocok

Yang Anda lihat: Encoder terlihat terkonfigurasi, tetapi AVA masih menandainya unavailable di modal reservasi.

Mengapa ini terjadi: AVA menampilkan online hanya saat agent tersambung dan tunnel dapat dijangkau. Status yang sama kini menggerakkan pemilihan encoder dinamis.

Perbaikan:

1. Periksa Registered Agents untuk kartu encoder.
2. Pastikan device tersambung dan tunnel dapat dijangkau.
3. Perbaiki masalah agent atau jaringan terlebih dahulu.
4. Segarkan Settings → Room Access.
5. Coba encode lagi.
6. Periksa ulang baris Status: di halaman settings.

Windows Agent tidak tersambung

Yang Anda lihat: Status menampilkan Not connected atau "Never online."

Perbaikan:

1. Buka zip yang diunduh dan jalankan download-installer.bat.
2. Biarkan file itu mengunduh installer .exe, lalu jalankan file tersebut.
3. Pastikan PC Windows memiliki akses internet.
4. Klik Reinstall pada kartu agent di Windows Agent jika perlu.
5. Jika ini penyiapan Be-Tech, pastikan juga layanan adapter lokal berjalan. Status Be-Tech dapat memerlukan hingga 5 menit untuk diperbarui setelah restart.
6. Segarkan status Registered Agents.
7. Kembali ke Settings → Room Access dan pastikan Status: berubah menjadi online.

Daftar encoder dinamis

Saat agent tersambung dan tunnel dapat dijangkau, daftar encoder dinamis harus menampilkan Online. Jika kartu encoder bersarang masih terlihat offline, segarkan halaman dan periksa agent terlebih dahulu.

Aksi service Windows Agent memerlukan izin

Yang Anda lihat: Windows meminta izin administrator saat Anda klik Start, Stop, atau Restart.

Mengapa ini terjadi: Tombol tray membutuhkan akses yang lebih tinggi untuk mengontrol service Windows.

Perbaikan:

1. Klik Yes pada prompt UAC.
2. Jika Anda bukan admin, minta seseorang dengan hak admin untuk menyetujuinya.
3. Coba aksi itu lagi jika Anda membatalkan prompt.

Aturan routing kiosk tidak muncul

Yang Anda lihat: Anda tidak dapat menemukan aturan routing di bawah Room Access atau bagian lama Kiosk to Encoder Routing.

Perbaikan:

1. Buka Settings → Kiosk.
2. Buka Device Routing.
3. Matikan Enable guest selection untuk menampilkan aturan routing manual.
4. Tambahkan setidaknya satu device di Physical Encoder Devices.

Masih Terkendala?

Hubungi success@vouch-technologies.com jika:

• ❌ Encoder tetap offline setelah pengecekan daya dan jaringan
• ❌ Program client Be-Tech terus berhenti
• ❌ Encoding kartu gagal di beberapa kiosk
• ❌ Heartbeat tetap tidak sehat selama lebih dari 30 menit

Detail yang membantu untuk disertakan:

• Jenis dan model encoder
• Pesan error Be-Tech yang persis
• Apakah Anda memakai Windows Agent atau Base URL langsung
• Screenshot Registered Agents dan Heartbeat Monitor
• Waktu masalah mulai terjadi

Panduan Terkait

• Ringkasan Encoder Keycard
• Atur Encoder Keycard
• Instruksi Tamu Keycard