# 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 der Zeiterfassungssoftware angelegten **Organisationseinheiten** (Abteilungen) mit zugehörigen `ObjectId`s zurück.

---

### 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 `webapi_test_parser.html` möglich die CSV Datei in ein JSON Array wo jeder Mitarbeieter eine JSON Objekt ist zu verwandeln.
Auch mit der passenden PHP Datei `Kalender-Export-Parser.php` 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"
      }
    ]
  }
  
  ]

  ```
`