REST API v1 · JSON

Koldwerk API

Lees klanten, installaties, werkbonnen en logboeken uit je Koldwerk-werkruimte vanuit eigen ETL-jobs, BI-tools of integraties. JSON-only, scoped Personal Access Tokens, rate-limit van 60 verzoeken per minuut per token.

Installaties kun je ook aanmaken en bijwerken. Dat schrijfpad is nieuw en is nog niet door een externe koppeling in productie gebruikt — bouw je eraan, laat het ons dan weten, dan lopen we mee.

Token aanmaken

Eigenaars genereren tokens in de app, onder Instellingen → API-tokens.

Tenant-scope

Elk token zit vast aan één werkruimte — cross-tenant lookup is niet mogelijk.

Rate-limit

60 requests per minuut per token. 429 + Retry-After bij overschrijding.

Authenticatie

Stuur het token in de Authorization-header als Bearer-credential. Het token wordt nooit door Koldwerk in plaintext bewaard — bij verlies maak je een nieuwe aan en trek je de oude in.

curl https://koldwerk.nl/api/v1/klanten \
  -H "Authorization: Bearer koldwerk_pat_xxxxxxxxxxxxxxxxxxxxxxxx"

Scopes

read:klanten

NAW + KvK + adres van klanten.

read:installaties

Installatie-metadata incl. koudemiddel-velden.

read:werkbonnen

Werkbonnen incl. handelingen en uren — zonder handtekening-base64.

read:logboeken

Audit-log entries (BRL 100 7-jaars traceability).

write:installaties

Installaties aanmaken en bijwerken. Koudemiddel, vulling, interne notities en de LMRA-verplichting blijven buiten bereik.

Endpoints

Methode	Pad	Scope	Beschrijving
GET	/api/v1/klanten	`read:klanten`	Gepagineerde klantenlijst (PII gedecodeerd).
GET	/api/v1/klanten/{id}	`read:klanten`	Detail van één klant.
GET	/api/v1/installaties	`read:installaties`	Installaties — filter op `customerId`.
GET	/api/v1/installaties/{id}	`read:installaties`	Detail van één installatie. Geeft een `ETag` terug.
POST	/api/v1/installaties	`write:installaties`	Installatie aanmaken. Vereist `Idempotency-Key`.
PATCH	/api/v1/installaties/{id}	`write:installaties`	Installatie bijwerken. Vereist `Idempotency-Key` + `If-Match`.
GET	/api/v1/werkbonnen	`read:werkbonnen`	Werkbonnen — filter op `installationId`, `from`, `to`.
GET	/api/v1/werkbonnen/{id}	`read:werkbonnen`	Werkbon-detail (zonder handtekening-base64).
GET	/api/v1/logboeken	`read:logboeken`	Audit-log — filter op `entity`, `entityId`, `from`, `to`.

Voorbeeld-flow

# 1. Lijst van klanten ophalen
curl "https://koldwerk.nl/api/v1/klanten?page=1&perPage=50" \
  -H "Authorization: Bearer $TOKEN"

# 2. Installaties van één klant
curl "https://koldwerk.nl/api/v1/installaties?customerId=cmxxxxx" \
  -H "Authorization: Bearer $TOKEN"

# 3. Werkbonnen van afgelopen maand
curl "https://koldwerk.nl/api/v1/werkbonnen?from=2026-04-01&to=2026-05-01" \
  -H "Authorization: Bearer $TOKEN"

# 4. Audit-log van één werkbon
curl "https://koldwerk.nl/api/v1/logboeken?entity=WorkOrder&entityId=cmxxxxx" \
  -H "Authorization: Bearer $TOKEN"