Dokumentation › API-Dokumentation
API-Dokumentation
Die Kindfair-API liest die Daten eines Betriebs für seine eigenen Systeme — Lohn, Personal, Planung. Schlüssel, Bereiche, Endpunkte, Fehler und Beispiele.
Die Kindfair-API gibt die Daten EINES Betriebs an dessen eigene Systeme weiter: an das Lohn- und Buchhaltungsprogramm, die Personalverwaltung, einen Kalender oder ein Fachverfahren. Sie liest nur — schreiben, ändern oder löschen lässt sich über sie nichts. Jede Anfrage braucht einen Schlüssel, und jeder Schlüssel öffnet nur die Bereiche, für die er ausgestellt ist.
Kindfair-API · Version 1.0.0 · Basisadresse: https://kindfair.net/api/v1
Schnellstart
- Der Admin deines Betriebs erzeugt unter Einstellungen › API-Zugriff einen Schlüssel und wählt nur die Bereiche, die dein System braucht.
- Hinterlege den Schlüssel in der geschützten Konfiguration deines Systems, etwa als Umgebungsvariable. Er erscheint nur einmal.
- Prüfe die Verbindung mit dem Endpunkt „Der eigene Schlüssel". Er nennt Betrieb, Bereiche und Ablauf.
- Hol danach die Daten seitenweise ab — mit cursor, bis naechster_cursor null ist.
export KINDFAIR_API_SCHLUESSEL="kfk_DEIN_SCHLUESSEL" curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/schluessel" # Nächste Seite curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/mitarbeitende?grenze=100&cursor=<naechster_cursor>"
Fragen zur Anbindung: Schreib an support@kindfair.net. Den Schlüssel selbst bekommst du vom Admin deines Betriebs, nicht vom Anbieter.
Schlüssel erzeugen
Den Schlüssel erzeugt der Admin des Betriebs selbst unter Einstellungen › API-Zugriff. Er gibt ihm einen Namen (z. B. „Lohnprogramm“), einen Zweck, die Bereiche, die er öffnen soll, und eine Laufzeit von höchstens einem Jahr. Gleichzeitig aktiv sein können höchstens 10 Schlüssel.
Das Erzeugen eines Schlüssels ist eine Weisung des Betriebs im Sinne des Vertrags zur Auftragsverarbeitung (§ 6): der Betrieb entscheidet, welche Daten an welches seiner Systeme gehen, und bleibt für die Verarbeitung dort verantwortlich.
Der Schlüssel erscheint genau einmal. Er wird nur als Prüfwert gespeichert und lässt sich nicht wiederherstellen — geht er verloren, wird ein neuer erzeugt und der alte gesperrt. Unter Einstellungen › API-Zugriff sieht der Admin jeden Schlüssel seines Betriebs mit Präfix, Bereichen, Ablauf und letzter Nutzung, dazu jeden einzelnen Abruf, und sperrt einen Schlüssel dort sofort und endgültig.
Authentifizierung
Der Schlüssel steht in jeder Anfrage in der Kopfzeile: Authorization: Bearer kfk_… — nie in der Adresse. Er beginnt mit „kfk_“ und ist 47 Zeichen lang. Er gehört in die geschützte Konfiguration des Systems, das ihn benutzt, nicht in ein Skript im Browser: die API antwortet Browsern fremder Seiten nicht (kein CORS).
Ein gesperrter, abgelaufener oder unbekannter Schlüssel bekommt 401. Wird ein Betrieb gesperrt, gilt keiner seiner Schlüssel mehr.
Bereiche (Scopes)
Ein Schlüssel öffnet nur die Bereiche, für die er ausgestellt ist. Fehlt der Bereich eines Endpunkts, antwortet die API mit 403 und liefert keine Daten. Den Bereich „klienten:lesen“ nur wählen, wenn das Zielsystem ihn wirklich braucht: er öffnet Sozialdaten der betreuten Personen, oft Minderjähriger.
Jeder Schlüssel öffnet nur die Bereiche, für die er ausgestellt ist.
| lohn:lesen | Lohn und Buchhaltung. Endpunkte: Abrechnungen, Auslagen, Fahrten, Abwesenheiten |
|---|---|
| personal:lesen | Personal. Endpunkte: Mitarbeitende |
| bewerbungen:lesen | Bewerbungen. Endpunkte: Bewerbungen |
| klienten:lesen | Klienten und Fachdaten. Endpunkte: Klienten, ProtokolleSozialdaten — nur wählen, wenn das System sie wirklich braucht. |
| planung:lesen | Planung und Kalender. Endpunkte: Abwesenheiten, Einsätze |
Paginierung
Listen kommen seitenweise, nach Kennung sortiert. grenze legt die Seitengröße fest (1 bis 500, Vorgabe 100). Ist die Seite voll, steht in naechster_cursor die Kennung des letzten Datensatzes — sie gehört als cursor in die nächste Anfrage. Auf der letzten Seite ist naechster_cursor null.
Neue Datensätze erscheinen dort, wo ihre Kennung sie einsortiert, nicht am Ende. Für einen Abgleich empfiehlt sich deshalb ein vollständiger Durchlauf je Tag oder ein Zeitraum mit von und bis.
Ratenbremse
Je Schlüssel höchstens 120 Anfragen in der letzten Minute, gleitend gezählt. Darüber antwortet die API mit 429 und der Kopfzeile Retry-After. Auch abgewiesene Anfragen zählen mit — ein System, das sofort erneut fragt, verlängert die Sperre, statt sie zu verkürzen.
Protokoll
Jeder Abruf mit einem bekannten Schlüssel wird protokolliert: Schlüssel, Endpunkt, Zeitpunkt, Antwort und Anzahl der gelieferten Datensätze — keine Inhalte, keine Filter, keine IP-Adresse. Der Admin des Betriebs sieht das Protokoll; es wird nach 30 Tagen gelöscht.
Versionierung
Die Version steht im Pfad (/api/v1). Innerhalb von v1 kommen höchstens neue Endpunkte und neue Felder hinzu; ein System sollte unbekannte Felder deshalb überlesen. Wird etwas entfernt, umbenannt oder in seiner Bedeutung geändert, entsteht /api/v2, und v1 bleibt mit Ankündigung mindestens sechs Monate daneben bestehen.
Dateien
v1 liefert zu Belegen nur den Dateinamen, keine Datei. Belege und andere Dateien lädt der Betrieb weiterhin in der Anwendung herunter oder über die Datenausfuhr unter Einstellungen.
Endpunkte
Der eigene Schlüssel
GET/api/v1/schluessel
Betrieb, Bereiche und Ablauf des Schlüssels, mit dem die Anfrage gestellt wird — der erste Aufruf einer neuen Anbindung.
Bereich: jeder gültige Schlüssel
Felder
| traeger | string | Name des Betriebs, dem der Schlüssel gehört. |
|---|---|---|
| praefix | string | Die ersten zwölf Zeichen des Schlüssels. |
| name | string | Name, unter dem der Schlüssel angelegt wurde. |
| scopes | array von string | Bereiche, die der Schlüssel öffnet. |
| ablauf_am | string (date-time) | Ablauf des Schlüssels. |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/schluessel"
Beispielantwort
{
"daten": {
"traeger": "Muster-Betrieb gGmbH",
"praefix": "kfk_Q2x9aB7c",
"name": "Lohnprogramm",
"scopes": [
"lohn:lesen",
"personal:lesen"
],
"ablauf_am": "2027-09-26T00:00:00Z"
}
}Fehler: 400, 401, 429, 503
Mitarbeitende
GET/api/v1/mitarbeitende
Alle Mitarbeitenden des Betriebs, auch ausgeschiedene (mit ausgeschieden_am). Keine Stammdaten der Personalakte (IBAN, Anschrift, Geburtsdatum).
Bereich: personal:lesen
Parameter
| grenze | integer | Datensätze je Seite, 1 bis 500. Vorgabe 100. |
|---|---|---|
| cursor | string (uuid) | Der Wert naechster_cursor der vorigen Antwort. Weglassen für die erste Seite. |
Felder
| id | string (uuid) | Kennung der Person. |
|---|---|---|
| vorname | string | Vorname. |
| nachname | string | Nachname. |
| funktion | string oder null | Funktion im Betrieb, z. B. „Betreuung“. |
| string oder null | Dienstliche E-Mail-Adresse. | |
| telefon | string oder null | Dienstliche Telefonnummer. |
| eintritt | string (date) oder null | Tag des Eintritts. |
| ausgeschieden_am | string (date) oder null | Tag des Ausscheidens; null, solange die Person beschäftigt ist. |
| soll_tage_monat | integer oder null | Soll-Arbeitstage im Monat. |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/mitarbeitende?grenze=100"
Beispielantwort
{
"daten": [
{
"id": "0b6c1f0e-6d7e-4c43-9c1e-3f6c8f0d2a11",
"vorname": "Lea",
"nachname": "Lohmann",
"funktion": "Betreuung",
"email": "lea.lohmann@traeger.example",
"telefon": "0421 123456",
"eintritt": "2025-04-01",
"ausgeschieden_am": null,
"soll_tage_monat": 20
}
],
"naechster_cursor": null
}Fehler: 400, 401, 403, 429, 503
Bewerbungen
GET/api/v1/bewerbungen
Bewerbungen mit Kontakt, Stelle und Stand. Kein Anschreiben, keine internen Notizen, keine Unterlagen. von/bis filtern nach Eingang. Bewerbungen werden in Kindfair nach Frist gelöscht — was ein Fremdsystem übernommen hat, ist dort ebenso zu löschen.
Bereich: bewerbungen:lesen
Parameter
| grenze | integer | Datensätze je Seite, 1 bis 500. Vorgabe 100. |
|---|---|---|
| cursor | string (uuid) | Der Wert naechster_cursor der vorigen Antwort. Weglassen für die erste Seite. |
| von | string (date) | Erster Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
| bis | string (date) | Letzter Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
Felder
| id | string (uuid) | Kennung der Bewerbung. |
|---|---|---|
| vorname | string | Vorname. |
| nachname | string | Nachname. |
| string | E-Mail-Adresse. | |
| telefon | string oder null | Telefonnummer. |
| stelle | string oder null | Stelle, auf die sich die Person bewirbt. |
| quelle | string oder null | Woher die Bewerbung kam. |
| stufe | string | Stand im Verfahren.Neu · In Prüfung · Gespräch · Hospitation · Zusage · Absage |
| verfuegbar_ab | string (date) oder null | Frühester Beginn. |
| eingegangen_am | string (date-time) | Eingang der Bewerbung. |
| entschieden_am | string (date-time) oder null | Zeitpunkt von Zusage oder Absage. |
| uebernommen_als | string (uuid) oder null | Kennung der Person unter /mitarbeitende, wenn die Bewerbung übernommen wurde. |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/bewerbungen?grenze=100&von=2026-09-01&bis=2026-09-30"
Beispielantwort
{
"daten": [
{
"id": "7d1b0c55-2f1e-4b8e-8a57-0e5e9d3c1f20",
"vorname": "Bea",
"nachname": "Berger",
"email": "bea@example.org",
"telefon": null,
"stelle": "Assistenz",
"quelle": "Formular",
"stufe": "Gespräch",
"verfuegbar_ab": "2026-11-01",
"eingegangen_am": "2026-09-20T08:14:00Z",
"entschieden_am": null,
"uebernommen_als": null
}
],
"naechster_cursor": null
}Fehler: 400, 401, 403, 429, 503
Abrechnungen
GET/api/v1/abrechnungen
Monatsabrechnungen der Auslagen und Fahrten. von/bis filtern nach Abrechnungsmonat.
Bereich: lohn:lesen
Parameter
| grenze | integer | Datensätze je Seite, 1 bis 500. Vorgabe 100. |
|---|---|---|
| cursor | string (uuid) | Der Wert naechster_cursor der vorigen Antwort. Weglassen für die erste Seite. |
| von | string (date) | Erster Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
| bis | string (date) | Letzter Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
Felder
| id | string (uuid) | Kennung der Monatsabrechnung. |
|---|---|---|
| mitarbeiter_id | string (uuid) | Person, deren Auslagen und Fahrten abgerechnet werden. |
| monat | string (date) | Erster Tag des abgerechneten Monats. |
| status | string | Stand der Abrechnung.Erfasst · Zur Prüfung · Freigegeben · Zur Korrektur |
| eingereicht_am | string (date-time) oder null | Zeitpunkt der Einreichung. |
| entschieden_am | string (date-time) oder null | Zeitpunkt der Freigabe oder Rückgabe. |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/abrechnungen?grenze=100&von=2026-09-01&bis=2026-09-30"
Beispielantwort
{
"daten": [
{
"id": "a3c9e1b2-5d44-4f0a-9b61-2c7e8d9f0a13",
"mitarbeiter_id": "0b6c1f0e-6d7e-4c43-9c1e-3f6c8f0d2a11",
"monat": "2026-09-01",
"status": "Freigegeben",
"eingereicht_am": "2026-10-01T09:00:00Z",
"entschieden_am": "2026-10-02T11:30:00Z"
}
],
"naechster_cursor": null
}Fehler: 400, 401, 403, 429, 503
Auslagen
GET/api/v1/auslagen
Belege mit Kennziffer, Betrag und Datum. Die Belegdatei selbst liefert v1 nicht. von/bis filtern nach Belegdatum.
Bereich: lohn:lesen
Parameter
| grenze | integer | Datensätze je Seite, 1 bis 500. Vorgabe 100. |
|---|---|---|
| cursor | string (uuid) | Der Wert naechster_cursor der vorigen Antwort. Weglassen für die erste Seite. |
| von | string (date) | Erster Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
| bis | string (date) | Letzter Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
Felder
| id | string (uuid) | Kennung des Belegs. |
|---|---|---|
| mitarbeiter_id | string (uuid) | Person, die die Auslage hatte. |
| abrechnung_id | string (uuid) | Monatsabrechnung, zu der der Beleg gehört. |
| kennziffer | integer | Kennziffer der Auslagenart. |
| betrag | number | Betrag in Euro, zwei Nachkommastellen. |
| datum | string (date) | Belegdatum. |
| dateiname | string oder null | Name der hochgeladenen Belegdatei — nur zur Zuordnung; die Datei selbst liefert v1 nicht. |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/auslagen?grenze=100&von=2026-09-01&bis=2026-09-30"
Beispielantwort
{
"daten": [
{
"id": "c4b1e2d3-6f55-4a1b-8c72-3d8f9e0a1b24",
"mitarbeiter_id": "0b6c1f0e-6d7e-4c43-9c1e-3f6c8f0d2a11",
"abrechnung_id": "a3c9e1b2-5d44-4f0a-9b61-2c7e8d9f0a13",
"kennziffer": 3,
"betrag": 12.5,
"datum": "2026-09-10",
"dateiname": "quittung.pdf"
}
],
"naechster_cursor": null
}Fehler: 400, 401, 403, 429, 503
Fahrten
GET/api/v1/fahrten
Fahrten mit Anlass, Kilometersumme und Kilometersatz — ohne die Adressen der Etappen. von/bis filtern nach Tag.
Bereich: lohn:lesen
Parameter
| grenze | integer | Datensätze je Seite, 1 bis 500. Vorgabe 100. |
|---|---|---|
| cursor | string (uuid) | Der Wert naechster_cursor der vorigen Antwort. Weglassen für die erste Seite. |
| von | string (date) | Erster Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
| bis | string (date) | Letzter Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
Felder
| id | string (uuid) | Kennung der Fahrt. |
|---|---|---|
| mitarbeiter_id | string (uuid) | Person, die gefahren ist. |
| abrechnung_id | string (uuid) | Monatsabrechnung, zu der die Fahrt gehört. |
| datum | string (date) | Tag der Fahrt. |
| anlass | string oder null | Anlass der Fahrt, wie erfasst. |
| kilometer | number | Summe der Kilometer aller Etappen. |
| kilometersatz_cent | integer oder null | Kilometersatz in Cent, festgeschrieben bei der Erfassung. |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/fahrten?grenze=100&von=2026-09-01&bis=2026-09-30"
Beispielantwort
{
"daten": [
{
"id": "d5c2f3e4-7a66-4b2c-9d83-4e9a0f1b2c35",
"mitarbeiter_id": "0b6c1f0e-6d7e-4c43-9c1e-3f6c8f0d2a11",
"abrechnung_id": "a3c9e1b2-5d44-4f0a-9b61-2c7e8d9f0a13",
"datum": "2026-09-11",
"anlass": "Termin beim Jugendamt",
"kilometer": 21,
"kilometersatz_cent": 30
}
],
"naechster_cursor": null
}Fehler: 400, 401, 403, 429, 503
Abwesenheiten
GET/api/v1/abwesenheiten
Urlaub und Abwesenheiten mit Zeitraum und Stand — ohne Grund, Ablehnungsgrund und Vertretung. von/bis liefern jede Abwesenheit, die den Zeitraum berührt.
Bereich: lohn:lesen oder planung:lesen
Parameter
| grenze | integer | Datensätze je Seite, 1 bis 500. Vorgabe 100. |
|---|---|---|
| cursor | string (uuid) | Der Wert naechster_cursor der vorigen Antwort. Weglassen für die erste Seite. |
| von | string (date) | Erster Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
| bis | string (date) | Letzter Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
Felder
| id | string (uuid) | Kennung der Abwesenheit. |
|---|---|---|
| mitarbeiter_id | string (uuid) | Abwesende Person. |
| art | string | „Urlaub“ oder „Abwesenheit“. Einen Grund liefert die API nicht.Urlaub · Abwesenheit |
| von | string (date) | Erster Tag. |
| bis | string (date) | Letzter Tag. |
| status | string | Stand des Antrags.Beantragt · Genehmigt · Bestätigt · Abgelehnt · Zurückgezogen |
| beantragt_am | string (date-time) oder null | Zeitpunkt des Antrags. |
| entschieden_am | string (date-time) oder null | Zeitpunkt der Entscheidung. |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/abwesenheiten?grenze=100&von=2026-09-01&bis=2026-09-30"
Beispielantwort
{
"daten": [
{
"id": "e6d3a4f5-8b77-4c3d-8e94-5f0b1a2c3d46",
"mitarbeiter_id": "0b6c1f0e-6d7e-4c43-9c1e-3f6c8f0d2a11",
"art": "Urlaub",
"von": "2026-10-01",
"bis": "2026-10-05",
"status": "Genehmigt",
"beantragt_am": "2026-09-01T07:00:00Z",
"entschieden_am": "2026-09-02T10:00:00Z"
}
],
"naechster_cursor": null
}Fehler: 400, 401, 403, 429, 503
Einsätze
GET/api/v1/einsaetze
Der Einsatzplan: wer wann bei wem. Namen der Klienten stehen nur unter /klienten (eigener Bereich). von/bis filtern nach Tag.
Bereich: planung:lesen
Parameter
| grenze | integer | Datensätze je Seite, 1 bis 500. Vorgabe 100. |
|---|---|---|
| cursor | string (uuid) | Der Wert naechster_cursor der vorigen Antwort. Weglassen für die erste Seite. |
| von | string (date) | Erster Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
| bis | string (date) | Letzter Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
Felder
| id | string (uuid) | Kennung des Einsatzes. |
|---|---|---|
| klient_id | string (uuid) | Betreute Person (Kennung unter /klienten). |
| mitarbeiter_id | string (uuid) | Eingesetzte Person. |
| datum | string (date) | Tag des Einsatzes. |
| zeitfenster | string | Zeitfenster.ganztags · bis 12 · ab 12 |
| art | string | Art des Einsatzes.Ganztags · Wechseltag · Vertretung |
| platz | integer | Platz im Betreuungsschlüssel (1 oder 2). |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/einsaetze?grenze=100&von=2026-09-01&bis=2026-09-30"
Beispielantwort
{
"daten": [
{
"id": "f7e4b5a6-9c88-4d4e-9fa5-6a1c2b3d4e57",
"klient_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c68",
"mitarbeiter_id": "0b6c1f0e-6d7e-4c43-9c1e-3f6c8f0d2a11",
"datum": "2026-09-20",
"zeitfenster": "ganztags",
"art": "Ganztags",
"platz": 1
}
],
"naechster_cursor": null
}Fehler: 400, 401, 403, 429, 503
Klienten
GET/api/v1/klienten
Die betreuten Personen, auch archivierte. Keine Notizen, keine Aufgaben, keine Akte.
Bereich: klienten:lesen
Parameter
| grenze | integer | Datensätze je Seite, 1 bis 500. Vorgabe 100. |
|---|---|---|
| cursor | string (uuid) | Der Wert naechster_cursor der vorigen Antwort. Weglassen für die erste Seite. |
Felder
| id | string (uuid) | Kennung der betreuten Person. |
|---|---|---|
| name | string | Name, wie im Betrieb geführt. |
| alter_jahre | integer oder null | Alter in Jahren. |
| hilfeart | string oder null | Art der Hilfe. |
| betreuungsschluessel | string oder null | Betreuungsschlüssel.1 Betreuende · 2 Betreuende |
| betreuung_seit | string (date) oder null | Beginn der Betreuung. |
| betreuung_bis | string (date) oder null | Ende der Betreuung. |
| archiviert_am | string (date-time) oder null | Zeitpunkt der Archivierung. |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/klienten?grenze=100"
Beispielantwort
{
"daten": [
{
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c68",
"name": "J. M.",
"alter_jahre": 15,
"hilfeart": "§ 35 SGB VIII",
"betreuungsschluessel": "1 Betreuende",
"betreuung_seit": "2026-03-01",
"betreuung_bis": null,
"archiviert_am": null
}
],
"naechster_cursor": null
}Fehler: 400, 401, 403, 429, 503
Protokolle
GET/api/v1/protokolle
Nur die Kopfdaten der Übergabe-, Einzugs- und Umzugsprotokolle — keine Haken, keine Fotos, keine Freitexte. von/bis filtern nach Tag.
Bereich: klienten:lesen
Parameter
| grenze | integer | Datensätze je Seite, 1 bis 500. Vorgabe 100. |
|---|---|---|
| cursor | string (uuid) | Der Wert naechster_cursor der vorigen Antwort. Weglassen für die erste Seite. |
| von | string (date) | Erster Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
| bis | string (date) | Letzter Tag des Zeitraums (JJJJ-MM-TT), einschließlich. |
Felder
| id | string (uuid) | Kennung des Protokolls. |
|---|---|---|
| klient_id | string (uuid) | Betreute Person. |
| unterbringung_id | string (uuid) oder null | Unterbringung, zu der das Protokoll gehört. |
| art | string | Art des Protokolls. „Eigenes Protokoll“ steht für eine vom Betrieb angelegte Protokollart.Übergabeprotokoll · Einzugsprotokoll · Umzugsprotokoll · Eigenes Protokoll |
| datum | string (date) oder null | Tag des Protokolls. |
| aufenthalt_bis | string (date) oder null | Ende des Aufenthalts laut Protokoll. |
| gespeichert_am | string (date-time) oder null | Zeitpunkt des Abschlusses; null, solange offen. |
Beispielaufruf
curl -sS -H "Authorization: Bearer $KINDFAIR_API_SCHLUESSEL" "https://kindfair.net/api/v1/protokolle?grenze=100&von=2026-09-01&bis=2026-09-30"
Beispielantwort
{
"daten": [
{
"id": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e80",
"klient_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c68",
"unterbringung_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d79",
"art": "Übergabeprotokoll",
"datum": "2026-09-02",
"aufenthalt_bis": null,
"gespeichert_am": "2026-09-02T18:00:00Z"
}
],
"naechster_cursor": null
}Fehler: 400, 401, 403, 429, 503
Fehler
Fehler kommen als application/problem+json nach RFC 9457. Jede Antwort trägt Cache-Control: no-store.
| Status | type | Bedeutung |
|---|---|---|
| 400 | urn:kindfair:api:parameter | Parameter ungültig: unbekannter Parameter, grenze außerhalb 1–500, Cursor oder Datum in falscher Form, von nach bis. |
| 401 | urn:kindfair:api:schluessel | Schlüssel fehlt, hat die falsche Form, ist unbekannt, gesperrt oder abgelaufen — oder der Betrieb ist gesperrt. Die Antwort unterscheidet die Fälle bewusst nicht. |
| 403 | urn:kindfair:api:bereich | Der Schlüssel ist gültig, trägt aber keinen der Bereiche, die der Endpunkt verlangt. Es werden keine Daten geliefert. |
| 429 | urn:kindfair:api:rate | Mehr als 120 Anfragen in der letzten Minute mit diesem Schlüssel. Auch abgewiesene Anfragen zählen mit. |
| 503 | urn:kindfair:api:nicht_erreichbar | Die Datenbank ist vorübergehend nicht erreichbar. |
In allen Beispielen steht $KINDFAIR_API_SCHLUESSEL für deinen Schlüssel — gesetzt mit dem Platzhalter kfk_DEIN_SCHLUESSEL. Ein echter Schlüssel gehört in keine Dokumentation und kein Ticket.