Changelog

Wijzigingshistorie van de Kinmu Public API. Incompatibele wijzigingen worden nooit binnen een major versie doorgevoerd: ze komen in een nieuwe versie en worden hier aangekondigd.

Versiebeleid

• De versie staat in de URL: https://api.kinmu.app/v1.
• Bevroren contract binnen v1. We voeren geen incompatibele wijzigingen door in v1.

Wat we een compatibele wijziging noemen (breekt niet)

Deze wijzigingen kunnen zonder aankondiging in v1 plaatsvinden; je integratie moet ze kunnen verwerken:

• Nieuwe endpoints of resources toevoegen.
• Nieuwe velden toevoegen aan een response.
• Nieuwe waarden toevoegen aan een enum die als uitbreidbaar is gedocumenteerd (bijv. custom afwezigheidstypen).
• Optionele parameters toevoegen aan query of body.
• De tekst van foutmeldingen wijzigen (title, detail) — baseer je logica daarom op het stabiele veld code.

Wat we een incompatibele wijziging noemen (breekt)

Vereist een nieuwe major versie (v2):

• Een endpoint, veld of enum-waarde verwijderen of hernoemen.
• Het type van een veld wijzigen of het verplicht maken.
• De betekenis van een veld of de code van een fout wijzigen.

Deprecatiebeleid (12 maanden)

Wanneer we een endpoint, veld of versie depreceren:

1. We kondigen het aan in deze changelog en op de developer-mailinglijst.
2. We markeren het als deprecated in de OpenAPI-spec en, waar van toepassing, met de response-headers Deprecation + Sunset.
3. Het blijft minimaal 12 maanden na de aankondiging werken voordat het verdwijnt.

Abonneer je op de aankondigingen via de supportpagina.

Historie

2026-08-27 — OpenAPI-spec en updated_since

• De spec declareert nu de codes 402 en 409 en de X-RateLimit-*-headers, die de API al meestuurde.
• De 409 staat nu ook bij POST /v1/reports en bij de idempotente webhook-operaties, waar hij ontbrak.
• updated_since geïmplementeerd op GET /v1/webhook-endpoints.
• updated_since als verouderd (deprecated) gemarkeerd bij GET /v1/vacation-balances en GET /v1/work-summaries: op die resources heeft hij nooit gefilterd. Hij wordt nog zonder effect geaccepteerd — zodat opnieuw gegenereerde SDK’s niet breken — en verdwijnt op 27-08-2027, volgens het deprecatiebeleid van 12 maanden. Vraag voor deze aggregaties de periode opnieuw op (year, from/to). Zie conventies.

2026-08-20 — e-mail van medewerker uniek per bedrijf

• De uniciteit van het e-mailadres bij het aanmaken van een medewerker geldt nu per bedrijf (voorheen wereldwijd). Aanmaken die eerder met 422 mislukten door een botsing met het e-mailadres van een ander bedrijf worden nu geaccepteerd.

2026-08-10 — sandbox en keys worden opgeruimd

• Bij het uitschakelen van de Public API-addon worden alle API-keys ingetrokken (reden addon_disabled), worden de gegenereerde rapporten verwijderd en wordt het sandboxbedrijf met alle data verwijderd. Opnieuw inschakelen levert een leeg sandboxbedrijf op en herstelt de keys niet. Zie sandbox.

2026-07-31 — abonnementsgate en intrekken

• De abonnementsgate wordt strenger: een opgebruikte proefperiode, een opgezegd en verstreken abonnement, een verlopen abonnement en een gearchiveerd bedrijf geven nu 403 subscription_inactive op /v1.
• Het intrekken van API-keys en webhooks (DELETE) vereist geen actief abonnement meer: een credential stilleggen is een beveiligingsmaatregel en moet altijd kunnen.

2026-07-30 — bedrijfsinstellingen bij het uitgeven van keys

• Het uitgeven van API-keys volgt de addon-instellingen per bedrijf: default_expiration_days (verloopdatum die wordt toegepast als je er geen expliciete vraagt) en max_active_keys (maximum aantal actieve keys, standaard 10).

v1 · 1.0.0

Resources bij de launch (MVP):

• Organization — GET /v1/organization (introspectie).
• Employees — medewerkers weergeven, ophalen, aanmaken, bijwerken en uit dienst melden.
• Check-ins — check-ins weergeven, ophalen en registreren.
• Work summaries — geaggregeerde werktijden voor de salarisadministratie.
• Absences — weergeven, ophalen, aanmaken, goedkeuren en afwijzen.
• Vacation balances — verlofsaldi.
• Locations / Units — organisatiestructuur (alleen-lezen).
• Reports — asynchrone rapporten (wettelijke urenregistratie en exports), met download van het bestand via GET /v1/reports/{id}/download.

Webhooks:

• Ondertekende uitgaande events (Standard Webhooks): endpointbeheer, ping versturen, deliveries weergeven en het handmatig opnieuw in de wachtrij zetten van een delivery via POST /v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry.