Support Hub/API & Integrations/Entwicklung eines Callback-Empfängers für biometrische…
Translated from the English article and reviewed by a person. Read the English original
Developer

Entwicklung eines Callback-Empfängers für biometrische Daten in Python, Node.js und PHP

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.

1

Prompt-Datei herunterladen

Wählen Sie im nächsten Abschnitt Ihre Sprache und laden Sie die zugehörige .txt-Prompt-Datei herunter.

2

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.

3

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.

Python

Flask, SQLite, nur Standardbibliothek

Python-Prompt herunterladen

Node.js

Express, JSON-Dateispeicher

Node.js-Prompt herunterladen

PHP

Reines PHP, SQLite, ohne Composer

PHP-Prompt herunterladen

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.

 

Was this article helpful?