API-referentie: architectuur, velden en statuscodes

De bouwstenen die alle bewerkingen delen: aanvraagstroom, algemene JSON-velden, templatetypen, statuscodes, poorten en payloadversleuteling.

API-referentie

API-architectuur

Eigenschap	Callback-API	RESTful API
Initiator	Apparaat / Biometric Gateway	Uw server
Richting	Apparaat → Uw server	Uw server → Apparaat
Latentie	Realtime (milliseconden)	~15 seconden
Trigger	Biometrisch event op het apparaat	HTTP POST vanuit uw code
Uw rol	Ontvangen & bevestigen	Opdracht sturen & wachten op/pollen naar antwoord
Response-body	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
Offlinegedrag	Gecachet door de engine; geleverd wanneer de server weer online is	In de wachtrij gezet door de engine; geleverd wanneer het apparaat weer verbinding maakt

API-referentie

Algemene velden

Alle aanvragen — zowel Callback als RESTful — delen deze velden op het hoogste niveau.

AuthTokenString. Een token van 32 tekens dat aanvragen van een specifiek apparaat identificeert en authenticeert. Wordt geconfigureerd in het API Monitor-portaal. Valideer dit bij elke inkomende callback.

OperationIDString. Een unieke identificatie voor deze bewerkingsinstantie (bijv. "j95xfejt3vr1"). RESTful-responses geven dezelfde OperationID terug, zodat u aanvragen aan responses kunt koppelen.

TimeString. UTC-tijdstempel van het moment waarop het event werd verwerkt, in het formaat YYYY-MM-DD HH:mm:ss GMT +0000. Tijdstempels van het apparaat zelf binnen de payload kunnen een andere tijdzoneverschuiving gebruiken.

stgid (queryparameter)String. Service Tag ID — identificeert het doelapparaat voor RESTful API-aanroepen. Geef dit als URL-queryparameter mee aan het endpoint uit uw API Monitor-account: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

Templatetypen

Biometrische en inloggegevens worden verzonden in een Template-array. Elk item heeft een Type-veld:

