Support Hub/API & Integrations/Een biometrische callback-receiver bouwen in Python,…
Translated from the English article and reviewed by a person. Read the English original
Developer

Een biometrische callback-receiver bouwen in Python, Node.js en PHP

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.

1

Download het promptbestand

Kies je taal in de volgende sectie en download het .txt-promptbestand.

2

Plak het in een AI-assistent

Open Claude, ChatGPT, Copilot of een willekeurige AI-codeertool en plak de volledige inhoud van de prompt.

3

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.

Python

Flask, SQLite, alleen standaardbibliotheek

Haal Python-prompt op

Node.js

Express, JSON-bestandsopslag

Haal Node.js-prompt op

PHP

Pure PHP, SQLite, geen Composer

Download PHP-prompt

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.

 

Was this article helpful?