# FTP & SFTP

Der FTP-/SFTP-Transport legt die transformierte Bestellung als Datei in ein Zielverzeichnis auf einem (S)FTP-Server. Typischer Einsatz: dateibasierte Importer in Warenwirtschaftssystemen (z. B. JTL-Wawi, Sage), EDI-Clearing-Anbieter oder Lieferantenportale, die Dropfolder überwachen. Benötigtes Addon: `delivery_ftp`.

## Wann FTP/SFTP wählen?

- Das Ziel-System importiert Bestellungen **aus einem überwachten Verzeichnis**
- Der Empfänger kann keinen HTTP-Endpoint bereitstellen, aber einen FTP-Server
- Sie tauschen mit einem **EDI-Clearing-Anbieter** Dateien aus

Für neue Integrationen bevorzugen Sie nach Möglichkeit [HTTP POST](/docs/http) oder [REST API](/docs/rest-api) – FTP ist altersbedingt oft weniger sicher und weniger transaktional.

## SFTP vs. FTP

| Aspekt | SFTP | FTP/FTPS |
|---|---|---|
| Transport | SSH (Port 22) | TCP (Port 21) + AUTH TLS |
| Verschlüsselung | Immer | Nur mit expliziter AUTH-TLS-Initialisierung |
| Authentifizierung | Passwort oder SSH-Key | Passwort |
| Firewall-Verhalten | Einfach (eine Verbindung) | Komplex (Active vs. Passive, Data-Port) |

**Empfehlung:** SFTP wo möglich. Klassisches FTP ist nur sinnvoll, wenn der Partner kein SFTP anbietet – dann bitte mindestens FTPS (AUTH TLS) nutzen.

## Einrichtung

1. **Transporte → Hinzufügen** → Typ: **FTP/SFTP**
2. **Protokoll**: `SFTP`, `FTP` oder `FTPS`
3. **Host**: z. B. `ftp.example.com`
4. **Port**: `22` (SFTP) oder `21` (FTP/FTPS) – manche Anbieter nutzen eigene Ports
5. **Benutzername**
6. **Authentifizierung**:
   - Passwort – wird verschlüsselt gespeichert
   - SSH-Key (nur SFTP) – Key-Pärchen wird in Orderport erzeugt, Public-Key an den Partner weitergegeben
7. **Pfad** auf dem Zielserver (z. B. `/inbox/orders/`)
8. **SSL/TLS-Verifikation**: aktiviert (Default) – nur bei selbstsignierten Zertifikaten deaktivieren, in Absprache mit dem Partner
9. **Passiv-Modus**: Standard für FTP – bei Firewall-Problemen Aktiv-Modus versuchen
10. Speichern → **Verbindung testen**

## Dateinamen

Orderport erzeugt Dateien nach dem Muster:

```
{external_order_id}_{YYYYMMDD_HHMMSS}.{ext}
```

- `ext` ist `xml` oder `json` je nach Ausgabeformat
- Retries bei Netzwerkfehler erzeugen im Erfolgsfall genau eine Datei
- Bei mehreren Zustellversuchen entstehen ggf. doppelte Dateien mit leicht anderen Timestamps – das Ziel-System sollte idempotent importieren

## Technische Details

### Atomarer Upload

Der Upload läuft in zwei Schritten: Orderport schreibt die Datei zuerst mit einer `.tmp`-Endung auf den Server und benennt sie erst nach erfolgreichem Transfer in den endgültigen Dateinamen um. Dadurch sieht das Ziel-System nie eine halb geschriebene Datei. Voraussetzung: der FTP/SFTP-Benutzer darf im Zielverzeichnis **schreiben und umbenennen**.

### SSH-Keys

Wenn Sie bei SFTP statt Passwort ein SSH-Key-Paar nutzen, erzeugt Orderport das Paar in OpenSSH-Format. Der öffentliche Teil wird Ihnen zum Download angeboten – Sie hinterlegen ihn in der `authorized_keys`-Datei des Ziel-Benutzers.

### Passwort-Speicherung

Passwörter und Secrets werden verschlüsselt abgelegt und nur im Arbeitsspeicher des Zustellungs-Vorgangs entschlüsselt. Klartexte erscheinen nie in Logs oder Datenbank-Dumps.

### Feature-Gate

Der FTP/SFTP-Transport ist hinter dem Addon `delivery_ftp`. Demo-Mandanten haben uneingeschränkten Zugang.

## Fehlerbehebung

| Symptom | Ursache | Lösung |
|---|---|---|
| „Connection refused" | Port geschlossen oder Host falsch | Host/Port prüfen, Firewall-Regeln beim Partner abklären |
| „Authentication failed" | Benutzername/Passwort falsch, oder SSH-Key nicht deponiert | Zugangsdaten prüfen; bei SSH-Key den Public-Key beim Partner in `authorized_keys` eintragen |
| Datei wird geschrieben, aber vom Importer nicht gelesen | Importer ignoriert `.tmp`-Dateien, aber Rename schlägt still fehl | Auf dem Server prüfen, ob Orderport Schreibrechte **und Umbenennungs-Rechte** im Zielverzeichnis hat |
| Aktive FTP-Verbindung funktioniert nicht | Firewall blockt eingehende Data-Connection | Passiv-Modus aktivieren (Default) |
| SSL-Fehler bei FTPS | Server nutzt selbstsigniertes Zertifikat | Mit dem Partner klären: idealerweise gültiges Zertifikat, notfalls SSL-Verifikation deaktivieren (erst nach Absprache) |
| Nach Upload „Permission denied" | Verzeichnis lässt kein Rename zu | Partner bitten, dem Benutzer das Rename-Recht zu geben |

## Nächste Schritte

- [Zugangsdaten](/docs/credentials)
- [JTL-Wawi](/docs/jtl-wawi) – klassischer SFTP-Drop-Consumer
- [Fehlerbehebung](/docs/fehlerbehebung)