Werftijd API

Veel bedrijven gebruiken al software zoals Odoo, Teamleader, Business Central of maatwerksystemen voor planning, facturatie of projectopvolging. Die tools doen veel goed — maar timetracking is vaak een zwakke plek. De registratie is omslachtig, niet mobiel-vriendelijk, of voldoet niet aan de Belgische wetgeving rond arbeidstijdregistratie.

De Werftijd API laat je toe om je bestaande software te verbinden met Werftijd. Timers starten en stoppen vanuit jouw systeem, terwijl Werftijd de correcte registratie, locatieverificatie en rapportage afhandelt. Zo hoef je geen keuze te maken tussen je vertrouwde software en een degelijke tijdsregistratie.

Heb je maatwerksoftware? Dan kan je via de API Werftijd volledig integreren in je eigen workflow — zonder dat werknemers van platform hoeven te wisselen.

Gebruik je AI agents voor planning, dispatching of projectopvolging? Dan kan je die agents rechtstreeks laten communiceren met Werftijd. Een agent die een opdracht toewijst aan een werknemer kan meteen ook de timer starten — zonder menselijke tussenkomst. Zo sluit Werftijd naadloos aan op geautomatiseerde workflows.

De API werkt via een event-flow: start, pause, resume, stop.

Authenticatie

Elke verbinding met de Werftijd API gebeurt via een API key. Dat is een unieke sleutel die je aanmaakt in Werftijd en meegeeft aan je externe systeem. Zo weet Werftijd van welk systeem een request komt en voor welk bedrijf.

Je kan meerdere API keys aanmaken — één per integratie. Gebruik je Odoo én een eigen app? Maak dan twee aparte keys, elk met een duidelijke naam. Zo kan je achteraf zien welk systeem wat verstuurd heeft, en kan je één key intrekken zonder de andere te verstoren.

API keys maak je aan via Admin → Instellingen → Connecties → Werftijd API.

Elke request voeg je de key toe als header:

Authorization: Bearer <API_KEY>

Basis‑URL

https://werftijd.be/api/external

Belangrijke concepten

external_id — de unieke identifier van een time entry vanuit jouw systeem. Werftijd gebruikt dit om entries te herkennen en dubbele registraties te vermijden.

Voorbeeld: je planningssysteem geeft elke taakopdracht een eigen ID. Dat ID stuur je mee als external_id, zodat je later kan pauzeren of stoppen zonder het interne Werftijd-ID te hoeven opvragen.

"external_id": "TAAK-2026-00842"

source — een label dat aangeeft welk systeem de request stuurt. Optioneel, standaard external. Handig als je meerdere integraties hebt: zo zie je in Werftijd meteen van waar een entry komt.

"source": "odoo"

technician_email — het e-mailadres van de werknemer in Werftijd. Dit moet exact overeenkomen met het adres waarmee de werknemer is aangemaakt.

Als je medewerkers al in Teamleader staan, kan je ze importeren via de Teamleader-connectie. Zo gebruik je overal hetzelfde e-mailadres en hoef je niets handmatig over te typen. Zie Connecties voor meer info.

"technician_email": "jan.janssen@bedrijf.be"

Endpoints

1) Start

POST /time-entries/start

Body:

{
  "external_id": "EXT-123",
  "technician_email": "user@bedrijf.be",
  "started_at": "2026-03-19T08:00:00Z",
  "start_lat": 51.2194,
  "start_lng": 4.4025,
  "source": "external"
}

2) Pause

POST /time-entries/pause

Body:

{
  "external_id": "EXT-123",
  "technician_email": "user@bedrijf.be",
  "occurred_at": "2026-03-19T10:15:00Z",
  "lat": 51.2199,
  "lng": 4.4050
}

3) Resume

POST /time-entries/resume

Body:

{
  "external_id": "EXT-123",
  "technician_email": "user@bedrijf.be",
  "occurred_at": "2026-03-19T10:30:00Z",
  "lat": 51.2201,
  "lng": 4.4062
}

4) Stop

POST /time-entries/stop

Body:

{
  "external_id": "EXT-123",
  "technician_email": "user@bedrijf.be",
  "occurred_at": "2026-03-19T16:00:00Z",
  "stop_lat": 51.2201,
  "stop_lng": 4.4102
}

Idempotentie

start is idempotent: een tweede start met hetzelfde external_id geeft de bestaande entry terug.
pause/resume/stop zijn state‑based en geven een status terug als de entry al in die status staat.

GPS‑data

start_lat/lng worden opgeslagen op de time‑entry.
stop_lat/lng worden opgeslagen op stop.
lat/lng bij pause/resume worden als events opgeslagen.

Errors

404: technieker of entry niet gevonden.
400: ongeldige status of ontbrekende velden.

Voorbeeld (curl)

curl -X POST "https://werftijd.be/api/external/time-entries/start" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "EXT-123",
    "technician_email": "user@bedrijf.be",
    "started_at": "2026-03-19T08:00:00Z",
    "start_lat": 51.2194,
    "start_lng": 4.4025
  }'