JTL-Wawi API Dokumentation

Erste Schritte

1. Installation

1. ZIP-Datei auf Ihren Windows-Server entpacken (z.B. C:\SQL2REST\)
2. StartWizard.bat doppelklicken
3. Der Assistent führt Sie durch alles: Verbindung testen, Views erstellen, Dienst installieren

ODBC Driver 17 wird benötigt, ist aber auf den meisten JTL-Wawi-Servern bereits installiert. Der Assistent prüft die Verbindung automatisch.

2. Erster API-Aufruf

Nach Abschluss des Wizards ist Ihre API sofort einsatzbereit:

curl -H "X-API-Key: YOUR_KEY" http://YOUR-SERVER:8000/customers

Ersetzen Sie YOUR_KEY durch den API-Schlüssel aus dem Setup-Wizard (gespeichert in config.ini).

Ersetzen Sie YOUR-SERVER durch localhost (gleicher Rechner) oder die IP-Adresse Ihres Servers. Standard-Port ist 8000; der Port kann im Setup-Wizard angepasst werden.

Basis-URL: lokal, im Netzwerk, von außen

Alle Beispiele auf dieser Seite verwenden http://YOUR-SERVER:8000 als Platzhalter. Die Endpunkte und Parameter sind immer identisch, nur die Basis-URL davor ändert sich:

Die API ist also nicht auf localhost beschränkt: derselbe API-Key und dieselben Endpunkte funktionieren lokal, im Netzwerk und über das Internet.

SQL2REST-Tunnel: HTTPS von außen, ohne Portfreigabe

Der Tunnel ist der Standardweg für den Zugriff von außen. Ein Klick im Dashboard, und SQL2REST bekommt eine feste HTTPS-Adresse. Es muss kein Port in der Firewall geöffnet und keine Domain oder Zertifikat eingerichtet werden, die Datenbank bleibt unsichtbar im eigenen Netz.

• ✓Feste HTTPS-URL, verschlüsselt, weiterhin nur Lesezugriff.
• ✓Keine Portfreigabe, kein Reverse Proxy, keine eigene Domain nötig.
• ✓Der MCP-Endpunkt liegt unter /mcp derselben Adresse.

Im Team-Tarif enthalten, für Personal als Add-on buchbar. Tarife ansehen.

Statt des Tunnels kannst du den externen Zugang auch selbst aufsetzen, mit einem eigenen Reverse Proxy (Cloudflare Tunnel oder Caddy). SQL2REST selbst läuft in beiden Fällen auf deinem Server.

Authentifizierung

Jede API-Anfrage erfordert einen API-Schlüssel als HTTP-Header:

X-API-Key: your-api-key-here

Der Header-Name ist standardmäßig X-API-Key und kann in config.ini unter [API] HeaderName geändert werden.

Hinweis: Query-Parameter-Authentifizierung wird nicht unterstützt. Der API-Schlüssel muss als Header gesendet werden.

Endpunkte

Alle Daten-Endpunkte erfordern einen gültigen API-Schlüssel und eine aktive Lizenz. Feldnamen hängen von Ihrer Spaltenzuordnung im Setup-Wizard ab.

Alle Endpunkte unterstützen: sort, order, limit, offset, mandant. Details siehe unten.

Kunden

Kunden auflisten mit optionaler Suche, Sortierung und Paginierung.

curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/customers?search=Müller"

{
  "data": [
    {
      "CustomerNumber": "10001",
      "Company": "Müller GmbH",
      "Email": "info@mueller-gmbh.de",
      "City": "Frankfurt"
    }
  ],
  "total": 3,
  "limit": 100,
  "offset": 0
}

Einzelnen Kunden nach Kundennummer abrufen.

curl -H "X-API-Key: YOUR_KEY" http://YOUR-SERVER:8000/customers/10001

