UurKlus
Integraties

API voor AI agents en Make

Met een API key kan een externe agent klanten, projecten, urenboekingen en conceptfacturen ophalen of aanmaken. Facturen worden bewust als concept aangemaakt, zodat je ze in UurKlus kunt controleren voordat je ze finaliseert of verstuurt.

Basis

Maak eerst een API key aan via Bedrijfsinstellingen > Integraties.

Base URL
https://uurklus.nl/api/agents/v1
Authenticatie
Authorization: Bearer uk_live_jouw_api_key

Testen vanuit ChatGPT

Een gewone chat kan meestal geen externe API met Bearer-header aanroepen.

Gebruik hiervoor een Custom GPT Action, een OpenAI Agent tool, Make, Postman of curl. De browser zonder Authorization-header geeft terecht Unauthorized terug.

Importeer onderstaand OpenAPI-schema in je Action/tool configuratie en stel de API key in als Bearer token.

OpenAPI-schema openen
Action authenticatie

Kies API key of Bearer authentication en gebruik je UurKlus API key als token.

Endpoints

Gebruik /{id} voor een specifiek record, of de lijst zonder id.

Methode Pad Doel
GET/clientsKlanten ophalen
GET/clients/{id}Een klant ophalen
POST/clientsKlant aanmaken
GET/projectsProjecten ophalen
GET/projects/{id}Een project ophalen
POST/projectsProject aanmaken
GET/invoicesLaatste 100 facturen ophalen
GET/invoices/{id}Een factuur met regels ophalen
POST/invoicesConceptfactuur aanmaken
GET/time-entriesLaatste 100 urenboekingen ophalen
GET/time-entries/{id}Een urenboeking ophalen
POST/time-entriesUren boeken op een actief project

Validatie voor uren

Uren boeken is bewust strikt, zodat een agent geen rommel of dubbele interpretaties opslaat.

projectId, date en durationMinutes zijn verplicht. Het project moet actief zijn en bij dezelfde administratie horen als de API key.

durationMinutes moet positief zijn, maximaal 1440 minuten en een veelvoud van 5. date mag niet vóór 2000-01-01 liggen en maximaal 31 dagen in de toekomst.

startTimeUtc en endTimeUtc zijn optioneel, maar moeten samen worden aangeleverd als UTC-tijd met Z. De berekende duur moet exact gelijk zijn aan durationMinutes.

Limieten

Elke API key heeft eigen limieten om loops en misbruik te voorkomen.

Per minuut
60

Maximaal 60 requests per API key per minuut.

Per dag
1000

Maximaal 1000 requests per API key per UTC-dag.

Bij overschrijding retourneert de API 429 Too Many Requests met een Retry-After header.

Concrete voorbeelden

De API accepteert JSON. Enumvelden gebruik je als tekst, zoals Business, Hourly of FixedFee.

Klant aanmaken
curl -X POST https://uurklus.nl/api/agents/v1/clients \
  -H "Authorization: Bearer uk_live_jouw_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Acme B.V.\",\"type\":\"Business\",\"email\":\"info@acme.nl\",\"invoiceEmail\":\"invoices@acme.nl\"}"
Project aanmaken
{
  "clientId": "00000000-0000-0000-0000-000000000000",
  "name": "Website onderhoud",
  "billingType": "Hourly",
  "hourlyRate": 85
}
Uren boeken
{
  "projectId": "11111111-1111-1111-1111-111111111111",
  "date": "2026-05-12",
  "startTimeUtc": "2026-05-12T07:00:00Z",
  "endTimeUtc": "2026-05-12T09:30:00Z",
  "durationMinutes": 150,
  "type": "Work",
  "isBillable": true,
  "description": "Landingpage gebouwd en getest"
}
Conceptfactuur aanmaken
{
  "clientId": "00000000-0000-0000-0000-000000000000",
  "projectId": "11111111-1111-1111-1111-111111111111",
  "invoiceDate": "2026-04-30",
  "customerReference": "PO-2026-001",
  "lines": [
    {
      "lineType": "Time",
      "description": "Ontwikkelwerk april",
      "quantity": 6.5,
      "unit": "uur",
      "unitPrice": 85,
      "vatRate": 21
    }
  ]
}