# 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): automatisch wiederholt Orderport eine Transformation nie. Manuell können Sie die Nachricht erneut zustellen, dann läuft auch die Transformation neu |

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)