Entwicklung eines Callback-Empfängers für biometrische Daten in Python, Node.js und PHP
Ein Callback-Empfänger ist der kleine Codebaustein, der jeden Fingerabdruck-, Gesichts- oder Kartenscan in einen Datensatz in Ihrem eigenen System umwandelt. Das Cams Biometrics Gateway sendet jeden verifizierten Scan als JSON-Anfrage an Ihren Server, und Ihr Server antwortet, um den Eingang zu bestätigen. Sie müssen diesen Empfänger nicht von Grund auf selbst schreiben. Cams stellt KI-Code-Generator-Prompts für Python, Node.js und PHP bereit: Fügen Sie einen davon in einen KI-Assistenten wie Claude oder ChatGPT ein, und Sie erhalten eine vollständige, lauffähige Datei mit einem Callback-Empfänger, einem REST-Client und einer Testoberfläche. Dieses Tutorial erklärt, was ein Empfänger leisten muss, wie Sie einen für Ihre Sprache generieren, wie Sie ihn konfigurieren und wie Sie ihn vor dem Livebetrieb testen.
01 · Die sechs Aufgaben
Was ein Callback-Empfänger leisten muss
Unabhängig von der verwendeten Sprache erledigt jeder biometrische Callback-Empfänger dieselben sechs Aufgaben. Dies sind auch die Punkte, die Sie in jedem generierten Code prüfen sollten.
| Aufgabe | Was es bedeutet | Warum es wichtig ist |
|---|---|---|
| 1. Anfrage annehmen | Einen HTTP/HTTPS-POST mit einem reinen JSON-Body empfangen | So liefert das Gateway jedes Ereignis aus |
| 2. Token prüfen | Den AuthToken mit Ihrem erwarteten Callback-Token vergleichen | Verhindert, dass Unbefugte gefälschte Anwesenheitsdaten an Ihre URL senden |
| 3. Nach Ereignistyp weiterleiten | Prüfen, welcher Schlüssel innerhalb von RealTime enthalten ist, und entsprechend verarbeiten | Nicht jeder Callback ist eine Buchung; manche melden Fotos oder Benutzeränderungen |
| 4. Duplikate überspringen | OperationID verwenden, um bereits gespeicherte Ereignisse zu ignorieren | Eine wiederholte Zustellung führt nie zu einem doppelten Datensatz |
| 5. Speichern und protokollieren | Die benötigten Felder speichern und jeden Callback protokollieren | Erzeugt den Datensatz, den Ihr HRMS, Ihre Lohnabrechnung oder Ihr Dashboard verwendet |
| 6. Mit „done“ antworten | {“status”:”done”} mit HTTP 200 zurückgeben | Teilt dem Gateway mit, dass das Ereignis sicher angekommen ist |
02 · Ihre Daten verstehen
Die Nutzlast, die Sie erhalten
Der häufigste Callback ist ein Buchungsprotokoll, das bei jedem Scan gesendet wird. Speichern Sie dieses Beispiel als sample.json, da Sie es später zum Testen Ihres Empfängers verwenden werden.
|
Callback-API, PunchLog-Anfrage an Ihren Empfänger gesendet {
"RealTime": {
"OperationID": "9nu1wak5616p",
"LabelName": "Burj Khalifa",
"SerialNumber": "ZHM11xxxxxxxx",
"PunchLog": {
"Type": "CheckOut",
"Temperature": "36.8",
"FaceMask": false,
"InputType": "Fingerprint",
"UserId": "2",
"LogTime": "2020-09-17 07:48:22 GMT +0530"
},
"AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
"Time": "2020-09-17 04:19:03 GMT +0000"
}
}
|
Nach der Verarbeitung eines Callbacks muss Ihr Empfänger mit HTTP 200 und genau diesem Body antworten:
|
Callback-API, Antwort, die Ihr Empfänger zurückgeben muss { "status": "done" } (HTTP 200)
|
Callback-Ereignistypen
Jeder Callback kommt innerhalb eines RealTime-Objekts an. Ihr Empfänger entscheidet, was zu tun ist, indem er prüft, welcher dieser Schlüssel vorhanden ist:
| Schlüssel innerhalb von RealTime | Was er meldet |
|---|---|
| PunchLog | Einen Anwesenheitsscan: wer, Kommen oder Gehen, wann und auf welche Weise |
| UserUpdated | Die Angaben eines Benutzers wurden auf dem Gerät aktualisiert |
Zwei Details, die Entwickler häufig übersehen
| Detail | Worauf zu achten ist |
|---|---|
| Der Antwortschlüssel wird kleingeschrieben | Geben Sie status in Kleinbuchstaben mit dem Wert done zurück. Übernehmen Sie nicht das großgeschriebene Feld Status aus RESTful-API-Antworten |
| Das LogTime-Format | LogTime sieht etwa so aus: 2020-09-17 07:48:22 GMT +0530. Es ist die tatsächliche Scanzeit mit dem Offset des Geräts. Parsen Sie den Wert mit dem Offset und verwenden Sie ihn als Anwesenheitszeit |
03 · Die KI den Code schreiben lassen
Ihren Empfänger mit KI-Code-Generator-Prompts erstellen
Cams veröffentlicht für jede unterstützte Serversprache eine fertige Prompt-Datei. Jeder Prompt enthält eine Zusammenfassung der Cams Web API 3.0-Spezifikation und klare Anweisungen zu dem, was erstellt werden soll. Sie fügen ihn in einen KI-Assistenten ein, und der Assistent erzeugt eine vollständige Implementierung in einer einzigen Datei für Ihren Stack.
|
Prompt-Datei herunterladen Wählen Sie im nächsten Abschnitt Ihre Sprache und laden Sie die zugehörige .txt-Prompt-Datei herunter. |
|
|
In einen KI-Assistenten einfügen Öffnen Sie Claude, ChatGPT, Copilot oder ein beliebiges KI-Coding-Tool und fügen Sie den gesamten Prompt-Inhalt ein. |
|
|
Eine vollständige, lauffähige Datei erhalten Die KI erzeugt eine einzelne Datei. Legen Sie Ihre Konfigurationswerte fest, stellen Sie die Datei bereit und führen Sie sie aus. |
| Jede generierte Datei enthält | Was sie tut |
|---|---|
| Callback-Empfänger | Liest den rohen POST-Body, prüft den AuthToken, leitet nach Ereignistyp weiter, protokolliert jeden Callback, speichert Buchungsprotokolle, sichert Anwesenheitsfotos und antwortet mit done |
| REST-Client | Eine generische Anfragefunktion sowie Wrapper-Funktionen für alle 27 RESTful-Operationen, etwa AddUser, DeleteUser, ResendAllUser und UpdateAccessTime |
| HTML-Testoberfläche | Eine Browserseite mit Ihren Konfigurationsfeldern, einem Dropdown für Operationen, einem JSON-Editor mit vorausgefüllten Anfragevorlagen, einer Antwortanzeige und einer Liste der letzten Callbacks |
|
Zuerst gilt die gehostete Dokumentation Jeder Prompt weist die KI an, die vollständige Cams Web API-Dokumentation zu lesen und sie als maßgebliche Quelle für Operationen, JSON-Schemas, Feldnamen und Antwortcodes zu behandeln. Wenn die Zusammenfassung im Prompt der gehosteten Dokumentation widerspricht, hat die Dokumentation Vorrang. |
04 · Wählen Sie Ihre Sprache
Prompts für Python, Node.js und PHP
Jeder Prompt ist so abgestimmt, dass idiomatischer Code mit minimalen Abhängigkeiten für die jeweilige Sprache entsteht.
|
|
|
Prompts sind außerdem verfügbar für C# (.NET 8) mit Minimal API, Java mit dem integrierten HttpServer und ohne Abhängigkeiten, Go mit net/http und nur der Standardbibliothek sowie Ruby mit Sinatra und SQLite. Alle finden Sie im Bereich KI-Code-Generator-Prompts der Cams Web API-Dokumentation. Prompts abrufen.
05 · Drei Werte festlegen
Konfiguration der generierten Datei
Die generierte Datei enthält am Anfang einen Konfigurationsblock. In der PHP-Version sieht er so aus; die anderen Sprachen verwenden dieselben drei Werte:
|
Konfigurationsblock, PHP-Version $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| Einstellung | Was einzutragen ist |
|---|---|
| base_url | Die RESTful-Endpunkt-URL aus Ihrem Cams API Monitor-Konto |
| stgid | Ihre Service-Tag-ID. |
| auth_token | Ihr AuthToken, der in Ihre ausgehenden RESTful-Anfragen aufgenommen und mit dem AuthToken in eingehenden Callback-Anfragen verglichen wird. |
|
Tokens nicht in gemeinsam genutztem Code ablegen Für einen schnellen Test ist es in Ordnung, Werte direkt in den Konfigurationsblock einzutragen. Verschieben Sie die Tokens vor dem Produktivbetrieb in Umgebungsvariablen oder einen Secrets-Manager, damit sie niemals in der Versionskontrolle oder in einer gemeinsam genutzten Datei landen. |
Sobald Sie den Empfänger konfiguriert und unter einer öffentlichen HTTPS-Adresse bereitgestellt haben, tragen Sie diese Adresse als Callback-URL im Cams Gateway ein. Ab dann erreicht jeder verifizierte Scan Ihren Empfänger in Echtzeit.
06 · Vor dem Anschluss der Geräte testen
Testen Ihres Empfängers
Zum Testen des Callback-Empfängers benötigen Sie kein biometrisches Gerät. Senden Sie ihm die Beispiel-Nutzlast selbst mit cURL, mit einem passenden Callback-Token, und prüfen Sie die Antwort.
|
Terminal, Test-Callback senden # Speichern Sie die Beispiel-Nutzlast als sample.json und senden Sie sie dann an Ihren Empfänger:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Erwartete Antwort (HTTP 200):
# {"status":"done"}
|
| Test | Was zu senden ist | Erwartetes Ergebnis |
|---|---|---|
| Gültiges Ereignis | sample.json, mit AuthToken auf Ihren auth_token gesetzt | HTTP 200 mit done, und die Buchung wird gespeichert |
| Doppeltes Ereignis | Dieselbe Anfrage ein zweites Mal | HTTP 200 mit done, und es wird kein zweiter Datensatz gespeichert |
| Falscher Token | sample.json mit einem anderen AuthToken | Abgelehnt, und nichts wird gespeichert |
| Kommen-Ereignis | sample.json, bei dem Type auf CheckIn geändert wurde | Als Kommen gespeichert |
| RESTful-Operation | Die integrierte HTML-Testoberfläche verwenden, um eine Operation zu senden | Eine Antwort mit Status und StatusCode |
Die generierte HTML-Testoberfläche macht die RESTful-Seite leicht ausprobierbar: Öffnen Sie die Datei im Browser, wählen Sie im Dropdown eine Operation, passen Sie das vorausgefüllte JSON an und senden Sie es ab. Die Anzeige der letzten Callbacks auf derselben Seite bestätigt, dass Ihre Test-Callbacks empfangen wurden.
07 · Checkliste für den Produktivbetrieb
Vor dem Livebetrieb prüfen
KI-generierter Code ist ein schneller und verlässlicher Ausgangspunkt, doch wie jeder Code sollte er geprüft werden, bevor er echte Mitarbeiterdaten verarbeitet.
| Punkt | Erledigt, wenn |
|---|---|
| Code geprüft | Ein Entwickler hat die generierte Datei gelesen und versteht, was jeder Abschnitt tut |
| Nur HTTPS | Der Empfänger ist nur über HTTPS mit einem gültigen Zertifikat erreichbar |
| Tokens geschützt | AuthTokens sind in Umgebungsvariablen oder einem Secrets-Manager gespeichert |
| Duplikate behandelt | OperationID wird gespeichert und geprüft, damit wiederholte Zustellungen ignoriert werden |
| Speicher geeignet | Der JSON-Dateispeicher ist für kleine Installationen geeignet; größere Einsätze sollten auf eine Produktionsdatenbank umziehen |
| Testoberfläche geschützt | Die HTML-Testseite ist auf öffentlichen Servern passwortgeschützt oder deaktiviert |
| Fotos sorgfältig behandelt | Auf der Festplatte gespeicherte Anwesenheitsfotos sind zugriffsbeschränkt und nur so lange aufbewahrt, wie es nötig ist |
| Überwachung eingerichtet | Fehler und ungewöhnliche Callback-Volumen werden von Ihrer eigenen Überwachung protokolliert und gemeldet |
|
Geschäftsregeln an anderer Stelle festlegen Die Aufgabe des Empfängers ist es, anzunehmen, zu prüfen, weiterzuleiten, zu speichern und zu bestätigen. Zu entscheiden, wer zu spät kommt, Überstunden zu berechnen oder Benachrichtigungen zu versenden, gehört in die Systeme, die die gespeicherten Ereignisse lesen, etwa Ihr HRMS, Ihr ERP oder Ihre Automatisierungswerkzeuge. Ein fokussierter Empfänger lässt sich leichter absichern und warten. |
Häufig gestellte Fragen
|
Muss ich selbst Code schreiben? In der Regel nicht. Die KI-Code-Generator-Prompts erzeugen eine vollständige, lauffähige Datei. Sie legen drei Konfigurationswerte fest, stellen die Datei bereit und testen sie. Ein Entwickler sollte den Code dennoch vor dem Produktivbetrieb prüfen. |
|
Mit welchen KI-Assistenten funktionieren die Prompts? Mit jedem leistungsfähigen KI-Coding-Assistenten, darunter Claude, ChatGPT und Copilot. Fügen Sie den gesamten Prompt-Inhalt auf einmal ein, damit der Assistent die vollständige Spezifikation erhält. |
|
Wo finde ich die RESTful-Endpunkt-URL und die Service-Tag-ID? Beide stammen aus Ihrem Cams API Monitor-Konto. RESTful-Anfragen werden an die Endpunkt-URL mit ?stgid= gefolgt von Ihrer Service-Tag-ID gesendet. |
|
Warum mit done auf ein doppeltes Ereignis antworten? Weil das Ereignis sicher angekommen ist, auch wenn Sie es bereits gespeichert hatten. Die Antwort done teilt dem Gateway mit, dass es das Ereignis nicht erneut senden muss. |
|
Kann ich eine Sprache verwenden, die nicht aufgeführt ist? Ja. Der Callback-Empfänger muss lediglich einen HTTPS-POST annehmen und JSON zurückgeben. Die Prompts sind eine Abkürzung, und dieselbe API funktioniert mit jeder Sprache, die dies leisten kann. |
Fazit: Vom Prompt zur Echtzeit-Anwesenheit an einem Nachmittag
Ein biometrischer Callback-Empfänger ist klein, doch er ist das Bauteil, das jeden verifizierten Scan in Live-Daten für Ihr HRMS, Ihre Lohnabrechnung, Ihre Dashboards und Automatisierungen verwandelt. Mit den Cams KI-Code-Generator-Prompts müssen Sie ihn nicht mehr auf einer leeren Seite entwickeln. Laden Sie den Prompt für Python, Node.js oder PHP herunter, fügen Sie ihn in Ihren KI-Assistenten ein, legen Sie drei Werte fest und testen Sie. Prüfen, sichern Sie ihn anschließend ab, und lassen Sie die Anwesenheitsdaten in Echtzeit zu fließen.
Das Cams Biometrics Gateway liefert die Ereignisse, die Ihr Empfänger benötigt. Seine Callback-API sendet jeden verifizierten Scan in Echtzeit, in einem einheitlichen JSON-Format, von Geräten mehrerer als 15 Marken, und seine RESTful-API bietet 27 Operationen, die Ihr generierter Client aufrufen kann. Die gesamte Kommunikation läuft über HTTP/HTTPS mit Validierung des Auth-Tokens und optionaler AES-256-Verschlüsselung. Entdecken Sie die Plattform unter CamsBiometrics.com und lesen Sie die vollständige Web-API-Dokumentation einschließlich aller KI-Code-Generator-Prompts: Prompts abrufen.