Zum Hauptinhalt springen

User

Benutzer gehören zu einem Tenant und tragen Rollen, die festlegen, was sie tun dürfen. Öffentliche v2-Endpoints verwenden snake_case-Schlüssel und sind in der OpenAPI-Spezifikation dokumentiert; die wichtigsten Punkte finden Sie unten.

Endpoints​

  • GET /api/v2/users — paginierte Liste der Tenant-Benutzer (ohne Service-Accounts).
  • POST /api/v2/users — legt einen Benutzer an oder lädt eine Person per E-Mail ein, wenn die Personen ihr Profil selbst verwalten (siehe Einladungen). Die E-Mail-Adresse wird beim Anlegen gesetzt und kann nicht mehr geändert werden.
  • PATCH /api/v2/users/{user_id} — JSON Merge Patch (RFC 7396). Felder weglassen, um sie unverändert zu lassen; ein Feld auf null setzen, um es zu leeren. lock_version ist optional: wenn angegeben, wird es gegen die gespeicherte Version geprüft (409 bei Abweichung); wenn weggelassen, entfällt die Nebenläufigkeitsprüfung.

Payloads​

Create (POST /api/v2/users)​

{
"email": "bea@example.com",
"firstname": "Bea",
"lastname": "Smith",
"role_ids": ["4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab"],
"phone_number": "+43123456789"
}

Antwort (created):

{
"id": "1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af",
"email": "bea@example.com",
"roles": ["dispatcher"],
"firstname": "Bea",
"lastname": "Smith",
"profile_status": "COMPLETE",
"created_at": "2024-01-15T10:30:00Z",
"status": "ACTIVE",
"is_profile_self_managed": false
}

Patch (PATCH /api/v2/users/{user_id})​

Content-Type: application/merge-patch+json (application/json wird als Alias akzeptiert)

{
"lock_version": 3,
"firstname": "Bea Updated",
"phone_number": null
}

Hinweise:

  • Die E-Mail-Adresse kann nach dem Anlegen nicht mehr geändert werden.
  • role_ids darf niemals leer sein.
  • firstname und lastname können nicht geleert werden. Wo is_profile_self_managed true ist, kann nur die Person selbst ihren Namen und ihre Telefonnummer ändern (sonst 422 users/profile-self-managed).

Einladungen​

In Workspaces, in denen Personen ein Anmeldekonto für alle ihre Tourfold-Workspaces behalten, verwaltet jede Person ihren Namen und ihre Telefonnummer selbst; ihre Benutzer tragen is_profile_self_managed: true. Dort lädt POST /api/v2/users eine Person per E-Mail ein:

{
"email": "lena.huber@example.com",
"role_ids": ["4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab"]
}
  • Eine Person, die neu bei Tourfold ist, erhält eine Einladungs-E-Mail und setzt ein Passwort; eine Person, die bereits ein Tourfold-Konto hat, erhält eine E-Mail, dass sie hinzugefügt wurde. In beiden Fällen hat der Benutzer profile_status: PENDING und weder firstname, lastname noch phone_number (die Eigenschaften fehlen), bis sich die Person zum ersten Mal in diesem Workspace anmeldet; zeigen Sie stattdessen die E-Mail-Adresse an. Diese Anmeldung füllt das Profil und sendet einen user.updated-Webhook mit profile_status: COMPLETE.
  • Die Anfrage enthält weder firstname, lastname noch phone_number: nur die Person setzt sie. Eine Anfrage mit einem dieser Felder erhält 422 users/profile-self-managed mit den Feldnamen in data.fields, und es wird kein Benutzer angelegt. Die Antwort verrät nicht, ob zu der E-Mail-Adresse bereits ein Konto bestand.
  • POST /api/v2/users/{user_id}/resend-set-password-email sendet die E-Mail erneut, solange can_resend_set_password_email true ist.

Wo der Workspace die Profile seiner Personen verwaltet (is_profile_self_managed: false), sind firstname und lastname erforderlich und phone_number ist optional, wie bisher. Ein leerer Name erhält in jedem Workspace einen field-required-Eintrag („must not be blank“) neben allen anderen Feldfehlern. Sind die übrigen Felder gültig, erhält ein fehlender oder auf null gesetzter Name 422 validation-failed mit einem field-required-Eintrag je fehlendem Namen.

Rollen​

Listet die Rollen des aktuellen Tenants mit ihren aktivierten Grants auf:

GET /api/v2/roles
{
"items": [
{
"id": "4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab",
"name": "dispatcher",
"role_type": "DISPATCHER",
"grants": ["getUsers", "updateUser"]
},
{
"id": "9f3b8e71-766f-4d5d-b9b4-8d57b92a9d52",
"name": "driver",
"role_type": "DRIVER",
"grants": ["getUsers"]
}
]
}