> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armin.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# JTL Wawi (API)

> Verbinde JTL-Wawi ERP für Bestellabfragen, Tracking und freigegebene Schreibaktionen in Chatarmin CX.

Die Integration **JTL Wawi (API)** verbindet deine JTL-Wawi-Instanz (On-Premise oder gehostet) mit Chatarmin CX, damit Agenten und KI-Agenten Bestellungen und Tracking abrufen und — wo du es erlaubst — Adressen ändern oder Bestellungen stornieren können.

<Note>
  Diese Anleitung gilt für **JTL-Wawi ERP** mit REST-API. Das ist nicht dasselbe wie [FFN Connect / Fly](/de/integrations/ffn-connect), wo Shopify mit einem Fulfillment-Lager synchronisiert wird.
</Note>

## Wann du sie nutzt

Nutze JTL Wawi (API), wenn:

* Bestellungen und Kunden in JTL-Wawi liegen (typisch im DACH-Raum)
* der Support WISMO, Adressänderungen, Stornos oder Bestellkontext aus Wawi braucht
* KI-Agenten Wawi-Daten lesen oder — mit Freigabe — schreiben sollen

## Voraussetzungen

Bevor du in cx verbindest, kläre auf JTL-Seite:

* **JTL-Wawi REST-API-Dienst läuft** — im JTL-Wawi Administrator ist der API-/App-Registrierungsdienst für externe Apps gestartet.
* **Du kennst das Datenbank-Segment in der API-URL** — der Name nach `/api/` (z. B. `eazybusiness`). Das ist der **Datenbankname**, nicht zwingend der Anzeigename des Windows-Dienstes.
* **Ein JTL-Wawi-Benutzer existiert** — diesen Benutzernamen trägst du in cx ein, nachdem du die App in Wawi freigegeben hast.
* **Dein API-Port ist von außen erreichbar** — Chatarmin CX ruft deinen Wawi-Server aus der Cloud auf. Der Port wird in JTL gesetzt (oft **5883**, Kunden nutzen auch **5679**, **50443** und andere). Private LAN-Adressen (z. B. `192.168.x.x`) funktionieren nicht.

## Server-URL-Format

In cx gibst du die volle Basis-URL der Wawi REST-API an:

```
https://DEIN-OEFFENTLICHER-HOST:DEIN-PORT/api/DEINE-DATENBANK
```

Beispiele (gleicher Datenbankname, unterschiedliche Ports — nutze den Port, den euer Administrator konfiguriert hat):

* `https://wawi.beispiel.de:5883/api/eazybusiness`
* `https://203.0.113.10:5679/api/eazybusiness`

<Warning>
  Nutze **öffentlichen Hostnamen oder öffentliche IP**, keine interne VM- oder Proxmox-LAN-Adresse. Das Segment nach `/api/` ist der **JTL-Datenbankname** (oft `eazybusiness`), nicht euer Shop- oder Windows-Dienstname. Wenn in Wawi **kein TLS-Zertifikat hinterlegt** ist, probiere `http://` statt `https://` in der URL.
</Warning>

<Tip>
  **5883** ist der häufige Standard-API-Port. Verbundene Chatarmin-Konten nutzen kundenspezifische Ports — Host, Port und Datenbank immer vom JTL-Administrator übernehmen, nicht von einem anderen Shop.
</Tip>

## Netzwerk und Firewall

Chatarmin CX muss eine **eingehende TCP-Verbindung auf deinen Wawi-API-Port** öffnen können (derselbe Port wie in der Server-URL). Konfiguriere alle relevanten Ebenen:

1. **Windows-Firewall** auf dem Wawi-Server — eingehendes TCP auf den API-Port für den Wawi-Dienst erlauben, inkl. Profil **Öffentlich**, wenn der Server von außerhalb des LAN erreichbar sein soll.
2. **Hypervisor-/Rechenzentrum-Firewall** (z. B. Proxmox) — denselben Port auf der VM freigeben; Standard-Drop blockiert cx, auch wenn Windows schon erlaubt.
3. **Edge-Firewall beim Hoster** — wenn Wawi beim Provider läuft, eingehenden Traffic auf euren API-Port zur öffentlichen VM-IP freigeben lassen.

cx stellt **ausgehende Verbindungen zu dir** her (kein Callback zu uns). Für die aktuelle **Outbound-IP-Allowlist** wende dich an deinen Chatarmin-CX-Ansprechpartner oder Support — alte IPs aus Tickets nicht raten.

