Partner-API — Dokumentation

Version 0.2.0 · Maschinenlesbare Spezifikation: openapi.yaml (OpenAPI 3.1)

Status: Endpunkte, Authentifizierung und Antwort-Konventionen entsprechen dem Zielstand der v1: OAuth2-Client-Registry, Freigaben durch die Einrichtungen, vollständige Zugriffs-Protokollierung. Diese Umgebung ist Staging mit Demo-Daten; der Produktivbetrieb startet nach Vereinbarung.

Überblick

Die KiDig Partner-API stellt Stammdaten von Einrichtungen für Integrationspartner bereit. Grundprinzip: Eine Einrichtung wird erst abrufbar, nachdem die Einrichtungsleitung die Partner-Anbindung in KiDig aktiviert hat (Freigabe / Grant). Diese Freigabe wird bei jeder Anfrage serverseitig geprüft — ein gültiges Token allein genügt nicht.

Alle Antworten sind JSON, Feldnamen sind englisch, Datumsangaben folgen ISO 8601. Die API ist unter /v1/ versioniert; neue optionale Felder können jederzeit hinzukommen und sind von Clients zu ignorieren. Jeder erfolgreiche Datenabruf wird im Prüfprotokoll der jeweiligen Einrichtung mit Ihrem System als Akteur vermerkt.

Authentifizierung

OAuth2 Client-Credentials: Mit Ihrer client_id und Ihrem client_secret fordern Sie ein Access-Token an. Das Token ist 30 Minuten gültig und wird als Authorization: Bearer-Header mitgesendet.

curl -X POST https://api-staging.kidig-online.de/v1/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
        "grant_type": "client_credentials",
        "client_id": "IHRE_CLIENT_ID",
        "client_secret": "IHR_CLIENT_SECRET"
      }'

Antwort:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 1800,
  "scope": "facility:read"
}

Fehler am Token-Endpunkt folgen RFC 6749: 401 {"error":"invalid_client"} bei falschen Zugangsdaten, 400 {"error":"unsupported_grant_type"} bei anderem grant_type.

Einrichtungen auflisten

GET/v1/facilities

Liefert alle Einrichtungen, die Ihrem System aktuell eine Freigabe erteilt haben — Sie müssen keine IDs austauschen. Das Feld externalFacilityId enthält den Verbindungscode, den die Einrichtungsleitung bei der Freigabe eingegeben hat: Ihr Schlüssel zum Abgleich mit Ihren eigenen Datensätzen. Widerrufene Einrichtungen verschwinden sofort aus der Liste.

{
  "facilities": [
    {
      "id": "9a261ab8-06f6-4ff7-b4b2-ed0995b2daf9",
      "name": "Kindergarten Gartenkind",
      "externalFacilityId": "KRZ-4711",
      "grantedAt": "2026-08-20T14:32:10.000Z"
    }
  ]
}

Empfohlener Sync: nächtlich diese Liste abrufen (mit ETag), neue Einträge zuordnen, dann pro Einrichtung die Detaildaten laden. Jeder Detailabruf wird im Prüfprotokoll der Einrichtung vermerkt.

Einrichtung abrufen

GET/v1/facilities/{facilityId}

curl https://api-staging.kidig-online.de/v1/facilities/9a261ab8-06f6-4ff7-b4b2-ed0995b2daf9 \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "9a261ab8-06f6-4ff7-b4b2-ed0995b2daf9",
  "name": "Kindergarten Gartenkind",
  "address": {
    "street": "Bienemajastraße 5",
    "zipCode": "79123",
    "town": "Marktfrühstück"
  },
  "country": "DE",
  "federalState": "BW"
}

Feld	Bedeutung
`id`	KiDig-UUID der Einrichtung
`name`	Name der Einrichtung
`address.street`	Straße und Hausnummer (kann `null` sein)
`address.zipCode`, `address.town`	PLZ und Ort (können `null` sein)
`country`	ISO 3166-1 alpha-2, z. B. `DE`
`federalState`	Bundesland-Kürzel, z. B. `BW`. Gesetzliche Feiertage berechnet KiDig selbst daraus — Partner senden bzw. leiten keine Feiertage ab.

Fehlerformat

Alle Fehler (außer am Token-Endpunkt und bei 429, siehe unten) sind RFC 7807 application/problem+json:

{
  "type": "https://api.kidig-online.de/problems/no-grant",
  "title": "No active grant for this facility",
  "status": 403,
  "requestId": "8e60828b-e7e0-4258-af83-d389a0f5a6ca"
}

Status	Bedeutung
`400`	`facilityId` ist keine UUID
`401`	Token fehlt, ist ungültig oder abgelaufen → neues Token anfordern
`403`	Keine aktive Freigabe für diese Einrichtung (oder die Einrichtungsleitung hat die Freigabe widerrufen)
`404`	Einrichtung existiert nicht
`429`	Rate-Limit erreicht. Diese Antwort kommt direkt vom vorgelagerten Limiter und hat keinen problem+json-Body und keine `X-Request-Id` — kurz warten und erneut versuchen

Wichtig für Ihre Fehlerbehandlung: 401 bedeutet „Token-Problem auf Ihrer Seite“, 403 bedeutet „die Einrichtung hat (noch) nicht freigegeben“. Bitte behandeln Sie beide Fälle getrennt.

Caching & Polling

Stammdaten ändern sich selten. Das empfohlene Sync-Muster ist nächtliches Polling mit ETags:

Bei jeder 200-Antwort den ETag-Header speichern.
Beim nächsten Abruf If-None-Match: "<etag>" mitsenden.
Unverändert → 304 Not Modified ohne Body. Geändert → 200 mit neuem ETag; die Unterschiede ermitteln Sie durch Vergleich mit Ihrem letzten Stand.

curl -i https://…/v1/facilities/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-None-Match: "01e5ac7f0c34227087f77a6a9f353c5a"'

Header & Support

Jede Antwort enthält einen X-Request-Id-Header (bei Fehlern zusätzlich als requestId im Body). Bitte geben Sie diese ID bei Support-Anfragen an — damit können wir die konkrete Anfrage in unseren Logs nachvollziehen.

Rate Limits

Aktuell gilt ein Limit von 5 Anfragen pro Sekunde pro IP; der Token-Endpunkt ist zusätzlich auf 10 Anfragen pro Minute pro IP begrenzt (ein Token gilt 30 Minuten — bitte wiederverwenden). Für den Produktivbetrieb ist ein partnerspezifisches Kontingent vorgesehen; bitte verteilen Sie Bulk-Synchronisierungen zeitlich (z. B. nächtlich, sequenziell).

Versionierung

Breaking Changes erscheinen nur unter einem neuen Pfad-Präfix (/v2/). Innerhalb von /v1/ gilt: neue Endpunkte, neue optionale Felder und neue Enum-Werte sind jederzeit möglich — Clients müssen unbekannte Felder und Werte ignorieren.