FAQ, SDK und Kosten

Häufige Fragen von Integratoren sowie Informationen dazu, wie SDK und API-Preise funktionieren.

Weitere Informationen

Häufig gestellte Fragen

Häufige Fragen zur Integration mit der Cams Biometrics Web API 3.0.

Allgemein

F: Was ist das Cams Biometric Gateway und seine Biometric API?
Das Cams Biometric Gateway ist eine universelle Cloud-Plattform, die eine Biometric API bereitstellt, über die jede Webanwendung in Echtzeit mit biometrischen Zeiterfassungs- und Zutrittskontrollgeräten kommunizieren kann. Es unterstützt 38 Operationen über Callback-APIs (eingehend) und RESTful-APIs (ausgehend) — ohne Geräte-SDK und ohne statische IP.
F: Benötige ich ein SDK für die Integration?
Nein. Cams stellt kein SDK bereit und verlangt auch keines. Die gesamte Kommunikation erfolgt über standardmäßige HTTP/HTTPS-POST-Requests mit JSON-Payloads. Jede Sprache, die HTTP-Aufrufe absetzen kann, funktioniert.
F: Welche Programmiersprachen werden unterstützt?
Jede Sprache, die HTTP-POST mit JSON senden und empfangen kann — PHP, Python, Java, C#, Node.js, Go, Ruby und weitere. Für 7 Sprachen stellen wir Prompts für KI-Codegeneratoren bereit.
F: Was ist die Cams Protocol Engine?
Sie ist die Cloud-Middleware zwischen den biometrischen Geräten und Ihrem Server. Sie übernimmt Protokollübersetzung, Datennormalisierung und Offline-Zwischenspeicherung und liefert unabhängig von Gerätemarke und -modell eine einheitliche JSON-API.
F: Was ist der API Monitor?
Der API Monitor ist Ihr Admin-Portal, in dem Sie Callback-URLs konfigurieren, AuthTokens verwalten, Security Keys festlegen, den Gerätestatus einsehen und auf Ihre RESTful-Endpunkt-URL und Service Tag IDs zugreifen.

Gerätekompatibilität

F: Welche biometrischen Geräte werden unterstützt?
Alle Geräte von Cams Biometrics (aufgeführt unter camsbiometrics.com/product) unterstützen mit Native Push die volle API. Auch unter developer.camsbiometrics.com verifizierte Geräte unterstützen Native Push vollständig.
F: Können Geräte, die nicht von Cams stammen (ZkTeco, eSSL, BioMax usw.), diese API nutzen?
Ja, mit einem Protocol Update. Geräte, die nicht von Cams stammen oder nicht verifiziert sind, arbeiten über Hybrid Push. Je nach Verbindungsmodus und Hardwarefunktionen können einige Funktionen eingeschränkt sein.
F: Was ist der Unterschied zwischen Native Push und Hybrid Push?
Native Push: Voller API-Umfang ohne Einschränkungen — alle 38 Operationen funktionieren. Verfügbar für Cams-Geräte und verifizierte Geräte.
Hybrid Push: Für Geräte, die nicht von Cams stammen bzw. nicht verifiziert sind. Die Funktionsverfügbarkeit hängt vom Kommunikationsmodus ab (SDK, DB Pull oder Dateiverarbeitung). Siehe Verbindungsmodi.
F: Welche biometrischen Verfahren werden unterstützt?
Fingerabdruck, Gesichtserkennung, Handvenen, RFID-/Proximity-Karte, numerische PIN/Passwort, Iris-Scan und Körpertemperaturmessung (geräteabhängig).
F: Einige API-Funktionen funktionieren mit meinem Gerät nicht. Warum?
Das hängt ab von (a) dem Verbindungsmodus — die Modi DB Pull und Dateiverarbeitung unterstützen nur den Anwesenheits-Push, keine RESTful-APIs, und (b) Hardwareeinschränkungen — manche Gerätemodelle unterstützen bestimmte Funktionen auf Firmware-Ebene nicht. Testen Sie mit Ihrer Hardware und wenden Sie sich für Unterstützung an den Cams-Support.

