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

# Payroll-Exportdokumente abrufen

> Ermitteln Sie Metadaten zu Payroll-Exporten, wählen Sie nach Tenant, Format und Monatsbereich aus und laden Sie eine verfügbare Datei sicher herunter.

Payroll-Exportdokumente sind über die Public API schreibgeschützt. Die API stellt Metadaten und eine Download-Operation bereit; sie bietet keine Erzeugung oder Löschung von Exporten an.

## Unterstützte Formate

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
sap_hcm
personio_csv
hrworks_csv
diamant_software_diamant_4
universal_csv
universal_txt
datev_lodas
datev_lug
```

Die Werte sind case-sensitive.

## Swimlane für den Abruf

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Scheduler
    participant INT as Integration
    participant API as JobHandy API
    participant PAY as Payroll-System

    Scheduler->>INT: Payroll-Abruf starten
    INT->>API: Dokumente nach Tenant, Typ und Monatsbereich auflisten
    API-->>INT: Seite mit Metadaten
    INT->>INT: Noch nicht verarbeitete Dokument-ID auswählen
    INT->>API: Dokumentmetadaten abrufen
    API-->>INT: fileName, mimeType, Zeitraum, Zeitstempel
    alt fileName ist verfügbar
        INT->>API: Dokument herunterladen
        API-->>INT: Binär- oder Textdatei
        INT->>PAY: Validieren und importieren
        INT->>INT: Dokument-ID und Importergebnis speichern
    else fileName ist null
        INT->>INT: Dokumentieren, dass keine Datei erzeugt wurde; Download nicht blind aufrufen
    end
```

## Dokumente auflisten

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --get 'https://api.jobhandy.io/v1/payroll/export-documents' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-ID: {{tenantId}}' \
  --data-urlencode 'filter=type=datev_lodas AND startMonth="2026-01" AND endMonth="2026-01"'
```

## Metadatenfelder

| Feld                     | Bedeutung                                                      |
| ------------------------ | -------------------------------------------------------------- |
| `id`                     | Stabiler Dokumentidentifikator für Metadaten und Download      |
| `tenant`                 | Eigentümer-Tenant                                              |
| `type`                   | Exportformat                                                   |
| `startMonth`             | Erster abgedeckter Payroll-Monat in `YYYY-MM`                  |
| `endMonth`               | Letzter abgedeckter Payroll-Monat in `YYYY-MM`                 |
| `fileName`               | Download-Dateiname oder `null`, wenn keine Datei erzeugt wurde |
| `mimeType`               | Aus dem Exportformat abgeleiteter Medientyp                    |
| `createdAt`, `updatedAt` | UTC-Zeitstempel der Metadaten                                  |

## Sicher herunterladen

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /payroll/export-documents/{id}/download
```

<Steps>
  <Step title="Metadaten lesen">
    Prüfen Sie Tenant, Typ, Monatsbereich, Dateiname und Medientyp.
  </Step>

  <Step title="Dateiverfügbarkeit prüfen">
    Fordern Sie keine Datei an, wenn `fileName` den Wert `null` besitzt.
  </Step>

  <Step title="Herunterladen">
    Prüfen Sie HTTP-Status und `Content-Type`, bevor Sie die Response als Datei speichern.
  </Step>

  <Step title="Nachgelagertes Format validieren">
    Wenden Sie vor dem Import die Encoding-, Trennzeichen-, Feld- und Periodenprüfungen des Payroll-Systems an.
  </Step>

  <Step title="Verarbeitungsstatus speichern">
    Speichern Sie Dokument-ID, Inhaltsmetadaten, Request-ID, Importzeitpunkt und Ergebnis.
  </Step>
</Steps>

## Verfügbarkeit und Zeitplanung

Der öffentliche OpenAPI-Vertrag definiert weder den Erzeugungszeitplan noch die Aufbewahrungsdauer oder ein allgemeines Polling-Intervall. Leiten Sie keinen Zeitplan aus `createdAt` ab. Verwenden Sie den kundenspezifischen Payroll-Prozess und behandeln Sie die Dokumentmetadaten als Quelle für die Verfügbarkeit.

## Downloadfehler

| Status / Fehler           | Maßnahme                                                       |
| ------------------------- | -------------------------------------------------------------- |
| `404 FILE_NOT_FOUND`      | Metadaten erneut lesen und prüfen, ob eine Datei vorhanden ist |
| `502 BAD_GATEWAY`         | Download mit begrenztem Backoff wiederholen                    |
| `503 SERVICE_UNAVAILABLE` | Download mit begrenztem Backoff wiederholen                    |
| `504 GATEWAY_TIMEOUT`     | Download wiederholen; unvollständige Daten verwerfen           |
| `429 RATE_LIMIT_EXCEEDED` | `Retry-After` berücksichtigen                                  |

Heruntergeladene Payroll-Daten müssen durch die Zugriffs-, Aufbewahrungs- und Löschkontrollen des Zielsystems geschützt werden.