Schnelltest außerhalb eures Büronetzwerks:

```bash theme={null}
curl -vk "https://DEIN-HOST:DEIN-PORT/api/DEINE-DATENBANK/v1/companies"
```

JSON oder HTTP 401/403 bedeutet: Port erreichbar. **Timeout** bedeutet: Firewall, falscher Host oder API-Dienst lauscht nicht.

## JTL Wawi (API) einrichten

### JTL-Wawi REST-API starten

Bevor du in cx verbindest, starte die JTL-Wawi-API auf deinem Server und stelle sicher, dass sie unter einem **öffentlichen Hostnamen oder einer öffentlichen IP** erreichbar ist (siehe [Netzwerk und Firewall](#netzwerk-und-firewall)). JTL beschreibt den REST-Server-Start hier: [API REST-Server starten](https://guide.jtl-software.com/jtl-wawi/jtl-wawi-api/api-rest-server-starten/).

### In Chatarmin CX verbinden

<Steps>
  <Step title="Integrationen öffnen">
    [Öffne die Integrationen](https://armin.cx/app/_/settings/integrations/jtlwawi) und wähle **JTL Wawi (API)**.
  </Step>

  <Step title="Server-URL eintragen">
    Klick auf **Konto hinzufügen**. Trage einen **Integrationsnamen** und deine **Server-URL** ein (z. B. `https://wawi.beispiel.de:5883/api/eazybusiness`). Klick **noch nicht** auf **Verbinden** — schließe zuerst den App-Registrierungs-Assistenten in JTL-Wawi ab (nächster Abschnitt).
  </Step>

  <Step title="In cx abschließen">
    Nach der Freigabe in JTL-Wawi: zurück in cx, **JTL-Wawi-Benutzernamen** eintragen (empfohlen: **`chatarmin/v1`**) und **Einrichtung abschließen**. Das Konto erscheint unter verbundenen Integrationen.
  </Step>
</Steps>

### App in JTL-Wawi registrieren (vor Verbinden)

<Warning>
  Der Assistent muss auf dem Bildschirm **Warten auf Registrierungsanfrage** stehen, **bevor** du in cx auf **Verbinden** klickst. Klickst du zu früh auf Verbinden, empfängt JTL die Anfrage nicht und der Ablauf wirkt hängend.
</Warning>

Am Wawi-Server-PC:

1. JTL-Wawi öffnen und **Admin → JTL-Wawi API → App-Registrierungen** wählen.

<Frame>
  <img src="https://mintcdn.com/chatarmincom/Wa9bSfwNd1DSToUw/images/integrations/jtl-wawi/jtl-wawi-registration-1.png?fit=max&auto=format&n=Wa9bSfwNd1DSToUw&q=85&s=fbfb754905b77f1f6a439ee79e36aebb" alt="JTL-Wawi Menü Admin bis JTL-Wawi API App-Registrierungen" width="1192" height="605" data-path="images/integrations/jtl-wawi/jtl-wawi-registration-1.png" />
</Frame>

2. Auf **Hinzufügen** klicken. Der Registrierungs-Assistent startet.

<Frame>
  <img src="https://mintcdn.com/chatarmincom/Wa9bSfwNd1DSToUw/images/integrations/jtl-wawi/jtl-wawi-registration-2.png?fit=max&auto=format&n=Wa9bSfwNd1DSToUw&q=85&s=5a23ae147243f73522e7f75a2d8af0b0" alt="JTL-Wawi API Anwendungsregistrierungen mit Hinzufügen-Button" width="1158" height="489" data-path="images/integrations/jtl-wawi/jtl-wawi-registration-2.png" />
</Frame>

3. Auf der Einführungsseite **Weiter** klicken.

<Frame>
  <img src="https://mintcdn.com/chatarmincom/Wa9bSfwNd1DSToUw/images/integrations/jtl-wawi/jtl-wawi-registration-3.png?fit=max&auto=format&n=Wa9bSfwNd1DSToUw&q=85&s=4431d6d97f3632e8656b24a5f35d0c5d" alt="JTL-Wawi App-Registrierung Assistent Einführung" width="1237" height="834" data-path="images/integrations/jtl-wawi/jtl-wawi-registration-3.png" />
</Frame>

4. Bei **Registrierung beginnen** wartet JTL-Wawi auf eine Registrierungsanfrage aus cx. Diesen Bildschirm offen lassen. Der Status zeigt, dass auf die Anwendung gewartet wird — **Weiter** bleibt deaktiviert, bis die Anfrage ankommt.

<Frame>
  <img src="https://mintcdn.com/chatarmincom/Wa9bSfwNd1DSToUw/images/integrations/jtl-wawi/jtl-wawi-registration-4.png?fit=max&auto=format&n=Wa9bSfwNd1DSToUw&q=85&s=48dfccebbabff1ac13e6a9cbd1926bc7" alt="JTL-Wawi wartet auf Registrierungsanfrage der externen App" width="1237" height="832" data-path="images/integrations/jtl-wawi/jtl-wawi-registration-4.png" />
</Frame>

5. Zurück in cx auf **Verbinden** klicken. In JTL-Wawi sollten die Anwendungsinformationen zu **chatarmin/v1** / **chatarmin.com** (*chatarmin.com GmbH*) erscheinen.

<Frame>
  <img src="https://mintcdn.com/chatarmincom/Wa9bSfwNd1DSToUw/images/integrations/jtl-wawi/jtl-wawi-registration-5.png?fit=max&auto=format&n=Wa9bSfwNd1DSToUw&q=85&s=6a8da7cd523865b408d1ad9315d2f1a1" alt="JTL-Wawi empfangene Anwendungsinformationen für chatarmin/v1" width="989" height="699" data-path="images/integrations/jtl-wawi/jtl-wawi-registration-5.png" />
</Frame>

6. In JTL-Wawi **Weiter** klicken, API-Benutzernamen setzen (empfohlen: **`chatarmin/v1`**), **Weiter** durch die Zugriffsverwaltung und den Assistenten abschließen.

7. In cx denselben Benutzernamen eintragen und **Einrichtung abschließen** klicken.

## JTL Wawi im Posteingang

Wenn ein Ticket-Kontakt zu einem Wawi-Kunden passt, kann Bestellkontext in der Ticket-Seitenleiste erscheinen — ohne Wechsel nach Wawi.

## KI-Agenten-Aktionen

JTL-Wawi-Aktionen können KI-Agenten z. B.:

* eine Bestellung abrufen
* Tracking abfragen
* eine Lieferadresse ändern
* Custom Fields oder Liefertermine aktualisieren
* eine Bestellung stornieren (mit Stornogrund, wenn konfiguriert)

Lass Schreibaktionen auf **Freigabe**, bis Testläufe zu euren Lagerregeln passen. Bestehende Workflows können JTL-Aktionen weiter für feste Legacy-Abläufe nutzen.

## Best practices

* Nutze den **Datenbanknamen** im URL-Pfad — falsche Pfade wirken wie generische Verbindungsfehler.
* Dokumentiere öffentliche URL und Firewall-Regeln mit dem Team für Proxmox/Hosting — cx kann Rechenzentrum-Firewall nicht aus dem Produkt heraus öffnen.
* HTTPS, sobald ein Zertifikat in Wawi liegt; HTTP nur, wenn die API ohne TLS antwortet.

## Troubleshooting

| Symptom                              | Wahrscheinliche Ursache                    | Was tun                                                                                                                                                      |
| ------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Failed to connect to JTL server**  | cx erreicht euren API-Port nicht (Timeout) | Windows- + Hypervisor- + Provider-Firewall auf **demselben Port wie in der URL** öffnen; API-Dienst prüfen; öffentliche Host/IP und Datenbanksegment prüfen. |
| **Invalid URL**                      | Ungültige Server-URL in cx                 | Format `https://host:port/api/eazybusiness` (oder euer Datenbankname), kein weiterer Pfad nach dem Datenbanksegment.                                         |
| **Registration not yet approved**    | App in Wawi nicht freigegeben              | **chatarmin/v1** unter Admin → App-Registrierung freigeben, dann erneut **Einrichtung abschließen**.                                                         |
| Verbindung vom Büro-PC, nicht von cx | Private IP oder nur-LAN-Firewall           | Öffentliche IP/Hostname + eingehend aus dem Internet (oder Chatarmin-Egress-IPs).                                                                            |
| HTTPS scheitert, HTTP geht           | Kein Zertifikat in Wawi                    | `http://` in der URL oder Zertifikat in Wawi hinterlegen.                                                                                                    |

Für REST-Feldreferenz nach erfolgreicher Verbindung: [JTL Wawi API-Dokumentation](https://wawi-api.jtl-software.com/) (Herstellerreferenz).