De voordelen van de API en webhooks

• 🔌 Koppel TimeKing met je eigen software of met een pakket waarvoor (nog) geen standaardkoppeling bestaat.

• 📥 Lees klanten, projecten, bonnen, medewerkers, facturen en meer uit TimeKing, bijvoorbeeld voor eigen rapportages.

• ✏️ Maak gegevens aan in TimeKing of wijzig en verwijder ze vanuit een ander systeem, zonder dubbel invoeren.

• 🔔 Laat een ander systeem direct weten dat er in TimeKing iets is opgeslagen of verwijderd, met maximaal 10 webhooks.

• 🔁 Koppel twee TimeKing-omgevingen aan elkaar via een webhook.

Beschikbare gegevens

Hieronder staat omschreven welke gegevens via de API beschikbaar zijn en waarvoor TimeKing webhooks verstuurt.

Gegevens via de API

Via de API kun je de onderstaande gegevens opvragen (als lijst of één item tegelijk), aanmaken, wijzigen en verwijderen:

• Klanten

• Projecten en projectcategorieën

• Bonnen en bonsoorten

• Planningen

• Medewerkers en medewerkercontracten

• Uitvoerders

• Werkzaamheden

• Materialen

• Voertuigen

• Eenheden

• Tarieven

• Uitgaven

• Verkoop & Verhuur-items

• Factuurregels en facturen

• Offertes

• Btw-tarieven

• Wegingen, weegbruggen en weegsoorten

• Verlof, verlofcategorieën en verzuim

Daarnaast kun je de beschikbaarheid van voertuigen en medewerkers in een periode opvragen en het totaal aantal items per soort.

Let op: een lijst geeft maximaal 1000 items per keer terug. Hoe je verder bladert, filtert en sorteert, staat in de API-referentie.

Webhooks

Een webhook is een adres (URL) waar TimeKing een bericht naartoe stuurt zodra er iets verandert. Per webhook kies je bij “Onderwerpen” voor welke items dat gebeurt:

• Voertuigen

• Medewerkers

• Klanten

• Projecten

• Werkzaamheden

• Materialen

• Eenheid

• Bonsoorten

• Bonnen

• Planningen

• Facturen

Het bericht bevat alleen wat er veranderd is, niet het hele item:

• van welke TimeKing-omgeving het komt (bijvoorbeeld jouwbedrijf.timeking.nl);

• het soort item (bijvoorbeeld klant of bon);

• het ID van het item;

• de actie: opgeslagen of verwijderd.

Het ontvangende systeem haalt daarna zelf de actuele gegevens op via de API.

Let op: een factuur wordt verstuurd op het moment dat je hem definitief maakt, niet bij elke wijziging van een concept. Bij het opslaan van andere items gaat er alleen een webhook uit als het item ook via een actieve koppeling (zie “Instellingen” → “Koppelingen”) gekoppeld is.

Werking

Een ander programma maakt verbinding met je eigen TimeKing-omgeving via het adres bij “API endpoint”, dat er zo uitziet: https://jouwbedrijf.timeking.nl/api/external/v1/. Bij elke aanvraag stuurt het programma de “(Private) API key” mee. Hoe dat precies werkt, met alle endpoints en voorbeelden, staat in de API-referentie. Geef die pagina aan je ontwikkelaar of softwareleverancier.

Er kunnen maximaal 60 aanvragen per minuut worden gedaan. Gaat een programma daarboven, dan krijgt het een foutmelding en moet het even wachten. Staat het schuifje “API actief” uit, dan weigert TimeKing alle aanvragen.

Webhooks worden direct verstuurd bij het opslaan of verwijderen van een item, en voor facturen bij het definitief maken. TimeKing wacht maximaal 5 seconden op een antwoord en probeert een mislukt bericht niet opnieuw. Het ontvangende systeem moet dus bereikbaar zijn via internet; adressen binnen een eigen netwerk worden niet aangeroepen.

Configureren

Om de API en webhooks te gebruiken moeten er de volgende stappen doorlopen worden:

1. API activeren in TimeKing.

2. Eventueel webhooks toevoegen.

1. API activeren in TimeKing

1. Ga in TimeKing naar “Instellingen” → “Algemeen” en open het tabblad “API”.

2. Zet het schuifje “API actief” aan.

3. Kopieer de “(Private) API key” en het “API endpoint” en geef ze aan je ontwikkelaar of softwareleverancier.

4. Klik onderaan op “Opslaan”.

2. Webhooks toevoegen

1. Klik op het tabblad “API” bij “API webhooks” op “Voeg een nieuwe webhook toe”.

2. Vul bij “URL” het adres in waar het bericht naartoe moet. Wil je een andere TimeKing-omgeving op de hoogte houden, dan is dat: https://[subdomein].timeking.nl/webhook/timeking?api_key=[API key van die omgeving].

3. Vink bij “Onderwerpen” aan voor welke items de webhook verstuurd moet worden.

4. Herhaal dit voor elke extra webhook (maximaal 10).

5. Klik onderaan op “Opslaan”.