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.

API Referansı

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

API Referansı

Ortak Alanlar

Tüm istekler — hem Callback hem RESTful — bu üst düzey alanları paylaşır.

AuthTokenString. Belirli bir cihazdan gelen istekleri tanımlayan ve doğrulayan 32 karakterlik bir token. API Monitor portalında yapılandırılır. Gelen her callback'te doğrulayın.

OperationIDString. Bu işlem örneği için benzersiz bir tanımlayıcı (örn. "j95xfejt3vr1"). RESTful yanıtlar aynı OperationID'yi geri döndürür; böylece istekleri yanıtlarla eşleştirebilirsiniz.

TimeString. Olayın işlendiği zamanın UTC zaman damgası, YYYY-MM-DD HH:mm:ss GMT +0000 biçiminde. Payload içindeki cihaz yerel zaman damgaları farklı bir saat dilimi farkı kullanabilir.

stgid (sorgu parametresi)String. Service Tag ID — RESTful API çağrıları için hedef cihazı tanımlar. API Monitor hesabınızda bulunan uç noktaya URL sorgu parametresi olarak iletin: 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:

Şablon Birleştirme Davranışı — Callback İşleyicileri İçin Önemli
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üncelleyin
Bir 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`

API Referansı

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.

Ek Bilgiler

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.

HTTPS önerilir. Üretimde geçerli bir SSL sertifikasıyla HTTPS kullanın. Sunucuyu yeniden başlatmadan otomatik yenilemeyi sağlayın.

Ek Bilgiler

Ö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:

Bu sayfaYukarıdaki her işlem bölümü, örnek verili ve kopyalamaya hazır istek ve yanıt JSON'u içerir.

Eski örnek sayfasıbiometric-web-api-sample-request-response.html — her işlem için açılır liste seçici.

Ek Bilgiler

Ş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.

AlgoritmaECB modunda ve PKCS5 dolgusuyla AES-256 (AES/ECB/PKCS5PADDING).

Anahtar yapılandırmasıAnahtarınızı API Monitor'da Güvenlik Anahtarı olarak ayarlayın. Yapılandırıldığında tüm ham JSON payload'ları şifrelenir.

KodlamaŞifreli payload'lar güvenli HTTP aktarımı için Base64 kodludur.

Java Örneği

Şifrele / Çöz (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");

Önemli: Şifreleme etkinleştirildiğinde, gelen Callback payload'larının şifresini çözün ve giden RESTful istek gövdelerini aynı anahtarla şifreleyin.