Mitarbeiter

Dieses Modul beschreibt die API-Endpunkte zur Verwaltung von Mitarbeitern in einem Account. Es umfasst das Erstellen, Bearbeiten, Abrufen, Auflisten und Löschen von Mitarbeitern. Mitarbeiter können auch Mitarbeiter, Nutzer oder User genannt werden.

Gültige Attribute

Attribut	Beschreibung	Details
`account_id`	ID des zugehörigen Accounts	Automatisch gesetzt, nicht manuell änderbar.
`avatar`	Dateiname des Profilbildes	Optional. Ohne Pfad-Angabe, z. B. `avatar.png`.
`discarded_at`	Zeitpunkt der Deaktivierung (oder `null`)	Kann nicht manuell gesetzt werden.
`email`	E-Mail-Adresse des Mitarbeiters	Optional, aber falls gesetzt: eindeutig innerhalb eines Accounts.
`name`	Name des Mitarbeiters	Frei wählbar.
`staff_number`	Eindeutige Personalnummer, für zB Datev	Optional, aber falls gesetzt: eindeutig innerhalb eines Accounts.
`status`	Aktueller Status	Kann nicht manuell gesetzt werden. Mögliche Werte: `created` (erstellt), `invited` (eingeladen), `active` (Einladung angenommen).

Beziehungen

Folgende Beziehungen können mit dem Parameter include in den Request eingebunden werden:

Beziehung	Typ	Beschreibung
`account`	belongs_to	Der Account, zu dem der Mitarbeiter gehört.
`account_memberships`	has_many	Triplets aus Mitarbeiter, Account und Rolle, also welche Rollen der Mitarbeiter im Account hat.
`teams`	has_many	Die Teams, in denen der Mitarbeiter Mitglied ist.
`team_memberships`	has_many	Triplets aus Mitarbeiter, Team und Rolle, also welche Rollen der Mitarbeiter in den Teams hat.

Meta-Daten: Berechtigungen

Können über den meta[permissions]-Parameter in den Request eingebunden werden. Sie geben an, welche Aktionen der aktuelle Benutzer auf den Mitarbeiter ausführen kann.

Gruppe	Beschreibung
`actions`	Gibt an, ob der Benutzer den Mitarbeiter `'edit'` (bearbeiten), `'delete'` (löschen), `'invite.create'` (einladen) oder `'invite.delete'` (Einladung löschen) kann.

Erstellen

Mit diesem Endpunkt kannst du einen neuen Mitarbeiter zu deinem Account hinzufügen. Optional kannst du auch gleich eine E-Mail-Adresse mitgeben, über die der Mitarbeiter später eingeladen werden kann.

Was passiert bei diesem Request?

Der neue Mitarbeiter wird im System angelegt.
Es wird keine Einladung verschickt.
Der Status ist zunächst created. Ein Wechsel auf invited oder active erfolgt erst später.

Endpunkt

POST /api/v1/users

Request & Response

Request

{
  "data": {
    "type": "user",
    "attributes": {
      "name": "Max Mustermann",
      "email": "[email protected]"
    }
  }
}

Hinweise:

name ist erforderlich
email ist optional, aber sinnvoll, wenn eine Einladung vorgesehen ist

Response

{
  "data": {
    "id": "98815bd8-f3e6-41ec-8c4a-25a431ac6ce4",
    "type": "user",
    "attributes": {
      ...
    }
  }
}

Bearbeiten

Mit diesem Endpunkt kannst du einen bestehenden Mitarbeiter aktualisieren. Typischerweise werden Name oder Email-Adresse geändert. Benutzerdefinierte Felder die du in den Stammdaten des Mitarbeiters findest, werden über diesen Endpunkt nicht aktualisiert. Siehe dazu die Dokumentation zu Feldwerten.

Was passiert bei diesem Request?

Die angegebenen Felder des Mitarbeiters werden überschrieben.
Felder, die nicht angegeben sind, bleiben unverändert.
Eine Änderung der E-Mail-Adresse hat keinen Einfluss auf den Login-Status oder Einladungen.

Endpunkt

PUT /api/v1/users/:user_id