Samenvoeggedrag van templates — belangrijk voor callbackhandlers
Wanneer gebruikersgegevens vanaf het apparaat worden gepusht (Callback-bewerkingen #3–#9), kunnen templates één voor één of in groepen binnenkomen, verspreid over meerdere callbacks. Elke callback bevat niet de volledige set templates van de gebruiker — alleen de templates die zijn toegevoegd of gewijzigd.

Uw server moet inkomende templates samenvoegen met de reeds opgeslagen templates van die gebruiker. De unieke sleutel van elke template is Type + Index. Bijvoorbeeld:
• Callback 1 komt binnen met Fingerprint Index 0 → opslaan
• Callback 2 komt binnen met Face Index 0 + Card → samenvoegen, de vingerafdruk niet overschrijven
• Callback 3 komt binnen met Fingerprint Index 0 (nieuwe gegevens) → de bestaande vingerafdruk op Index 0 bijwerken
Vervang bij een callback nooit alle templates — voer altijd een upsert uit op Type + Index.

Type	Beschrijving	Belangrijkste extra velden
`Card`	RFID-/proximitykaartnummer	`Data` (kaartnummer als string)
`Password`	Numerieke PIN	`Data` (PIN als string)
`Fingerprint`	Vingerafdruktemplate — Base64-gecodeerde binaire gegevens	`Index` (vingerindex 0–9), `Size`, `Data`
`Face`	Gezichtstemplate — Base64-gecodeerde JPEG of binaire gegevens	`Index`, `Size`, `Data`
`Palm`	Handpalmadertemplate — Base64-gecodeerde binaire gegevens	`Index`, `Data`
`UserPhoto`	Profielfoto van de gebruiker — Base64-gecodeerde JPEG	`Data`

API-referentie

Responsestatuscodes

RESTful API-responses bevatten een numerieke StatusCode. Callback-API-responses gebruiken, ongeacht de uitkomst, altijd de eenvoudige vorm {"status":"done"}.

Code	Status	Beschrijving
`0`	Geslaagd	De bewerking is succesvol voltooid.
`1`	Ongeldige aanvraaggegevens	De JSON-body is onjuist opgebouwd of bevat ongeldige waarden.
`2`	Ongeldige Service Tag ID	De queryparameter `stgid` komt met geen enkel geregistreerd apparaat overeen.
`3`	Ongeldige aanvraag	De aanvraagstructuur komt niet overeen met het verwachte bewerkingsformaat.
`4`	Ongeldige versleuteling	De payloadversleuteling (AES-256) kon niet worden ontsleuteld. Controleer uw versleutelingssleutel.
`5`	Apparaat offline	Het doelapparaat is momenteel niet verbonden met de Biometric Gateway.
`6`	Time-out van bewerking	Het apparaat heeft de opdracht niet binnen het tijdvenster bevestigd.
`7`	Ongeldig auth-token	De `AuthToken` in de aanvraag komt niet overeen met het voor het apparaat geconfigureerde token.
`8`	Gebruiker bestaat al	Er is een Add-bewerking uitgevoerd voor een UserID die al op het apparaat bestaat.
`9`	Gebruiker niet gevonden	De opgegeven UserID bestaat niet op het apparaat.
`10`	Templatefout	De biometrische templategegevens zijn beschadigd of hebben een niet-ondersteund formaat.
`11`	Apparaatgeheugen vol	Het apparaat heeft zijn maximale capaciteit aan gebruikers of templates bereikt.
`13`	Ongeldige beveiligingssleutel	De in de API Monitor geconfigureerde beveiligingssleutel komt niet overeen.
`15`	Functie niet ondersteund	De gevraagde bewerking wordt niet ondersteund door dit apparaatmodel of deze communicatiemodus.
`999`	Onbekende fout	Er is een onverwachte fout opgetreden. Neem contact op met Cams-support en vermeld de OperationID.

Aanvullende informatie

Ondersteunde poorten

Om aanwezigheidsinformatie realtime te ontvangen, moet uw server een HTTP(S)-endpoint beschikbaar stellen dat de Cams Protocol Engine kan bereiken.

Poort	Protocol	Gebruik
`80`	HTTP	Productie. Koppel uw callback-URL aan poort 80. Wordt geconfigureerd in de API Monitor en automatisch aangeroepen bij registraties.
`443`	HTTPS	Productie (beveiligd). HTTPS met een geldig SSL-certificaat. Aanbevolen voor productie.
`8123`	HTTP	Alleen voor testen. Niet-standaardpoort die tijdens de ontwikkeling tijdelijk beschikbaar is.

HTTPS aanbevolen. Gebruik in productie HTTPS met een geldig SSL-certificaat. Zorg voor automatische verlenging zonder herstart van de server.

Aanvullende informatie

Voorbeeldgegevens

Voorbeeld-requests en -responses voor alle 38 bewerkingen staan hierboven bij elke bewerking. Voor een samenvattend overzicht:

Deze paginaElke bewerking hierboven bevat kopieerklare request- en response-JSON met voorbeeldgegevens.

Oudere voorbeeldpaginabiometric-web-api-sample-request-response.html — keuzelijst voor elke bewerking.

Aanvullende informatie

Versleuteling

Optioneel kan AES-256-versleuteling worden ingeschakeld voor alle gegevens die worden uitgewisseld tussen de Cams Protocol Engine en uw server.

AlgoritmeAES-256 in ECB-modus met PKCS5-padding (AES/ECB/PKCS5PADDING).

SleutelconfiguratieStel uw sleutel in als Security Key in de API Monitor. Zodra deze is ingesteld, worden alle onbewerkte JSON-payloads versleuteld.

CoderingVersleutelde payloads worden voor veilig HTTP-transport Base64-gecodeerd.

Java-voorbeeld

Versleutelen / ontsleutelen (Java)

// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));

// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");

Belangrijk: Wanneer versleuteling is ingeschakeld, ontsleutelt u inkomende Callback-payloads en versleutelt u uitgaande RESTful request-bodies met dezelfde sleutel.