Membangun Receiver Callback Biometrik dengan Python, Node.js, dan PHP
Receiver callback adalah bagian kecil kode yang mengubah setiap pemindaian sidik jari, wajah, atau kartu menjadi catatan di sistem Anda sendiri. Cams Biometrics Gateway mengirimkan setiap pemindaian yang telah terverifikasi ke server Anda sebagai permintaan JSON, dan server Anda membalas untuk mengonfirmasi bahwa data telah diterima. Anda tidak perlu menulis receiver tersebut dari awal. Cams menyediakan AI Code Generator Prompts untuk Python, Node.js, dan PHP: tempel salah satunya ke asisten AI seperti Claude atau ChatGPT, dan Anda akan mendapatkan satu file lengkap yang siap dijalankan, berisi receiver callback, REST client, dan antarmuka pengujian. Tutorial ini menjelaskan apa yang harus dilakukan receiver, cara membuatnya untuk bahasa Anda, cara mengonfigurasinya, dan cara mengujinya sebelum digunakan secara langsung.
01 · Enam Tugas Utama
Tugas yang Harus Dilakukan Receiver Callback
Apa pun bahasa yang Anda gunakan, setiap receiver callback biometrik melakukan enam tugas yang sama. Inilah juga yang perlu diperiksa pada kode apa pun yang Anda hasilkan.
| Tugas | Artinya | Mengapa penting |
|---|---|---|
| 1. Terima permintaan | Terima HTTP/HTTPS POST dengan body JSON mentah | Inilah cara Gateway mengirimkan setiap event |
| 2. Verifikasi token | Periksa AuthToken terhadap token callback yang diharapkan | Mencegah pihak lain mengirim data kehadiran palsu ke URL Anda |
| 3. Arahkan berdasarkan jenis event | Periksa kunci mana yang ada di dalam RealTime dan proses sesuai dengan itu | Tidak setiap callback adalah data absensi; sebagian melaporkan foto atau perubahan pengguna |
| 4. Lewati duplikat | Gunakan OperationID untuk mengabaikan event yang sudah Anda simpan | Pengiriman ulang tidak akan pernah menjadi catatan ganda |
| 5. Simpan dan catat | Simpan kolom yang Anda butuhkan dan catat setiap callback | Membuat catatan yang akan digunakan oleh HRMS, penggajian, atau dasbor Anda |
| 6. Balas dengan done | Kembalikan {“status”:”done”} dengan HTTP 200 | Memberi tahu Gateway bahwa event telah diterima dengan aman |
02 · Kenali Data Anda
Payload yang Akan Anda Terima
Callback yang paling umum adalah log absensi, yang dikirim setiap kali seseorang melakukan pemindaian. Simpan contoh ini sebagai sample.json, karena Anda akan menggunakannya untuk menguji receiver Anda nanti.
|
Callback API, permintaan PunchLog yang dikirim ke receiver Anda {
"RealTime": {
"OperationID": "9nu1wak5616p",
"LabelName": "Burj Khalifa",
"SerialNumber": "ZHM11xxxxxxxx",
"PunchLog": {
"Type": "CheckOut",
"Temperature": "36.8",
"FaceMask": false,
"InputType": "Fingerprint",
"UserId": "2",
"LogTime": "2020-09-17 07:48:22 GMT +0530"
},
"AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
"Time": "2020-09-17 04:19:03 GMT +0000"
}
}
|
Setelah memproses callback apa pun, receiver Anda harus membalas dengan HTTP 200 dan body yang persis seperti ini:
|
Callback API, respons yang harus dikembalikan receiver Anda { "status": "done" } (HTTP 200)
|
Jenis event callback
Setiap callback diterima di dalam objek RealTime. Receiver Anda memutuskan apa yang harus dilakukan dengan memeriksa kunci mana yang ada:
| Kunci di dalam RealTime | Yang dilaporkan |
|---|---|
| PunchLog | Pemindaian absensi: siapa, check-in atau check-out, kapan, dan dengan cara apa |
| UserUpdated | Detail pengguna telah diperbarui di perangkat |
Dua detail yang sering terlewat oleh developer
| Detail | Hal yang perlu diperhatikan |
|---|---|
| Kunci balasan menggunakan huruf kecil | Kembalikan status dengan huruf kecil dan nilai done. Jangan menyalin kolom Status berhuruf kapital dari respons RESTful API |
| Format LogTime | LogTime terlihat seperti 2020-09-17 07:48:22 GMT +0530. Ini adalah waktu pemindaian sebenarnya beserta offset perangkat. Parsing dengan offset tersebut dan gunakan sebagai waktu absensi |
03 · Biarkan AI Menulis Kodenya
Buat Receiver Anda dengan AI Code Generator Prompts
Cams menerbitkan file prompt siap pakai untuk setiap bahasa server yang didukung. Setiap prompt berisi ringkasan spesifikasi Cams Web API 3.0 dan instruksi yang jelas tentang apa yang harus dibuat. Anda menempelkannya ke asisten AI, dan asisten tersebut menghasilkan implementasi lengkap dalam satu file untuk stack Anda.
|
Unduh file prompt Pilih bahasa Anda di bagian berikutnya dan unduh file prompt .txt-nya. |
|
|
Tempel ke asisten AI Buka Claude, ChatGPT, Copilot, atau alat coding AI apa pun, lalu tempel seluruh isi prompt. |
|
|
Dapatkan file lengkap yang berfungsi AI menghasilkan satu file. Atur nilai konfigurasi Anda, deploy, lalu jalankan. |
| Setiap file yang dihasilkan mencakup | Fungsinya |
|---|---|
| Receiver callback | Membaca body POST mentah, memvalidasi AuthToken, mengarahkan berdasarkan jenis event, mencatat setiap callback, menyimpan log absensi, menyimpan foto kehadiran, dan membalas dengan done |
| REST client | Fungsi permintaan generik beserta fungsi pembungkus untuk semua 27 operasi RESTful, seperti AddUser, DeleteUser, ResendAllUser, dan UpdateAccessTime |
| Antarmuka pengujian HTML | Halaman browser dengan kolom konfigurasi Anda, dropdown operasi, editor JSON yang telah terisi templat permintaan, penampil respons, dan daftar callback terbaru |
|
Dokumentasi yang dihosting diutamakan Setiap prompt meminta AI untuk membaca dokumentasi lengkap Cams Web API dan menjadikannya sumber otoritatif untuk operasi, skema JSON, nama kolom, dan kode respons. Jika ada sesuatu dalam ringkasan prompt yang bertentangan dengan dokumentasi yang dihosting, dokumentasi tersebut yang berlaku. |
04 · Pilih Bahasa Anda
Prompt untuk Python, Node.js, dan PHP
Setiap prompt disesuaikan untuk menghasilkan kode yang idiomatis dengan dependensi minimal untuk bahasanya.
|
|
|
Prompt juga tersedia untuk C# (.NET 8) dengan Minimal API, Java dengan HttpServer bawaan dan tanpa dependensi, Go dengan net/http dan hanya standard library, serta Ruby dengan Sinatra dan SQLite. Anda dapat menemukan semuanya di bagian AI Code Generator Prompts pada dokumentasi Cams Web API. Dapatkan Prompt.
05 · Tiga Nilai yang Perlu Diatur
Mengonfigurasi File yang Dihasilkan
File yang dihasilkan memiliki blok konfigurasi di bagian atas. Pada versi PHP, bentuknya seperti ini, dan bahasa lain menggunakan tiga nilai yang sama:
|
Blok konfigurasi, versi PHP $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| Pengaturan | Yang harus diisi |
|---|---|
| base_url | URL endpoint RESTful dari akun Cams API Monitor Anda |
| stgid | Service Tag ID Anda. |
| auth_token | AuthToken Anda, disertakan dalam permintaan RESTful keluar dan diperiksa terhadap AuthToken pada permintaan callback masuk. |
|
Jangan simpan token di kode bersama Untuk pengujian cepat, memasukkan nilai langsung ke blok konfigurasi tidak masalah. Sebelum digunakan secara langsung, pindahkan token ke environment variable atau secrets manager, agar tidak pernah masuk ke version control atau file bersama. |
Setelah dikonfigurasi dan dideploy di alamat HTTPS publik, atur alamat tersebut sebagai Callback URL di Cams Gateway. Sejak saat itu, setiap pemindaian yang terverifikasi akan sampai ke receiver Anda secara real time.
06 · Uji Sebelum Menghubungkan Perangkat
Menguji Receiver Anda
Anda tidak memerlukan perangkat biometrik untuk menguji receiver callback. Kirimkan sendiri payload contoh dengan cURL, menggunakan token callback yang sesuai, lalu periksa responsnya.
|
Terminal, kirim callback uji # Simpan payload contoh sebagai sample.json, lalu kirim ke receiver Anda:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Respons yang diharapkan (HTTP 200):
# {"status":"done"}
|
| Uji | Yang dikirim | Hasil yang diharapkan |
|---|---|---|
| Event valid | sample.json, dengan AuthToken diatur ke auth_token Anda | HTTP 200 dengan done, dan data absensi tersimpan |
| Event duplikat | Permintaan yang sama untuk kedua kalinya | HTTP 200 dengan done, dan tidak ada catatan kedua yang tersimpan |
| Token salah | sample.json dengan AuthToken yang berbeda | Ditolak, dan tidak ada yang tersimpan |
| Event check-in | sample.json dengan Type diubah menjadi CheckIn | Tersimpan sebagai check-in |
| Operasi RESTful | Gunakan antarmuka pengujian HTML bawaan untuk mengirim operasi | Respons dengan Status dan StatusCode |
Antarmuka pengujian HTML yang dihasilkan memudahkan Anda mencoba sisi RESTful: buka file di browser, pilih operasi dari dropdown, sesuaikan JSON yang sudah terisi, lalu kirim. Penampil callback terbaru di halaman yang sama mengonfirmasi bahwa callback uji Anda telah diterima.
07 · Daftar Periksa Produksi
Tinjau Sebelum Digunakan Secara Langsung
Kode yang dihasilkan AI adalah titik awal yang cepat dan andal, tetapi seperti kode apa pun, kode tersebut sebaiknya ditinjau sebelum menangani data karyawan yang sebenarnya.
| Item | Selesai ketika |
|---|---|
| Kode telah ditinjau | Developer telah membaca file yang dihasilkan dan memahami fungsi setiap bagian |
| Hanya HTTPS | Receiver hanya dapat diakses melalui HTTPS dengan sertifikat yang valid |
| Token terlindungi | AuthToken disimpan di environment variable atau secrets manager |
| Duplikat ditangani | OperationID disimpan dan diperiksa sehingga pengiriman berulang diabaikan |
| Penyimpanan sesuai | Penyimpanan file JSON cukup untuk pengaturan kecil; penerapan yang lebih besar dapat beralih ke database produksi |
| Antarmuka pengujian terlindungi | Halaman pengujian HTML dilindungi kata sandi atau dinonaktifkan di server publik |
| Foto ditangani dengan hati-hati | Foto kehadiran yang disimpan di disk dikontrol aksesnya dan hanya disimpan selama diperlukan |
| Pemantauan tersedia | Error dan volume callback yang tidak biasa dicatat dan diberi peringatan oleh sistem pemantauan Anda sendiri |
|
Simpan aturan bisnis di tempat lain Tugas receiver adalah menerima, memverifikasi, mengarahkan, menyimpan, dan mengonfirmasi. Menentukan siapa yang terlambat, menghitung lembur, atau mengirim pemberitahuan menjadi tanggung jawab sistem yang membaca event yang tersimpan, seperti HRMS, ERP, atau alat otomasi Anda. Receiver yang terfokus lebih mudah diamankan dan dipelihara. |
Pertanyaan yang Sering Diajukan
|
Apakah saya perlu menulis kode sendiri? Biasanya tidak. AI Code Generator Prompts menghasilkan file lengkap yang berfungsi. Anda mengatur tiga nilai konfigurasi, men-deploy, dan menguji. Developer tetap sebaiknya meninjau kode sebelum digunakan secara langsung. |
|
Asisten AI mana yang dapat digunakan dengan prompt? Asisten coding AI apa pun yang mumpuni, termasuk Claude, ChatGPT, dan Copilot. Tempel seluruh isi prompt sekaligus agar asisten memiliki spesifikasi lengkap. |
|
Di mana saya menemukan URL endpoint RESTful dan Service Tag ID? Keduanya berasal dari akun Cams API Monitor Anda. Permintaan RESTful dikirim ke URL endpoint dengan ?stgid= diikuti oleh Service Tag ID Anda. |
|
Mengapa membalas dengan done untuk event duplikat? Karena event tersebut memang telah diterima dengan aman, meskipun Anda sudah menyimpannya sebelumnya. Membalas dengan done memberi tahu Gateway bahwa event tidak perlu dikirim ulang. |
|
Bisakah saya menggunakan bahasa yang tidak tercantum? Bisa. Receiver callback hanya perlu menerima HTTPS POST dan mengembalikan JSON. Prompt adalah jalan pintas, dan API yang sama dapat digunakan dengan bahasa apa pun yang mampu melakukan hal tersebut. |
Kesimpulan: Dari Prompt ke Absensi Real-Time dalam Sehari
Receiver callback biometrik memang kecil, tetapi ia adalah bagian yang mengubah setiap pemindaian yang terverifikasi menjadi data langsung untuk HRMS, penggajian, dasbor, dan otomasi Anda. Dengan Cams AI Code Generator Prompts, Anda tidak perlu membangunnya dari nol. Unduh prompt untuk Python, Node.js, atau PHP, tempel ke asisten AI Anda, atur tiga nilai, dan uji. Setelah itu, tinjau, amankan, dan biarkan data absensi real-time mulai mengalir.
Cams Biometrics Gateway menyediakan event yang dibutuhkan receiver Anda. Callback API-nya mengirimkan setiap pemindaian yang terverifikasi secara real time, dalam satu format JSON yang konsisten, dari perangkat lebih dari 15 merek, dan RESTful API-nya menawarkan 27 operasi yang dapat dipanggil oleh client yang Anda hasilkan. Seluruh komunikasi berjalan melalui HTTP/HTTPS dengan validasi auth token dan enkripsi AES-256 opsional. Jelajahi platform di CamsBiometrics.com dan baca dokumentasi Web API lengkap, termasuk setiap AI Code Generator Prompt: Dapatkan Prompt.