KlaarZZP API

Met de API registreer je automatisch uren en ritten vanuit je eigen tools (bijvoorbeeld Zapier, Make, Apple Shortcuts of een eigen script) en haal je je cijfers op. De API hoort bij een actief abonnement of proefperiode van KlaarZZP Online.

Authenticatie

Maak een sleutel aan in de app via Instellingen › API-sleutels en stuur hem mee als Bearer-token:

Authorization: Bearer kz_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Basis-URL: https://klaarzzp.nl/api/v1/ · Formaat: JSON · Bedragen in de API-antwoorden zijn in centen.

Endpoints

Methode	Pad	Omschrijving
GET	`/hours?year=2027`	Uren van een jaar
POST	`/hours`	Uren toevoegen: `{"date":"2027-01-04","hours":7.5,"client":"Jansen","activity":"Ontwerp","billable":true}`
GET / POST	`/trips`	Ritten: `{"date":"2027-01-04","km":42,"kind":"zakelijk","from_loc":"Hilversum","to_loc":"Amsterdam","purpose":"Klantbezoek"}` · kind: zakelijk, woon-werk of prive
GET / POST	`/expenses`	Uitgaven: `{"date":"2027-02-01","total":121.00,"vat_rate":21,"category":"software","business_pct":100}`
GET / POST	`/clients`	Klanten: `{"name":"Jansen BV","email":"","address":"","vat_id":""}`
PUT / DELETE	`/{hours\|trips\|expenses\|clients}/{id}`	Wijzigen of verwijderen
GET	`/invoices?year=2027`	Facturen van een jaar
POST	`/invoices`	Factuur maken: `{"client_id":"cl_…","lines":[{"description":"Ontwerp","qty":10,"price":85,"vat_rate":21}]}`
POST	`/invoices/{id}/status`	Markeer betaald: `{"status":"betaald","paid_at":"2027-03-20"}`
GET	`/vat?year=2027`	Btw-aangifte per kwartaal (rubriek 1a, 1b, 1e, 5b, te betalen, deadline)
GET	`/dashboard?year=2027`	Omzet, winst, uren, urencriterium, kilometers

Voorbeeld (curl)

curl -X POST https://klaarzzp.nl/api/v1/trips \
  -H "Authorization: Bearer $KLAARZZP_KEY" \
  -H "content-type: application/json" \
  -d '{"date":"2027-01-04","km":42,"kind":"zakelijk","purpose":"Klantbezoek"}'

Foutcodes

401 ontbrekende of ongeldige sleutel
402 geen actief abonnement (lezen kan nog, schrijven niet)
404 niet gevonden
422 ongeldige invoer (zie error in het antwoord)

Vragen of een koppeling nodig? Mail support@klaarzzp.nl.