Toegang tot de geklokte tijden van je werknemers
Klokin biedt klanten en externe ontwikkelaars een API om toegang te krijgen tot de geklokte tijden van hun werknemers. Lees de inhoud van deze pagina zorgvuldig door om te begrijpen hoe onze API werkt en om de beperkingen en verantwoordelijkheden te begrijpen.
De API is gebaseerd op HTTP en volgt bepaalde, maar niet alle REST-principes. Dit document gaat ervan uit dat je bekend bent met het HTTP-protocol zoals gedocumenteerd in RFC 2616, je hoeft geen kennis van REST te hebben.
Voorbeeld aanroep data ophalen
Het is gemakkelijk dus laten we er meteen in duiken met een paar voorbeelden. Stel dat we alle kloktijden willen ophalen binnen een bepaalde periode
bijvoorbeeld 1 januari 2023 t/m 31 januari 2023. Dit is het ruwe HTTP-verzoek dat we naar de server kunnen sturen om ze op te halen:
GET
/restapi/retrieve?api_key=46HSvVytUFa4q7bz4WfaJSuKx3KWS8Y6&dataset=rawdata&returntype=json&date_start=2022-12-01&date_end=2022-12-31
HTTP/1.1
User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
Host: jesubdomein.klokin.nl
Accept: */*
Het bovenstaande verzoek is als volgt uitgevoerd met het opdrachtregel hulpprogramma curl:
curl_init("https://jesubdomein.klokin.nl/restapi/retrieve?api_key=46HSvVytUFa4q7bz4WfaJSuKx3KWS8Y6&dataset=rawdata&returntype=json&date_start=2022-12-01&date_end=2022-12-31")
In deze handleiding gebruiken we curl om te laten zien hoe verzoeken kunnen worden uitgevoerd. Voor de eenvoudige verzoeken zoals hierboven, kun je ook gewoon de URL
in een webbrowser typen. Houd er echter rekening mee dat niet alle verzoeken via een browser kunnen worden uitgevoerd. Een browser zal ook niet alle details van het antwoord
van de server tonen.
We zullen de parameters even onder de loep nemen
`https://jesubdomein.klokin.nl/restapi/` => je api is beschikbaar onder je eigen subdomein
`retrieve` => we willen data ophalen
`api_key` => de api key die je gegenereert hebt vanuit je account op Klokin
`dataset` => welke data wil je, in dit voorbeeld gebruiken we rawdata om alle kloktijden op te halen
`returntype` => hoe wil je de data ontvangen: als json of csv bestand
`date_start` => de startdatum van de kloktijden
`date_end` => de einddatum van de kloktijden
Het antwoord van de API op bovenstaand verzoek is een json array:
JSON Response {
"msg":"Succes",
"results":6
"data":[
{"klokin":"2022-12-01 07:31:12","klokuit":"2022-12-01 17:12:33","employee_id":"23","extern_id":"4099","naam":"Magazijn"},
{"klokin":"2022-12-01 07:56:53","klokuit":"2022-12-01 14:56:06","employee_id":"1","extern_id":"5156","naam":"Distributie"},
{"klokin":"2022-12-01 08:11:53","klokuit":"2022-12-01 12:53:30","employee_id":"2","extern_id":"2093","naam":"Administratie"},
{"klokin":"2022-12-02 06:56:44","klokuit":"2022-12-02 15:43:24","employee_id":"23","extern_id":"4099","naam":"Magazijn"},
{"klokin":"2022-12-02 07:42:08","klokuit":"2022-12-02 14:02:53","employee_id":"2","extern_id":"2093","naam":"Administratie"},
{"klokin":"2022-12-02 09:01:31","klokuit":"2022-12-02 15:30:12","employee_id":"1","extern_id":"5156","naam":"Distributie"}
]
}
Voorbeeld aanroep data inschieten / bewerken
Het is ook mogelijk je data in ons systeem via de API bij te werken. Dit werkt via een POST. Stel dat je de werkorders waarop je personeel inklokt en uitklokt vanuit je eigen applicatie wilt
doorgeven aan Klokin. Dit is een voorbeeld van een POST die je naar de server kan sturen om de data door te geven:
POST/restapi/put
Host: jesubdomein.klokin.nl
De velden die je gebruikt in je post zijn:
api_key: jouw sleutel
dataset: clusteritems
data:[ [8,"MPWO-101",0],[8,"MPWO-102",0],[8,"MPWO-103",2] ]
Mocht je meer informatie willen of een bepaalde functie nodig hebben dan horen we het graag. Neem in dat geval gerust even contact op om de mogelijkheden te bespreken.
Let op: op het moment dat je de API aanzet via je account wordt er een geheime sleutel gegenereerd. Je bent zelf verantwoordelijk voor het veilig versturen en het veilig gebruiken
van deze sleutel. Mocht je niet zeker zijn of de sleutel nog geheim is dan kan je het best een nieuwe sleutel genereren. Mocht je de samenwerking met een partner (die de sleutel
in bezit heeft) beeindigen dan kan je de api toegang ook weer volledig blokkeren. Dit doe je ook via je account pagina!