Referensi API: arsitektur, field, dan kode status
Komponen dasar yang dipakai semua operasi: alur permintaan, field JSON umum, jenis template, kode status, port, dan enkripsi payload.
Jawaban cepat
Apa dua alur API itu?
API Callback mengirim peristiwa dari perangkat (melalui Cams Biometric Gateway) ke server Anda secara real-time. API RESTful memungkinkan server Anda mengirim perintah ke perangkat, dan responsnya tiba dalam sekitar 15 detik. Jika server Anda offline, engine menyimpan callback dalam cache; perintah REST diantrekan sampai perangkat terhubung kembali.
Kode status apa saja yang dikembalikan API RESTful?
Sebuah StatusCode numerik: 0 berhasil, 1 data permintaan tidak valid, 2 Service Tag ID tidak valid, 3 permintaan tidak valid, 4 enkripsi tidak valid, 5 perangkat offline, 6 operasi timeout, 7 auth token tidak valid, 8 pengguna sudah ada, 9 pengguna tidak ditemukan, 10 kesalahan template, 11 memori perangkat penuh, 13 kunci keamanan tidak valid, 15 fitur tidak didukung, 999 kesalahan tidak diketahui. Respons callback selalu menggunakan {"status":"done"}.
Apa arti kode status 5 (Perangkat Offline)?
Perangkat tujuan saat ini tidak terhubung ke Biometric Gateway. Lihat kode status 5.
Bagaimana cara mengautentikasi permintaan?
Setiap permintaan membawa AuthToken, token 32 karakter yang mengidentifikasi satu perangkat dan diatur di portal API Monitor. Validasi token ini pada setiap callback masuk. Panggilan REST juga menyertakan perangkat sebagai parameter query stgid (Service Tag ID). Lihat Field Umum.
Port apa yang dibutuhkan server saya?
Port 80 (HTTP) atau 443 (HTTPS) untuk produksi; HTTPS dengan sertifikat yang valid disarankan. Port 8123 (HTTP) hanya untuk pengujian. Lihat Port yang Didukung.
Bagaimana payload dienkripsi?
Enkripsi bersifat opsional. Jika diaktifkan, payload menggunakan AES-256 dalam mode ECB dengan padding PKCS5 (AES/ECB/PKCS5PADDING), dengan kunci berupa Security Key yang diatur di API Monitor, dan di-encode Base64 untuk transpor HTTP. Dekripsi callback masuk dan enkripsi body REST keluar dengan kunci yang sama. Lihat Enkripsi.
Bagaimana menangani template yang tiba melalui beberapa callback?
Gabungkan. Setiap callback hanya membawa template yang ditambahkan atau diubah. Kunci unik sebuah template adalah Type + Index, jadi lakukan upsert berdasarkan pasangan tersebut dan jangan pernah mengganti seluruh set template pengguna. Lihat Jenis Template.
Jenis template apa saja yang ada?
Card, Password, Fingerprint, Face, Palm, dan UserPhoto. Template Fingerprint, Face, dan Palm di-encode Base64, dan indeks sidik jari berkisar 0–9.
Arsitektur API
| Properti | API Callback | API RESTful |
|---|---|---|
| Pemrakarsa | Perangkat / Biometric Gateway | Server Anda |
| Arah | Perangkat → Server Anda | Server Anda → Perangkat |
| Latensi | Real-time (milidetik) | ~15 detik |
| Pemicu | Peristiwa biometrik di perangkat | HTTP POST dari kode Anda |
| Peran Anda | Menerima & mengonfirmasi | Mengirim perintah & polling/menunggu respons |
| Body respons | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| Perilaku offline | Di-cache oleh mesin; dikirim saat server kembali online | Diantrekan oleh mesin; dikirim saat perangkat tersambung kembali |
Field Umum
Semua permintaan — baik Callback maupun RESTful — memakai field tingkat atas berikut.
"j95xfejt3vr1"). Respons RESTful mengembalikan OperationID yang sama sehingga Anda dapat mencocokkan permintaan dengan respons.YYYY-MM-DD HH:mm:ss GMT +0000. Stempel waktu lokal perangkat di dalam payload dapat memakai offset zona waktu yang berbeda.POST https://<your-endpoint>?stgid=YOUR_TAG_ID.Jenis Template
Data biometrik dan kredensial dibawa dalam array Template. Setiap item memiliki field Type:
Saat data pengguna di-push dari perangkat (operasi Callback #3–#9), template dapat tiba satu per satu atau berkelompok, melalui beberapa callback. Setiap callback tidak berisi seluruh set template pengguna — hanya template yang ditambahkan atau diubah.
Server Anda harus menggabungkan template yang masuk dengan template yang sudah tersimpan untuk pengguna tersebut. Kunci unik setiap template adalah
Type + Index. Contoh:• Callback 1 tiba dengan
Fingerprint Index 0 → simpan• Callback 2 tiba dengan
Face Index 0 + Card → gabungkan, jangan timpa sidik jari• Callback 3 tiba dengan
Fingerprint Index 0 (data baru) → perbarui sidik jari yang ada di Index 0Jangan pernah mengganti semua template pada sebuah callback — selalu lakukan upsert berdasarkan
Type + Index.
| Tipe | Deskripsi | Field tambahan utama |
|---|---|---|
Card | Nomor kartu RFID / proximity | Data (string nomor kartu) |
Password | PIN numerik | Data (string PIN) |
Fingerprint | Template sidik jari — biner berenkode Base64 | Index (indeks jari 0–9), Size, Data |
Face | Template wajah — JPEG atau biner berenkode Base64 | Index, Size, Data |
Palm | Template vena telapak tangan — biner berenkode Base64 | Index, Data |
UserPhoto | Foto profil pengguna — JPEG berenkode Base64 | Data |
Kode Status Respons
Respons API RESTful menyertakan StatusCode numerik. Respons API Callback selalu memakai bentuk sederhana {"status":"done"} apa pun hasilnya.
| Kode | Status | Deskripsi |
|---|---|---|
0 | Berhasil | Operasi berhasil diselesaikan. |
1 | Data Permintaan Tidak Valid | Body JSON salah format atau berisi nilai yang tidak valid. |
2 | Service Tag ID Tidak Valid | Query parameter stgid tidak cocok dengan perangkat terdaftar mana pun. |
3 | Permintaan Tidak Valid | Struktur permintaan tidak sesuai dengan format operasi yang diharapkan. |
4 | Enkripsi Tidak Valid | Enkripsi payload (AES-256) tidak dapat didekripsi. Periksa kunci enkripsi Anda. |
5 | Perangkat Offline | Perangkat tujuan saat ini tidak terhubung ke Biometric Gateway. |
6 | Operasi Timeout | Perangkat tidak mengonfirmasi perintah dalam batas waktu. |
7 | Auth Token Tidak Valid | AuthToken dalam permintaan tidak cocok dengan token yang dikonfigurasi pada perangkat. |
8 | Pengguna Sudah Ada | Operasi Add dicoba untuk UserID yang sudah ada di perangkat. |
9 | Pengguna Tidak Ditemukan | UserID yang ditentukan tidak ada di perangkat. |
10 | Kesalahan Template | Data template biometrik rusak atau dalam format yang tidak didukung. |
11 | Memori Perangkat Penuh | Perangkat telah mencapai kapasitas maksimum pengguna atau template. |
13 | Kunci Keamanan Tidak Valid | Kunci keamanan yang dikonfigurasi di API Monitor tidak cocok. |
15 | Fitur Tidak Didukung | Operasi yang diminta tidak didukung oleh model perangkat atau mode komunikasi ini. |
999 | Kesalahan Tidak Dikenal | Terjadi kesalahan yang tidak terduga. Hubungi dukungan Cams dengan menyertakan OperationID. |
Port yang Didukung
Untuk menerima informasi absensi real-time, server Anda harus menyediakan endpoint HTTP(S) yang dapat dijangkau oleh Cams Protocol Engine.
| Port | Protokol | Penggunaan |
|---|---|---|
80 | HTTP | Produksi. Ikatkan callback URL Anda ke port 80. Dikonfigurasi di API Monitor dan dipanggil otomatis saat absensi. |
443 | HTTPS | Produksi (aman). HTTPS dengan sertifikat SSL yang valid. Disarankan untuk produksi. |
8123 | HTTP | Hanya untuk pengujian. Port non-standar yang tersedia sementara selama pengembangan. |
Data Contoh
Contoh payload permintaan dan respons untuk semua 38 operasi didokumentasikan di atas pada setiap bagian operasi. Untuk tampilan gabungan:
Enkripsi
Enkripsi AES-256 opsional dapat diaktifkan untuk semua data yang dipertukarkan antara Cams Protocol Engine dan server Anda.
AES/ECB/PKCS5PADDING).Contoh Java
// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));
// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");