Changelog

Änderungshistorie der Kinmu Public API. Inkompatible Änderungen passieren nie innerhalb einer Major-Version: Sie kommen in eine neue Version und werden hier angekündigt.

Versionierungspolitik

Die Version steht in der URL: https://api.kinmu.app/v1.
Eingefrorener Vertrag innerhalb von v1. Wir führen keine inkompatiblen Änderungen in v1 ein.

Was wir als kompatible Änderung betrachten (bricht nichts)

Diese Änderungen können in v1 ohne Vorankündigung passieren; deine Integration muss sie tolerieren:

Neue Endpoints oder Ressourcen hinzufügen.
Neue Felder in einer Antwort hinzufügen.
Neue Werte in einem als erweiterbar dokumentierten Enum hinzufügen (z. B. eigene Abwesenheitstypen).
Optionale Parameter in Query oder Body hinzufügen.
Den Text von Fehlermeldungen ändern (title, detail) — deshalb muss deine Logik auf dem stabilen Feld code basieren.

Baue tolerante Clients. Ignoriere unbekannte Felder und verlasse dich nicht auf eine feste Reihenfolge in Listen. So betreffen dich kompatible Änderungen nicht.

Was wir als inkompatible Änderung betrachten (bricht)

Erfordert eine neue Major-Version (v2):

Einen Endpoint, ein Feld oder einen Enum-Wert entfernen oder umbenennen.
Den Typ eines Felds ändern oder es verpflichtend machen.
Die Bedeutung eines Felds oder den Code eines Fehlers ändern.

Deprecation-Policy (12 Monate)

Wenn wir einen Endpoint, ein Feld oder eine Version deprecaten:

Wird es in diesem Changelog und auf der Entwickler-Mailingliste angekündigt.
Wird es im OpenAPI-Spec als deprecated markiert und, wo zutreffend, mit den Response-Headern Deprecation + Sunset versehen.
Bleibt es ab der Ankündigung mindestens 12 Monate in Betrieb, bevor es entfernt wird.

Abonniere die Ankündigungen auf der Support-Seite.

Historie

Alle unten aufgeführten Änderungen sind kompatibel: Keine bricht eine bestehende v1-Integration. Sie stehen hier, weil sie das beobachtbare Verhalten ändern.

2026-08-27 — OpenAPI-Spec und `updated_since`

Die Spec deklariert jetzt die Codes 402 und 409 sowie die X-RateLimit-*-Header, die die API bereits ausgeliefert hat.
Der 409 ist zusätzlich bei POST /v1/reports und bei den idempotenten Webhook-Operationen deklariert, wo er fehlte.
updated_since in GET /v1/webhook-endpoints implementiert.
updated_since als veraltet (deprecated) markiert bei GET /v1/vacation-balances und GET /v1/work-summaries: Es hat bei diesen Ressourcen nie gefiltert. Es wird weiterhin wirkungslos akzeptiert — damit regenerierte SDKs nicht brechen — und am 27.08.2027 entfernt, gemäß der 12-Monats-Deprecation-Politik. Frage bei diesen Aggregaten den Zeitraum erneut ab (year, from/to). Siehe Konventionen.

2026-08-20 — Mitarbeiter-E-Mail pro Unternehmen eindeutig

Die Eindeutigkeit der E-Mail beim Anlegen einer Person gilt jetzt pro Unternehmen (vorher global). Anlagen, die zuvor mit 422 an einer Kollision mit der E-Mail eines anderen Unternehmens scheiterten, werden jetzt akzeptiert.

2026-08-10 — Sandbox und Keys werden deprovisioniert

Beim Deaktivieren des Public-API-Addons werden alle API-Keys widerrufen (Grund addon_disabled), die erzeugten Reports gelöscht und das Sandbox-Unternehmen samt Daten entfernt. Ein erneutes Aktivieren provisioniert eine leere Sandbox und stellt die Keys nicht wieder her. Siehe Sandbox.

2026-07-31 — Abo-Gate und Widerruf

Das Abo-Gate wird strenger: abgelaufene Testphase, gekündigtes und abgelaufenes Abonnement, verfallenes Abonnement und archiviertes Unternehmen liefern in /v1 jetzt 403 subscription_inactive.
Das Widerrufen von API-Keys und Webhooks (DELETE) verlangt kein aktives Abonnement mehr: Eine Credential abzuschalten ist eine Sicherheitsmaßnahme und muss immer möglich sein.

2026-07-30 — Unternehmenseinstellungen bei der Key-Ausstellung

Die Ausstellung von API-Keys berücksichtigt die Addon-Einstellungen pro Unternehmen: default_expiration_days (Ablauf, wenn du keinen expliziten anforderst) und max_active_keys (Obergrenze aktiver Keys, standardmäßig 10).

`v1` · 1.0.0

OpenAPI-Spec veröffentlicht (openapi-v1.json, v1.0.0). Die interaktive Referenz liest den echten Spec. Die Oberfläche von v1 ist ein eingefrorener Vertrag; Änderungen werden hier mit der 12-monatigen Deprecation-Policy angekündigt.

Ressourcen des Launch (MVP):

Organization — GET /v1/organization (Introspektion).
Employees — auflisten, abrufen, anlegen, aktualisieren und austragen.
Check-ins — Stempelungen auflisten, abrufen und erfassen.
Work summaries — aggregierte Arbeitszeiten für die Lohnabrechnung.
Absences — auflisten, abrufen, erstellen, genehmigen und ablehnen.
Vacation balances — Urlaubssalden.
Locations / Units — Organisationsstruktur (nur lesend).
Reports — asynchrone Reports (gesetzlicher Arbeitszeitnachweis und Exporte), mit Datei-Download über GET /v1/reports/{id}/download.

Webhooks:

Signierte ausgehende Events (Standard Webhooks): Verwaltung von Endpoints, ping-Versand, Auflisten der Zustellungen und manuelles Neueinstellen einer Zustellung über POST /v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry.