Personal & HR — API und MCP
Überblick
Dieser Bereich stellt 87 Operationen bereit. Jede davon ist zugleich ein MCP-Werkzeug.
Der Bereich hängt am Modul-Schalter module.hr. Ist das Modul aus, antworten diese Operationen mit 404.
Operationen
| Methode | Pfad | Zweck | Recht | Parameter |
|---|---|---|---|---|
GET | /api/v1/hr-absence-balances | Liste der HrAbsenceBalance | hr.absence.view_own | page, employeeId, year, retentionDue |
DELETE | /api/v1/hr-absence-balances/{ulid} | Lösch-Vorschlag der Aufbewahrung bestätigen — Löscht ein Urlaubskonto endgültig — nur, wenn der Aufbewahrungslauf es zur Löschung vorgeschlagen hat (retentionDueAt gesetzt; Regel hr_absence, 6 Jahre, Lohnunterlagen). Sonst 409: Urlaubskonten pflegt der Ablauf, nicht die Hand. | hr.document.manage · Objektregel hr.absence.view | ulid |
GET | /api/v1/hr-absence-balances/{ulid} | Eine HrAbsenceBalance lesen | hr.absence.view_own | ulid |
PATCH | /api/v1/hr-absence-balances/{ulid} | Urlaubskonto von Hand korrigieren — Überschreibt den anteilig berechneten Jahresanspruch (entitlementDays, danach als „von Hand" markiert), den Übertrag (carryoverDays) oder den Eröffnungsbestand genommener Tage zum Stichtag (openingTakenDays). Genommen/geplant leitet das System weiter aus den Abwesenheiten ab. | hr.employee.edit · Objektregel hr.absence.view | ulid, + Rumpf |
POST | /api/v1/hr-absence-balances/{ulid}/retention-keep | Lösch-Vorschlag verwerfen und Aufbewahrung verlängern — Verwirft den Lösch-Vorschlag der Aufbewahrung und hält das Urlaubskonto bis retentionUntil (Pflicht, Y-m-d, in der Zukunft). Gelöscht wird ausschließlich über DELETE. | hr.document.manage · Objektregel hr.absence.view | ulid, + Rumpf |
GET | /api/v1/hr-absence-types | Liste der HrAbsenceType | hr.absence.view_own | page |
POST | /api/v1/hr-absence-types | Eine HrAbsenceType anlegen | hr.absencetype.manage | + Rumpf |
DELETE | /api/v1/hr-absence-types/{ulid} | Eine HrAbsenceType löschen | hr.absencetype.manage | ulid |
GET | /api/v1/hr-absence-types/{ulid} | Eine HrAbsenceType lesen | hr.absence.view_own | ulid |
PATCH | /api/v1/hr-absence-types/{ulid} | Eine HrAbsenceType ändern | hr.absencetype.manage | ulid, + Rumpf |
GET | /api/v1/hr-absences | Liste der HrAbsence | hr.absence.view_own | page, employeeId, status, from, to, typeCode, q, retentionDue, order[startDate], order[period] |
POST | /api/v1/hr-absences | Eine HrAbsence anlegen | hr.absence.request_own | + Rumpf |
POST | /api/v1/hr-absences/bulk-decision | Mehrere Abwesenheitsantraege auf einmal entscheiden — Genehmigt bzw. lehnt bis zu 100 Antraege ab. Jeder Antrag wird EINZELN gegen den objektbezogenen Voter geprueft; die Antwort nennt je Antrag den Ausgang (Teilerfolg ist erlaubt). | hr.absence.approve | + Rumpf |
DELETE | /api/v1/hr-absences/{ulid} | Lösch-Vorschlag der Aufbewahrung bestätigen — Löscht eine Abwesenheit endgültig — nur, wenn der Aufbewahrungslauf sie zur Löschung vorgeschlagen hat (retentionDueAt gesetzt; Regel 6 Jahre, Lohnunterlagen). Sonst 409: im laufenden Betrieb wird storniert, nicht gelöscht. | hr.document.manage · Objektregel hr.absence.view | ulid |
GET | /api/v1/hr-absences/{ulid} | Eine HrAbsence lesen | Objektregel hr.absence.view | ulid |
POST | /api/v1/hr-absences/{ulid}/approve | Approve hr absence — Approve hr absence. Dedicated action endpoint — not a standard CRUD create. | hr.absence.approve | ulid, + Rumpf |
POST | /api/v1/hr-absences/{ulid}/cancel | Cancel hr absence — Cancel hr absence. Dedicated action endpoint — not a standard CRUD create. | hr.absence.cancel | ulid, + Rumpf |
POST | /api/v1/hr-absences/{ulid}/eau | eAU-Stand einer Krankmeldung festhalten — HR vermerkt den Stand der elektronischen AU (pending = erwartet, retrieved = vom Lohnbüro abgerufen, not_available = keine eAU, z. B. Privatarzt/Ausland) mit Abrufdatum und Kennung. Der Abruf selbst läuft über die Software des Lohnbüros; leerer Stand entfernt den Vermerk. | hr.document.manage · Objektregel hr.absence.view | ulid, + Rumpf |
POST | /api/v1/hr-absences/{ulid}/provide-proof | Nachweis zur Abwesenheit nachreichen — Reicht den geforderten Nachweis nach: verknüpft das Dokument mit der Abwesenheit und setzt proofProvidedAt. | hr.absence.cancel | ulid, + Rumpf |
POST | /api/v1/hr-absences/{ulid}/reject | Abwesenheitsantrag ablehnen — Endgültige Ablehnung: Status rejected, Entscheider und Zeitpunkt werden festgehalten, das Urlaubskonto bleibt unberührt. Nur aus requested möglich (sonst 409) — eine bereits genehmigte Abwesenheit wird über /cancel zurückgenommen, nicht hier. Body optional {decisionNote}. | hr.absence.approve | ulid, + Rumpf |
POST | /api/v1/hr-absences/{ulid}/retention-keep | Lösch-Vorschlag verwerfen und Aufbewahrung verlängern — Verwirft den Lösch-Vorschlag der Aufbewahrung und hält die Abwesenheit bis retentionUntil (Pflicht, Y-m-d, in der Zukunft). Gelöscht wird ausschließlich über DELETE. | hr.document.manage · Objektregel hr.absence.view | ulid, + Rumpf |
GET | /api/v1/hr-availability | Liste der HrAvailability | hr.absence.view_team · hr.employee.view | from, to, employeeId |
GET | /api/v1/hr-checklist-procedures | Abläufe (SOPs), aus denen eine Checklisten-Vorlage entstehen kann — Veröffentlichte Arbeitsanweisungen mit Referenz, Titel und Zahl der Schritte. Die Referenz an POST /v1/hr-checklist-templates als procedureRef übergeben — die Schritte werden dann als Vorlagen-Schritte übernommen. | hr.onboarding.manage | search, limit |
GET | /api/v1/hr-checklist-templates | Liste der HrChecklistTemplate | hr.onboarding.manage | page, mode |
POST | /api/v1/hr-checklist-templates | Eine HrChecklistTemplate anlegen | hr.onboarding.manage | + Rumpf |
DELETE | /api/v1/hr-checklist-templates/{ulid} | Eine HrChecklistTemplate löschen | hr.onboarding.manage | ulid |
GET | /api/v1/hr-checklist-templates/{ulid} | Eine HrChecklistTemplate lesen | hr.onboarding.manage | ulid |
PATCH | /api/v1/hr-checklist-templates/{ulid} | Eine HrChecklistTemplate ändern | hr.onboarding.manage | ulid, + Rumpf |
GET | /api/v1/hr-employee-change-requests | Liste der HrEmployeeChangeRequest | hr.employee.view_self · hr.employee.edit · hr.skill.manage | page, status, kind, employeeId, mine |
GET | /api/v1/hr-employee-change-requests/{ulid} | Änderungsantrag mit Nutzlast — Zeigt zusätzlich die beantragten Werte (entschlüsselt) — nur für den Antragsteller und die Entscheider der Art. | hr.employee.view_self · hr.employee.edit · hr.skill.manage | ulid |
POST | /api/v1/hr-employee-change-requests/{ulid}/approve | Antrag freigeben — Übernimmt die beantragten Werte — Kontaktdaten in die verschlüsselte Ablage, eine Fähigkeit ins Profil. Payload {note?}. | hr.employee.edit · hr.skill.manage | ulid, + Rumpf |
POST | /api/v1/hr-employee-change-requests/{ulid}/reject | Antrag ablehnen — Lehnt den Antrag ab; der Mitarbeiter wird benachrichtigt. Payload {note?} — die Begründung steht am Antrag. | hr.employee.edit · hr.skill.manage | ulid, + Rumpf |
GET | /api/v1/hr-employee-documents | Liste der HrEmployeeDocument | hr.document.view · hr.document.manage · hr.employee.view_self | page, employeeId, type, q, retentionDue |
POST | /api/v1/hr-employee-documents | Eine HrEmployeeDocument anlegen | hr.document.manage | + Rumpf |
DELETE | /api/v1/hr-employee-documents/{ulid} | Eine HrEmployeeDocument löschen | hr.document.manage | ulid |
GET | /api/v1/hr-employee-documents/{ulid} | Eine HrEmployeeDocument lesen | hr.document.view · hr.document.manage · hr.employee.view_self | ulid |
POST | /api/v1/hr-employee-documents/{ulid}/retention-keep | Lösch-Vorschlag verwerfen und Aufbewahrung verlängern — Verwirft den Lösch-Vorschlag der Aufbewahrungsfrist und setzt eine neue, ausdrückliche Aufbewahrung bis retentionUntil (Pflichtangabe, Y-m-d, in der Zukunft). Gelöscht wird ausschließlich über DELETE — dieser Aufruf hält das Dokument. | hr.document.manage | ulid, + Rumpf |
GET | /api/v1/hr-employee-goals | Liste der HrEmployeeGoal | hr.goal.view · hr.goal.view_team · hr.employee.view_self | page, employeeId, mine, current |
POST | /api/v1/hr-employee-goals | Eine HrEmployeeGoal anlegen | hr.goal.manage · hr.goal.manage_team | + Rumpf |
DELETE | /api/v1/hr-employee-goals/{ulid} | Eine HrEmployeeGoal löschen | hr.goal.manage | ulid |
GET | /api/v1/hr-employee-goals/{ulid} | Eine HrEmployeeGoal lesen | hr.goal.view | ulid |
PATCH | /api/v1/hr-employee-goals/{ulid} | Eine HrEmployeeGoal ändern | hr.goal.manage | ulid, + Rumpf |
GET | /api/v1/hr-feedback-entries | Liste der HrFeedbackEntry | hr.feedback.view · hr.feedback.view_team · hr.employee.view_self | page, employeeId, kind |
POST | /api/v1/hr-feedback-entries | Eine HrFeedbackEntry anlegen | hr.feedback.manage · hr.feedback.manage_team | + Rumpf |
DELETE | /api/v1/hr-feedback-entries/{ulid} | Eine HrFeedbackEntry löschen | hr.feedback.manage | ulid |
GET | /api/v1/hr-feedback-entries/{ulid} | Eine HrFeedbackEntry lesen | hr.feedback.view | ulid |
PATCH | /api/v1/hr-feedback-entries/{ulid} | Eine HrFeedbackEntry ändern | hr.feedback.manage | ulid, + Rumpf |
GET | /api/v1/hr-occasions | Anstehende Geburtstage und Dienstjubiläen — Nur Personen, die zugestimmt haben. Geburtstage ohne Jahr (Tag + Monat). Fenster ab from (Y-m-d, Standard heute) über days Tage (1–366, Standard 30); kind schränkt auf birthday oder anniversary ein. | hr.occasion.view | from, days, kind |
POST | /api/v1/hr-onboarding-assistant | Onboarding-Frage beantworten — Beantwortet eine Frage zum eigenen Einstieg im Kontext der Personaldaten und der offenen Checklisten-Schritte. Ohne employeeUlid gilt die eigene Person; eine fremde Person setzt das Recht zur Checklisten-Pflege voraus. | hr.employee.view_self · hr.onboarding.manage | + Rumpf |
GET | /api/v1/hr-onboarding-checklists | Liste der HrOnboardingChecklist | hr.onboarding.manage | page, employeeId, mode, status, responsibleId |
POST | /api/v1/hr-onboarding-checklists/from-template | Eine HrOnboardingChecklist anlegen | hr.onboarding.manage | + Rumpf |
GET | /api/v1/hr-onboarding-checklists/{ulid} | Eine HrOnboardingChecklist lesen | hr.onboarding.manage | ulid |
POST | /api/v1/hr-onboarding-checklists/{ulid}/complete-item | Checklisten-Eintrag erledigen — Markiert einen Eintrag als erledigt und löst idempotent die daran hängenden Schritte aus (Provisionierung, Betriebsmittel, Aufgabe). | hr.onboarding.manage | ulid, + Rumpf |
POST | /api/v1/hr-onboarding-checklists/{ulid}/items | Checklisten-Eintrag hinzufügen — Fügt der On- bzw. Offboarding-Checkliste einen Eintrag hinzu. | hr.onboarding.manage | ulid, + Rumpf |
POST | /api/v1/hr-onboarding-checklists/{ulid}/skip-item | Checklisten-Eintrag überspringen — Überspringt einen Eintrag, ohne die daran hängenden Schritte auszulösen. | hr.onboarding.manage | ulid, + Rumpf |
GET | /api/v1/hr-payroll-export-checks | Retrieves a HrPayrollExportCheck resource. — Vorab-Prüfung des Lohn-Exports: ist der Zeitraum für die Lohnabrechnung gesperrt, wie viele Anwesenheitstage sind nicht freigegeben, welche Warnungen verlangt der Export als Bestätigung (confirmWarnings). Liest nur; fremde Marke 404, ohne Arbeitszeit-Modul 409. | hr.payroll.export | from, to, brandId |
GET | /api/v1/hr-payroll-export-runs | Liste der HrPayrollExportRun | hr.payroll.export | page, format, brandId |
GET | /api/v1/hr-payroll-export-runs/{ulid} | Eine HrPayrollExportRun lesen | hr.payroll.export | ulid |
POST | /api/v1/hr-payroll-exports | Creates a HrPayrollExport resource. — Lohn-Export eines Zeitraums (max. 366 Tage) mit Protokoll. format=csv Übersicht je Mitarbeiter, format=datev DATEV-LODAS-Bewegungsdaten, format=wage-types Lohnarten-CSV — beide nur für genau einen Kalendermonat (422). brandId schneidet auf eine Marke (fremde Marke 404, ohne brandId alle Marken des Rechts). Ist der Zeitraum nicht gesperrt oder sind Anwesenheitstage nicht freigegeben, antwortet der Export mit 409 und den Warnungen — erst confirmWarnings=true exportiert trotzdem (Vorab-Prüfung: GET /v1/hr-payroll-export-checks). Ohne aktives Arbeitszeit-Modul 409. Freelancer sind ausgenommen. | hr.payroll.export | + Rumpf |
GET | /api/v1/hr-role-options | Rollen zur Auswahl im Onboarding-Schritt „Rolle zuweisen" — Kennung und Name aller Rollen, alphabetisch — die Auswahlliste für On-/Offboarding-Schritte, die einem neuen Mitarbeiter eine Rolle geben. Ohne Rechte und Mitglieder der Rollen. | hr.onboarding.manage | — |
GET | /api/v1/hr-skills | Liste der HrSkill | hr.skill.view · hr.employee.edit_self_limited | page, category, active |
POST | /api/v1/hr-skills | Eine HrSkill anlegen | hr.skill.manage | + Rumpf |
DELETE | /api/v1/hr-skills/{ulid} | Eine HrSkill löschen | hr.skill.manage | ulid |
GET | /api/v1/hr-skills/{ulid} | Eine HrSkill lesen | hr.skill.view · hr.employee.edit_self_limited | ulid |
PATCH | /api/v1/hr-skills/{ulid} | Eine HrSkill ändern | hr.skill.manage | ulid, + Rumpf |
GET | /api/v1/hr-team-calendar | Team-Abwesenheitskalender — Abwesenheiten der Belegschaft im Zeitraum (höchstens ein Jahr) mit Engpass-Tagen und Urlaubssperren. Die Art der Abwesenheit und offene Anträge sieht nur, wer Team-Abwesenheiten lesen darf; alle anderen sehen nur, wer fehlt. | hr.absence.view_own | from, to, teamId |
GET | /api/v1/hr-vacation-blocks | Liste der HrVacationBlock | hr.absence.view_own | page, status, from, to, teamId |
POST | /api/v1/hr-vacation-blocks | Urlaubssperre anlegen oder vorschlagen — HR legt die Sperre sofort aktiv an; die Teamleitung schlägt sie für ein eigenes Team vor (Status proposed). Für die ganze Belegschaft (ohne teamId) nur HR. | hr.vacation_block.manage · hr.vacation_block.propose | + Rumpf |
GET | /api/v1/hr-vacation-blocks/{ulid} | Eine HrVacationBlock lesen | hr.absence.view_own | ulid |
POST | /api/v1/hr-vacation-blocks/{ulid}/activate | Vorgeschlagene Urlaubssperre in Kraft setzen — Nur HR. Ab dann werden Urlaubsanträge im Zeitraum abgewiesen. | hr.vacation_block.manage | ulid, + Rumpf |
POST | /api/v1/hr-vacation-blocks/{ulid}/release | Urlaubssperre aufheben bzw. Vorschlag ablehnen — Nur HR. Eine aktive Sperre wird aufgehoben, ein Vorschlag abgelehnt. | hr.vacation_block.manage | ulid, + Rumpf |
GET | /api/v1/hr/absence-statuses | Liste der HrAbsenceStatus | hr.absence.view_own | page |
POST | /api/v1/hr/absence-statuses | Eine HrAbsenceStatus anlegen | hr.config.manage | + Rumpf |
DELETE | /api/v1/hr/absence-statuses/{key} | Eine HrAbsenceStatus löschen | hr.config.manage | key |
GET | /api/v1/hr/absence-statuses/{key} | Eine HrAbsenceStatus lesen | hr.absence.view_own | key |
PATCH | /api/v1/hr/absence-statuses/{key} | Eine HrAbsenceStatus ändern | hr.config.manage | key, + Rumpf |
GET | /api/v1/hr/employee-calendar-connections | Liste der EmployeeCalendarConnection | hr.calendar.manage | — |
POST | /api/v1/hr/employee-calendar-connections | Eine EmployeeCalendarConnection anlegen | hr.calendar.manage | + Rumpf |
DELETE | /api/v1/hr/employee-calendar-connections/{ulid} | Eine EmployeeCalendarConnection löschen | hr.calendar.manage | ulid |
GET | /api/v1/hr/employee-calendar-connections/{ulid} | Eine EmployeeCalendarConnection lesen | hr.calendar.manage | ulid |
PATCH | /api/v1/hr/employee-calendar-connections/{ulid} | Eine EmployeeCalendarConnection ändern | hr.calendar.manage | ulid, + Rumpf |
POST | /api/v1/hr/employee-calendar-connections/{ulid}/sync | Sync employee calendar connection — Sync employee calendar connection. Dedicated action endpoint — not a standard CRUD create. | hr.calendar.manage | ulid, + Rumpf |
GET | /api/v1/hr/goal-statuses | Liste der HrGoalStatus | hr.goal.view · hr.goal.view_team · hr.employee.view_self | page |
POST | /api/v1/hr/goal-statuses | Eine HrGoalStatus anlegen | hr.config.manage | + Rumpf |
DELETE | /api/v1/hr/goal-statuses/{key} | Eine HrGoalStatus löschen | hr.config.manage | key |
GET | /api/v1/hr/goal-statuses/{key} | Eine HrGoalStatus lesen | hr.goal.view · hr.goal.view_team · hr.employee.view_self | key |
PATCH | /api/v1/hr/goal-statuses/{key} | Eine HrGoalStatus ändern | hr.config.manage | key, + Rumpf |
Zweckangaben, die nicht dem Standardmuster folgen, stammen unverändert aus der Schnittstellen-Beschreibung im Code.