API v1 (Timesheet Pro)

Inhoudsopgave

Een koppeling opzetten
    - De API inschakelen
    - De verbinding opzetten en testen
    - Voorbeeldcode in PHP

Een koppeling opzetten

Voor het opzetten van een koppeling en het controleren of de connectie succesvol verloopt, bestaat een speciale testfunctie. Voordat u deze kunt gebruiken, is het echter noodzakelijk om de API-koppeling in te schakelen in TimeTick Timesheet Pro. In dit hoofdstuk beschrijven we hoe dit proces verloopt.

De API inschakelen

Ben je een ontwikkelaar? De API is ook toegankelijk via een proefaccount. Voor het testen van de API is het daarom aan te raden om een proefaccount voor Timesheet Pro aan te vragen en alle tests hierop te doen. Op die manier hoef je een bestaande account niet te vervuilen met testdata.

Het inschakelen van de API doet u via Timesheet Pro. Het is hiervoor noodzakelijk om een beheerdersaccount te gebruiken! Om de koppeling in te schakelen, logt u in via de normale weg op https://timesheet.timetick.nl/ en klikt u rechtsboven in het menu op "Management". Er verschijnt een uitklapmenu en u klikt op "Koppelingen". Hier gaat u naar "Timesheet Pro API".

Vervolgens klikt u (indien noodzakelijk) op "API-toegang inschakelen". Er verschijnt op dit moment meer informatie. Op de achtergrond heeft de software een gebruikersnaam en wachtwoord gegenereerd, die gebruikt kunnen worden om verbinding te maken met de API. U kunt de API-toegang op elk moment weer uitschakelen en dan wordt het per direct onmogelijk om verbinding te maken met uw account.

Let op: bij het uitschakelen van de API-toegang worden de inloggegevens verwijderd. Bij het opnieuw inschakelen van de API kan dus niet met dezelfde inloggegevens worden aangemeld bij de API! Dit is een veiligheidsoptie, die ervoor zorgt dat wanneer u bijvoorbeeld stopt met een bepaalde (software)partner, u wel gebruik kunt blijven maken van de API, maar de partner waarmee u gestopt bent niet meer.

U ziet nu twee velden voor u: een gebruikersnaam en een wachtwoord. Deze gegevens zijn nodig voor het verbinden. Als u de koppeling zelf ontwikkelt, kunt u deze in het vervolg van de documentatie gebruiken. Als u de koppeling laat ontwikkelen door een extern softwarebedrijf, hebben zij deze gegevens nodig voor het opzetten van de koppeling met TimeTick.

De verbinding opzetten en testen

Het opzetten van de verbinding gaat heel eenvoudig en kan getest worden zonder een regel code te hoeven schrijven. Een prima softwarepakket om dit te kunnen doen is SoapUI.

De verbinding bestaat uit 2 onderdelen:

  • De URL
  • POST-data

De basis-URL waarmee verbonden moet worden is: https://timesheet.timetick.nl/pro/api/
Daarnaast gaan we gebruik maken van een specifieke functie om de connectie te testen. Deze functie heet testConnection.

Dat betekent dat de volledige URL als volgt zal worden opgebouwd: https://timesheet.timetick.nl/pro/api/testConnection

Vervolgens hebben we de gegevens nodig die we zojuist uit de beheerdersaccount hebben gehaald (api_user en api_pass).

POST-data:

Naam Waarde Verplicht
api_user De waarde uit beheerdersaccount Ja
api_pass De waarde uit beheerdersaccount Ja


Als je deze request uitvoert, krijg je als het goed is de volgende melding:

Connection succeeded! You're good to go :-)

En als je volledige headers aan hebt staan, iets vergelijkbaars met:

HTTP/1.1 200 OK
Date: Wed, 31 Jul 2019 16:16:07 GMT
Server: Apache/2.4.10 (Debian)
Set-Cookie: PHPSESSID=ajlcn5tes3kdhpnojs28eio6q0; path=/
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
Content-Length: 43
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/html; charset=utf-8

Connection succeeded! You're good to go :-)

Als je deze melding krijgt, kun je succesvol verbinden met de API, en kun je verder met de rest van de documentatie.

Krijg je een andere melding?
Het is natuurlijk ook mogelijk dat je een andere melding krijgt. In dat geval is het belangrijk om stapsgewijs het probleem te onderzoeken:

  • Kloppen de inloggegevens en gebruik je niet de inloggegevens van het gebruikersaccount i.p.v. de API inloggegevens?
  • Zijn de inloggegevens vrij van spaties aan begin en einde, en is er niets ongewenst meegekopieerd?
  • Maak je daadwerkelijk gebruik van een POST, en niet bijvoorbeeld een GET?
  • Als je CURL gebruikt, kan het helpen om de optie CURLOPT_SSL_VERIFYPEER op 0 te zetten. Daarmee wordt het SSL-certificaat niet geverifieerd bij de Certificate Authority.

Belangrijk:
De inloggegevens moeten altijd meegestuurd worden, bij elke request die met de API gedaan wordt. Maak het daarom een vast onderdeel van je code, dat scheelt een hoop tijd, moeite en frustratie!

Voorbeeldcode in PHP

Een voorbeeldcode zou er bijvoorbeeld als volgt uit kunnen zien:


function curlPost($url, $postData)
{
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $server_output = curl_exec($ch);
  curl_close ($ch);

  return $server_output;
}

$url = "https://timesheet.timetick.nl/pro/api/testConnection";
$postData = array("api_user" => "[username]","api_pass" => "[password]");
echo curlPost($url, $postData);



Reacties

Er zijn nog geen reacties.
 Meld je aan met LinkedIn om te reageren