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

# Quickstart

> Erstellen Sie Zugangsdaten, prüfen Sie die Erreichbarkeit, authentifizieren Sie sich, fragen Sie Mitarbeiter ab und validieren Sie einen Schreibvorgang ohne Speicherung.

Dieser Quickstart prüft den vollständigen Integrationspfad, ohne dass ein dauerhafter Schreibvorgang erforderlich ist.

## Voraussetzungen

* Zugriff auf die [JobHandy-Administration](https://app.jobhandy.io/admin)
* Portalberechtigung **IT**, **HR** oder **Company-Admin**, um einen Key zu erstellen
* Ein dedizierter API-Key mit dem erforderlichen Unternehmens- und Divisionsscope
* Eine serverseitige Runtime, die Secrets sicher speichern kann

<Card title="Zuerst API-Key erstellen" icon="key" horizontal href="/de/get-started/api-key-management">
  Erstellen und speichern Sie einen Key mit passendem Scope, bevor Sie die geschützten Beispiele ausführen.
</Card>

## 1. Öffentliche Erreichbarkeit prüfen

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url 'https://api.jobhandy.io/v1/health'
```

Eine erfolgreiche Antwort bestätigt, dass der öffentliche API-Endpoint erreichbar ist. Sie validiert weder den API-Key noch den Tenant-Scope oder den Zugriff auf geschützte Ressourcen.

## 2. Request-ID erzeugen

Verwenden Sie für jeden logischen Versuch eine neue UUID v4 oder v7. Die API gibt eine übermittelte ID zurück oder erzeugt selbst eine, wenn der Header fehlt.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
X-Request-ID: {{requestId}}
```

`X-Request-ID` dient ausschließlich der Korrelation. Sie ist kein Idempotency Key.

## 3. Mitarbeiter auflisten

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request GET \
    --url 'https://api.jobhandy.io/v1/employees?page=1&pageSize=10' \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'X-Request-ID: {{requestId}}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const requestId = crypto.randomUUID();
  const response = await fetch(
    'https://api.jobhandy.io/v1/employees?page=1&pageSize=10',
    {
      headers: {
        'X-API-Key': process.env.JOBHANDY_API_KEY,
        'X-Request-ID': requestId,
      },
    },
  );
  const payload = await response.json();
  console.log(response.status, response.headers.get('x-request-id'), payload);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import uuid
  import requests

  request_id = str(uuid.uuid4())
  response = requests.get(
      'https://api.jobhandy.io/v1/employees',
      params={'page': 1, 'pageSize': 10},
      headers={
          'X-API-Key': os.environ['JOBHANDY_API_KEY'],
          'X-Request-ID': request_id,
      },
      timeout=30,
  )
  print(response.status_code, response.headers.get('X-Request-ID'))
  response.raise_for_status()
  print(response.json())
  ```

  ```powershell PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
  $requestId = [guid]::NewGuid().ToString()
  $headers = @{
      'X-API-Key'    = $env:JOBHANDY_API_KEY
      'X-Request-ID' = $requestId
  }
  Invoke-RestMethod `
      -Method Get `
      -Uri 'https://api.jobhandy.io/v1/employees?page=1&pageSize=10' `
      -Headers $headers
  ```
</CodeGroup>

## 4. Bei Bedarf auf einen Tenant einschränken

Wenn der Key mehrere Unternehmen abdeckt, fügen Sie die Tenant-ID hinzu, die von JobHandy-Ressourcen zurückgegeben oder beim Integrations-Onboarding bereitgestellt wurde:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
X-Tenant-ID: {{tenantId}}
```

Lassen Sie den Header weg, wenn bewusst eine Collection über alle Tenants im Scope benötigt wird. Siehe [Tenant-Scope](/de/concepts/tenant-scope).

## 5. Filter-Quoting testen

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --get 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'filter=lastName="van Example"'
```

Der HTTP-Client URL-encodiert den unveränderten Filterausdruck. Werte mit Leerzeichen müssen in Anführungszeichen gesetzt werden.

## 6. Schreibvorgang ohne Speicherung validieren

Verwenden Sie eine unterstützte Schreiboperation mit `dryRun=true`. Das folgende Beispiel validiert eine Mitarbeiteränderung, speichert sie jedoch nicht:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PATCH \
  --url 'https://api.jobhandy.io/v1/employees/EMPLOYEE_ID?dryRun=true' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Request-ID: {{requestId}}' \
  --data '{"phoneNumber":"+49 221 1234567"}'
```

Ein erfolgreicher Dry Run gibt den voraussichtlichen Mitarbeiterzustand zurück. Er reserviert keinen Zustand; der reale Schreibvorgang kann weiterhin fehlschlagen, wenn sich die Ressource zwischen Validierung und Speicherung ändert.

## 7. Fehlerantwort erkennen

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "TENANT_NOT_IN_SCOPE",
    "message": "The selected tenant is not available to this API key.",
    "requestId": "{{requestId}}"
  }
}
```

Verwenden Sie `error.code` für Programmlogik, `error.message` für die Diagnose und `error.requestId` für Logs und Supportanfragen.

## Erfolgskriterien

Der Quickstart ist abgeschlossen, wenn alle folgenden Bedingungen erfüllt sind:

* `GET /health` antwortet erfolgreich
* eine geschützte Anfrage wird mit Ihrem API-Key authentifiziert
* die Tenant-Auswahl verhält sich entsprechend dem Key-Scope
* die Antwort enthält oder spiegelt `X-Request-ID`
* ein gequoteter Filter liefert eine gültige Collection-Antwort
* ein unterstützter Dry Run liefert eine Projektion, ohne Daten zu ändern
* Ihre Logs enthalten weder den API-Key noch unnötige personenbezogene Daten

<Card title="Produktiven Betrieb vorbereiten" icon="clipboard-check" horizontal href="/de/get-started/go-live-checklist">
  Schließen Sie vor der Aktivierung eines Zeitplans die Sicherheits-, Retry-, Reconciliation-, Monitoring- und Betriebsmaßnahmen ab.
</Card>