REST API

Klokin API

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 bekijken

Een greep uit de Klokin API calls:

  • Ruwe data ophalen
  • Geklokte tijden ophalen
  • Tijden op werkorders ophalen
  • Tijden op projecten ophalen
  • Werkorders automatisch importeren
  • Projecten automatisch importeren
  • JSONals returntype
  • CSV als returntype
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: */*
Curl

Aanroep via curl

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.

Belangrijk

Gebruik je API-sleutel veilig

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.

Genereer opnieuw

Mocht je niet zeker zijn of de sleutel nog geheim is dan kan je het best een nieuwe sleutel genereren.

Blokkeer toegang

Mocht je de samenwerking met een partner die de sleutel in bezit heeft beëindigen dan kan je de api toegang ook weer volledig blokkeren.

Bespreek functies

Mocht je meer informatie willen of een bepaalde functie nodig hebben dan horen we het graag.

Contact opnemen
Parameters

De parameters onder de loep

Subdomein

https://jesubdomein.klokin.nl/restapi/ is beschikbaar onder je eigen subdomein.

retrieve

Met retrieve geef je aan dat je data wilt ophalen.

api_key

De api key die je gegenereert hebt vanuit je account op Klokin.

dataset

Welke data wil je ontvangen? 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 / date_end

De startdatum en einddatum van de kloktijden.

Response

JSON array als antwoord

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"}
  ]
}
POST

Data inschieten of 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]
]