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.

Referensi API

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

Referensi API

Field Umum

Semua permintaan — baik Callback maupun RESTful — memakai field tingkat atas berikut.

AuthTokenString. Token 32 karakter yang mengidentifikasi dan mengautentikasi permintaan dari perangkat tertentu. Dikonfigurasi di portal API Monitor. Validasi pada setiap callback masuk.

OperationIDString. Pengenal unik untuk instans operasi ini (mis. "j95xfejt3vr1"). Respons RESTful mengembalikan OperationID yang sama sehingga Anda dapat mencocokkan permintaan dengan respons.

TimeString. Stempel waktu UTC saat peristiwa diproses, dalam format YYYY-MM-DD HH:mm:ss GMT +0000. Stempel waktu lokal perangkat di dalam payload dapat memakai offset zona waktu yang berbeda.

stgid (query param)String. Service Tag ID — mengidentifikasi perangkat tujuan untuk panggilan API RESTful. Kirim sebagai query parameter URL ke endpoint yang ada di akun API Monitor Anda: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

Jenis Template

Data biometrik dan kredensial dibawa dalam array Template. Setiap item memiliki field Type:

Perilaku Penggabungan Template — Penting bagi Handler Callback
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 0
Jangan 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`

Referensi API

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.

Informasi Tambahan

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.

HTTPS disarankan. Gunakan HTTPS dengan sertifikat SSL yang valid untuk produksi. Pastikan pembaruan otomatis tanpa restart server.

Informasi Tambahan

Data Contoh

Contoh payload permintaan dan respons untuk semua 38 operasi didokumentasikan di atas pada setiap bagian operasi. Untuk tampilan gabungan:

Halaman iniSetiap bagian operasi di atas menyertakan JSON permintaan dan respons siap salin beserta data contoh.

Halaman contoh lamabiometric-web-api-sample-request-response.html — pemilih dropdown untuk setiap operasi.

Informasi Tambahan

Enkripsi

Enkripsi AES-256 opsional dapat diaktifkan untuk semua data yang dipertukarkan antara Cams Protocol Engine dan server Anda.

AlgoritmaAES-256 dalam mode ECB dengan padding PKCS5 (AES/ECB/PKCS5PADDING).

Konfigurasi kunciAtur kunci Anda sebagai Security Key di API Monitor. Setelah dikonfigurasi, semua payload JSON mentah dienkripsi.

PengodeanPayload terenkripsi dienkode Base64 agar aman untuk transportasi HTTP.

Contoh Java

Enkripsi / Dekripsi (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");

Penting: Saat enkripsi diaktifkan, dekripsi payload Callback masuk dan enkripsi body permintaan RESTful keluar menggunakan kunci yang sama.