API-Referenz: Architektur, Felder und Statuscodes
Die Bausteine, die alle Operationen gemeinsam haben: Anfrageablauf, allgemeine JSON-Felder, Template-Typen, Statuscodes, Ports und Payload-Verschlüsselung.
Schnelle Antworten
Welche zwei API-Abläufe gibt es?
Die Callback-API sendet Ereignisse vom Gerät (über das Cams Biometric Gateway) in Echtzeit an Ihren Server. Die RESTful-API ermöglicht es Ihrem Server, Befehle an ein Gerät zu senden; die Antwort trifft nach etwa 15 Sekunden ein. Ist Ihr Server offline, puffert die Engine die Callbacks; REST-Befehle werden in eine Warteschlange gestellt, bis das Gerät wieder verbunden ist.
Welche Statuscodes gibt die RESTful-API zurück?
Ein numerischer StatusCode: 0 Erfolg, 1 ungültige Anfragedaten, 2 ungültige Service Tag ID, 3 ungültige Anfrage, 4 ungültige Verschlüsselung, 5 Gerät offline, 6 Zeitüberschreitung der Operation, 7 ungültiges Auth-Token, 8 Benutzer existiert bereits, 9 Benutzer nicht gefunden, 10 Template-Fehler, 11 Gerätespeicher voll, 13 ungültiger Sicherheitsschlüssel, 15 Funktion nicht unterstützt, 999 unbekannter Fehler. Callback-Antworten verwenden immer {"status":"done"}.
Was bedeutet Statuscode 5 (Gerät offline)?
Das Zielgerät ist derzeit nicht mit dem Biometric Gateway verbunden. Siehe Statuscode 5.
Wie authentifiziere ich Anfragen?
Jede Anfrage enthält einen AuthToken, ein 32-stelliges Token, das ein Gerät identifiziert und im API-Monitor-Portal festgelegt wird. Prüfen Sie es bei jedem eingehenden Callback. REST-Aufrufe übergeben das Gerät außerdem als Abfrageparameter stgid (Service Tag ID). Siehe Allgemeine Felder.
Welche Ports benötigt mein Server?
Port 80 (HTTP) oder 443 (HTTPS) für den Produktivbetrieb; empfohlen wird HTTPS mit einem gültigen Zertifikat. Port 8123 (HTTP) dient nur zum Testen. Siehe Unterstützte Ports.
Wie wird der Payload verschlüsselt?
Die Verschlüsselung ist optional. Wenn aktiviert, verwenden Payloads AES-256 im ECB-Modus mit PKCS5-Padding (AES/ECB/PKCS5PADDING), mit dem im API Monitor festgelegten Sicherheitsschlüssel, und werden für den HTTP-Transport Base64-kodiert. Entschlüsseln Sie eingehende Callbacks und verschlüsseln Sie ausgehende REST-Bodys mit demselben Schlüssel. Siehe Verschlüsselung.
Wie gehe ich mit Templates um, die über mehrere Callbacks eintreffen?
Führen Sie sie zusammen. Jeder Callback enthält nur die hinzugefügten oder geänderten Templates. Der eindeutige Schlüssel eines Templates ist Type + Index; führen Sie daher ein Upsert über dieses Paar durch und ersetzen Sie nie den gesamten Template-Satz eines Benutzers. Siehe Template-Typen.
Welche Template-Typen gibt es?
Card, Password, Fingerprint, Face, Palm und UserPhoto. Fingerprint-, Face- und Palm-Templates sind Base64-kodiert, und der Fingerabdruck-Index reicht von 0–9.
API-Architektur
| Eigenschaft | Callback-API | RESTful-API |
|---|---|---|
| Initiator | Gerät / Biometric Gateway | Ihr Server |
| Richtung | Gerät → Ihr Server | Ihr Server → Gerät |
| Latenz | Echtzeit (Millisekunden) | ~15 Sekunden |
| Auslöser | Biometrisches Ereignis am Gerät | HTTP-POST aus Ihrem Code |
| Ihre Rolle | Empfangen & bestätigen | Befehl senden & auf Antwort warten bzw. abfragen |
| Response-Body | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| Offline-Verhalten | Wird von der Engine zwischengespeichert; zugestellt, sobald der Server wieder online ist | Wird von der Engine in die Warteschlange gestellt; zugestellt, sobald sich das Gerät wieder verbindet |
Allgemeine Felder
Alle Anfragen — sowohl Callback als auch RESTful — haben diese übergeordneten Felder gemeinsam.
"j95xfejt3vr1"). RESTful-Antworten geben dieselbe OperationID zurück, sodass Sie Anfragen und Antworten zuordnen können.YYYY-MM-DD HH:mm:ss GMT +0000. Geräte-lokale Zeitstempel innerhalb des Payloads können einen anderen Zeitzonen-Offset verwenden.POST https://<your-endpoint>?stgid=YOUR_TAG_ID.Template-Typen
Biometrische Daten und Zugangsdaten werden in einem Template-Array übertragen. Jedes Element hat ein Type-Feld:
Wenn Benutzerdaten vom Gerät gesendet werden (Callback-Operationen #3–#9), können Templates einzeln oder in Gruppen über mehrere Callbacks verteilt eintreffen. Ein Callback enthält nicht den vollständigen Template-Satz des Benutzers — er enthält nur die hinzugefügten oder geänderten Templates.
Ihr Server muss eingehende Templates mit den bereits gespeicherten Templates dieses Benutzers zusammenführen. Der eindeutige Schlüssel jedes Templates ist
Type + Index. Beispiel:• Callback 1 trifft mit
Fingerprint Index 0 ein → speichern• Callback 2 trifft mit
Face Index 0 + Card ein → zusammenführen, den Fingerabdruck nicht überschreiben• Callback 3 trifft mit
Fingerprint Index 0 (neue Daten) ein → vorhandenen Fingerabdruck bei Index 0 aktualisierenErsetzen Sie bei einem Callback niemals alle Templates — führen Sie immer ein Upsert über
Type + Index durch.
| Typ | Beschreibung | Wichtige Zusatzfelder |
|---|---|---|
Card | RFID-/Proximity-Kartennummer | Data (Kartennummer als String) |
Password | Numerische PIN | Data (PIN als String) |
Fingerprint | Fingerabdruck-Template — Base64-codierte Binärdaten | Index (Fingerindex 0–9), Size, Data |
Face | Gesichts-Template — Base64-codiertes JPEG oder Binärdaten | Index, Size, Data |
Palm | Handvenen-Template — Base64-codierte Binärdaten | Index, Data |
UserPhoto | Benutzerprofilfoto — Base64-codiertes JPEG | Data |
Antwortstatuscodes
RESTful-API-Antworten enthalten einen numerischen StatusCode. Callback-API-Antworten verwenden unabhängig vom Ergebnis immer die einfache Form {"status":"done"}.
| Code | Status | Beschreibung |
|---|---|---|
0 | Erfolg | Der Vorgang wurde erfolgreich abgeschlossen. |
1 | Ungültige Anfragedaten | Der JSON-Body ist fehlerhaft oder enthält ungültige Werte. |
2 | Ungültige Service Tag ID | Der Query-Parameter stgid stimmt mit keinem registrierten Gerät überein. |
3 | Ungültige Anfrage | Die Anfragestruktur entspricht nicht dem erwarteten Operationsformat. |
4 | Ungültige Verschlüsselung | Der Payload (AES-256-verschlüsselt) konnte nicht entschlüsselt werden. Prüfen Sie Ihren Verschlüsselungsschlüssel. |
5 | Gerät offline | Das Zielgerät ist derzeit nicht mit dem Biometric Gateway verbunden. |
6 | Zeitüberschreitung der Operation | Das Gerät hat den Befehl nicht innerhalb des Zeitfensters bestätigt. |
7 | Ungültiges Auth-Token | Der AuthToken in der Anfrage stimmt nicht mit dem für das Gerät konfigurierten Token überein. |
8 | Benutzer existiert bereits | Es wurde versucht, per Add-Operation eine UserID anzulegen, die auf dem Gerät bereits vorhanden ist. |
9 | Benutzer nicht gefunden | Die angegebene UserID existiert auf dem Gerät nicht. |
10 | Template-Fehler | Die biometrischen Template-Daten sind beschädigt oder liegen in einem nicht unterstützten Format vor. |
11 | Gerätespeicher voll | Das Gerät hat seine maximale Benutzer- oder Template-Kapazität erreicht. |
13 | Ungültiger Sicherheitsschlüssel | Der im API Monitor konfigurierte Sicherheitsschlüssel stimmt nicht überein. |
15 | Funktion nicht unterstützt | Die angeforderte Operation wird von diesem Gerätemodell oder Kommunikationsmodus nicht unterstützt. |
999 | Unbekannter Fehler | Es ist ein unerwarteter Fehler aufgetreten. Wenden Sie sich unter Angabe der OperationID an den Cams-Support. |
Unterstützte Ports
Um Anwesenheitsinformationen in Echtzeit zu empfangen, muss Ihr Server einen HTTP(S)-Endpunkt bereitstellen, den die Cams Protocol Engine erreichen kann.
| Port | Protokoll | Verwendung |
|---|---|---|
80 | HTTP | Produktion. Binden Sie Ihre Callback-URL an Port 80. Wird im API Monitor konfiguriert und bei Buchungen automatisch aufgerufen. |
443 | HTTPS | Produktion (sicher). HTTPS mit gültigem SSL-Zertifikat. Für den Produktivbetrieb empfohlen. |
8123 | HTTP | Nur zum Testen. Nicht standardmäßiger Port, der während der Entwicklung vorübergehend verfügbar ist. |
Beispieldaten
Beispiel-Requests und -Responses für alle 38 Operationen sind oben in den jeweiligen Operationsabschnitten dokumentiert. Für eine zusammengefasste Ansicht:
Verschlüsselung
Optional kann die AES-256-Verschlüsselung für den gesamten Datenaustausch zwischen der Cams Protocol Engine und Ihrem Server aktiviert werden.
AES/ECB/PKCS5PADDING).Java-Beispiel
// 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");