Callback-API (Gerät → Server)

F: Was ist die Callback-API?
Die Callback-API liefert Echtzeit-Ereignisse von biometrischen Geräten an Ihren Server. Sobald eine Buchung erfolgt oder ein Benutzer am Gerät geändert wird, sendet die Cams Protocol Engine sofort einen JSON-Payload per POST an Ihre konfigurierte Callback-URL.
F: Was muss mein Server antworten?
Geben Sie immer {"status":"done"} mit HTTP-Status 200 zurück — auch wenn Ihre interne Verarbeitung fehlschlägt. Blockieren Sie die Cams Protocol Engine niemals. Stellen Sie aufwendige Verarbeitung für die asynchrone Ausführung in eine Warteschlange.
F: Was passiert, wenn mein Server bei einer Buchung offline ist?
Das Biometric Gateway speichert alle Ereignisse zwischen und stellt sie automatisch zu, sobald Ihr Server wieder online ist. Es gehen keine Daten verloren.
F: Wie gehe ich mit doppelten Buchungen um?
Implementieren Sie auf Ihrem Server eine Duplikaterkennung anhand der Kombination aus UserID + LogTime. Dieselbe Buchung kann bei der Offline-Wiederherstellung oder bei Netzwerk-Wiederholungen erneut gesendet werden.
F: Welche Buchungstypen werden unterstützt?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. Das Feld InputType zeigt das verwendete biometrische Verfahren: Fingerprint, Face, Palm, Card oder Password.
F: Wie funktionieren Benutzer-Templates in Callbacks?
Wird ein Benutzer am Gerät aktualisiert (Operationen #3–#9), können Templates einzeln oder in Gruppen über mehrere Callbacks verteilt eintreffen. Jeder Callback enthält nur die geänderten Templates — nicht den vollständigen Satz. Ihr Server muss per Merge/Upsert mit Type + Index als eindeutigem Schlüssel arbeiten. Überschreiben Sie niemals alle Templates bei einem einzelnen Callback.
F: Kann ich Anwesenheitsfotos empfangen?
Ja. Operation #10 RealTimeAttendancePhoto liefert ein Base64-codiertes JPEG, das zum Zeitpunkt der Buchung aufgenommen wurde. Sie ist vom Buchungsprotokoll-Callback (#11) getrennt und auf Geräten mit Kameraunterstützung verfügbar.
F: Enthält der Callback Temperatur und Maskenerkennung?
Ja, wenn das Gerät dies unterstützt. Das PunchLog-Objekt enthält Temperature (gemessene Körpertemperatur) und FaceMask (Boolean — ob eine Gesichtsmaske erkannt wurde).

RESTful-API (Server → Gerät)

F: Was ist die RESTful-API?
Mit der RESTful-API kann Ihr Server Befehle an biometrische Geräte senden — Benutzer hinzufügen/löschen, Logs laden, Biometrie registrieren und den Zutritt steuern. Sie senden JSON per POST an die Endpunkt-URL aus Ihrem API-Monitor-Konto.
F: Wo finde ich meine RESTful-Endpunkt-URL?
Melden Sie sich in Ihrem API Monitor-Konto an. Dort sind Ihre RESTful-Endpunkt-URL und die Service Tag IDs (stgid) aufgeführt.
F: Wie hoch ist die Latenz bei RESTful-Befehlen?
Etwa 15 Sekunden. Das Biometric Gateway stellt Ihren Befehl in die Warteschlange und liefert ihn an das Gerät aus, sobald es sich das nächste Mal verbindet (bei Online-Geräten nahezu durchgehend).
F: Was ist der maximale Datumsbereich für LoadLog?
Empfohlen sind maximal 30 Tage pro Anfrage. Für größere Zeiträume senden Sie mehrere Anfragen mit aufeinanderfolgenden Zeitfenstern.
F: Kann ich einen Benutzer mit mehreren biometrischen Templates auf einmal hinzufügen?
Ja. Das Template-Array akzeptiert mehrere Einträge. Operation #27 fügt beispielsweise einen Benutzer mit Karte + Fingerabdruck + Passwort + Gesicht + Handvenen + Benutzerfoto in einer einzigen Anfrage hinzu.
F: Was passiert, wenn das Gerät offline ist, während ich einen RESTful-Befehl sende?
Das Biometric Gateway stellt den Befehl in die Warteschlange und liefert ihn automatisch aus, sobald sich das Gerät wieder verbindet. Sie erhalten den Statuscode 5 (Device Offline), wenn das Gerät nicht innerhalb des Zeitfensters antwortet.
F: Wie prüfe ich das Ergebnis eines Befehls?
RESTful-Antworten enthalten das Feld StatusCode. Der Code 0 bedeutet Erfolg. Die vollständige Liste der Fehlercodes und ihre Bedeutung finden Sie unter Antwortstatuscodes.
F: Kann ich die Fingerabdruck-Registrierung aus der Ferne auslösen?
Ja. Operation #35 EnrollFingerPrint startet eine Registrierungssitzung am Gerät. Der Benutzer muss jedoch persönlich am Gerät anwesend sein, um seinen Finger zu scannen.

Sicherheit & Netzwerk

F: Kann ich HTTPS für Callbacks verwenden?
Ja. HTTPS mit gültigem SSL-Zertifikat auf Port 443 wird vollständig unterstützt und für den Produktivbetrieb empfohlen.
F: Ist die Verschlüsselung Pflicht?
Nein. Die AES-256-Verschlüsselung ist optional. Zum Aktivieren konfigurieren Sie im API Monitor einen Security Key. Ist sie aktiviert, werden alle JSON-Payloads mit AES/ECB/PKCS5PADDING und Base64-Kodierung ver- bzw. entschlüsselt.
F: Wie prüfe ich, ob ein Callback tatsächlich von Cams stammt?
Jeder Callback enthält ein AuthToken-Feld. Vergleichen Sie es mit dem in Ihrem API Monitor konfigurierten Token. Lehnen Sie jede Anfrage mit abweichendem Token ab.
F: Welche Ports muss ich öffnen?
Port 80 (HTTP) oder 443 (HTTPS) für den Produktivbetrieb. Port 8123 steht nur zum Testen zur Verfügung. Siehe Unterstützte Ports.
F: Wie teste ich lokal, ohne auf einem Server bereitzustellen?
Verwenden Sie eine öffentliche IP mit Portweiterleitung oder ein Tunneling-Tool wie ngrok. Eine Schritt-für-Schritt-Anleitung finden Sie unter Lokal testen.

Daten & Designaspekte

F: Welches Datenformat verwendet die API?
Alle Requests und Responses sind rohes JSON mit UTF-8-Kodierung. Verwenden Sie den Header Content-Type: application/json. Keine Formularkodierung.
F: Welches Zeitstempelformat wird verwendet?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (z. B. 2020-09-17 07:48:22 GMT +0530). Das Feld Time ist in UTC; geräte-lokale Zeitstempel (wie LogTime, OperationTime) können einen anderen Zeitzonen-Offset verwenden.
F: Wie gehe ich mit Offline-Buchungen und nachträglichen Daten um?
Konzipieren Sie Ihre Anwendung so, dass sie Buchungen akzeptiert, die nicht in chronologischer Reihenfolge eintreffen. War ein Gerät offline, sendet es die zwischengespeicherten Buchungen nach dem Wiederverbinden. Möglicherweise müssen Sie den Anwesenheitsstatus nachträglich anpassen (z. B. einen Benutzer, der als „abwesend“ angezeigt wurde, auf „anwesend“ setzen).
F: Wie ermittle ich IN/OUT, wenn ein Benutzer mehrere Geräte nutzt?
Sortieren Sie alle Buchungen eines Benutzers über alle Geräte hinweg nach LogTime und wenden Sie dann Ihre Geschäftslogik an. Verlassen Sie sich nicht allein auf das Feld Type (CheckIn/CheckOut) eines einzelnen Geräts, wenn der Benutzer an verschiedenen Geräten bucht.
F: Was ist die OperationID und wie verwende ich sie?
Eine eindeutige String-Kennung für jede Operation. Bei eingehenden Callbacks wird sie vom Biometric Gateway erzeugt. Bei ausgehenden RESTful-Requests sollten Sie pro Request eine eindeutige erzeugen (UUID oder zeitstempelbasiert). Die Antwort gibt sie zurück, sodass Sie Request-/Response-Paare zuordnen können.
F: Wie werden biometrische Templates gespeichert und übertragen?
Biometrische Daten (Fingerabdruck, Gesicht, Handvenen, Benutzerfoto) sind im Feld Data des Template-Objekts Base64-codiert. Fingerabdruck- und Gesichts-Templates enthalten zusätzlich Size (Länge in Byte) und Index (Slot-Nummer). Kartennummern und PINs sind einfache Strings.

Preise & Lizenzierung

F: Wie wird die API lizenziert?
Pro biometrischem Gerät. Im ersten Jahr sind API-Aktivierung + Jahreslizenz erforderlich. In den Folgejahren genügt die Verlängerung der Jahreslizenz. Die Preise finden Sie unter API-Kosten.
F: Was passiert, wenn meine API-Lizenz abläuft?
Die API-Kommunikation für dieses Gerät wird eingestellt, bis die Lizenz verlängert wird. Ihre vorhandenen Daten bleiben unberührt, es werden jedoch keine neuen Callbacks oder RESTful-Befehle mehr verarbeitet.
F: Gibt es eine On-Premise-Option?
Ja. Die Protocol Engine Lite kann auf Ihrem eigenen Server (Windows/Linux) für reine LAN- oder selbst gehostete Umgebungen installiert werden. Einzelheiten erhalten Sie unter sales@camsbiometrics.com.
Weitere Informationen

SDK für biometrische Zeiterfassung

Cams bietet kein klassisches SDK an. Alle Operationen nutzen standardmäßige HTTP-Callback- und RESTful-APIs — es muss keine Bibliothek installiert werden.

Kein SDK erforderlich. Die Kommunikation läuft vollständig über die Cams Protocol Engine mit Callback-URLs und RESTful-HTTP-Endpunkten.

Das macht die Integration mit jeder Webplattform unkompliziert:

OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooIndividuelle Web-Apps
Weitere Informationen

API-Kosten

API-Lizenzen werden pro biometrischem Gerät abgerechnet. Erstes Jahr = Aktivierung + Lizenz; Folgejahre = nur Lizenzverlängerung.

LeistungUSDHinweise
Native Push — Cams- & verifizierte Geräte
API-Aktivierung$120Einmalig pro Gerät.
Jährliche API-Lizenz$60 – $120Jährliche Verlängerung erforderlich.
Protocol Update (nicht von Cams)$120 – $280Einmalig. Aktiviert das Cams-Protokoll auf Geräten, die nicht von Cams stammen.
Hybrid Push — ZKTeco, eSSL & alle Drittanbieter-Marken
API-Aktivierung$150Einmalig pro Gerät.
Jährliche API-Lizenz$90 – $150Jährliche Verlängerung erforderlich.
Hybrid Connector (nicht verifiziert)$150 – $300Einmalig. Erforderlich für nicht verifizierte Geräte, die Hybrid Push verwenden.
Hardware & Sonstiges
Hardware$220 – $720Variiert je nach Modell.
Protocol Engine Lite (On-Premise) — Für reine LAN- oder selbst gehostete Umgebungen. Kosten: $500–$10,000. Details erhalten Sie beim Vertrieb.