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

# Retrieve payroll export documents

> Discover payroll export metadata, select by tenant, format, and month range, and download an available file safely.

Payroll export documents are read-only through the Public API. The API exposes metadata and a download operation; it does not expose export generation or deletion.

## Supported formats

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

Values are case-sensitive.

## Retrieval swimlane

```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: Start payroll retrieval
    INT->>API: List documents by tenant, type, and month range
    API-->>INT: Metadata page
    INT->>INT: Select unprocessed document ID
    INT->>API: Get document metadata
    API-->>INT: fileName, mimeType, period, timestamps
    alt fileName is available
        INT->>API: Download document
        API-->>INT: Binary or text file
        INT->>PAY: Validate and import
        INT->>INT: Store document ID and import result
    else fileName is null
        INT->>INT: Record no file produced; do not call download blindly
    end
```

## List documents

```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"'
```

## Metadata fields

| Field                    | Meaning                                                |
| ------------------------ | ------------------------------------------------------ |
| `id`                     | Stable document identifier for metadata and download   |
| `tenant`                 | Owning tenant                                          |
| `type`                   | Export format                                          |
| `startMonth`             | First covered payroll month in `YYYY-MM`               |
| `endMonth`               | Last covered payroll month in `YYYY-MM`                |
| `fileName`               | Download filename, or `null` when no file was produced |
| `mimeType`               | Media type derived from the export format              |
| `createdAt`, `updatedAt` | UTC metadata timestamps                                |

## Download safely

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

<Steps>
  <Step title="Read metadata">
    Confirm tenant, type, month range, filename, and media type.
  </Step>

  <Step title="Check file availability">
    Do not request a file when `fileName` is `null`.
  </Step>

  <Step title="Download">
    Inspect HTTP status and `Content-Type` before writing the response as a file.
  </Step>

  <Step title="Validate downstream format">
    Apply the payroll system's encoding, delimiter, field, and period checks before import.
  </Step>

  <Step title="Persist processing state">
    Store document ID, content metadata, request ID, import timestamp, and outcome.
  </Step>
</Steps>

## Availability and scheduling

The public OpenAPI contract does not define the export-generation schedule, retention period, or a universal polling interval. Do not invent a cadence from `createdAt`. Use the customer-specific payroll process and treat document metadata as the source for availability.

## Download failures

| Status / error            | Action                                          |
| ------------------------- | ----------------------------------------------- |
| `404 FILE_NOT_FOUND`      | Re-read metadata and confirm that a file exists |
| `502 BAD_GATEWAY`         | Retry the download with bounded backoff         |
| `503 SERVICE_UNAVAILABLE` | Retry the download with bounded backoff         |
| `504 GATEWAY_TIMEOUT`     | Retry the download; discard incomplete data     |
| `429 RATE_LIMIT_EXCEEDED` | Honor `Retry-After`                             |

Downloaded payroll data must be protected by the destination system's access, retention, and deletion controls.