Payroll-Exportdokumente abrufen

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

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

Dokumente auflisten

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

GET /payroll/export-documents/{id}/download

Metadaten lesen

Prüfen Sie Tenant, Typ, Monatsbereich, Dateiname und Medientyp.

Dateiverfügbarkeit prüfen

Fordern Sie keine Datei an, wenn fileName den Wert null besitzt.

Herunterladen

Prüfen Sie HTTP-Status und Content-Type, bevor Sie die Response als Datei speichern.

Nachgelagertes Format validieren

Wenden Sie vor dem Import die Encoding-, Trennzeichen-, Feld- und Periodenprüfungen des Payroll-Systems an.

Verarbeitungsstatus speichern

Speichern Sie Dokument-ID, Inhaltsmetadaten, Request-ID, Importzeitpunkt und Ergebnis.

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.

Erste Schritte

Architektur & Konzepte

Integrationsleitfäden

Betrieb

Unterstützte Formate

Swimlane für den Abruf

Dokumente auflisten

Metadatenfelder

Sicher herunterladen

Verfügbarkeit und Zeitplanung

Downloadfehler

​Unterstützte Formate

​Swimlane für den Abruf

​Dokumente auflisten

​Metadatenfelder

​Sicher herunterladen

​Verfügbarkeit und Zeitplanung

​Downloadfehler

Unterstützte Formate

Swimlane für den Abruf

Dokumente auflisten

Metadatenfelder

Sicher herunterladen

Verfügbarkeit und Zeitplanung

Downloadfehler