{
  "data": {
    "CustomerNumber": "10001",
    "Company": "Müller GmbH",
    "FirstName": "Thomas",
    "LastName": "Müller",
    "Email": "info@mueller-gmbh.de",
    "City": "Frankfurt",
    "Country": "DE"
  }
}

Aufträge

Aufträge auflisten mit Filtern nach Kunde, Status und Zeitraum.

curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/orders?from=2024-01-01&status=Versendet"

Einzelnen Auftrag nach Auftragsnummer abrufen.

Positionen eines Auftrags abrufen.

Retouren

Drei Endpunkte für Retouren (RMA): Kopfdaten auflisten, eine einzelne Retoure abrufen und die Positionen einer Retoure abrufen.

Retouren auflisten mit Filtern nach Kunde, Status, RMA-Nummer und Zeitraum. Standardmäßig nach Retourendatum absteigend sortiert (neueste zuerst).

curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/returns?from=2024-01-01&status=Offen"

Einzelne Retoure nach RMA-Nummer abrufen.

curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/returns/RMA-2024-0042"

Positionen einer Retoure abrufen.

curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/returns/RMA-2024-0042/items"

Felder der /returns-Antwort

Kopfdaten je Retoure. Feldnamen können je nach Spaltenzuordnung im Setup-Wizard abweichen.

Felder der /returns/{rma_number}/items-Antwort

Eine Zeile je zurückgesendeter Position.

Rechnungen

Rechnungen auflisten mit Filtern nach Kunde, Status und Zeitraum.

Mit dem Parameter ?order= können alle Rechnungen zu einem bestimmten Auftrag abgerufen werden:

curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/invoices?order=86957"

Produkte

Produkte auflisten mit optionaler Suche.

Einzelnes Produkt nach Artikelnummer (SKU) abrufen.

Felder der /products-Antwort

Die folgende Tabelle listet alle Felder, die der /products-Endpunkt zurückgeben kann.

* TaricCode und CountryOfOrigin sind optionale Felder und müssen im Setup-Wizard (Feldauswahl) aktiviert werden, damit sie von der API und dem MCP zurückgegeben werden. Standardmäßig sind sie deaktiviert.

Attribute (Merkmale)

SQL2REST erkennt JTL-Merkmale (standardisierte Varianten-Beschreibungen wie Farbe, Größe, Material) und stellt sie über drei Wege zur Verfügung: einen Katalog-Endpunkt, eingebettete Werte auf Produkten und einen Filter-Parameter.

Alle Merkmal-Definitionen mit ihren möglichen Werten, gruppiert nach Name.

curl -H "X-API-Key: YOUR_KEY" http://YOUR-SERVER:8000/attributes

{
  "data": [
    { "name": "Farbe", "values": ["Rot", "Blau", "Grün"] },
    { "name": "Größe", "values": ["S", "M", "L"] }
  ],
  "total": 2
}

Eingebettete Attribute auf Produkten

Der Endpunkt /products/{sku} liefert immer ein attributes-Objekt, gruppiert nach Attributname. Bei /products opt-in über ?include=attributes, um N+1 zu vermeiden.

{
  "data": {
    "SKU": "ART-001",
    "ProductName": "T-Shirt",
    "attributes": {
      "Farbe": ["Rot"],
      "Größe": ["M"]
    }
  }
}

Produkte nach Attribut filtern

Der Parameter ?attribute[name]=wert filtert Produkte. Attributnamen sind die deutschen JTL-Originalnamen (kleingeschrieben). Mehrere Filter werden mit UND verknüpft.

# Einzelner Filter
curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/products?attribute[farbe]=rot&include=attributes"

# Mehrere Filter (UND-verknüpft)
curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/products?attribute[farbe]=rot&attribute[groesse]=m"

Erweiterter Modus (JTL-IDs)

Mit ?advanced=true wird das Antwort-Format auf Objekte mit JTL_AttributeId (kMerkmal) und JTL_ValueId (kMerkmalWert) umgestellt. Nützlich für Write-Back über die offizielle JTL-API.

