# FTP/SFTP-Pull

Statt einen Webhook aufzurufen können Lieferanten Bestellungen auch in ein FTP- oder SFTP-Verzeichnis ablegen. Orderport ruft das Verzeichnis dann alle 5 Minuten ab, holt neue Dateien, verarbeitet sie und verschiebt sie in ein Archivverzeichnis. Ideal für ältere ERP-Systeme oder Lieferanten, die keine Webhooks aussenden können.

Derselbe Mechanismus ist der Standard-Eingang für den [Belegausgang](/docs/belegausgang): Auftragsbestätigungen, Rechnungen und Gutschriften werden als XML im SFTP-Verzeichnis abgelegt und von der jeweiligen Beleg-Pipeline abgeholt — am besten mit eigenem Dateimuster pro Belegart (z. B. `RE_*.xml`).

> **Addon erforderlich:** Der FTP/SFTP-Empfang ist als optionales Addon für **89 €/Monat** netto buchbar. Aktivieren Sie das Addon unter **Einstellungen → Abrechnung**.

## Funktionsweise

1. Sie konfigurieren die FTP-/SFTP-Zugangsdaten Ihres Lieferanten direkt an der Pipeline.
2. Alle 5 Minuten verbindet sich Orderport von Hetzner aus zu Ihrem Lieferanten-Server.
3. Alle Dateien im konfigurierten Pfad, die dem Datei-Muster entsprechen, werden gelesen.
4. Jede Datei wird wie ein Webhook-Payload verarbeitet (Mapping, Transformation, Auslieferung an die konfigurierten Transports).
5. Erfolgreich verarbeitete Dateien wandern in das Unterverzeichnis `.processed/` auf dem Lieferanten-Server, fehlgeschlagene in `.failed/`.

## Konfiguration

Auf der Pipeline-Bearbeitungsseite finden Sie den Bereich **Eingang**. Dort können Sie zwischen *Webhook* und *FTP/SFTP-Pull* wechseln.

| Feld | Beschreibung |
|---|---|
| **Protokoll** | `SFTP` (Port 22, empfohlen) oder `FTP` (Port 21, unverschlüsselt). |
| **Host** | Der Server-Hostname Ihres Lieferanten, z. B. `ftp.kunde.de`. |
| **Port** | Standard 22 für SFTP, 21 für FTP. |
| **Benutzername** | Der Login-Name auf dem Lieferanten-Server. |
| **Passwort** | Wird verschlüsselt in der Datenbank gespeichert. Beim Bearbeiten leer lassen, um das bestehende Passwort beizubehalten. |
| **Pfad** | Das Verzeichnis, das gepollt werden soll, z. B. `/outbox`. |
| **Datei-Muster** | Glob-Pattern wie `*.xml`, `*.json` oder `order-*.edi`. Standard: `*.xml`. |
| **Polling-Intervall** | In Minuten. Standard: 5. Häufiger als 5 Minuten ist möglich, aber meist nicht nötig. |

Mit der Schaltfläche **Verbindung testen** prüfen Sie sofort, ob Login und Pfad korrekt sind. Sie sehen die Antwortzeit in Millisekunden, sobald der Test durchläuft.

## Verzeichnis-Konvention

Orderport erstellt im konfigurierten Pfad zwei Unterverzeichnisse, falls noch nicht vorhanden:

```
/outbox
├── order-1234.xml         ← noch nicht verarbeitet
├── order-1235.xml         ← noch nicht verarbeitet
├── .processed/            ← erfolgreich verarbeitet
│   └── order-1230.xml
└── .failed/               ← Verarbeitung fehlgeschlagen
    └── order-1228.xml
```

Dateien, deren Name mit einem Punkt beginnt (z. B. `.lock`), werden ignoriert. So können Lieferanten Dateien sicher als `.tmp` hochladen und am Ende per Rename veröffentlichen, ohne dass Orderport halbfertige Files greift.

## Unterstützte Formate

Der Content-Type wird aus der Dateiendung abgeleitet:

| Endung | Content-Type | Eingangsformat-Beispiele |
|---|---|---|
| `.xml` | `application/xml` | cXML, openTrans |
| `.json` | `application/json` | Shopware 6, Shopify, generisches JSON |
| `.edi` / `.edifact` | `application/edifact` | EDIFACT |

Die Pipeline muss auf den passenden Eingangstyp konfiguriert sein.

## Idempotenz & Duplikate

Orderport schützt vor Doppelverarbeitung auf zwei Ebenen:

1. **Eindeutiger Polling-Lauf**: Es läuft niemals mehr als ein Polling-Job parallel (`withoutOverlapping`).
2. **Externe Bestell-ID**: Wird in den meisten Eingangsformaten extrahiert. Wiederholte Lieferungen mit gleicher Bestell-ID werden idempotent abgewiesen.

## Sicherheit

- Passwörter werden mit `Laravel Crypt` (AES-256) verschlüsselt in der Datenbank abgelegt; Klartext ist nie gespeichert.
- Verbindungen erfolgen ausschließlich von Orderport zu Ihrem Server (ausgehend). Sie müssen keinen eingehenden Port öffnen.
- Wenn Ihr Lieferant nur Verbindungen aus festen IP-Bereichen erlaubt: Orderport-Cluster-IPs erhalten Sie auf Anfrage.
- Empfehlung: Verwenden Sie einen dedizierten Login-User mit Zugriff nur auf das `outbox/`-Verzeichnis.

## Audit-Log

Folgende Ereignisse werden im Audit-Log festgehalten:

| Event | Bedeutung |
|---|---|
| `inbound.ftp_poll_started` | Ein Polling-Lauf wurde gestartet. |
| `inbound.ftp_file_processed` | Eine Datei wurde erfolgreich verarbeitet. |
| `inbound.ftp_file_failed` | Eine Datei konnte nicht verarbeitet werden (z. B. Parse-Fehler). |
| `inbound.ftp_connection_failed` | Die FTP-/SFTP-Verbindung schlug fehl. |

## Wann Webhook, wann FTP-Pull?

| Anwendungsfall | Empfehlung |
|---|---|
| Lieferant kann Webhook aufrufen | [JSON-Webhook](json-webhook.md) bevorzugen — sofortige Verarbeitung. |
| Lieferant exportiert Dateien aus ERP | FTP/SFTP-Pull. |
| Lieferant ist Ariba/Coupa/cXML-Netzwerk | cXML über JSON-Webhook (XML-Body). |
| Sie haben eine eigene Integration | [API-Zugang](api-zugang.md) mit API-Key. |