Parameter

Name	Beschreibung
`user_id`	Die ID des Mitarbeiters, der bearbeitet wird.

Die ID des Mitarbeiters wird in der URL übergeben.

Request & Response

Request

{
  "data": {
    "type": "user",
    "attributes": {
      "name": "Maria Musterfrau",
      "email": "[email protected]"
    }
  }
}

Hinweise:

Wird die E-Mail-Adresse geändert, muss sie weiterhin im Account eindeutig sein.

Response

{
  "data": {
    "id": "0c55b234-91f4-465d-810e-7e87ad1136ff",
    "type": "user",
    "attributes": {
      ...
    }
  }
}

Anzeigen

Mit diesem Endpunkt kannst du die Details eines einzelnen Mitarbeiters abrufen. Der Benutzer wird über seine eindeutige ID identifiziert. Zusätzlich kannst du verwandte Ressourcen wie Account oder Teams über den include-Parameter einbinden.

Endpunkt

GET /api/v1/users/:user_id

Parameter

Name	Beschreibung
`user_id`	Die ID des Mitarbeiters, der abgerufen wird.

Optional: Nutze include, um verknüpfte Ressourcen wie account, teams oder account_memberships direkt mitzuliefern.

Response

{
  "data": {
    "id": "98815bd8-f3e6-41ec-8c4a-25a431ac6ce4",
    "type": "user",
    "attributes": {
      ...
    }
  }
}

Beispiele

Einzelner Mitarbeiter und zugehörigen Teams

GET /api/v1/users/:user_id?include=teams

Auflisten

Mit diesem Endpunkt kannst du eine Liste aller Mitarbeiter im aktuellen Account abrufen. Optional kannst du Suchfilter und Relationen verwenden, um gezielt nach bestimmten Benutzern zu suchen.

Die Ergebnisse sind paginiert. Standardmäßig werden 20 Einträge pro Seite zurückgegeben.

Endpunkt

GET /api/v1/users

Response

{
  "data": [
    {
      "id": "98815bd8-f3e6-41ec-8c4a-25a431ac6ce4",
      "type": "user",
      "attributes": {
        ...
      }
    },
    {
      ...
    }
  ]
}

Beispiele

Alle Mitarbeiter, deren Name „test“ enthält

GET /api/v1/users?filter[name]=ct:test

Alle Mitarbeiter, die noch nicht eingeladen wurden

GET /api/v1/users?filter[status]=eq:created

Alle Mitarbeiter ohne E-Mail

GET /api/v1/users?filter[email_blank]=1

Alle Mitarbeiter mit ihren jeweiligen Teams

GET /api/v1/users?include=teams

Alle Mitarbeiter und den Aktionen, die der aktuelle Benutzer ausführen kann

GET /api/v1/users?meta[permissions]=actions

Löschen

Mit diesem Endpunkt kannst du einen bestehenden Mitarbeiter aus dem System entfernen. Dabei handelt es sich um einen soft delete: Der Benutzer bleibt technisch erhalten, ist aber nicht mehr sichtbar oder nutzbar.

Was passiert bei diesem Request?

Der Mitarbeiter wird als gelöscht markiert.
discarded_at enthält einen Zeitstempel der Löschung.
Der Mitarbeiter kann sich nicht mehr eingeloggen.
Der Mitarbeiter kann nicht mehr eingeladen werden.
Der Mitarbeiter ist nicht mehr in der Mitarbeiterliste sichtbar.
Bestehende Referenzen (z. B. in Logs) bleiben erhalten.

Endpunkt

DELETE /api/v1/users/:user_id

Parameter

Name	Beschreibung
`user_id`	Die ID des Mitarbeiters, der gelöscht werden soll.

Request

DELETE /api/v1/users/0c55b234-91f4-465d-810e-7e87ad1136ff

Response

{
  "data": {
    "id": "0c55b234-91f4-465d-810e-7e87ad1136ff",
    "type": "user",
    "attributes": {
      "name": "Maria Musterfrau",
      "email": "[email protected]",
      "status": "deleted",
      "discarded_at": "2024-12-01T10:45:00Z"
    }
  }
}