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

> Erstellen Sie sichere, produktionsreife HR- und Payroll-Integrationen mit der JobHandy Public API.

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

Die JobHandy Public API ist eine Server-zu-Server-Schnittstelle zum Synchronisieren von Mitarbeiterstammdaten, Verarbeiten von HR-Entscheidungen zu Bestellungen, Melden von Vorfällen, Pflegen organisatorischer Divisionen und Abrufen von Payroll-Exportdokumenten.

<Columns cols={3}>
  <Card title="Produktive Basis-URL" icon="globe">
    `https://api.jobhandy.io/v1`
  </Card>

  <Card title="Authentifizierung" icon="key-round">
    `X-API-Key` bei jeder geschützten Anfrage
  </Card>

  <Card title="Anfragekorrelation" icon="hash">
    UUID v4 oder v7 in `X-Request-ID`
  </Card>
</Columns>

<CardGroup cols={2}>
  <Card title="API-Key erstellen" icon="key" href="/de/get-started/api-key-management">
    Erstellen Sie im JobHandy-Administrationsbereich einen Key mit passendem Scope.
  </Card>

  <Card title="Quickstart beginnen" icon="rocket" href="/de/get-started/quickstart">
    Prüfen Sie Erreichbarkeit und Authentifizierung, lesen Sie Mitarbeiter und validieren Sie einen Schreibvorgang.
  </Card>

  <Card title="API-Referenz öffnen" icon="braces" href="/de/api-reference/overview">
    Prüfen Sie alle Operationen, Parameter, Antworten, Schemas und Fehlerfälle.
  </Card>

  <Card title="OpenAPI herunterladen" icon="download" href="/de/api-reference/openapi-specification">
    Verwenden Sie den maßgeblichen OpenAPI-3.1-Vertrag im JSON- oder YAML-Format.
  </Card>
</CardGroup>

## Integrationskontext

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    HRIS[HRIS / HCM] --> INT[Kundenintegration]
    PAY[Payroll-System] --> INT
    IP[Integrationsplattform] --> INT

    INT -->|X-API-Key| API[JobHandy Public API]
    INT -.->|X-Tenant-ID bei Bedarf| API
    INT -.->|X-Request-ID empfohlen| API

    API --> EMP[Mitarbeiter]
    API --> ORD[Bestellungen]
    API --> INC[Vorfälle]
    API --> DIV[Divisionen]
    API --> EXP[Payroll-Exporte]
```

Die Kundenintegration ist für Zeitplanung, Mapping, Retry-Steuerung, Checkpoints, sichere Secret-Speicherung und nachgelagerte Verarbeitung verantwortlich. JobHandy validiert die Anfrage, erzwingt den Scope des API-Keys, wendet die dokumentierten Statusregeln an und gibt zur Korrelation eine Request-ID zurück.

## Was Sie integrieren können

<Columns cols={3}>
  <Card title="Mitarbeitersynchronisation" icon="users" href="/de/guides/sync-employees">
    Mitarbeiter anlegen, unterstützte Felder aktualisieren, Divisionen zuweisen und Konten sperren oder entsperren.
  </Card>

  <Card title="HR-Prüfung von Bestellungen" icon="badge-check" href="/de/guides/process-orders">
    Zu prüfende Bestellungen abrufen und eine Freigabe- oder Ablehnungsentscheidung übermitteln.
  </Card>

  <Card title="Vorfallsmeldungen" icon="triangle-alert" href="/de/guides/manage-incidents">
    Mitarbeitervorfälle anlegen und aktualisieren sowie zulässige Nachweisdokumente hochladen.
  </Card>

  <Card title="Organisationsstruktur" icon="network" href="/de/guides/manage-divisions">
    Tenant-eigene Divisionshierarchien und Kostenstellen erstellen und pflegen.
  </Card>

  <Card title="Payroll-Abruf" icon="file-spreadsheet" href="/de/guides/payroll-exports">
    Metadaten zu Payroll-Exporten ermitteln und verfügbare Dateien herunterladen.
  </Card>

  <Card title="Betriebsüberwachung" icon="heart-pulse" href="/de/api-reference/health/get-health">
    Die grundlegende Verfügbarkeit der Public API ohne API-Key prüfen.
  </Card>
</Columns>

## Grundregeln

<AccordionGroup>
  <Accordion title="Ausschließlich produktiver Endpoint" defaultOpen icon="server">
    Öffentliche Integrationen verwenden `https://api.jobhandy.io/v1`. Interne Entwicklungs- oder Stage-Hosts sind nicht Bestandteil des öffentlichen Vertrags.
  </Accordion>

  <Accordion title="Zugriff nach dem Least-Privilege-Prinzip" icon="shield-check">
    Ein API-Key kann ausschließlich auf die in seinem Scope ausgewählten Tenants und Divisionen zugreifen. `X-Tenant-ID` kann diesen Scope einschränken, aber niemals erweitern.
  </Accordion>

  <Accordion title="Dry Run ist keine Sandbox" icon="flask-conical">
    Unterstützte Schreiboperationen akzeptieren `dryRun=true`. Die Anfrage wird gegen den aktuellen produktiven Scope und Zustand validiert; die dokumentierte Änderung und ihre Side Effects werden jedoch nicht ausgeführt.
  </Accordion>

  <Accordion title="Unbekannte Felder werden abgelehnt" icon="braces">
    Request-Schemas sind geschlossen. Senden Sie ausschließlich dokumentierte Eigenschaften und Medientypen.
  </Accordion>

  <Accordion title="Request-IDs sind keine Idempotency Keys" icon="hash">
    `X-Request-ID` korreliert Anfragen und Antworten. Der Header dedupliziert keine Schreibvorgänge und macht einen Retry nicht automatisch sicher.
  </Accordion>
</AccordionGroup>

## Ressourcenmodell

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    KEY[Scope des API-Keys] --> TEN[Tenant / Unternehmen]
    TEN --> DIV[Divisionen]
    TEN --> EMP[Mitarbeiter]
    EMP --> ORD[Bestellungen]
    EMP --> INC[Vorfälle]
    ORD --> OA[Bestellanhänge]
    INC --> IA[Vorfallsanhänge]
    TEN --> PE[Payroll-Exportdokumente]
```

Weitere Informationen zu Eigentümerschaft, Beziehungen und Begriffen finden Sie unter [Architektur und Ressourcenmodell](/de/concepts/architecture-resource-model).

## Empfohlener Weg in den produktiven Betrieb

<Steps>
  <Step title="Dedizierten API-Key erstellen">
    Wählen Sie nur die Unternehmen und Divisionen aus, die die Integration tatsächlich benötigt.
  </Step>

  <Step title="Quickstart vollständig durchführen">
    Prüfen Sie Health, Authentifizierung, Tenant-Auswahl, Request-IDs und Dry-Run-Validierung.
  </Step>

  <Step title="Passenden Integrationsleitfaden umsetzen">
    Folgen Sie dem Ablauf für Mitarbeiter, Bestellungen, Vorfälle, Divisionen oder Payroll-Exporte.
  </Step>

  <Step title="Go-live-Checkliste abschließen">
    Prüfen Sie Secret-Speicherung, Retries, Reconciliation, Monitoring und Supportbereitschaft.
  </Step>
</Steps>

<Card title="Go-live-Checkliste prüfen" icon="clipboard-check" horizontal href="/de/get-started/go-live-checklist">
  Stellen Sie vor der Aktivierung produktiver Zeitpläne sicher, dass die Integration sicher betrieben werden kann.
</Card>