# Daten aus der Zeiterfassung übernehmen

Die Zeiterfassungssoftware bietet eine WebAPI-Schnittstelle zur automatisierten Datenabfrage, z.B. für Kalenderfehlzeiten.

---

## Voraussetzungen
 
- REST WebAPI Client (curl, Bruno, Postman, ...)
- IIS Webserver mit HTTPS-Unterstützung 
- Lizenz zur Nutzung der WebAPI für den Export von Daten

---

## Installation & Einrichtung

### 1. Export in der Zeiterfassungssoftware anlegen

- Navigiere zu:  
  `Einrichtung → Modelle → Datenaustausch → Exportdefinition → [+] Neu`
- Lade dort das gewünschte Export-Layout hoch.

---

### 2. (De)Aktivierung der zusätzlichen Zeitstempelverschlüsselung

- Als **Systemadministrator** in der Weboberfläche anmelden  
- Navigiere zu:  
  `Einrichtung → Personen → Systemstart (Datum 01.01.2000) auswählen`  
  `Systemeinstellungen → API Web-Service → Datenschutzeinstellung`
- Stelle sicher, dass **„Auf zusätzliche Client-Autorisierung wird verzichtet“** aktiviert ist.
- Erstelle ein Bearer-Token unter:  
  `https://<WebUI-URL>/Environment/Account/Token.aspx`  

  Mit folgenden Angaben:
  - **Schnittstelle:** `webapi`  
  - **Login:** Ein zugelassenes Benutzerkonto

---

## API-Anfragen

### 3. Verfügbare Exporte abfragen

```bash
curl --request GET \
     --url https://<Server-URL>/<API-Site>/api/export/ \
     --header 'authorization: <Token>'
```

> Gibt eine JSON-Liste aller in der Zeiterfassungssoftware definierten **Exportdefinitionen** zurück.  
> Die jeweilige **`ObjectId`** wird für spätere Anfragen benötigt.

---

### 4. Organisationseinheiten abfragen

```bash
curl --request GET \
     --url https://<Server-URL>/<API-Site>/api/organization/ \
     --header 'authorization: <Token>'
```

> Liefert alle in Zeiterfassungssoftware angelegten **Organisationseinheiten** (Abteilungen) mit zugehörigen `ObjectId`s.

---

### 5. Export beantragen

```bash
curl --request POST \
     --url https://<Server-URL>/<API-Site>/api/export \
     --header 'authorization: <Token>' \
     --header 'content-type: application/json' \
     --data '{
       "ExportDefinition": "<ObjectId aus Schritt 3>",
       "organizationUnit": "<ObjectId aus Schritt 4>",
       "DateFrom": "01.01.2024",
       "DateUntil": "31.01.2024"
     }'
```

> Gibt eine GUID zurück, die zur Abfrage der generierten Daten verwendet wird.

---

### 6. Exportdaten abrufen

```bash
curl --request GET \
     --url https://<Server-URL>/<API-Site>/api/export/<GUID> \
     --header 'authorization: <Token>'
```

> **Mögliche Antworten:**

- **Daten liegen vor:**  
  Die Antwort enthält die exportierten Daten. Beispiel:
  ```csv
  <PersonalNr>;<Nachname>;<Vorname>;<Datum>;<E-Mail/Username>;<FehlzeitNr erster Halbtag>;<FehlzeitNr zweiter Halbtag>;<FehlzeitName erster Halbtag>;<FehlzeitName zweiter Halbtag>;<TagestypNr>;<Name des Tages/Feiertag>
  4711;Musterfrau;Max;01.06.2025;Max.Musterfrau@kunde.tld;;;;;2;Sonntag;
  4711;Musterfrau;Max;02.06.2025;Max.Musterfrau@kunde.tld;85;85;Mob.Arb.;Mob.Arb.;3;Montag;
  4711;Musterfrau;Max;03.06.2025;Max.Musterfrau@kunde.tld;85;85;Mob.Arb.;Mob.Arb.;4;Dienstag;
  4711;Musterfrau;Max;04.06.2025;Max.Musterfrau@kunde.tld;85;85;Mob.Arb.;Mob.Arb.;5;Mittwoch;
  4711;Musterfrau;Max;05.06.2025;Max.Musterfrau@kunde.tld;90;90;GLZ;GLZ;6;Donnerstag;
  4711;Musterfrau;Max;06.06.2025;Max.Musterfrau@kunde.tld;;;;;7;Freitag;
  4711;Musterfrau;Max;07.06.2025;Max.Musterfrau@kunde.tld;;;;;8;Samstag;
  4711;Musterfrau;Max;08.06.2025;Max.Musterfrau@kunde.tld;;;;;48;Pfingstsonntag;
  4711;Musterfrau;Max;09.06.2025;Max.Musterfrau@kunde.tld;;;;;49;Pfingstmontag;
  ...
  ```

- **Export läuft noch:**  
  Rückgabe folgender JSON-Statusmeldung: 
  `{
  "Result": "JobPending",
  "Message": ""
}

---

### 7. Parsing Data / Weiterverarbeitung

Es ist mit der API Test test2.html möglich die CSV Datei in ein JSON Array wo jeder Mitarbeieter eine JSON Objekt ist zu verwandeln.
Auch mit der Passenden PHP Date ist die Konvertierung im Backend möglich, nicht nur wie in test2.html im Frontend.

Ein solches Ergrbnis kann dabei erwartet werden:
  ```json
[
  {
    "nr": "33",
    "nachname": "Musterman",
    "vorname": "Hans",
    "email": "Hans.Musterman@kunde.tld",
    "tage_fehlzeit": [
      {
        "datum": "02.06.2025",
        "fehlzeitNR1HT": "85",
        "fehlzeitNR2HT": "85",
        "fehlzeitName1HT": "Mob.Arb.",
        "fehlzeitName2HT": "Mob.Arb.",
        "tagtypNR": "3",
        "tagtypName": "Montag"
      },
       {
        "datum": "03.06.2025",
        "fehlzeitNR1HT": "85",
        "fehlzeitNR2HT": "85",
        "fehlzeitName1HT": "Mob.Arb.",
        "fehlzeitName2HT": "Mob.Arb.",
        "tagtypNR": "4",
        "tagtypName": "Dienstag"
      },
       {
        "datum": "04.06.2025",
        "fehlzeitNR1HT": "85",
        "fehlzeitNR2HT": "85",
        "fehlzeitName1HT": "Mob.Arb.",
        "fehlzeitName2HT": "Mob.Arb.",
        "tagtypNR": "5",
        "tagtypName": "Mittwoch"
      },
       {
        "datum": "05.06.2025",
        "fehlzeitNR1HT": "90",
        "fehlzeitNR2HT": "90",
        "fehlzeitName1HT": "GLZ",
        "fehlzeitName2HT": "GLZ",
        "tagtypNR": "6",
        "tagtypName": "Donnerstag"
      }
    ],
    "tage_feiertage": [
      {
        "datum": "08.06.2025",
        "fehlzeitNR1HT": "",
        "fehlzeitNR2HT": "",
        "fehlzeitName1HT": "",
        "fehlzeitName2HT": "",
        "tagtypNR": "48",
        "tagtypName": "Pfingstsonntag"
      },
      {
        "datum": "09.06.2025",
        "fehlzeitNR1HT": "",
        "fehlzeitNR2HT": "",
        "fehlzeitName1HT": "",
        "fehlzeitName2HT": "",
        "tagtypNR": "49",
        "tagtypName": "Pfingstmontag"
      }
    ]
  }
  
  ]

  ```
`