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

# Bestellungen und HR-Entscheidungen verarbeiten

> Rufen Sie Bestellungen in HR-Prüfung ab, validieren Sie genau eine finale Entscheidung, gleichen Sie Timeouts ab und laden Sie Bestelldokumente herunter.

Die Public API bietet Lesezugriff auf Bestellungen und genau eine HR-Entscheidungsoperation für eine Bestellung im Status `under_review`.

## Statusmodell

Das Bestellschema kann folgende Werte zurückgeben:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
under_review
rejected
approved
active
archived
withdrawn
```

Die öffentliche Decision-Operation steuert ausschließlich den dokumentierten Übergang von `under_review` zu `approved` oder `rejected`. Weitere Lifecycle-Übergänge werden serverseitig oder außerhalb dieser Operation ausgeführt.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
stateDiagram-v2
    [*] --> under_review
    under_review --> approved: decision=approved
    under_review --> rejected: decision=rejected
    approved --> active: außerhalb der Decision-Operation
    active --> archived: außerhalb der Decision-Operation
    under_review --> withdrawn: außerhalb der Decision-Operation
```

## Swimlane der HR-Prüfung

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Portal as JobHandy
    participant INT as HR-Integration
    participant HR as HR-Prüfer
    participant API as JobHandy API
    participant NOTIFY as Benachrichtigungsprozess

    Portal->>Portal: Bestellung erreicht under_review
    INT->>API: GET /orders?filter=status=under_review
    API-->>INT: Zu prüfende Bestellungen
    INT->>HR: Mitarbeiter, Produkte, Daten und Dokumente anzeigen
    HR-->>INT: Freigeben oder ablehnen
    INT->>API: POST /orders/{id}/decision?dryRun=true
    API-->>INT: Projizierte Bestellung oder Validierungsfehler
    INT->>API: POST /orders/{id}/decision
    API->>NOTIFY: Zugehörige Benachrichtigungen auslösen
    API-->>INT: Aktualisierte Bestellung + Request-ID
```

Der öffentliche Vertrag bestätigt, dass eine Freigabe entsprechende Benachrichtigungen auslöst, nennt jedoch keine konkreten Empfänger oder Zustellkanäle. Bauen Sie keine Kundenlogik auf einer undokumentierten Empfängerliste auf.

## Zu bearbeitende Bestellungen abrufen

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --get 'https://api.jobhandy.io/v1/orders' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-ID: {{tenantId}}' \
  --data-urlencode 'filter=status=under_review' \
  --data-urlencode 'sort=createdAt'
```

## Aktuellen Zustand prüfen

Rufen Sie unmittelbar vor einer Entscheidung `GET /orders/{id}` auf und prüfen Sie:

* der Status ist weiterhin `under_review`
* der Mitarbeiter entspricht dem erwarteten Datensatz und die Anfrage verwendet den vorgesehenen Tenant-Kontext
* Produktmodell, Hersteller, Artikelgruppe, Umsatzsteuersatz, Brutto- und Nettobeträge, Servicebeträge und Zubehörkennzeichen stimmen mit der Prüfung überein
* Vertragsfelder sind akzeptabel
* erforderliche Anhänge sind verfügbar

<Note>
  `vatRate`, `grossAmount`, `netAmount`, `grossService` und `netService` sind Dezimalzeichenfolgen. Bewahren Sie deren Genauigkeit auf und verwenden Sie für Berechnungen einen exakten Dezimaldatentyp. `model`, `manufacturerName`, `articleGroupName`, `service`, `grossService` und `netService` können entsprechend dem Schema `null` sein.
</Note>

<Info>
  Order-Responses enthalten `tenant` und `divisionId` nicht mehr. Die Informationen zur HR-Prüfung werden in `hrHistory` zurückgegeben; `decisionBy` ist dort eine nullable Benutzer-ID anstelle des bisherigen Actor-Category-Werts.
</Info>

## Validieren und anwenden

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /orders/{id}/decision?dryRun=true
Content-Type: application/json
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "decision": "approved"
}
```

Senden Sie nach einer erfolgreichen Projektion dieselbe Anfrage ohne `dryRun=true`.

## Parallelität und Finalität

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A[Prüfer übermittelt Entscheidung] --> B[Aktuelle Bestellung lesen]
    B --> C{status = under_review?}
    C -- Nein --> D[Vorhandenen finalen Zustand abgleichen]
    C -- Ja --> E[Entscheidung per Dry Run validieren]
    E --> F[Entscheidung anwenden]
    F --> G{Response empfangen?}
    G -- Ja --> H[Ergebnis speichern]
    G -- Timeout --> I[Bestellung erneut lesen]
    I --> J{Gewünschte Entscheidung vorhanden?}
    J -- Ja --> H
    J -- Nein --> K[Manuelle oder kontrollierte Retry-Entscheidung]
```

## Konfliktbehandlung

| Fehler                     | Bedeutung                                                       | Maßnahme                                   |
| -------------------------- | --------------------------------------------------------------- | ------------------------------------------ |
| `ORDER_ALREADY_DECIDED`    | Es existiert bereits eine finale HR-Entscheidung                | Erneut lesen und abgleichen                |
| `INVALID_STATE_TRANSITION` | Bestellung ist für die angeforderte Entscheidung nicht zulässig | Retries stoppen und Workflow aktualisieren |
| `EMPLOYEE_BLOCKED`         | Mitarbeiterstatus verhindert die Operation                      | Mitarbeiter- oder Fachstatus klären        |
| `409` nach Dry Run         | Zustand hat sich vor der Speicherung geändert                   | Bestellung erneut lesen                    |

## Bestelldokumente herunterladen

Verwenden Sie die von einer Bestellung zurückgegebene Attachment-ID:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /orders/attachments/{id}
```

Prüfen Sie Status und `Content-Type`, bevor Sie die Response als Datei behandeln. Wiederholen Sie transiente Downloadfehler mit begrenztem Backoff.