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.

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": "[email protected]",
      "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": "[email protected]",
    "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.

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.

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
    }
  ]
}

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
        }
      ]
    }
  ]
}

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.

Claude Desktop Konfiguration

{
  "mcpServers": {
    "sql2rest": {
      "command": "C:\\SQL2REST\\sql2rest.exe",
      "args": ["--mcp"]
    }
  }
}

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

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 30-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.