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.

API-Referenz

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

API-Referenz

Allgemeine Felder

Alle Anfragen — sowohl Callback als auch RESTful — haben diese übergeordneten Felder gemeinsam.

AuthTokenString. Ein 32-stelliges Token, das Anfragen eines bestimmten Geräts identifiziert und authentifiziert. Wird im API-Monitor-Portal konfiguriert. Prüfen Sie es bei jedem eingehenden Callback.

OperationIDString. Eine eindeutige Kennung für diese Operationsinstanz (z. B. "j95xfejt3vr1"). RESTful-Antworten geben dieselbe OperationID zurück, sodass Sie Anfragen und Antworten zuordnen können.

TimeString. UTC-Zeitstempel der Ereignisverarbeitung im Format YYYY-MM-DD HH:mm:ss GMT +0000. Geräte-lokale Zeitstempel innerhalb des Payloads können einen anderen Zeitzonen-Offset verwenden.

stgid (Query-Parameter)String. Service Tag ID — identifiziert das Zielgerät bei RESTful-API-Aufrufen. Wird als URL-Query-Parameter an den Endpunkt aus Ihrem API Monitor-Konto übergeben: 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:

Template-Merge-Verhalten — Wichtig für Callback-Handler
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 aktualisieren
Ersetzen 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`

API-Referenz

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.

Weitere Informationen

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.

HTTPS empfohlen. Verwenden Sie im Produktivbetrieb HTTPS mit einem gültigen SSL-Zertifikat. Stellen Sie die automatische Erneuerung ohne Server-Neustart sicher.

Weitere Informationen

Beispieldaten

Beispiel-Requests und -Responses für alle 38 Operationen sind oben in den jeweiligen Operationsabschnitten dokumentiert. Für eine zusammengefasste Ansicht:

Diese SeiteJeder Operationsabschnitt oben enthält kopierfertiges Request- und Response-JSON mit Beispieldaten.

Ältere Beispielseitebiometric-web-api-sample-request-response.html — Dropdown-Auswahl für jede Operation.

Weitere Informationen

Verschlüsselung

Optional kann die AES-256-Verschlüsselung für den gesamten Datenaustausch zwischen der Cams Protocol Engine und Ihrem Server aktiviert werden.

AlgorithmusAES-256 im ECB-Modus mit PKCS5-Padding (AES/ECB/PKCS5PADDING).

SchlüsselkonfigurationLegen Sie Ihren Schlüssel als Security Key im API Monitor fest. Ist er konfiguriert, werden alle rohen JSON-Payloads verschlüsselt.

KodierungVerschlüsselte Payloads werden für den sicheren HTTP-Transport Base64-codiert.

Java-Beispiel

Verschlüsseln / Entschlüsseln (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");

Wichtig: Wenn die Verschlüsselung aktiviert ist, entschlüsseln Sie eingehende Callback-Payloads und verschlüsseln ausgehende RESTful-Request-Bodys mit demselben Schlüssel.