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

# Häufig gestellte Fragen

> Antworten auf häufige Fragen zu Zugangsdaten, Umgebungen, Scope, Requests, Ressourcen, Retries und Betrieb.

## Zugriff und API-Keys

<AccordionGroup>
  <Accordion title="Wie erstelle ich einen API-Key?" defaultOpen>
    Öffnen Sie die [JobHandy-Administration](https://app.jobhandy.io/admin), wechseln Sie zu **IT-Einstellungen**, wählen Sie **API-Keys** und klicken Sie auf **Create API Key**. Siehe [API-Key-Verwaltung](/de/get-started/api-key-management).
  </Accordion>

  <Accordion title="Welche Portalberechtigungen dürfen Keys verwalten?">
    Mindestens eine der Berechtigungen **IT**, **HR** oder **Company-Admin** ist erforderlich.
  </Accordion>

  <Accordion title="Kann ich mehrere Keys erstellen?">
    Ja. Verwenden Sie getrennte Keys für getrennte Integrationen, Verantwortlichkeiten oder Scopes.
  </Accordion>

  <Accordion title="Kann ein Key auf mehrere Unternehmen zugreifen?">
    Ein Key kann auf die Unternehmen und Divisionen begrenzt werden, die im Administrationsportal ausgewählt wurden. Die API stellt jedes autorisierte Unternehmen anschließend als Tenant-Kontext dar.
  </Accordion>

  <Accordion title="Kann ich Name oder Scope eines vorhandenen Keys ändern?">
    Der dokumentierte Betriebsprozess verlässt sich nicht auf Änderungen vorhandener Zugangsdaten. Erstellen Sie einen Ersatz-Key mit dem erforderlichen Namen und Scope, stellen Sie ihn bereit und prüfen Sie ihn, bevor Sie den alten Key deaktivieren.
  </Accordion>

  <Accordion title="Kann ich den vollständigen Key später erneut anzeigen?">
    Behandeln Sie die Anzeige bei der Erstellung als sicheren Erfassungszeitpunkt. Wenn die Zugangsdaten nicht mehr verfügbar sind, erstellen und verteilen Sie einen Ersatz, statt von einer Wiederherstellung des geheimen Werts auszugehen.
  </Accordion>

  <Accordion title="Was ist der Unterschied zwischen Deaktivierung und Löschung?">
    Eine Deaktivierung beendet die Authentifizierung und erlaubt eine spätere Reaktivierung. Eine Löschung nimmt den Key dauerhaft aus dem Portalprozess außer Betrieb.
  </Accordion>
</AccordionGroup>

## Umgebungen und Tests

<AccordionGroup>
  <Accordion title="Gibt es eine öffentliche Sandbox- oder Stage-Basis-URL?" defaultOpen>
    Der öffentliche Vertrag dokumentiert ausschließlich `https://api.jobhandy.io/v1`. Interne Entwicklungs-Hosts sind nicht Bestandteil der Kundenkonfiguration.
  </Accordion>

  <Accordion title="Ist dryRun=true eine Testumgebung?">
    Nein. Der Modus validiert einen unterstützten Schreibvorgang gegen den aktuellen produktiven Scope und Zustand, ohne die dokumentierte Änderung oder Side Effects anzuwenden.
  </Accordion>

  <Accordion title="Garantiert ein Dry Run, dass der reale Schreibvorgang erfolgreich ist?">
    Nein. Ein Dry Run sperrt oder reserviert keinen Zustand. Behandeln Sie Konflikte beim realen Request erneut.
  </Accordion>
</AccordionGroup>

## Tenant und Scope

<AccordionGroup>
  <Accordion title="Was ist der Unterschied zwischen Unternehmen und Tenant?" defaultOpen>
    Unternehmen ist der fachlich sichtbare Portalbegriff. Tenant ist die technische API-Grenze und der Identifikator dieser Organisation.
  </Accordion>

  <Accordion title="Wann ist X-Tenant-ID erforderlich?">
    Senden Sie den Header, wenn eine Operation sonst keinen eindeutigen Tenant bestimmen kann oder wenn eine Collection bewusst auf einen autorisierten Tenant eingeschränkt werden soll.
  </Accordion>

  <Accordion title="Kann X-Tenant-ID zusätzlichen Zugriff gewähren?">
    Nein. Der Header kann ausschließlich den bereits dem API-Key zugewiesenen Scope einschränken.
  </Accordion>

  <Accordion title="Wie erhalte ich eine Tenant-ID?">
    Verwenden Sie die Tenant-ID aus autorisierten Ressourcen-Responses oder die beim Integrations-Onboarding bereitgestellte ID. Verwenden Sie keinen Unternehmensnamen und keine Divisions-ID.
  </Accordion>

  <Accordion title="Kann ich einen vorhandenen Mitarbeiter in einen anderen Tenant verschieben?">
    Nicht über `PATCH /employees/{id}`. Der Endpoint kann `divisionId` ausschließlich innerhalb desselben Tenants ändern oder entfernen.
  </Accordion>
</AccordionGroup>

## Requests und Retries

<AccordionGroup>
  <Accordion title="Ist X-Request-ID erforderlich?" defaultOpen>
    Der Header ist optional, wird aber dringend empfohlen. Fehlt er, erzeugt die API selbst eine ID.
  </Accordion>

  <Accordion title="Ist X-Request-ID ein Idempotency Key?">
    Nein. Es handelt sich um Korrelationsmetadaten; die ID dedupliziert keine Anfrage.
  </Accordion>

  <Accordion title="Was muss ich nach einem Write-Timeout tun?">
    Lesen oder suchen Sie die betroffene Ressource erneut, bevor Sie einen weiteren Schreibvorgang senden. Der Server kann die Änderung bereits gespeichert haben, bevor die Verbindung in einen Timeout gelaufen ist.
  </Accordion>

  <Accordion title="Werden unbekannte Request-Felder ignoriert?">
    Nein. Request-Schemas sind geschlossen; unbekannte Eigenschaften werden abgelehnt.
  </Accordion>

  <Accordion title="Kann ich GET-Anfragen wiederholen?">
    Transiente Read-Fehler können in der Regel mit begrenztem Backoff sicher wiederholt werden. Berücksichtigen Sie bei `429` den Header `Retry-After`.
  </Accordion>
</AccordionGroup>

## Collections und Filter

<AccordionGroup>
  <Accordion title="Wie groß darf eine Seite maximal sein?" defaultOpen>
    `pageSize` akzeptiert Werte von `1` bis `1000`; der Serverstandard ist `100`.
  </Accordion>

  <Accordion title="Kann ich nach mehreren Feldern sortieren?">
    Nein. Verwenden Sie genau ein vom Endpoint unterstütztes skalares Feld, optional mit vorangestelltem `-` für absteigende Sortierung.
  </Accordion>

  <Accordion title="Sind String-Filter case-sensitive?">
    String-Vergleiche sind case-insensitive. Enum-Werte bleiben case-sensitive.
  </Accordion>

  <Accordion title="Wie filtere ich Namen mit Leerzeichen oder Apostrophen?">
    Setzen Sie Werte mit Leerzeichen in Anführungszeichen und escapen Sie ein Apostroph mit `\'`. URL-encodieren Sie den vollständigen Filterwert.
  </Accordion>

  <Accordion title="Sind Collection-Seiten ein Snapshot?">
    Der öffentliche Vertrag garantiert keine Snapshot-Konsistenz. Verwenden Sie Checkpoints und berücksichtigen Sie parallele Änderungen.
  </Accordion>
</AccordionGroup>

## Ressourcen

<AccordionGroup>
  <Accordion title="Kann ich einen Mitarbeiter löschen?" defaultOpen>
    Es ist keine öffentliche Employee-Delete-Operation definiert. Verwenden Sie den dokumentierten Status `blocked` zum Sperren des Kontos und behandeln Sie die Löschung über den zuständigen Fachprozess.
  </Accordion>

  <Accordion title="Kann ich die geschäftliche E-Mail-Adresse eines Mitarbeiters ändern?">
    Die geschäftliche E-Mail-Adresse ist über den öffentlichen Employee-Patch-Endpoint nicht änderbar.
  </Accordion>

  <Accordion title="Kann eine Bestellentscheidung geändert werden?">
    Die Decision-Operation ist für Bestellungen im Status `under_review` vorgesehen. Eine finale Entscheidung kann `ORDER_ALREADY_DECIDED` zurückgeben; lesen und gleichen Sie den Zustand erneut ab, statt ihn zu überschreiben.
  </Accordion>

  <Accordion title="Kann ich für einen noch nicht aktivierten Mitarbeiter einen Vorfall erstellen?">
    Nein. `POST /incidents` antwortet mit `422 EMPLOYEE_NOT_ACTIVATED` und erstellt keinen Vorfall. Schließen Sie zuerst die Aktivierung des Mitarbeiters ab und senden Sie anschließend eine neue Anfrage mit einer neuen `X-Request-ID`.
  </Accordion>

  <Accordion title="Wann können Vorfallsanhänge hochgeladen werden?">
    Der Endpoint akzeptiert Bild- oder PDF-Anhänge für einen bearbeitbaren abgeschlossenen Vorfall, vorbehaltlich der Grenzwerte für Dateianzahl und vollständige Body-Größe.
  </Accordion>

  <Accordion title="Warum kann ein Payroll-Export fileName = null enthalten?">
    Das Metadatenschema erlaubt ausdrücklich `null`, wenn keine Datei erzeugt wurde. Rufen Sie die Download-Operation nicht blind auf.
  </Accordion>
</AccordionGroup>

## Betrieb

<AccordionGroup>
  <Accordion title="Wie hoch sind die numerischen Rate Limits?" defaultOpen>
    Der Vertrag definiert die Header `RateLimit-Policy`, `RateLimit` und `Retry-After` anstelle eines einheitlichen festen Kontingents. Lesen Sie die wirksamen Werte aus den Responses.
  </Accordion>

  <Accordion title="Bietet die API Webhooks an?">
    Der aktuelle öffentliche v1-Vertrag definiert keine Endpoints zur Webhook-Registrierung oder Event-Subscription. Verwenden Sie clientinitiiertes Polling.
  </Accordion>

  <Accordion title="Gibt es offizielle SDKs?">
    Die OpenAPI-Spezifikation ist der maßgebliche maschinenlesbare Vertrag. Erzeugen oder entwickeln Sie einen für Ihre Umgebung geeigneten Client und ergänzen Sie eigene Betriebskontrollen.
  </Accordion>

  <Accordion title="Welche Informationen benötigt der Support?">
    Senden Sie UTC-Zeit, Methode, Pfad, Status, Fehlercode, Request-ID, Tenant-Kontext und bereinigte Reproduktionsschritte. Senden Sie niemals den API-Key.
  </Accordion>
</AccordionGroup>