{
  "data": [
    {
      "name": "Farbe",
      "JTL_AttributeId": 5,
      "values": [
        { "value": "Rot", "JTL_ValueId": 12 },
        { "value": "Blau", "JTL_ValueId": 13 }
      ]
    }
  ]
}

Attribute ausblenden

Über den Abschnitt [MERKMALE] in der config.ini können einzelne Attribute aus allen Antworten ausgeblendet werden (Komma-getrennt, Groß-/Kleinschreibung wird ignoriert). Versuche, diese Namen als Filter zu nutzen, liefern HTTP 400.

[MERKMALE]
Disabled = InternalCode, LegacyFlag

Bestand

Lagerbestand auflisten mit optionalem SKU-Filter. Jede Zeile enthält: SKU, InternalArticleId, AvailableStock, ReservedStock, IncomingStock, BlockedStock und StockLevel.

Lagerbestand eines Artikels aufgeteilt nach Lager abrufen. Eine Zeile pro Lager mit WarehouseId, WarehouseName, WarehouseActive und StockInWarehouse.

curl -H "X-API-Key: YOUR_KEY" http://YOUR-SERVER:8000/products/ART-001/stock

{
  "data": [
    {
      "SKU": "ART-001",
      "WarehouseId": 1,
      "WarehouseName": "Main",
      "WarehouseActive": 1,
      "StockInWarehouse": 42.0
    }
  ]
}

Lagerbestand aller Artikel aufgeteilt nach Lager (Sammelabruf für den Bestandsabgleich). Eine Zeile je Artikel und Lager mit SKU, WarehouseId, WarehouseName, WarehouseActive, StockInWarehouse und AvailableInWarehouse. Seitenweise über limit und offset.

curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/stock/by-warehouse?shop_id=1"

Lieferungen

Lieferungen auflisten mit Filtern nach Auftrag, Versanddienstleister und Zeitraum.

Lieferscheine

Lieferscheine auflisten mit optionaler Suche und Datumsfilter.

{
  "data": [
    {
      "DeliveryNoteNumber": "LS-10042",
      "DeliveryNoteDate": "2024-03-15",
      "OrderNumber": "86957",
      "CustomerNumber": "10001"
    }
  ],
  "total": 12,
  "limit": 100,
  "offset": 0
}

Einzelnen Lieferschein nach Lieferscheinnummer abrufen. Positionen werden automatisch eingeschlossen.

curl -H "X-API-Key: YOUR_KEY" http://YOUR-SERVER:8000/delivery-notes/LS-10042

Lieferscheine mit Positionen in einem Aufruf abrufen.

{
  "data": [
    {
      "DeliveryNoteNumber": "LS-10042",
      "DeliveryNoteDate": "2024-03-15",
      "OrderNumber": "86957",
      "CustomerNumber": "10001",
      "items": [
        {
          "ArticleNumber": "ART-001",
          "ArticleName": "Produkt A",
          "Quantity": 2
        }
      ]
    }
  ]
}

Einkauf (Wareneingang)

Drei Endpunkte für Einkaufsprozesse: Wareneingänge (stock movements), Lieferanten (suppliers) und Lieferantenbestellungen (purchase orders). Standardmäßig deaktiviert. Im Setup-Wizard unter Schritt 3 "Einkauf / Wareneingang" aktivieren. Wenn aus, geben die Endpunkte 404 zurück.

Wareneingänge auflisten (Buchungen auf Lagerplätzen). Lieferant und Bestellung sind nur für Buchungsart 10 (Wareneingang aus Bestellung) befüllt; andere Buchungsarten liefern NULL für diese Spalten.

curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/goods-receipts?booking_type=10&since=2026-01-01"

