{"openapi":"3.1.0","info":{"title":"UurKlus Agent API","version":"1.0.0","description":"API voor AI agents en automatiseringen om klanten, projecten, urenboekingen en conceptfacturen te lezen en aan te maken."},"servers":[{"url":"https://uurklus.nl/api/agents/v1"}],"paths":{"/clients":{"get":{"operationId":"listClients","summary":"Klanten ophalen","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}},"post":{"operationId":"createClient","summary":"Klant aanmaken","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentClientRequest"}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}}},"/clients/{id}":{"get":{"operationId":"getClient","summary":"Klant ophalen","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}}},"/projects":{"get":{"operationId":"listProjects","summary":"Projecten ophalen","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}},"post":{"operationId":"createProject","summary":"Project aanmaken","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProjectRequest"}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}}},"/projects/{id}":{"get":{"operationId":"getProject","summary":"Project ophalen","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}}},"/invoices":{"get":{"operationId":"listInvoices","summary":"Facturen ophalen","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}},"post":{"operationId":"createInvoice","summary":"Conceptfactuur aanmaken","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentInvoiceRequest"}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}}},"/invoices/{id}":{"get":{"operationId":"getInvoice","summary":"Factuur ophalen","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}}},"/time-entries":{"get":{"operationId":"listTimeEntries","summary":"Laatste 100 urenboekingen ophalen","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}},"post":{"operationId":"createTimeEntry","summary":"Uren boeken","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTimeEntryRequest"}}}},"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}}},"/time-entries/{id}":{"get":{"operationId":"getTimeEntry","summary":"Urenboeking ophalen","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}},"schemas":{"AgentClientRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Klantnaam"},"type":{"type":"string","enum":["Business","Private"]},"contactName":{"type":"string","description":"Contactpersoon"},"email":{"type":"string","description":"E-mailadres"},"invoiceEmail":{"type":"string","description":"Factuur e-mailadres"},"preferredLanguage":{"type":"string","enum":["nl-NL","en-US"]},"phone":{"type":"string","description":"Telefoon"},"mobile":{"type":"string","description":"Mobiel"},"street":{"type":"string","description":"Straat"},"houseNumber":{"type":"string","description":"Huisnummer"},"postalCode":{"type":"string","description":"Postcode"},"city":{"type":"string","description":"Plaats"},"country":{"type":"string","description":"Landcode of landnaam"},"vatNumber":{"type":"string","description":"BTW nummer"},"chamberOfCommerceNumber":{"type":"string","description":"KvK nummer"},"notes":{"type":"string","description":"Notities"}}},"AgentProjectRequest":{"type":"object","required":["clientId","name"],"properties":{"clientId":{"type":"string","format":"uuid","description":"Client GUID"},"name":{"type":"string","description":"Projectnaam"},"description":{"type":"string","description":"Omschrijving"},"referenceCode":{"type":"string","description":"Referentie"},"status":{"type":"string","enum":["Draft","Active","Completed","Cancelled"]},"billingType":{"type":"string","enum":["Hourly","FixedFee"]},"plannedStartDate":{"type":"string","format":"date","description":"Startdatum"},"plannedEndDate":{"type":"string","format":"date","description":"Einddatum"},"hourlyRate":{"type":"number","format":"decimal"},"fixedPriceAmount":{"type":"number","format":"decimal"},"fixedPriceDescription":{"type":"string","description":"Vaste prijs omschrijving"},"street":{"type":"string","description":"Straat"},"houseNumber":{"type":"string","description":"Huisnummer"},"postalCode":{"type":"string","description":"Postcode"},"city":{"type":"string","description":"Plaats"},"country":{"type":"string","description":"Landcode of landnaam"}}},"AgentInvoiceRequest":{"type":"object","required":["clientId"],"properties":{"clientId":{"type":"string","format":"uuid","description":"Client GUID"},"projectId":{"type":"string","format":"uuid","description":"Project GUID"},"invoiceDate":{"type":"string","format":"date","description":"Factuurdatum"},"dueDate":{"type":"string","format":"date","description":"Vervaldatum"},"customerReference":{"type":"string","description":"Klantreferentie"},"buyerReference":{"type":"string","description":"Buyer reference"},"orderReference":{"type":"string","description":"Orderreferentie"},"notes":{"type":"string","description":"Notities"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/AgentInvoiceLineRequest"}}}},"AgentInvoiceLineRequest":{"type":"object","required":["description","unitPrice"],"properties":{"lineType":{"type":"string","enum":["Time","Material","FixedFee","Discount"]},"description":{"type":"string","description":"Omschrijving"},"quantity":{"type":"number","format":"decimal"},"unit":{"type":"string","description":"Eenheid"},"unitPrice":{"type":"number","format":"decimal"},"vatRate":{"type":"number","format":"decimal"}}},"AgentTimeEntryRequest":{"type":"object","additionalProperties":false,"required":["projectId","date","durationMinutes"],"properties":{"projectId":{"type":"string","format":"uuid","description":"Project GUID. Het project moet actief zijn en bij dezelfde administratie horen."},"date":{"type":"string","format":"date","description":"Werkdatum. Toegestaan bereik: vanaf 2000-01-01 tot maximaal 31 dagen in de toekomst."},"startTimeUtc":{"type":"string","format":"date-time","description":"Optioneel. UTC starttijd. Als startTimeUtc is gevuld, is endTimeUtc verplicht en moet durationMinutes exact overeenkomen."},"endTimeUtc":{"type":"string","format":"date-time","description":"Optioneel. UTC eindtijd. Moet na startTimeUtc liggen."},"durationMinutes":{"type":"integer","minimum":5,"maximum":1440,"multipleOf":5,"description":"Duur in minuten. Verplicht, positief, maximaal 24 uur en altijd een veelvoud van 5."},"type":{"type":"string","enum":["Work","Travel","Break","Other"]},"isBillable":{"type":"boolean","description":"Standaard true. Als false wordt totalAmount niet berekend."},"hourlyRate":{"type":"number","format":"decimal","minimum":0,"maximum":100000,"description":"Optioneel uurtarief voor deze boeking. Als leeg, gebruikt UurKlus het projecttarief."},"description":{"type":"string","maxLength":2000,"description":"Korte omschrijving van het werk."}}}}},"security":[{"bearerAuth":[]}]}