> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Begriffe

> Verwenden Sie einheitliche Definitionen für Unternehmen, Tenants, Divisionen, Benutzer, Zugangsdaten, Scope und Ressourcen.

Verwenden Sie diese Begriffe in Implementierung, Logging, Support und Dokumentation einheitlich.

| Begriff                | Definition                                                                                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Unternehmen**        | Fachlich sichtbare Organisation im JobHandy-Administrationsportal                                                                       |
| **Tenant**             | Technische API-Repräsentation einer Organisation; identifiziert durch eine Tenant-ID                                                    |
| **Division**           | Hierarchische Organisationseinheit, die genau einem Tenant gehört                                                                       |
| **Portalbenutzer**     | Menschlicher Benutzer, der sich am JobHandy-Administrationsportal anmeldet                                                              |
| **Portalberechtigung** | Menschliche Berechtigung wie IT, HR oder Company-Admin                                                                                  |
| **API-Key**            | Server-zu-Server-Zugangsdaten, die in `X-API-Key` gesendet wird                                                                         |
| **API-Key-Scope**      | Tenants und Divisionen, auf die der Key zugreifen darf                                                                                  |
| **Tenant-Kontext**     | Für eine Anfrage ausgewählter Tenant, üblicherweise über `X-Tenant-ID`                                                                  |
| **Ressourcen-ID**      | Undurchsichtiger Identifikator eines Mitarbeiters, einer Bestellung, eines Vorfalls, einer Division, eines Anhangs oder Exportdokuments |
| **Dry Run**            | Validierung eines unterstützten Schreibvorgangs ohne die dokumentierte Speicherung und Side Effects                                     |
| **Request-ID**         | UUID v4 oder v7 zur Korrelation eines einzelnen Request-Versuchs; kein Idempotency Key                                                  |

## Unternehmen und Tenant

In der Benutzeroberfläche wählen Administratoren Unternehmen und organisatorische Bereiche aus. In der API wird die entsprechende technische Grenze durch eine Tenant-ID dargestellt.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    UI[Unternehmen im Administrationsportal] -->|technische Repräsentation| TEN[Tenant in der API]
    TEN --> D1[Division]
    TEN --> D2[Division]
```

Gehen Sie nicht davon aus, dass ein Unternehmensname ein stabiler technischer Identifikator ist. Speichern Sie die von der API verwendete Tenant-ID.

## Zwei unabhängige Autorisierungsebenen

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    USER[Portalbenutzer] --> PERM[IT / HR / Company-Admin]
    PERM --> MANAGE[Darf API-Keys verwalten]

    KEY[API-Key] --> SCOPE[Ausgewählter Tenant- und Divisionsscope]
    SCOPE --> ACCESS[Darf passende API-Ressourcen lesen oder ändern]
```

Ein Portalbenutzer kann zur Erstellung von Keys berechtigt sein, während jeder einzelne Key weiterhin einen eigenen eingeschränkten API-Scope besitzt.

## Tenant und Division

* Ein Tenant besitzt seine Divisionshierarchie.
* Eine Division kann eine übergeordnete Division besitzen oder als Root-Division angelegt sein.
* Ein Mitarbeiter kann einem Tenant und optional einer Division zugeordnet sein.
* Eine Divisions-ID kann keinen Zugriff außerhalb des Key-Scopes gewähren.
* Öffentliche Mitarbeiter-Updates können einen bereits zugeordneten Mitarbeiter nicht in einen anderen Tenant verschieben.

## Operation, Request und Retry

Eine **logische Operation** kann mehrere HTTP-Versuche umfassen. Erzeugen Sie für jeden Versuch eine neue `X-Request-ID` und verknüpfen Sie die Versuche in Ihren eigenen Logs. Die Wiederverwendung einer ID macht die Operation nicht idempotent.