{
  "data": [
    {
      "receipt_id": 12482,
      "received_at": "2026-04-15",
      "booked_at": "2026-04-15T09:21:00",
      "delivered_at": "2026-04-14",
      "booking_type": 10,
      "booking_type_label": "Wareneingang",
      "qty": 250,
      "unit_cost": 4.85,
      "sku": "RAW-001",
      "article_name": "Rohstoff A",
      "supplier_id": 12,
      "supplier_name": "Musterlieferant GmbH",
      "supplier_no": "LIEF-0012",
      "po_id": 1019,
      "po_number": "1019",
      "po_qty_ordered": 250,
      "po_qty_delivered_total": 250,
      "po_qty_still_open": 0
    }
  ],
  "total": 22,
  "limit": 100,
  "offset": 0
}

Einzelnen Wareneingang nach JTL-ID (kWarenLagerEingang) abrufen.

Lieferanten auflisten mit Suche, Aktiv-Filter und Adress- und Konditions-Spalten.

{
  "data": [
    {
      "supplier_id": 12,
      "supplier_no": "LIEF-0012",
      "company_name": "Musterlieferant GmbH",
      "contact": "Max Mustermann",
      "street": "Musterstraße 1",
      "postal_code": "10115",
      "city": "Berlin",
      "country": "DE",
      "email": "info@musterlieferant.de",
      "vat_id": "DE123456789",
      "payment_term_days": 30,
      "discount_days": 10,
      "discount_pct": 2.0,
      "currency": "EUR",
      "active": "Y"
    }
  ],
  "total": 17,
  "limit": 100,
  "offset": 0
}

Einzelnen Lieferanten nach JTL-ID (kLieferant) abrufen.

Lieferantenbestellungen als flache Header+Position-Zeilen. Eine Zeile pro Bestellposition. Für Soll-Ist-Reporting open_only=true verwenden.

curl -H "X-API-Key: YOUR_KEY" "http://YOUR-SERVER:8000/purchase-orders?open_only=true"

Einzelne Bestellung mit verschachtelten Positionen unter positions abrufen.

{
  "data": {
    "po_id": 1019,
    "po_number": "1019",
    "created_at": "2026-03-12",
    "expected_delivery": "2026-04-15",
    "status": 2,
    "currency": "EUR",
    "supplier_id": 12,
    "supplier_name": "Musterlieferant GmbH",
    "supplier_no": "LIEF-0012",
    "positions": [
      {
        "position_id": 4421,
        "sku": "RAW-001",
        "article_name": "Rohstoff A",
        "qty_ordered": 250,
        "qty_delivered": 250,
        "qty_open": 0,
        "unit_price_net": 4.85
      }
    ]
  }
}

Cross-API: SQL2REST lesen + JTL schreiben

Die Felder mit JTL_-Präfix sind Schlüsselwerte aus Ihrer JTL-Datenbank. Sie sind im Wizard standardmäßig deaktiviert (siehe Abschnitt "Erweitert" im Setup) und werden nur benötigt, wenn Sie zusätzlich zur read-only API von SQL2REST auch über die offizielle JTL-API in JTL schreiben (zum Beispiel Auftragsstatus aktualisieren). Reine Leseintegrationen können diese Felder ignorieren.

# 1. Read order via SQL2REST (this API)
GET /orders?order_number=12345
# response includes: JTL_SalesOrderId: 9, JTL_CustomerId: 42

# 2. Use JTL_SalesOrderId to update via the official JTL API
PATCH https://your-jtl-server/api/eazybusiness/v1/salesOrder/9

Sync-Endpunkte

Vorverbundene Endpunkte für CRM-Integrationen. Liefern Daten aus mehreren Tabellen in einem Aufruf.

Aufträge mit Kunden-, Rechnungs- und Versanddaten in einem Aufruf.

Batch-Kundensynchronisation mit höherem Limit (bis zu 1000).

Filtern & Suchen

Zwei Arten von Filtern stehen zur Verfügung:

Textsuche (LIKE)

Der search-Parameter durchsucht Name und Nummer. Verfügbar auf /customers und /products.

Exakte Filter

Filterparameter liefern exakte Übereinstimmungen:

