# Eingangsnachrichten

Eine **InboundMessage** ist der Datenbankeintrag, der für jede empfangene Bestellung angelegt wird. Sie durchläuft einen klar definierten Lebenszyklus – vom Eingang über Transformation und Zustellung bis zur (oft automatisch nach 90 Tagen erfolgenden) Payload-Löschung.

## Lebenszyklus

```
empfangen → queued → processing → delivered
                 │        │
                 │        └→ permanently_failed   (Transformation gescheitert)
                 └→ failed → (retry) → delivered
                                    └→ permanently_failed
                                            │
                                            └→ „Erneut zustellen" → queued (manuell)
```

### Statuswerte

| Status | Bedeutung |
|---|---|
| **queued** | Empfangen und authentifiziert, wartet auf Verarbeitung |
| **processing** | Der Job läuft – Payload wird transformiert und an die Transporte übergeben |
| **delivered** | Mindestens ein Transport hat erfolgreich zugestellt |
| **failed** | Aktueller Versuch ist gescheitert, Retry ist eingereiht |
| **permanently_failed** | Nach 5 erfolglosen Zustellversuchen – oder sofort, wenn die Transformation scheitert (z. B. fehlerhafte Mapping-Regeln) oder die Pipeline keine aktive Zustellung hat: automatisch wiederholt Orderport eine Transformation nie. Manuell können Sie die Nachricht erneut zustellen, dann läuft auch die Transformation neu. Den Grund nennt die Detailseite oben im Kasten „Warum ist das fehlgeschlagen?“ |

Sie sehen den Status im Dashboard und in der Bestellungs-Liste. Die Detailseite zeigt zusätzlich die einzelnen **Transport-Logs** – pro Versuch einen Eintrag mit HTTP-Status, Antwortzeit und Fehlermeldung.

### Was passiert bei Duplikaten?

Bestellungen, die als Duplikat erkannt werden (`order_type=new` mit bereits existierender `external_order_id` in derselben Pipeline), erzeugen **keine neue** InboundMessage. Stattdessen antwortet Orderport idempotent (HTTP 409 für JSON, Status-Code 409 im cXML-Response) und die bestehende Nachricht bleibt unverändert. Siehe [Duplikatserkennung](/docs/duplikatserkennung).

## Retry-Strategie

Bei fehlgeschlagener Zustellung startet Orderport automatisch neue Versuche. Der Abstand wächst mit jedem Versuch:

| Versuch | Wartezeit vor dem nächsten Versuch |
|---|---|
| 1. Fehlschlag | 1 Minute |
| 2. Fehlschlag | 5 Minuten |
| 3. Fehlschlag | 30 Minuten |
| 4. Fehlschlag | 2 Stunden |
| 5. Fehlschlag | 24 Stunden |

Nach dem 5. Fehlschlag ist der Status `permanently_failed`. Administratoren können die Nachricht danach jederzeit manuell erneut zustellen (Detailseite, **„Erneut zustellen"**) – solange das Eingangsdokument noch vorliegt, also innerhalb von 90 Tagen. Orderport meldet den endgültigen Fehlschlag außerdem per E-Mail. Mehr dazu in [Fehlerbehebung](/docs/fehlerbehebung).

## Payload-Aufbewahrung

Jede Nachricht enthält zwei Payload-Felder:

- `raw_payload` – das Original-Dokument wie es angekommen ist (XML/JSON/EDIFACT-Text)
- `transformed_payload` – das Ergebnis nach Transformation (das, was an Ihr Zielsystem geht)

Beide werden in der Datenbank gespeichert, damit Sie im Fehlerfall nachvollziehen können, was genau passiert ist. Nach **90 Tagen** werden beide Felder automatisch auf `NULL` gesetzt – ein scheduler-getriebenes Cleanup (`orders:cleanup-payloads --days=90`) löscht sie. Die Nachricht selbst (Status, Timestamps, Transport-Log-Zusammenfassung) bleibt für spätere Statistik und Audit.

Eine längere Aufbewahrung ist auf Anfrage möglich, aber gegen Aufpreis (erhöhter Speicherbedarf).

## Was Sie mit Bestellungen in der UI tun können

Auf der Detailseite:

- **Status ansehen** inklusive aller Transport-Versuche
- **Payload-Vorschau** (raw und transformiert, solange nicht durch Cleanup gelöscht)
- **Erneut zustellen** – setzt die Nachricht zurück auf `queued` und lässt sie vollständig neu laufen: Transformation **und** Zustellung. Korrigierte Mapping-Regeln oder Transport-Zugangsdaten greifen dabei
- **Als zugestellt markieren** – setzt den Status auf `delivered` (nur für Sonderfälle; es wird nichts an Ihr Zielsystem gesendet)

Beide Aktionen stehen nur bei den Status `failed` und `permanently_failed` zur Verfügung und sind
Administratoren vorbehalten; Mitglieder sehen die Nachricht, lösen aber keine Zustellung aus.
Bulk-Aktionen (mehrere Nachrichten gleichzeitig) sind in Planung.

## Technische Details

### Entkoppelter Empfang und Verarbeitung

Empfang und Transport laufen zeitlich entkoppelt: Der HTTP-Handler nimmt das Payload synchron an, prüft die Authentifizierung und antwortet dem Absender sofort (HTTP 202 bei JSON, HTTP 200 mit cXML-Response bei XML). Die eigentliche Transformation und Zustellung passiert asynchron in einer Queue. Dadurch antwortet Orderport Partnern in der Regel innerhalb weniger hundert Millisekunden, auch wenn das Zielsystem langsam ist.

### Transport-Logs

Jeder Zustellungsversuch – erfolgreich oder nicht – erzeugt einen Eintrag im Transport-Log. Er enthält:

- welcher Transport genutzt wurde
- die laufende Versuchs-Nummer
- das Ergebnis (`success` oder `failed`)
- den HTTP-Status des Zielsystems (falls zutreffend)
- die Antwortzeit in Millisekunden
- die ersten 5 000 Zeichen der Antwort
- eine Fehlermeldung bei Abbruch

### Aufbewahrung

Der Datensatz einer Nachricht bleibt dauerhaft erhalten; nur die Payload-Felder (raw + transformiert) werden nach 90 Tagen geleert. Audit-Log-Einträge laufen nach 365 Tagen ab. Beide Fristen sind auf Anfrage anpassbar. Mehr in [Limits & Kontingente](/docs/limits-und-kontingente).

## Nächste Schritte

- [Bestellungen verwalten](/docs/bestellungen)
- [Fehlerbehebung](/docs/fehlerbehebung)
- [Duplikatserkennung](/docs/duplikatserkennung)
- [Limits & Kontingente](/docs/limits-und-kontingente)
