TerraBytes.Personio.SDK

SDK/API Client
 

   

Dieser Client stellt eine typsichere, strukturierte Anbindung an die Personio REST API v1 zur Verfügung. Ziel ist eine vollständige Integration aller API-Endpunkte mit übersichtlicher Struktur, konfigurierbarer Authentifizierung und sauberem Paging- und Fehlerverhalten.

Struktur

Projekte

Personio.Api.Client: Enthält alle HTTP-Clients, DTOs, Konfigurationsmodelle und Endpunktdefinitionen

Personio.Api.XafBridge (optional): Adapter für DevExpress XAF-Objektspeicherung

Hauptklassen (Clients)

EmployeeClient: Zugriff auf Mitarbeitende (/v1/company/employees)

TimeOffClient: Zugriff auf Abwesenheiten (/v1/company/time-offs)

TimeOffTypeClient: Zugriff auf Abwesenheitstypen (/v1/company/time-off-types)

AttendanceClient: Zugriff auf An- und Abwesenheiten

AbsencePeriodClient: Zugriff auf Zeiträume

DocumentCategoryClient: Zugriff auf Dokumentenkategorien

Serviceklasse

PersonioDataFetchService: Koordiniert den sequentiellen Abruf aller Personio-Daten, verwendet die einzelnen Clients

---

Authentifizierung

Die Authentifizierung erfolgt über ClientId und ClientSecret. Die Klasse PersonioAuthService verwaltet das Token und aktualisiert es automatisch.

Header:

Authorization: Bearer {token}

X-Personio-Partner-ID

X-Personio-App-ID

---

Konfiguration

Zentrale Konfiguration über PersonioFetchOptions bzw. PersonioEmployeeQueryOptions

public class PersonioFetchOptions
{
    public string ClientId { get; set; }
    public string ClientSecret { get; set; }
    public string PartnerId { get; set; }
    public string AppId { get; set; }
    public DateTime? UpdatedSince { get; set; }
    public string? Email { get; set; }
    public List<string>? Attributes { get; set; }
    public PersonioPagingOptions? Paging { get; set; }
}

public class PersonioPagingOptions
{
    public int? Limit { get; set; } = 100;
    public int? Offset { get; set; } = 0;
}

---

Paging

Alle GET-Endpunkte mit Paginierung unterstützen die automatische Navigation durch limit, offset und metadata.total_pages.

---

Beispiel: Mitarbeiter abrufen

var options = new PersonioEmployeeQueryOptions
{
    PartnerId = "xyz",
    AppId = "abc",
    UpdatedSince = DateTime.UtcNow.AddDays(-7),
    Attributes = new List<string> { "first_name", "last_name", "email" }
};

var employees = await _employeeClient.GetAllEmployeesRawAsync(options);

---

Besonderheiten

Vollständige Deserialisierung dynamischer Attribute mit Typinformationen

Saubere Trennung zwischen Rohdaten (Raw) und gemappten Wrapper-Objekten (Entry)

Fehlerhandling mit HttpRequestException und Logging

---

TODO / Geplant

Unterstützung für Webhook-Endpunkte

Upload/Download von Dokumenten

Integration der v2 API (wenn veröffentlicht)