API-referentie: architectuur, velden en statuscodes

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

Snelle antwoorden

Wat zijn de twee API-stromen?

De Callback API stuurt gebeurtenissen van het apparaat (via de Cams Biometric Gateway) in realtime naar uw server. Met de RESTful API kan uw server opdrachten naar een apparaat sturen; het antwoord komt binnen ongeveer 15 seconden. Als uw server offline is, buffert de engine callbacks; REST-opdrachten worden in de wachtrij geplaatst totdat het apparaat weer verbinding maakt.

Welke statuscodes geeft de RESTful API terug?

Een numerieke StatusCode: 0 geslaagd, 1 ongeldige aanvraaggegevens, 2 ongeldige Service Tag ID, 3 ongeldige aanvraag, 4 ongeldige versleuteling, 5 apparaat offline, 6 time-out van bewerking, 7 ongeldig authenticatietoken, 8 gebruiker bestaat al, 9 gebruiker niet gevonden, 10 templatefout, 11 apparaatgeheugen vol, 13 ongeldige beveiligingssleutel, 15 functie niet ondersteund, 999 onbekende fout. Callback-antwoorden gebruiken altijd {"status":"done"}.

Wat betekent statuscode 5 (Apparaat offline)?

Het doelapparaat is momenteel niet verbonden met de Biometric Gateway. Zie statuscode 5.

Hoe authenticeer ik aanvragen?

Elke aanvraag bevat een AuthToken, een token van 32 tekens dat één apparaat identificeert en wordt ingesteld in het API Monitor-portaal. Valideer het bij elke inkomende callback. REST-aanroepen geven het apparaat ook door als queryparameter stgid (Service Tag ID). Zie Algemene velden.

Welke poorten heeft mijn server nodig?

Poort 80 (HTTP) of 443 (HTTPS) voor productie; HTTPS met een geldig certificaat wordt aanbevolen. Poort 8123 (HTTP) is alleen bedoeld voor tests. Zie Ondersteunde poorten.

Hoe wordt de payload versleuteld?

Versleuteling is optioneel. Wanneer ingeschakeld, gebruiken payloads AES-256 in ECB-modus met PKCS5-padding (AES/ECB/PKCS5PADDING), met de beveiligingssleutel (Security Key) die in de API Monitor is ingesteld, en worden ze Base64-gecodeerd voor HTTP-transport. Ontsleutel inkomende callbacks en versleutel uitgaande REST-bodies met dezelfde sleutel. Zie Versleuteling.

Hoe ga ik om met templates die over meerdere callbacks binnenkomen?

Voeg ze samen. Elke callback bevat alleen de templates die zijn toegevoegd of gewijzigd. De unieke sleutel van een template is Type + Index, dus voer een upsert uit op dat paar en vervang nooit de volledige templateset van een gebruiker. Zie Templatetypen.

Welke templatetypen bestaan er?

Card, Password, Fingerprint, Face, Palm en UserPhoto. Fingerprint-, Face- en Palm-templates zijn Base64-gecodeerd en de vingerafdrukindex loopt van 0–9.

API-architectuur

EigenschapCallback-APIRESTful API
InitiatorApparaat / Biometric GatewayUw server
RichtingApparaat → Uw serverUw server → Apparaat
LatentieRealtime (milliseconden)~15 seconden
TriggerBiometrisch event op het apparaatHTTP POST vanuit uw code
Uw rolOntvangen & bevestigenOpdracht sturen & wachten op/pollen naar antwoord
Response-body{"status":"done"}{"Status":"done","OperationID":"…","StatusCode":0}
OfflinegedragGecachet door de engine; geleverd wanneer de server weer online isIn de wachtrij gezet door de engine; geleverd wanneer het apparaat weer verbinding maakt

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.
TypeBeschrijvingBelangrijkste extra velden
CardRFID-/proximitykaartnummerData (kaartnummer als string)
PasswordNumerieke PINData (PIN als string)
FingerprintVingerafdruktemplate — Base64-gecodeerde binaire gegevensIndex (vingerindex 0–9), Size, Data
FaceGezichtstemplate — Base64-gecodeerde JPEG of binaire gegevensIndex, Size, Data
PalmHandpalmadertemplate — Base64-gecodeerde binaire gegevensIndex, Data
UserPhotoProfielfoto van de gebruiker — Base64-gecodeerde JPEGData

Responsestatuscodes

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

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

Ondersteunde poorten

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

PoortProtocolGebruik
80HTTPProductie. Koppel uw callback-URL aan poort 80. Wordt geconfigureerd in de API Monitor en automatisch aangeroepen bij registraties.
443HTTPSProductie (beveiligd). HTTPS met een geldig SSL-certificaat. Aanbevolen voor productie.
8123HTTPAlleen 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.

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.

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.