Sortierung & Paginierung

Alle Listen-Endpunkte unterstützen Sortierung und Paginierung.

Hinweis: /shipments verwendet sort_order statt order.

Datumsfilter

Zeitraum-Filter über from/to-Parameter (jeweils einschließlich).

Multi-Mandant

Wenn Sie mehrere JTL-Datenbanken konfiguriert haben, verwenden Sie den mandant-Parameter, um die Zieldatenbank auszuwählen. Standard ist 1.

Mandanten-Limits nach Tarif

Auto-Discovery

Der Setup-Wizard analysiert automatisch Ihr JTL-Datenbankschema und erkennt die richtigen Spalten für jeden Endpunkt.

• Erkennt Ihre JTL-Wawi Version automatisch (1.5 bis 2.0)
• Ordnet Standardfelder automatisch zu (Kundennummer, Bestelldatum, SKU etc.)
• Nicht erkannte Felder können manuell per Dropdown zugeordnet werden
• Spaltenvorschau zeigt echte Beispieldaten aus Ihrer Datenbank

Eigene Felder

SQL2REST erkennt automatisch benutzerdefinierte Felder (Eigene Felder) in Ihrer JTL-Datenbank und macht sie per API verfügbar.

• Unterstützt Artikel-, Kunden- und Bestellungsfelder
• Alle JTL-Feldtypen: Text, Ganzzahl, Dezimalzahl, Datum
• Pro Gruppe aktivierbar/deaktivierbar im Setup-Wizard (Schritt 3)
• Standardmäßig deaktiviert - nur aktive Felder erscheinen in der API

Eigene Felder erscheinen in der API-Antwort mit dem Präfix CF_:

{
  "SKU": "ART-001",
  "ProductName": "Widget",
  "CF_Energie_KJ": 500,
  "CF_Zutaten": "Mehl, Zucker, Butter",
  "CF_WEEE_Pickup": 1
}

Um Eigene Felder nachträglich zu aktivieren, führen Sie den Setup-Wizard erneut aus.

Community Mapping

Wenn Sie eine Spalte manuell zuordnen, können Sie diese Zuordnung anonym teilen, um die Erkennung für alle Nutzer zu verbessern.

• Nur bei expliziter Zustimmung im Wizard (Opt-in)
• Es werden nur Tabellen-/Spaltennamen geteilt, niemals Geschäftsdaten

Details zum Datenschutz: /datenschutz

Rechnungs-PDFs

Rechnungs-PDF nach Rechnungsnummer herunterladen. Standardmäßig deaktiviert, kann im Setup-Wizard oder in config.ini aktiviert werden.

Die Suche extrahiert den numerischen Teil der Rechnungsnummer (RE-12345 → 12345) und sucht rekursiv in allen konfigurierten Ordnern und Unterordnern. Bei mehreren Treffern wird die neueste Datei verwendet.

curl -H "X-API-Key: YOUR_KEY" http://YOUR-SERVER:8000/invoices/86774/pdf --output rechnung.pdf

Gibt die PDF-Datei direkt als Download zurück (Content-Type: application/pdf). Bei nicht gefundener Rechnung: 404.

Konfiguration

Es reicht, den Hauptordner anzugeben - Unterordner wie Jahres- oder Monatsverzeichnisse werden automatisch durchsucht:

InvoicePdfPath = \\SERVER\Buchhaltung\Rechnungsausgang
; Findet auch: \2026\04\RE-12345.pdf

MCP Server (KI)

SQL2REST kann als MCP-Server für KI-Assistenten genutzt werden. 15 Tools und 2 Resources stehen zur Verfügung.

sql2rest.exe --mcp

Voraussetzung: Die API muss als Windows-Dienst laufen. Der MCP-Server liest den API-Schlüssel aus config.ini.

