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
| 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 |
Algemene velden
Alle aanvragen — zowel Callback als RESTful — delen deze velden op het hoogste niveau.
"j95xfejt3vr1"). RESTful-responses geven dezelfde OperationID terug, zodat u aanvragen aan responses kunt koppelen.YYYY-MM-DD HH:mm:ss GMT +0000. Tijdstempels van het apparaat zelf binnen de payload kunnen een andere tijdzoneverschuiving gebruiken.POST https://<your-endpoint>?stgid=YOUR_TAG_ID.Templatetypen
Biometrische en inloggegevens worden verzonden in een Template-array. Elk item heeft een Type-veld:
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 bijwerkenVervang 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 |
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. |
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. |
Voorbeeldgegevens
Voorbeeld-requests en -responses voor alle 38 bewerkingen staan hierboven bij elke bewerking. Voor een samenvattend overzicht:
Versleuteling
Optioneel kan AES-256-versleuteling worden ingeschakeld voor alle gegevens die worden uitgewisseld tussen de Cams Protocol Engine en uw server.
AES/ECB/PKCS5PADDING).Java-voorbeeld
// 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");