Support Hub/API & Integrations/Membangun Receiver Callback Biometrik dengan Python,…
Translated from the English article and reviewed by a person. Read the English original
Developer

Membangun Receiver Callback Biometrik dengan Python, Node.js, dan PHP

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.

1

Unduh file prompt

Pilih bahasa Anda di bagian berikutnya dan unduh file prompt .txt-nya.

2

Tempel ke asisten AI

Buka Claude, ChatGPT, Copilot, atau alat coding AI apa pun, lalu tempel seluruh isi prompt.

3

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.

Python

Flask, SQLite, hanya standard library

Dapatkan prompt Python

Node.js

Express, penyimpanan file JSON

Dapatkan prompt Node.js

PHP

PHP murni, SQLite, tanpa Composer

Unduh prompt PHP

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.

 

Was this article helpful?