API referansı: mimari, alanlar ve durum kodları
Her işlemde ortak olan yapı taşları: istek akışı, ortak JSON alanları, şablon türleri, durum kodları, portlar ve payload şifreleme.
Hızlı yanıtlar
İki API akışı nedir?
Callback API, olayları cihazdan (Cams Biometric Gateway üzerinden) sunucunuza gerçek zamanlı olarak gönderir. RESTful API ise sunucunuzun cihaza komut göndermesini sağlar ve yanıt yaklaşık 15 saniye içinde gelir. Sunucunuz çevrimdışıysa motor callback'leri önbelleğe alır; REST komutları cihaz yeniden bağlanana kadar kuyruğa alınır.
RESTful API hangi durum kodlarını döndürür?
Sayısal bir StatusCode: 0 başarılı, 1 geçersiz istek verisi, 2 geçersiz Service Tag ID, 3 geçersiz istek, 4 geçersiz şifreleme, 5 cihaz çevrimdışı, 6 işlem zaman aşımı, 7 geçersiz auth token, 8 kullanıcı zaten mevcut, 9 kullanıcı bulunamadı, 10 şablon hatası, 11 cihaz belleği dolu, 13 geçersiz güvenlik anahtarı, 15 özellik desteklenmiyor, 999 bilinmeyen hata. Callback yanıtları her zaman {"status":"done"} kullanır.
Durum kodu 5 (Cihaz Çevrimdışı) ne anlama gelir?
Hedef cihaz şu anda Biometric Gateway'e bağlı değil. Bkz. durum kodu 5.
İstekleri nasıl doğrularım?
Her istek, tek bir cihazı tanımlayan ve API Monitor portalında ayarlanan 32 karakterlik bir AuthToken taşır. Gelen her callback'te bunu doğrulayın. REST çağrıları ayrıca cihazı stgid (Service Tag ID) sorgu parametresi olarak iletir. Bkz. Ortak Alanlar.
Sunucumun hangi portlara ihtiyacı var?
Üretim için 80 (HTTP) veya 443 (HTTPS) portu; geçerli sertifikalı HTTPS önerilir. 8123 (HTTP) portu yalnızca test içindir. Bkz. Desteklenen Portlar.
Yük nasıl şifrelenir?
Şifreleme isteğe bağlıdır. Etkinleştirildiğinde yükler, API Monitor'de belirlenen Security Key ile PKCS5 dolgulu ECB modunda AES-256 (AES/ECB/PKCS5PADDING) kullanır ve HTTP aktarımı için Base64 ile kodlanır. Gelen callback'leri çözmek ve giden REST gövdelerini şifrelemek için aynı anahtarı kullanın. Bkz. Şifreleme.
Birkaç callback ile gelen şablonları nasıl işlerim?
Birleştirin. Her callback yalnızca eklenen veya değiştirilen şablonları taşır. Bir şablonun benzersiz anahtarı Type + Index çiftidir; bu çifte göre upsert yapın ve bir kullanıcının tüm şablon kümesini asla değiştirmeyin. Bkz. Şablon Türleri.
Hangi şablon türleri var?
Card, Password, Fingerprint, Face, Palm ve UserPhoto. Fingerprint, Face ve Palm şablonları Base64 ile kodlanır ve parmak izi indeksi 0–9 aralığındadır.
API Mimarisi
| Özellik | Callback API | RESTful API |
|---|---|---|
| Başlatan | Cihaz / Biometric Gateway | Sunucunuz |
| Yön | Cihaz → Sunucunuz | Sunucunuz → Cihaz |
| Gecikme | Gerçek zamanlı (milisaniye) | ~15 saniye |
| Tetikleyici | Cihazda biyometrik olay | Kodunuzdan HTTP POST |
| Rolünüz | Al ve onayla | Komut gönder ve yanıtı sorgula/bekle |
| Yanıt gövdesi | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| Çevrimdışı davranış | Motor tarafından önbelleğe alınır; sunucu tekrar çevrimiçi olduğunda iletilir | Motor tarafından kuyruğa alınır; cihaz yeniden bağlandığında iletilir |
Ortak Alanlar
Tüm istekler — hem Callback hem RESTful — bu üst düzey alanları paylaşır.
"j95xfejt3vr1"). RESTful yanıtlar aynı OperationID'yi geri döndürür; böylece istekleri yanıtlarla eşleştirebilirsiniz.YYYY-MM-DD HH:mm:ss GMT +0000 biçiminde. Payload içindeki cihaz yerel zaman damgaları farklı bir saat dilimi farkı kullanabilir.POST https://<your-endpoint>?stgid=YOUR_TAG_ID.Şablon Türleri
Biyometrik ve kimlik bilgisi verileri bir Template dizisinde taşınır. Her öğede bir Type alanı bulunur:
Kullanıcı verisi cihazdan push edildiğinde (Callback işlemleri #3–#9), şablonlar birden fazla callback boyunca tek tek veya gruplar halinde gelebilir. Her callback kullanıcının tüm şablon setini içermez — yalnızca eklenen veya değişen şablonları taşır.
Sunucunuz gelen şablonları o kullanıcı için saklanan mevcut şablonlarla birleştirmelidir. Her şablon için benzersiz anahtar
Type + Index'tir. Örneğin:• Callback 1,
Fingerprint Index 0 ile gelir → saklayın• Callback 2,
Face Index 0 + Card ile gelir → birleştirin, parmak izini ezmeyin• Callback 3,
Fingerprint Index 0 (yeni veri) ile gelir → Index 0'daki mevcut parmak izini güncelleyinBir callback'te asla tüm şablonları değiştirmeyin — her zaman
Type + Index ile upsert yapın.
| Tür | Açıklama | Temel ek alanlar |
|---|---|---|
Card | RFID / yakınlık kartı numarası | Data (kart numarası string'i) |
Password | Sayısal PIN | Data (PIN string'i) |
Fingerprint | Parmak izi şablonu — Base64 kodlu ikili veri | Index (parmak indeksi 0–9), Size, Data |
Face | Yüz şablonu — Base64 kodlu JPEG veya ikili veri | Index, Size, Data |
Palm | Avuç içi damar şablonu — Base64 kodlu ikili veri | Index, Data |
UserPhoto | Kullanıcı profil fotoğrafı — Base64 kodlu JPEG | Data |
Yanıt Durum Kodları
RESTful API yanıtları sayısal bir StatusCode içerir. Callback API yanıtları, sonuçtan bağımsız olarak her zaman basit {"status":"done"} biçimini kullanır.
| Kod | Durum | Açıklama |
|---|---|---|
0 | Başarılı | İşlem başarıyla tamamlandı. |
1 | Geçersiz İstek Verisi | JSON gövdesi hatalı biçimlendirilmiş veya geçersiz değerler içeriyor. |
2 | Geçersiz Service Tag ID | stgid sorgu parametresi kayıtlı hiçbir cihazla eşleşmiyor. |
3 | Geçersiz İstek | İstek yapısı beklenen işlem biçimiyle eşleşmiyor. |
4 | Geçersiz Şifreleme | Payload şifrelemesi (AES-256) çözülemedi. Şifreleme anahtarınızı kontrol edin. |
5 | Cihaz Çevrimdışı | Hedef cihaz şu anda Biometric Gateway'e bağlı değil. |
6 | İşlem Zaman Aşımı | Cihaz, komutu zaman aşımı süresi içinde onaylamadı. |
7 | Geçersiz Auth Token | İsteği içindeki AuthToken, cihazın yapılandırılmış token'ıyla eşleşmiyor. |
8 | Kullanıcı Zaten Mevcut | Cihazda zaten var olan bir UserID için Ekleme işlemi denendi. |
9 | Kullanıcı Bulunamadı | Belirtilen UserID cihazda mevcut değil. |
10 | Şablon Hatası | Biyometrik şablon verisi bozuk veya desteklenmeyen bir biçimde. |
11 | Cihaz Belleği Dolu | Cihaz, azami kullanıcı veya şablon kapasitesine ulaştı. |
13 | Geçersiz Güvenlik Anahtarı | API Monitor'da yapılandırılan güvenlik anahtarı eşleşmiyor. |
15 | Özellik Desteklenmiyor | İstenen işlem bu cihaz modeli veya iletişim modu tarafından desteklenmiyor. |
999 | Bilinmeyen Hata | Beklenmeyen bir hata oluştu. OperationID ile birlikte Cams destek ekibiyle iletişime geçin. |
Desteklenen Portlar
Gerçek zamanlı devam bilgisini alabilmek için sunucunuzun, Cams Protocol Engine'in ulaşabileceği bir HTTP(S) uç noktası sunması gerekir.
| Port | Protokol | Kullanım |
|---|---|---|
80 | HTTP | Üretim. Callback URL'nizi 80 numaralı porta bağlayın. API Monitor'da yapılandırılır ve okutmalarda otomatik çağrılır. |
443 | HTTPS | Üretim (güvenli). Geçerli SSL sertifikalı HTTPS. Üretim için önerilir. |
8123 | HTTP | Yalnızca test. Geliştirme sırasında geçici olarak kullanılabilen standart dışı port. |
Örnek Veriler
38 işlemin tamamı için örnek istek ve yanıt payload'ları yukarıda her işlem bölümünde belgelenmiştir. Birleşik görünüm için:
Şifreleme
Cams Protocol Engine ile sunucunuz arasında değiştirilen tüm veriler için isteğe bağlı AES-256 şifreleme etkinleştirilebilir.
AES/ECB/PKCS5PADDING).Java Örneği
// 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");