Für den Zugriff von außen brauchst du HTTPS. Am einfachsten über den SQL2REST-Tunnel (ein Klick, keine Portfreigabe); der MCP-Endpunkt liegt dann unter /mcp der Tunnel-Adresse. Alternativ ein eigener Reverse Proxy mit Cloudflare Tunnel oder Caddy.

Claude Desktop Konfiguration

{
  "mcpServers": {
    "SQL2REST": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://dein-tunnel.jtl2api.com/mcp",
        "--transport", "http-only",
        "--header", "X-API-Key:${SQL2REST_KEY}"
      ],
      "env": { "SQL2REST_KEY": "dein-api-key" }
    }
  }
}

Claude Desktop überträgt native HTTP-MCP-Blöcke nicht zuverlässig, daher läuft die Verbindung über die mcp-remote-Bridge (Node.js 20+ auf der Workstation). http:// für LAN, https:// hinter einem Reverse Proxy. Vollständige Anleitung: JTL-Wawi mit Claude Desktop verbinden.

Verfügbare Tools

Kompatibel mit: Claude Desktop, Claude Code, Cursor, Windsurf, ChatGPT Desktop und jedem MCP-Client.

Aktualisierung

SQL2REST enthält ein Auto-Update. Einfach update.bat als Administrator ausführen. Das Skript prüft auf neue Versionen, lädt das Update herunter, verifiziert die Integrität (SHA-256) und wendet es automatisch an.

Update-Benachrichtigung

Wenn eine neue Version verfügbar ist, zeigt der Setup-Wizard automatisch einen Hinweis an. Öffnen Sie den Wizard über StartWizard.bat. Das Banner erscheint zwischen Header und Schritt-Anzeige.

Auto-Update (empfohlen)

1. Rechtsklick auf update.bat → „Als Administrator ausführen"
2. Versionsvergleich prüfen und mit Y bestätigen

Manuelles Update (offline)

1. Laden Sie die neueste Version aus Ihrem Dashboard herunter
2. Führen Sie als Administrator aus: update.bat C:\Pfad\zur\sql2rest-latest.zip

Was passiert

• Prüft auf neue Versionen (Auto-Update) oder nutzt die angegebene ZIP-Datei
• Dienst wird über NSSM gestoppt (Fallback: taskkill)
• config.ini wird gesichert und nach dem Update wiederhergestellt
• Download wird per SHA-256-Hash verifiziert
• Dienst wird automatisch neu gestartet

Setup erneut öffnen

Um den Setup-Wizard erneut auszuführen (z.B. nach einem JTL-Update, damit neue Felder wie ProductGroup in die Views übernommen werden):

1. ApiDashboard.bat ausführen — das öffnet das API-Dashboard im Browser, ohne den Dienst zu stoppen. (StartWizard.bat funktioniert ebenfalls, stoppt aber kurz den Dienst.)
2. Auf der Karte "Lokale REST-API" auf das Zahnrad-Symbol klicken. Das startet den Setup-Wizard erneut.
3. Den Schema-Schritt erneut durchlaufen. Danach werden neue und aktualisierte Felder in die Views übernommen.

Bereinigung

Die Bereinigungsfunktion entfernt alle SQL-Views und den Read-Only SQL2REST-Datenbankbenutzer. Vollständig reversibel: führen Sie den Wizard erneut aus, um alles neu einzurichten.

• Zugänglich über den Erfolgsbildschirm des Wizards
• Erfordert Admin-SQL-Zugangsdaten (der config.ini-Benutzer ist Read-Only)
• Optional: config.ini löschen, um in den Setup-Modus zurückzukehren

Fehlercodes

402-Antwortformat

{
  "detail": {
    "message": "Valid license required",
    "url": "https://sql2rest.com/jtl-wawi#pricing"
  }
}

Testversion

Die 14-Tage-Testversion wird automatisch beim Setup erstellt und hat folgende Einschränkungen:

Nicht verfügbare Endpunkte liefern Status 402 mit Upgrade-Link. Upgraden Sie unter /jtl-wawi#pricing.