> ## 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.

# JobHandy Public API – Referenz

> Maßgebliche Referenz für JobHandy-Operationen, Request-Verhalten, Ressourcen, Fehler und den OpenAPI-3.1-Vertrag.

<Badge color="green" shape="pill" icon="circle-check">Produktion</Badge> <Badge color="purple" shape="pill" icon="file-code">OpenAPI 3.1</Badge>

## Verbindungsdaten

| Einstellung          | Wert                                 |
| -------------------- | ------------------------------------ |
| Basis-URL            | `https://api.jobhandy.io/v1`         |
| Authentifizierung    | `X-API-Key`, außer bei `GET /health` |
| Tenant-Auswahl       | `X-Tenant-ID`, wo dokumentiert       |
| Korrelation          | `X-Request-ID`, UUID v4 oder v7      |
| JSON-Medientyp       | `application/json`                   |
| Öffentliche Umgebung | Ausschließlich Produktion            |

## Ressourcen

<Columns cols={3}>
  <Card title="Mitarbeiter" icon="users" href="/de/api-reference/employees">
    Stammdaten, Kontosperrung, Tenant-Zuordnung und Divisionszuweisung.
  </Card>

  <Card title="Bestellungen" icon="shopping-bag" href="/de/api-reference/orders">
    Abruf, HR-Freigabeentscheidungen, Produkte, Vertragsdaten und Dokumente.
  </Card>

  <Card title="Vorfälle" icon="triangle-alert" href="/de/api-reference/incidents">
    Meldung, serververwalteter Lifecycle-Status, unterstützte Updates und Nachweisdateien.
  </Card>

  <Card title="Divisionen" icon="network" href="/de/api-reference/divisions">
    Tenant-eigene Hierarchie, Reihenfolge unter Geschwistern, Parent-Beziehungen und Kostenstellen.
  </Card>

  <Card title="Payroll-Exporte" icon="file-spreadsheet" href="/de/api-reference/payroll-export-documents">
    Schreibgeschützte Dokumentmetadaten und Downloads verfügbarer Dateien.
  </Card>

  <Card title="Health" icon="heart-pulse" href="/de/api-reference/health">
    Öffentlicher Endpoint zur grundlegenden Verfügbarkeitsprüfung.
  </Card>
</Columns>

## Operationsmatrix

| Ressource               | Lesen | Erstellen |       Aktualisieren | Löschen | Spezialoperation                                                     |
| ----------------------- | ----: | --------: | ------------------: | ------: | -------------------------------------------------------------------- |
| Mitarbeiter             |    Ja |        Ja |                  Ja |    Nein | Sperren/Entsperren über Update                                       |
| Bestellungen            |    Ja |      Nein |    Nur Entscheidung |    Nein | Bestellung in Prüfung freigeben oder ablehnen; Anhänge herunterladen |
| Vorfälle                |    Ja |        Ja | Unterstützte Felder |    Nein | Zulässige Anhänge hochladen                                          |
| Divisionen              |    Ja |        Ja |                  Ja |    Nein | Hierarchievalidierung                                                |
| Payroll-Exportdokumente |    Ja |      Nein |                Nein |    Nein | Verfügbare Datei herunterladen                                       |
| Health                  |    Ja |      Nein |                Nein |    Nein | Keine Authentifizierung                                              |

## Einheitliches Verhalten

<AccordionGroup>
  <Accordion title="Authentifizierung und Scope" defaultOpen>
    Geschützte Anfragen erfordern `X-API-Key`. Die API erzwingt den Tenant- und Divisionsscope des Keys für jede Ressource und Referenz.
  </Accordion>

  <Accordion title="Optionale Parameter">
    Optionale Query- und Headerparameter sind in der Referenz sichtbar, werden aber erst nach Auswahl in generierte Requests übernommen.
  </Accordion>

  <Accordion title="Dry Runs">
    Unterstützte Schreibvorgänge akzeptieren `dryRun=true` und geben die dokumentierte Projektion zurück, ohne Speicherung oder Side Effects anzuwenden.
  </Accordion>

  <Accordion title="Fehler">
    Fehler verwenden `{ "error": { "code", "message", "requestId" } }`. Die Response-Liste der jeweiligen Operation ist maßgeblich.
  </Accordion>

  <Accordion title="Retries">
    Reads können innerhalb begrenzter Richtlinien wiederholt werden. Writes erfordern nach Timeouts oder Konflikten eine Reconciliation des aktuellen Zustands.
  </Accordion>
</AccordionGroup>

## Vor der Verwendung einer Operation

1. Prüfen Sie, ob der API-Key den erforderlichen Scope enthält.
2. Ermitteln Sie, ob `X-Tenant-ID` erforderlich ist.
3. Prüfen Sie Side Effects und Dry-Run-Unterstützung.
4. Erzeugen und protokollieren Sie `X-Request-ID`.
5. Behandeln Sie jeden dokumentierten Response-Status.
6. Definieren Sie die Reconciliation, bevor Sie einen Write wiederholen.

<CardGroup cols={2}>
  <Card title="Fehlerbehandlung" icon="circle-alert" href="/de/concepts/error-handling">
    Ordnen Sie HTTP-Status, API-Fehlercode, Korrekturmaßnahme und Retrybarkeit zu.
  </Card>

  <Card title="OpenAPI-Spezifikation" icon="download" href="/de/api-reference/openapi-specification">
    Laden Sie den vollständigen maschinenlesbaren Vertrag herunter.
  </Card>
</CardGroup>