Een biometrische callback-receiver bouwen in Python, Node.js en PHP
Een callback-receiver is het kleine stukje code dat elke vingerafdruk-, gezichts- of kaartscan omzet in een record in je eigen systeem. Cams Biometrics Gateway stuurt elke geverifieerde scan als JSON-verzoek naar je server, en je server antwoordt om te bevestigen dat die is aangekomen. Je hoeft die receiver niet vanaf nul te schrijven. Cams biedt AI Code Generator Prompts voor Python, Node.js en PHP: plak er een in een AI-assistent zoals Claude of ChatGPT, en je krijgt een compleet werkend bestand met een callback-receiver, een REST-client en een testinterface. Deze handleiding legt uit wat een receiver moet doen, hoe je er een voor jouw taal genereert, hoe je hem configureert en hoe je hem test voordat je live gaat.
01 · De zes taken
Wat een callback-receiver moet doen
Welke taal je ook gebruikt, elke biometrische callback-receiver doet dezelfde zes taken. Dit is ook wat je moet controleren in elke code die je genereert.
| Taak | Wat het betekent | Waarom het belangrijk is |
|---|---|---|
| 1. Het verzoek accepteren | Een HTTP/HTTPS POST met een ruwe JSON-body ontvangen | Zo levert de Gateway elke gebeurtenis af |
| 2. Het token verifiëren | Controleer de AuthToken tegen je verwachte callback-token | Voorkomt dat anderen valse aanwezigheidsregistraties naar je URL sturen |
| 3. Routeren op gebeurtenistype | Kijk welke sleutel binnen RealTime staat en verwerk die dienovereenkomstig | Niet elke callback is een stempeling; sommige melden foto's of gebruikerswijzigingen |
| 4. Duplicaten overslaan | Gebruik OperationID om gebeurtenissen te negeren die je al hebt opgeslagen | Een herhaalde levering wordt nooit een dubbel record |
| 5. Opslaan en loggen | Sla de velden op die je nodig hebt en log elke callback | Maakt het record dat je HRMS, salarisadministratie of dashboard gebruikt |
| 6. Antwoorden met done | Retourneer {“status”:”done”} met HTTP 200 | Laat de Gateway weten dat de gebeurtenis veilig is aangekomen |
02 · Ken je gegevens
De payload die je ontvangt
De meest voorkomende callback is een stempellog, die elke keer wordt verzonden wanneer iemand scant. Sla dit voorbeeld op als sample.json, want je gebruikt het later om je receiver te testen.
|
Callback API, PunchLog-verzoek verzonden naar je receiver {
"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"
}
}
|
Na het verwerken van een callback moet je receiver antwoorden met HTTP 200 en precies deze body:
|
Callback API, antwoord dat je receiver moet retourneren { "status": "done" } (HTTP 200)
|
Callback-gebeurtenistypen
Elke callback komt binnen in een RealTime-object. Je receiver bepaalt wat hij moet doen door te controleren welke van deze sleutels aanwezig is:
| Sleutel binnen RealTime | Wat het meldt |
|---|---|
| PunchLog | Een aanwezigheidsscan: wie, in- of uitchecken, wanneer en hoe |
| UserUpdated | De gegevens van een gebruiker zijn op het apparaat bijgewerkt |
Twee details waar ontwikkelaars over struikelen
| Detail | Waar je op moet letten |
|---|---|
| De antwoordsleutel is kleine letters | Retourneer status in kleine letters met de waarde done. Kopieer niet het veld Status met hoofdletter uit RESTful API-antwoorden |
| Het LogTime-formaat | LogTime ziet eruit als 2020-09-17 07:48:22 GMT +0530. Het is de werkelijke scantijd met de offset van het apparaat. Parseer het met de offset en gebruik het als aanwezigheidstijd |
03 · Laat AI de code schrijven
Genereer je receiver met AI Code Generator Prompts
Cams publiceert per ondersteunde serverтaal een kant-en-klaar promptbestand. Elke prompt bevat een samenvatting van de Cams Web API 3.0-specificatie en duidelijke instructies voor wat er gebouwd moet worden. Je plakt die in een AI-assistent, en de assistent genereert een complete implementatie in één bestand voor jouw stack.
|
Download het promptbestand Kies je taal in de volgende sectie en download het .txt-promptbestand. |
|
|
Plak het in een AI-assistent Open Claude, ChatGPT, Copilot of een willekeurige AI-codeertool en plak de volledige inhoud van de prompt. |
|
|
Krijg een volledig werkend bestand De AI genereert één bestand. Stel je configuratiewaarden in, deploy het en voer het uit. |
| Elk gegenereerd bestand bevat | Wat het doet |
|---|---|
| Callback-receiver | Leest de ruwe POST-body, valideert de AuthToken, routeert op gebeurtenistype, logt elke callback, slaat stempellogs op, bewaart aanwezigheidsfoto's en antwoordt met done |
| REST-client | Een generieke requestfunctie plus wrapperfuncties voor alle 27 RESTful-operaties, zoals AddUser, DeleteUser, ResendAllUser en UpdateAccessTime |
| HTML-testinterface | Een browserpagina met je configuratievelden, een operatiedropdown, een JSON-editor vooraf ingevuld met requestsjablonen, een responseviewer en een lijst met recente callbacks |
|
Eerst de gehoste documentatie Elke prompt vertelt de AI om de volledige Cams Web API-documentatie te lezen en die te behandelen als de gezaghebbende bron voor operaties, JSON-schema's, veldnamen en responscodes. Als iets in de promptsamenvatting afwijkt van de gehoste documentatie, gaat de documentatie voor. |
04 · Kies je taal
Prompts voor Python, Node.js en PHP
Elke prompt is afgestemd op idiomatische code met minimale afhankelijkheden voor de betreffende taal.
|
|
|
Prompts zijn ook beschikbaar voor C# (.NET 8) met Minimal API, Java met de ingebouwde HttpServer zonder afhankelijkheden, Go met net/http en alleen de standaardbibliotheek, en Ruby met Sinatra en SQLite. Je vindt ze allemaal in de sectie AI Code Generator Prompts van de Cams Web API-documentatie. Haal prompts op.
05 · Drie waarden instellen
Het gegenereerde bestand configureren
Het gegenereerde bestand heeft bovenaan een configuratieblok. In de PHP-versie ziet het er zo uit, en de andere talen gebruiken dezelfde drie waarden:
|
Configuratieblok, PHP-versie $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| Instelling | Wat je invult |
|---|---|
| base_url | De RESTful endpoint-URL uit je Cams API Monitor-account |
| stgid | Je Service Tag ID. |
| auth_token | Je AuthToken, opgenomen in je uitgaande RESTful-requests en gecontroleerd tegen de AuthToken in binnenkomende callback-requests. |
|
Bewaar tokens buiten gedeelde code Voor een snelle test is het prima om waarden in het configuratieblok te typen. Verplaats de tokens vóór productie naar omgevingsvariabelen of een secrets manager, zodat ze nooit in versiebeheer of in een gedeeld bestand terechtkomen. |
Zodra het is geconfigureerd en gedeployd op een publiek HTTPS-adres, stel je dat adres in als Callback URL in Cams Gateway. Vanaf dat moment bereikt elke geverifieerde scan je receiver in realtime.
06 · Test voordat je apparaten koppelt
Je receiver testen
Je hebt geen biometrisch apparaat nodig om de callback-receiver te testen. Stuur de voorbeeldpayload zelf met cURL, met een overeenkomend callback-token, en controleer de respons.
|
Terminal, stuur een testcallback # Save the sample payload as sample.json, then send it to your receiver:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Expected response (HTTP 200):
# {"status":"done"}
|
| Test | Wat je stuurt | Verwacht resultaat |
|---|---|---|
| Geldige gebeurtenis | sample.json, met de AuthToken ingesteld op je auth_token | HTTP 200 met done, en de stempeling is opgeslagen |
| Dubbele gebeurtenis | Dezelfde request nogmaals | HTTP 200 met done, en er wordt geen tweede record opgeslagen |
| Verkeerd token | sample.json met een andere AuthToken | Afgewezen, en er wordt niets opgeslagen |
| Inchecken-gebeurtenis | sample.json met Type gewijzigd in CheckIn | Opgeslagen als inchecken |
| RESTful-operatie | Gebruik de ingebouwde HTML-testinterface om een operatie te versturen | Een respons met Status en StatusCode |
De gegenereerde HTML-testinterface maakt de RESTful-kant eenvoudig om uit te proberen: open het bestand in een browser, kies een operatie uit de dropdown, pas de vooraf ingevulde JSON aan en verstuur die. De viewer voor recente callbacks op dezelfde pagina bevestigt dat je testcallbacks zijn ontvangen.
07 · Productiechecklist
Controleer voordat je live gaat
AI-gegenereerde code is een snel en betrouwbaar startpunt, maar net als elke code moet hij worden gecontroleerd voordat hij echte medewerkersgegevens verwerkt.
| Onderdeel | Klaar wanneer |
|---|---|
| Code gecontroleerd | Een ontwikkelaar heeft het gegenereerde bestand gelezen en begrijpt wat elk onderdeel doet |
| Alleen HTTPS | De receiver is alleen bereikbaar via HTTPS met een geldig certificaat |
| Tokens beschermd | AuthTokens zijn opgeslagen in omgevingsvariabelen of een secrets manager |
| Duplicaten afgehandeld | OperationID wordt opgeslagen en gecontroleerd, zodat herhaalde leveringen worden genegeerd |
| Opslag geschikt | De JSON-bestandsopslag is prima voor kleine opzetten; grotere implementaties kunnen overstappen naar een productiedatabase |
| Testinterface beveiligd | De HTML-testpagina is met een wachtwoord beveiligd of uitgeschakeld op publieke servers |
| Foto's zorgvuldig behandeld | Aanwezigheidsfoto's die op schijf zijn opgeslagen, zijn toegangsbeheerd en worden alleen zolang nodig bewaard |
| Monitoring aanwezig | Fouten en ongebruikelijke callbackvolumes worden gelogd en gemeld door je eigen monitoring |
|
Houd bedrijfsregels elders De taak van de receiver is accepteren, verifiëren, routeren, opslaan en bevestigen. Bepalen wie te laat is, overwerk berekenen of meldingen versturen hoort thuis in de systemen die de opgeslagen gebeurtenissen lezen, zoals je HRMS, ERP of automatiseringstools. Een gerichte receiver is makkelijker te beveiligen en te onderhouden. |
Veelgestelde vragen
|
Moet ik zelf code schrijven? Meestal niet. De AI Code Generator Prompts leveren een compleet werkend bestand. Je stelt drie configuratiewaarden in, deployt het en test het. Een ontwikkelaar moet de code vóór productie toch nog controleren. |
|
Welke AI-assistenten werken met de prompts? Elke capabele AI-codeerassistent, waaronder Claude, ChatGPT en Copilot. Plak de volledige inhoud van de prompt in één keer, zodat de assistent de volledige specificatie heeft. |
|
Waar vind ik de RESTful endpoint-URL en de Service Tag ID? Beide komen uit je Cams API Monitor-account. RESTful-requests worden naar de endpoint-URL gepost, met ?stgid= gevolgd door je Service Tag ID. |
|
Waarom antwoord ik met done voor een dubbele gebeurtenis? Omdat de gebeurtenis wél veilig is aangekomen, ook al had je hem al opgeslagen. Antwoorden met done laat de Gateway weten dat hij hem niet opnieuw hoeft te sturen. |
|
Kan ik een taal gebruiken die niet in de lijst staat? Ja. De callback-receiver hoeft alleen een HTTPS POST te accepteren en JSON te retourneren. De prompts zijn een snelkoppeling; dezelfde API werkt met elke taal die dat kan. |
Conclusie: van prompt naar realtime aanwezigheid in een middag
Een biometrische callback-receiver is klein, maar het is het onderdeel dat elke geverifieerde scan omzet in live gegevens voor je HRMS, salarisadministratie, dashboards en automatiseringen. Met de Cams AI Code Generator Prompts hoef je hem niet meer vanaf een leeg blad te bouwen. Download de prompt voor Python, Node.js of PHP, plak die in je AI-assistent, stel drie waarden in en test. Controleer hem daarna, beveilig hem en laat realtime aanwezigheidsgegevens gaan stromen.
Cams Biometrics Gateway levert de gebeurtenissen die je receiver nodig heeft. De Callback API stuurt elke geverifieerde scan in realtime, in één consistent JSON-formaat, van apparaten van meer dan 15 merken, en de RESTful API biedt 27 operaties die je gegenereerde client kan aanroepen. Alle communicatie verloopt via HTTP/HTTPS met validatie van het auth-token en optionele AES-256-versleuteling. Ontdek het platform op CamsBiometrics.com en lees de volledige Web API-documentatie, inclusief elke AI Code Generator Prompt: Haal prompts op.