CSS EDV Support Logo

MESO-OData API

(.NET Core) WebService, welcher Zugriff auf die Mesonic WinLine© WinLine Daten im REST OData-Standard bietet. Ideal zur Anbindung externer Systeme und mobiler Apps

Stand: 02.12.2025

MESO API Framework

Enterprise-REST-APIs für die Integration mit Mesonic WinLine© ERP-Systemen

Dieses Framework stellt containerisierte REST-APIs zur nahtlosen Integration mit WinLine ERP-Systemen bereit. Perfekt für Entwickler, die Anwendungen, mobile Apps, Web-Portale oder beliebige Systeme erstellen, die auf WinLine-Daten zugreifen müssen.

Was ist eine REST-API? Eine REST-API (Representational State Transfer Application Programming Interface) ist eine standardisierte Schnittstelle, über die verschiedene Softwaresysteme miteinander kommunizieren können. Sie ermöglicht den Zugriff auf Daten und Funktionen über einfache HTTP-Anfragen (wie beim Surfen im Internet).

Was sind Container? Container sind standardisierte Software-Pakete, die alle benötigten Komponenten (Code, Laufzeitumgebung, Bibliotheken) enthalten. Sie können unabhängig vom Betriebssystem auf jedem Server mit Docker ausgeführt werden - ähnlich wie eine portable Mini-Anwendung.

📑 Inhaltsverzeichnis

🚀 Verfügbare API-Services

1. MESOOData API (mesoapi-odata)

Vollständige OData v4 REST-API für umfassenden WinLine-Datenzugriff

Bietet standardisierte OData-REST-Endpunkte für alle WinLine-Entitäten. Ideal für datengetriebene Anwendungen, Reporting-Tools und umfassende Integrationen, wenn Sie Zugriff auf das komplette WinLine-Datenmodell benötigen.

Docker Image: ghcr.io/css-edv-support/mesoapi-odata
Endpunkte: /api/odata/ | Dokumentation: /swagger
Ideal für: Vollständige Integrationen, Data Warehousing, umfassende Reporting-Lösungen

2. MESOOData Reduced API (mesoapireduced-odata)

Schlanke OData-API optimiert für wesentliche Geschäftsdaten

Optimierte Version mit Fokus auf Kern-Geschäftsentitäten wie Artikel, Kunden, Aufträge. Diese API enthält nur die am häufigsten verwendeten Daten und ist dadurch schneller und ressourcenschonender. Perfekt für mobile Apps und leistungskritische Anwendungen.

Docker Image: ghcr.io/css-edv-support/mesoapireduced-odata
Endpunkte: /odata/ | Dokumentation: /swagger
Ideal für: Mobile Apps, Web-Shops, Dashboard-Anwendungen, Schnelle Integrationen

Empfehlung für Einsteiger: Beginnen Sie mit der Reduced API. Sie deckt die meisten Anwendungsfälle ab und ist einfacher zu verstehen, da sie nur die wichtigsten Geschäftsobjekte bereitstellt.

3. MesoWebAPI (mesoapi-webapi)

Geschäftsorientierte REST-API mit benutzerdefinierten Operationen

Bietet spezialisierte Geschäftsmethoden, Datenvalidierung und komplexe Operationen, die über einfache Datenabfragen (CRUD) hinausgehen. Nutzen Sie diese API, wenn Sie komplexe Geschäftslogik benötigen, wie z.B. Bestellvorgänge, Preisberechnungen oder Dokumentengenerierung.

Docker Image: ghcr.io/css-edv-support/mesoapi-webapi
Endpunkte: /business/api/ und /business/odata/ | Dokumentation: /swagger
Ideal für: Workflow-Automatisierung, E-Commerce-Integration, Geschäftslogik-Operationen

Hinweis: CRUD steht für Create (Erstellen), Read (Lesen), Update (Aktualisieren), Delete (Löschen) - die vier grundlegenden Datenbankoperationen.

4. MesoIdentityApi

Zentrale Authentifizierung und Benutzerverwaltung

Übernimmt Benutzerauthentifizierung, JWT-Token-Management und rollenbasierte Zugriffskontrolle, integriert mit WinLine-Benutzersystemen. Verwenden Sie diese API, wenn Ihre Anwendung mit WinLine-Benutzerkonten arbeiten soll.

Docker Image: Auf Anfrage verfügbar
Endpunkte: /auth/ | Dokumentation: /swagger
Ideal für: Multi-User-Anwendungen, Rollenbasierte Zugriffskontrolle

5. MesoWebBrowser

Demo-Blazor-Anwendung zur Veranschaulichung der API-Integration

Interaktive Webanwendung, die zeigt, wie MESO-APIs in realen Szenarien verwendet werden. Enthält vollständige Beispiele für Datenanzeige, Filterung und Benutzerinteraktionen mit WinLine-Daten - ideal zum Lernen und als Ausgangspunkt für eigene Entwicklungen.

Technologie: Blazor Server mit DevExpress-Komponenten
Zweck: Referenzimplementierung und Test-Oberfläche
Ideal für: Entwickler, die Beispielcode und Best Practices suchen

6. MesoOData.Client

.NET Client-Bibliothek für einfache API-Integration

NuGet-Package mit vorgefertigten C#-Klassen und Methoden für die nahtlose Integration der MESO-APIs in .NET-Anwendungen. Vereinfacht den Zugriff auf WinLine-Daten erheblich und erspart Ihnen die manuelle Implementierung von HTTP-Aufrufen.

NuGet Package: MesoOData.Client
Zweck: Vereinfachte .NET-Integration mit IntelliSense-Unterstützung
Ideal für: .NET-Entwickler (C#, VB.NET, F#), die typsichere API-Zugriffe wünschen

Tipp für .NET-Entwickler: Nutzen Sie die Client-Bibliothek statt direkter HTTP-Aufrufe. Sie erhalten automatische Code-Vervollständigung, Typ-Sicherheit und müssen sich nicht um die Details der HTTP-Kommunikation kümmern.

🏗️ Integrations-Architektur

Das MESO API Framework fungiert als moderne Brücke zwischen Ihren Anwendungen und dem WinLine ERP-System:

┌─────────────────────────────────────────────┐
│           Ihre Anwendungen                  │
│   (Web Apps, Mobile Apps, Portale)         │
├─────────────────────────────────────────────┤
│              MESO APIs                      │
│  OData API │ Reduced API │ Business API    │ 
├─────────────────────────────────────────────┤
│            WinLine ERP System               │
│        (Daten + System Datenbanken)        │
└─────────────────────────────────────────────┘

Einfacher Integrations-Workflow für Einsteiger: 1. Bereitstellen - Die MESO-API-Container mit Ihren WinLine-Datenbankverbindungen starten 2. Konfigurieren - Authentifizierung einrichten (API-Keys oder JWT-Tokens) 3. Zugriff - Auf WinLine-Daten über Standard-REST/OData-Aufrufe zugreifen 4. Erstellen - Ihre Anwendungen mit bekannten HTTP/JSON-APIs entwickeln

Hinweis für Einsteiger: Sie benötigen keine Kenntnisse der WinLine-internen Strukturen. Die APIs stellen die Daten über standardisierte, dokumentierte Schnittstellen bereit, die Sie mit jeder Programmiersprache nutzen können, die HTTP-Anfragen unterstützt (z.B. JavaScript, Python, C#, Java).

⚡ Schnellstart - Container-Hosting

Voraussetzungen

Docker installieren: Falls Sie Docker noch nicht haben, laden Sie es von docker.com herunter. Docker Desktop ist für Windows und macOS verfügbar, unter Linux installieren Sie Docker Engine über Ihren Paketmanager.

Wählen Sie Ihren API-Container

Empfehlung für den Einstieg: Reduced API
Die Reduced API ist optimal für die meisten Anwendungsfälle und bietet die wichtigsten Geschäftsdaten mit optimierter Leistung:

docker run -d \
  --name meso-api \
  -p 5500:80 \
  -e ConnectionStrings__WinLineXPODataConnection="Server=ihr-server;Database=WinLineData;User Id=api-user;Password=IhrSicheresPasswort123;TrustServerCertificate=true" \
  -e ConnectionStrings__WinLineXPOSystemConnection="Server=ihr-server;Database=WinLineSystem;User Id=api-user;Password=IhrSicheresPasswort123;TrustServerCertificate=true" \
  -e AppSettings__LicenseNumber="IHRE_CSS_LIZENZ" \
  -e AppSettings__CustomerNumber="IHRE_KUNDENNUMMER" \
  -e AppSettings__ApiKeyHeaderValue="ihr-sicherer-api-key" \
  ghcr.io/css-edv-support/mesoapireduced-odata:latest

Wichtig: Ersetzen Sie ihr-server, api-user, IhrSicheresPasswort123, IHRE_CSS_LIZENZ, IHRE_KUNDENNUMMER und ihr-sicherer-api-key durch Ihre tatsächlichen Werte. Verwenden Sie ein starkes Passwort mit Groß-/Kleinbuchstaben, Zahlen und Sonderzeichen sowie einen sicheren, zufällig generierten API-Key für Produktivumgebungen.

Für umfassenden Datenzugriff (Vollständige OData API):
Nutzen Sie die Full API, wenn Sie Zugriff auf alle WinLine-Tabellen und -Felder benötigen:

docker run -d \
  --name meso-full-api \
  -p 5501:80 \
  -e ConnectionStrings__WinLineXPODataConnection="Server=ihr-server;Database=WinLineData;User Id=api-user;Password=IhrSicheresPasswort123;TrustServerCertificate=true" \
  -e ConnectionStrings__WinLineXPOSystemConnection="Server=ihr-server;Database=WinLineSystem;User Id=api-user;Password=IhrSicheresPasswort123;TrustServerCertificate=true" \
  -e AppSettings__LicenseNumber="IHRE_CSS_LIZENZ" \
  -e AppSettings__CustomerNumber="IHRE_KUNDENNUMMER" \
  -e AppSettings__ApiKeyHeaderValue="ihr-sicherer-api-key" \
  ghcr.io/css-edv-support/mesoapi-odata:latest

Für Geschäftslogik und benutzerdefinierte Operationen:
Die Business API bietet spezialisierte Methoden für komplexe Geschäftsvorgänge:

docker run -d \
  --name meso-business-api \
  -p 5502:80 \
  -e ConnectionStrings__WinLineXPODataConnection="Server=ihr-server;Database=WinLineData;User Id=api-user;Password=IhrSicheresPasswort123;TrustServerCertificate=true" \
  -e ConnectionStrings__WinLineXPOSystemConnection="Server=ihr-server;Database=WinLineSystem;User Id=api-user;Password=IhrSicheresPasswort123;TrustServerCertificate=true" \
  -e AppSettings__LicenseNumber="IHRE_CSS_LIZENZ" \
  -e AppSettings__CustomerNumber="IHRE_KUNDENNUMMER" \
  -e AppSettings__ApiKeyHeaderValue="ihr-sicherer-api-key" \
  ghcr.io/css-edv-support/mesoapi-webapi:latest

Installation überprüfen

Nach dem Start eines Containers können Sie über diese Endpunkte überprüfen, ob alles korrekt funktioniert:

Tipp für Einsteiger: Öffnen Sie die Swagger-Dokumentation in Ihrem Browser. Dort können Sie alle verfügbaren API-Funktionen interaktiv testen, ohne Code schreiben zu müssen. Klicken Sie auf “Authorize”, geben Sie Ihren API-Key ein, und probieren Sie verschiedene Abfragen aus.

🔧 Konfiguration & Lizenzierung

Erforderliche Umgebungsvariablen

Alle APIs benötigen diese Kerneinstellungen:

Variable Beschreibung Beispiel Erforderlich
ConnectionStrings__WinLineXPODataConnection WinLine Geschäftsdatenbank-Verbindung Server=sql-srv;Database=WL_Data;User Id=api;******;TrustServerCertificate=true ✅
ConnectionStrings__WinLineXPOSystemConnection WinLine Systemdatenbank-Verbindung Server=sql-srv;Database=WL_System;User Id=api;******;TrustServerCertificate=true ✅
AppSettings__LicenseNumber CSS EDV Support Lizenznummer 12345678 ✅
AppSettings__CustomerNumber Ihre Kundennummer von CSS 987654321 ✅

Authentifizierungs-Konfiguration

Wählen Sie eine oder beide Authentifizierungsmethoden:

Variable Beschreibung Beispiel Erforderlich
AppSettings__ApiKeyHeaderValue Statischer API-Key für X-MesoAPI-Key Header mein-sicherer-api-key-2024 ⭕
AppSettings__UseWinLineJwtLogin WinLine-Benutzerauthentifizierung aktivieren true ⭕
AppSettings__Secret JWT-Signierungsgeheimnis (bei JWT-Verwendung) ihr-jwt-geheimnis-key ⭕
AppSettings__DefaultCompany Standard-Firmencode 500M ⭕

WinLine SessionManager Konfiguration (Optional)

Der WinLineSessionManager ermöglicht automatisches Session-Pooling für Controller-Methoden, die WinLine Server Credentials benötigen. Wenn keine expliziten Zugangsdaten in den API-Requests übergeben werden, werden Sessions automatisch aus einem verwalteten Pool akquiriert.

Vorteile: - 🚀 Schnellere API-Anfragen durch Session-Wiederverwendung - 🔄 Automatische Session-Verwaltung und -Erneuerung - 💪 Robuste Fehlerbehandlung mit automatischem Retry - 📊 Optimierte Ressourcennutzung durch Connection-Pooling

WinLine Server Konfiguration

Variable Beschreibung Beispiel Erforderlich
WinLineServer__Url WinLine Server URL http://winline-server.example.com/ ⭕

Session-Pool Einstellungen

Variable Beschreibung Standard Erforderlich
SessionSettings__MinimumSessions Minimale Anzahl an Sessions im Pool 5 ⭕
SessionSettings__ValidationInterval Intervall für Session-Validierung 00:05:00 ⭕
SessionSettings__SessionRefreshInterval Intervall für Session-Aktualisierung 01:00:00 ⭕
SessionSettings__DefaultUser Standard-Benutzername für Session-Pool serviceuser ⭕
SessionSettings__DefaultPassword Standard-Passwort für Session-Pool *** ⭕
SessionSettings__DefaultCompany Standard-Mandant 500M ⭕
SessionSettings__DefaultLanguage Standard-Sprache (0=Deutsch, 1=Englisch) 0 ⭕
SessionSettings__MaxConsecutiveLoginFailures Max. aufeinanderfolgende Login-Fehler 5 ⭕
SessionSettings__LoginFailureResetInterval Intervall zum Zurücksetzen des Fehler-Zählers 00:05:00 ⭕

Beispiel-Konfiguration in appsettings.json

{
  "WinLineServer": {
    "Url": "http://winline-server.example.com/"
  },
  "SessionSettings": {
    "MinimumSessions": 5,
    "ValidationInterval": "00:05:00",
    "SessionRefreshInterval": "01:00:00",
    "DefaultUser": "serviceuser",
    "DefaultPassword": "servicepassword",
    "DefaultCompany": "500M",
    "DefaultLanguage": 0,
    "MaxConsecutiveLoginFailures": 5,
    "LoginFailureResetInterval": "00:05:00"
  }
}

Hinweis: Der SessionManager wird nur aktiviert, wenn WinLineServer__Url und SessionSettings__DefaultUser konfiguriert sind. Ohne diese Konfiguration arbeiten die APIs weiterhin mit expliziten Credentials aus den API-Request-Parametern.

Verwendung in API-Requests

Mit expliziten Credentials (wie bisher):

POST /Fallanlage/ErzeugeFall?MesonicServerUrl=http://server&Benutzer=user&Passwort=pass&Mandant=500M

Mit SessionManager (neue Möglichkeit):

# SessionManager akquiriert automatisch eine Session, wenn keine Parameter übergeben werden
POST /Fallanlage/ErzeugeFall

Gemischte Nutzung:

# Eigener Mandant mit SessionManager-Session
POST /Fallanlage/ErzeugeFall?Mandant=600M

Docker Compose für Produktion

version: '3.9'

services:
  # Reduced OData API - Häufigste Wahl
  meso-reduced-api:
    image: ghcr.io/css-edv-support/mesoapireduced-odata:latest
    container_name: meso-reduced-api
    restart: unless-stopped
    ports:
      - "5500:80"
    environment:
      # Datenbankverbindungen
      - ConnectionStrings__WinLineXPODataConnection=Server=sql-server;Database=WinLine_Data;User Id=api_user;******;TrustServerCertificate=true
      - ConnectionStrings__WinLineXPOSystemConnection=Server=sql-server;Database=WinLine_System;User Id=api_user;******;TrustServerCertificate=true
      
      # Lizenzierung (ERFORDERLICH)
      - AppSettings__LicenseNumber=12345678
      - AppSettings__CustomerNumber=987654321
      
      # Authentifizierung
      - AppSettings__ApiKeyHeaderValue=production-api-key-2024
      - AppSettings__UseWinLineJwtLogin=false
      
      # WinLine SessionManager (Optional - für automatisches Session-Pooling)
      - WinLineServer__Url=http://winline-server.example.com/
      - SessionSettings__MinimumSessions=5
      - SessionSettings__ValidationInterval=00:05:00
      - SessionSettings__SessionRefreshInterval=01:00:00
      - SessionSettings__DefaultUser=serviceuser
      - SessionSettings__DefaultPassword=servicepassword
      - SessionSettings__DefaultCompany=500M
      - SessionSettings__DefaultLanguage=0
      - SessionSettings__MaxConsecutiveLoginFailures=5
      - SessionSettings__LoginFailureResetInterval=00:05:00
      
      # Optionale Einstellungen
      - AppSettings__DefaultCompany=500M
      - DOTNET_ENVIRONMENT=Production
      - TZ=Europe/Berlin

  # Business API - Für benutzerdefinierte Operationen
  # meso-business-api:
  #   image: ghcr.io/css-edv-support/mesoapi-webapi:latest
  #   container_name: meso-business-api
  #   restart: unless-stopped
  #   ports:
  #     - "5502:80"
  #   environment:
  #     # Gleiche Konfiguration wie oben

🔑 Lizenzierungsanforderungen

Wichtig: Alle MESO-APIs benötigen eine gültige Lizenz von CSS EDV Support:

Ohne gültige Lizenz starten die APIs nicht oder stellen den Betrieb nach einer Testperiode ein.

🔐 Authentifizierungsmethoden

API-Key-Authentifizierung (Empfohlen)

Einfach und sicher für Server-zu-Server-Kommunikation:

# API-Key in Umgebung setzen
export MESO_API_KEY="ihr-sicherer-api-key"

# X-MesoAPI-Key Header in alle Anfragen einschließen
curl -H "X-MesoAPI-Key: $MESO_API_KEY" \
     http://localhost:5500/odata/Artikelview

JWT-Authentifizierung (WinLine-Benutzer)

Für Anwendungen, bei denen sich WinLine-Benutzer authentifizieren müssen:

# 1. JWT im Container aktivieren
# -e AppSettings__UseWinLineJwtLogin=true
# -e AppSettings__Secret="ihr-jwt-geheimnis"

# 2. Anmeldung mit WinLine-Anmeldedaten
curl -X POST http://localhost:5500/auth/login \
     -H "Content-Type: application/json" \
     -d '{
       "username": "winline-benutzername",
       "password": "winline-passwort"
     }'

# Antwort enthält JWT-Token:
# {
#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "expiration": "2024-10-05T10:30:00Z",
#   "username": "winline-benutzername",
#   "groups": ["Verkauf", "Geschäftsführung"]
# }

# 3. JWT-Token im Authorization-Header verwenden
curl -H "Authorization: ******" \
     http://localhost:5500/odata/Artikelview

📊 OData REST API Verwendung

Die OData-APIs bieten Standard-REST-Endpunkte nach der OData v4-Spezifikation. Alle Beispiele verwenden API-Key-Authentifizierung.

Was ist OData? OData (Open Data Protocol) ist ein standardisiertes Protokoll für den Zugriff auf Daten über REST-APIs. Es bietet eine einheitliche Abfragesprache, mit der Sie Daten filtern, sortieren, paginieren und erweitern können - ähnlich wie SQL-Abfragen, aber über HTTP.

Kern-Geschäftsentitäten

Artikel (Artikelview)
Die wichtigsten Operationen für den Zugriff auf Artikeldaten:

# Alle Artikel abrufen
GET /odata/Artikelview
curl -H "X-MesoAPI-Key: $API_KEY" http://localhost:5500/odata/Artikelview

# Bestimmten Artikel nach Nummer abrufen
GET /odata/Artikelview?$filter=Artikelnummer eq '10001'
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5500/odata/Artikelview?\$filter=Artikelnummer eq '10001'"

# Artikel nach Bezeichnung suchen (Teilstring-Suche)
GET /odata/Artikelview?$filter=contains(Bezeichnung,'Laptop')
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5500/odata/Artikelview?\$filter=contains(Bezeichnung,'Laptop')"

# Nur bestimmte Felder abrufen (spart Bandbreite)
GET /odata/Artikelview?$select=Artikelnummer,Bezeichnung,VkPreis1
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5500/odata/Artikelview?\$select=Artikelnummer,Bezeichnung,VkPreis1"

# Artikel nach Preis sortiert abrufen (Top 20)
GET /odata/Artikelview?$orderby=VkPreis1 desc&$top=20
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5500/odata/Artikelview?\$orderby=VkPreis1 desc&\$top=20"

Hinweis: Das $-Zeichen in URLs muss in Bash-Befehlen mit \$ escaped werden. In Browsern oder API-Tools wie Postman können Sie $ direkt verwenden.

Kunden (Kunden)

# Alle Kunden abrufen
GET /odata/Kunden
curl -H "X-MesoAPI-Key: $API_KEY" http://localhost:5500/odata/Kunden

# Kunde nach Namen suchen
GET /odata/Kunden?$filter=contains(Name1,'Mueller')
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5500/odata/Kunden?\$filter=contains(Name1,'Mueller')"

# Kunde mit Adressen abrufen
GET /odata/Kunden?$expand=Adressen
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5500/odata/Kunden?\$expand=Adressen"

Aufträge (Aufträge)

# Aktuelle Aufträge abrufen
GET /odata/Auftraege?$filter=Datum ge 2024-01-01&$orderby=Datum desc
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5500/odata/Auftraege?\$filter=Datum ge 2024-01-01&\$orderby=Datum desc"

# Auftrag mit Auftragspositionen abrufen
GET /odata/Auftraege?$expand=Auftragspositionen
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5500/odata/Auftraege?\$expand=Auftragspositionen"

Erweiterte OData-Abfragen

Filtern und Suchen

# Mehrere Bedingungen mit UND (and) verknüpfen
GET /odata/Artikelview?$filter=VkPreis1 gt 100 and Artikelgruppe eq 'HARDWARE'

# Mehrere Bedingungen mit ODER (or) verknüpfen
GET /odata/Artikelview?$filter=Artikelgruppe eq 'SOFTWARE' or Artikelgruppe eq 'HARDWARE'

# Datumsbereich filtern
GET /odata/Auftraege?$filter=Datum ge 2024-01-01 and Datum le 2024-12-31

# Null-Wert-Prüfungen (nur Kunden mit E-Mail)
GET /odata/Kunden?$filter=Email ne null

# String-Funktionen kombinieren
GET /odata/Artikelview?$filter=startswith(Artikelnummer,'10') and length(Bezeichnung) gt 10

OData-Vergleichsoperatoren: - eq = gleich (equal) - ne = ungleich (not equal) - gt = größer als (greater than) - ge = größer oder gleich (greater or equal) - lt = kleiner als (less than) - le = kleiner oder gleich (less or equal)

Paginierung und Sortierung
Für große Datenmengen sollten Sie Paginierung verwenden:

# Paginierung mit $top (Anzahl) und $skip (Überspringen)
GET /odata/Artikelview?$top=50&$skip=100&$count=true

# Mehrere Sortierkriterien
GET /odata/Artikelview?$orderby=Artikelgruppe,VkPreis1 desc

# Nur Gesamtzahl der Datensätze abrufen (ohne Daten)
GET /odata/Artikelview/$count

Tipp: Verwenden Sie $count=true in Ihren Abfragen, um neben den Daten auch die Gesamtanzahl zu erhalten. Dies ist nützlich für die Implementierung von Pagination in Ihrer Anwendung.

Daten-Erweiterung (Verknüpfungen/Joins)

# Einstufige Erweiterung - Auftrag mit Kundendaten
GET /odata/Auftraege?$expand=Kunde

# Mehrstufige Erweiterung - Auftrag mit Kunde und dessen Adressen
GET /odata/Auftraege?$expand=Kunde($expand=Adressen)

# Selektive Erweiterung mit Filterung - nur Positionen mit Menge > 5
GET /odata/Auftraege?$expand=Auftragspositionen($filter=Menge gt 5)

🔧 Business-API-Methoden (MesoWebAPI)

Die Business API bietet spezialisierte Endpunkte für komplexe Vorgänge, die über einfache CRUD-Operationen hinausgehen.

Lager-Operationen

# Aktuelle Lagerbestände abrufen
GET /business/api/Bestand?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/business/api/Bestand?mesocomp=500M"

# Lagerbestand für bestimmten Artikel abrufen
GET /business/api/Bestand/GetByProductId/10001?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/business/api/Bestand/GetByProductId/10001?mesocomp=500M"

# Lagerbestand nach EAN-Code abrufen
GET /business/api/Bestand/GetByStockEAN/1234567890123?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/business/api/Bestand/GetByStockEAN/1234567890123?mesocomp=500M"

Dokument-Operationen

# Rechnung als PDF generieren und herunterladen
POST /business/api/Documents/GenerateInvoicePdf
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"invoiceNumber": "RE-2024-001", "mesocomp": "500M"}' \
     http://localhost:5502/business/api/Documents/GenerateInvoicePdf

# Kundendaten exportieren
POST /business/api/Export/Customers
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"format": "excel", "filters": {"customerGroup": "A"}}' \
     http://localhost:5502/business/api/Export/Customers

Validierung und Geschäftslogik

# Kundendaten vor Erstellung validieren
POST /business/api/Validation/ValidateCustomer
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Neue Firma GmbH",
       "email": "[email protected]",
       "vatNumber": "DE123456789"
     }' \
     http://localhost:5502/business/api/Validation/ValidateCustomer

# Auftragssumme mit Rabatten berechnen
POST /business/api/Calculation/CalculateOrderTotal
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "customerId": "K-10001",
       "items": [
         {"articleNumber": "10001", "quantity": 2},
         {"articleNumber": "10002", "quantity": 1}
       ],
       "discountPercent": 5
     }' \
     http://localhost:5502/business/api/Calculation/CalculateOrderTotal

Archiv-Operationen

# Archivdokumente durchsuchen
GET /business/api/Archive/Search?keywords=Rechnung&documentType=RE
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/business/api/Archive/Search?keywords=Rechnung&documentType=RE"

# Archivdokument herunterladen
GET /business/api/Archive/Download/12345
curl -H "X-MesoAPI-Key: $API_KEY" \
     http://localhost:5502/business/api/Archive/Download/12345 \
     --output dokument.pdf

Fall-Operationen (CRM)

# Fall erstellen
POST /Fallanlage/ErzeugeFall
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "workflownummer": 254,
       "kontonummer": "230A001",
       "kurzbeschreibung": "Bitte Rechnung prüfen"
     }' \
     "http://localhost:5502/Fallanlage/ErzeugeFall?mandant=500M"

# Fall mit Anhängen in einem Request erstellen (NEU in Version 2024.12)
POST /Fallanlage/ErzeugeFallMitAnhaengen
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -F "workflownummer=254" \
     -F "schrittnummer=1" \
     -F "kontonummer=230A001" \
     -F "kurzbeschreibung=Bitte Rechnung prüfen" \
     -F "anhaenge=@/pfad/zur/datei1.pdf" \
     -F "anhaenge=@/pfad/zur/datei2.jpg" \
     "http://localhost:5502/Fallanlage/ErzeugeFallMitAnhaengen?mandant=500M&benutzernummer=8"

# Fall mit base64-kodierten Anhängen erstellen (NEU in Version 2024.12)
# Unterstützt sowohl reinen Base64-String als auch Data URL Format
POST /Fallanlage/ErzeugeFallMitBase64Anhaengen
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "workflownummer": 254,
       "schrittnummer": 1,
       "kontonummer": "230A001",
       "kurzbeschreibung": "Bitte Rechnung prüfen",
       "anhaenge": [
         {
           "dateiname": "rechnung.pdf",
           "base64Inhalt": "JVBERi0xLjQKJeLjz9MKMy..."
         },
         {
           "dateiname": "bild.png",
           "base64Inhalt": "data:image/png;base64,iVBORw0KGgoAAAANS..."
         }
       ]
     }' \
     "http://localhost:5502/Fallanlage/ErzeugeFallMitBase64Anhaengen?mandant=500M"

# Anhänge zu bestehendem Fall hinzufügen
POST /Fallanlage/ErzeugeFallUploads
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -F "fallUploads=@/pfad/zur/datei.pdf" \
     "http://localhost:5502/Fallanlage/ErzeugeFallUploads?fallId=12345&schrittnummer=1&mandant=500M"

🎯 Typische Integrations-Szenarien

Daten-Synchronisation für Mobile Apps

# Geänderte Daten seit der letzten Synchronisation abrufen
GET /odata/Artikelview?$filter=ModifiedDate gt 2024-10-01T08:00:00Z&$select=Artikelnummer,Bezeichnung,VkPreis1,ModifiedDate

# Leichtgewichtige Kundensuche für mobile Anwendungen
GET /odata/Kunden?$select=Kundennummer,Name1,Email&$filter=contains(Name1,'suchbegriff')&$top=10

E-Commerce-Integration (Online-Shop)

# Produktkatalog mit Bildern und Lagerbestand abrufen
GET /odata/Artikelview?$filter=WebshopArtikel eq true&$select=Artikelnummer,Bezeichnung,VkPreis1,WebshopBeschreibung&$expand=Lagerbestand

# Bestellung über Business API anlegen
POST /business/api/Orders/CreateWebOrder
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "customerEmail": "[email protected]",
       "items": [
         {"sku": "10001", "quantity": 2, "price": 299.99}
       ],
       "shippingAddress": {...},
       "paymentMethod": "CreditCard"
     }' \
     http://localhost:5502/business/api/Orders/CreateWebOrder

Berichte und Auswertungen

# Verkaufsstatistik abrufen
GET /business/api/Reports/SalesStatistics?startDate=2024-01-01&endDate=2024-12-31&groupBy=month

# Meistverkaufte Produkte ermitteln
GET /odata/Auftragspositionen?$apply=groupby((Artikelnummer),aggregate(Menge with sum as TotalSold))&$orderby=TotalSold desc&$top=10

🐳 Container-Verwaltung und Bereitstellung

Neue Bereitstellungs-Strategie verfügbar! 📋 Siehe DEPLOYMENT.md für den neuen automatischen Beta/Release-Workflow

Schneller Start: Automatisierte Bereitstellung

Das MESO API Framework nutzt jetzt automatisierte Bereitstellungs-Workflows:

# Beta-Umgebung (Staging/Testing)
docker-compose -f docker-compose.beta.yml up -d

# Produktions-Umgebung
docker-compose -f docker-compose.production.yml up -d

Docker Compose für mehrere APIs

Mehrere APIs gleichzeitig ausführen für umfassende Abdeckung:

version: '3.9'

services:
  # Reverse Proxy für API-Routing
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - meso-reduced-api
      - meso-business-api

  # Reduced OData API
  meso-reduced-api:
    image: ghcr.io/css-edv-support/mesoapireduced-odata:latest
    restart: unless-stopped
    environment:
      - ConnectionStrings__WinLineXPODataConnection=${WINLINE_DATA_CONNECTION}
      - ConnectionStrings__WinLineXPOSystemConnection=${WINLINE_SYSTEM_CONNECTION}
      - AppSettings__LicenseNumber=${LICENSE_NUMBER}
      - AppSettings__CustomerNumber=${CUSTOMER_NUMBER}
      - AppSettings__ApiKeyHeaderValue=${API_KEY}
      - DOTNET_ENVIRONMENT=Production

  # Business API
  meso-business-api:
    image: ghcr.io/css-edv-support/mesoapi-webapi:latest
    restart: unless-stopped
    environment:
      - ConnectionStrings__WinLineXPODataConnection=${WINLINE_DATA_CONNECTION}
      - ConnectionStrings__WinLineXPOSystemConnection=${WINLINE_SYSTEM_CONNECTION}
      - AppSettings__LicenseNumber=${LICENSE_NUMBER}
      - AppSettings__CustomerNumber=${CUSTOMER_NUMBER}
      - AppSettings__ApiKeyHeaderValue=${API_KEY}
      - DOTNET_ENVIRONMENT=Production

  # SQL Server (falls lokal ausgeführt)
  # sqlserver:
  #   image: mcr.microsoft.com/mssql/server:2022-latest
  #   environment:
  #     - ACCEPT_EULA=Y
  #     - SA_PASSWORD=IhrSicheres@Passwort
  #   ports:
  #     - "1433:1433"
  #   volumes:
  #     - sqlserver_data:/var/opt/mssql

# volumes:
#   sqlserver_data:

Umgebungsvariablen-Datei (.env)

# Datenbankverbindungen
WINLINE_DATA_CONNECTION=Server=sql-server;Database=WinLine_Data;User Id=api_user;Password=SicheresPasswort123;TrustServerCertificate=true
WINLINE_SYSTEM_CONNECTION=Server=sql-server;Database=WinLine_System;User Id=api_user;Password=SicheresPasswort123;TrustServerCertificate=true

# Lizenzierung
LICENSE_NUMBER=12345678
CUSTOMER_NUMBER=987654321

# Sicherheit
API_KEY=production-api-key-2024

Kubernetes-Bereitstellung

apiVersion: apps/v1
kind: Deployment
metadata:
  name: meso-reduced-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: meso-reduced-api
  template:
    metadata:
      labels:
        app: meso-reduced-api
    spec:
      containers:
      - name: api
        image: ghcr.io/css-edv-support/mesoapireduced-odata:latest
        ports:
        - containerPort: 80
        env:
        - name: ConnectionStrings__WinLineXPODataConnection
          valueFrom:
            secretKeyRef:
              name: meso-secrets
              key: winline-data-connection
        - name: ConnectionStrings__WinLineXPOSystemConnection
          valueFrom:
            secretKeyRef:
              name: meso-secrets
              key: winline-system-connection
        - name: AppSettings__LicenseNumber
          valueFrom:
            secretKeyRef:
              name: meso-secrets
              key: license-number
        - name: AppSettings__CustomerNumber
          valueFrom:
            secretKeyRef:
              name: meso-secrets
              key: customer-number
        - name: AppSettings__ApiKeyHeaderValue
          valueFrom:
            secretKeyRef:
              name: meso-secrets
              key: api-key
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 80
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 80
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: meso-reduced-api-service
spec:
  selector:
    app: meso-reduced-api
  ports:
  - port: 80
    targetPort: 80
  type: LoadBalancer

🔍 Überwachung und Betrieb

Systemstatus-Prüfungen

Alle APIs bieten Endpunkte zur Überprüfung des Systemstatus:

# Basis-Statusprüfung
curl http://localhost:5500/health

# Detaillierte Statusinformationen
curl http://localhost:5500/health/detailed

# Datenbankverbindung prüfen
curl http://localhost:5500/health/database

Protokollierung

Die APIs verwenden strukturierte Protokollierung mit Serilog. Log-Level über Umgebungsvariablen konfigurieren:

# Umgebungsvariablen für Protokollierung
-e Logging__LogLevel__Default=Information
-e Logging__LogLevel__Microsoft=Warning
-e Logging__LogLevel__Microsoft.AspNetCore=Warning
-e Serilog__MinimumLevel=Information

# In Datei protokollieren (Volume einbinden)
-v /host/logs:/app/logs
-e Serilog__WriteTo__0__Name=File
-e Serilog__WriteTo__0__Args__path=/app/logs/meso-api-.txt
-e Serilog__WriteTo__0__Args__rollingInterval=Day

Leistungsoptimierung

# Produktions-Umgebungsvariablen
-e DOTNET_ENVIRONMENT=Production
-e ASPNETCORE_URLS=http://+:80
-e DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=false

# Speicheroptimierung
-e DOTNET_gcServer=true
-e DOTNET_gcConcurrent=true

# Verbindungspooling
-e ConnectionStrings__WinLineXPODataConnection="...;Pooling=true;Max Pool Size=100;Min Pool Size=5"

📚 API-Dokumentation und Erkennbarkeit

Interaktive Dokumentation

Jede API bietet umfassende Swagger-Dokumentation:

Metadaten-Erkennung

# OData-Metadaten (Entitätsmodelle)
curl http://localhost:5500/odata/$metadata

# OpenAPI-Spezifikation
curl http://localhost:5500/swagger/v1/swagger.json

# Verfügbare Endpunkte
curl http://localhost:5500/odata/

# Service-Dokument
curl http://localhost:5500/odata/\$metadata

Testen mit API-Sammlungen

Das Repository enthält umfassende Test-Sammlungen im Verzeichnis ApiTestCollections/, die importiert werden können in:

🔧 Fehlerbehebung

Häufige Probleme

Lizenzvalidierungsfehler

# Lizenzkonfiguration prüfen
curl -H "X-MesoAPI-Key: $API_KEY" http://localhost:5500/health/license

# Lizenz-Umgebungsvariablen überprüfen
docker exec container-name env | grep AppSettings__License

Datenbankverbindungsprobleme

# Datenbankverbindung testen
curl -H "X-MesoAPI-Key: $API_KEY" http://localhost:5500/health/database

# Verbindungsstrings prüfen
docker logs container-name | grep -i "connection\|database"

Authentifizierungsprobleme

# API-Key überprüfen
curl -v -H "X-MesoAPI-Key: falscher-key" http://localhost:5500/odata/Artikelview

# JWT-Konfiguration prüfen (falls verwendet)
curl -X POST http://localhost:5500/auth/login \
     -H "Content-Type: application/json" \
     -d '{"username": "test", "password": "test"}'

Leistungsprobleme

# Container-Ressourcenverbrauch prüfen
docker stats container-name

# API-Antwortzeiten überwachen
curl -w "@curl-format.txt" -H "X-MesoAPI-Key: $API_KEY" http://localhost:5500/odata/Artikelview

# Detaillierte Protokollierung aktivieren
docker run -e Logging__LogLevel__Default=Debug ...

🤝 Support & Ressourcen

Technischer Support

Ressourcen

Lizenzierung & Vertrieb

📝 Versionshistorie

Version 2024.12 (Dezember 2024)

💎 Hinzugefügt: - WinLineSessionManager Integration für automatisches Session-Pooling in Controller-Methoden - Neuer FallanlageController-Endpunkt ErzeugeFallMitAnhaengen für kombinierte Fall-Erstellung mit Anhängen in einem Request - Neuer FallanlageController-Endpunkt ErzeugeFallMitBase64Anhaengen für Fall-Erstellung mit base64-kodierten Anhängen - Optionale Konfiguration für Standard-WinLine-Verbindung über appsettings.json - WebServiceParameterProvider Service für intelligente Session-Verwaltung - WebServiceParameterModelBinder für automatische Parameter-Bindung mit SessionManager-Fallback - WinLine Server Client NuGet-Pakete (WinLineServerClient, WinLineServer.ApiExtensions) - Einsteiger-freundliche Erklärungen für REST-API, Container und OData - Detaillierte OData-Operatoren-Dokumentation - Praktische Tipps und Hinweise für Entwickler - Verbesserte Schnellstart-Anleitung mit Schritt-für-Schritt-Erklärungen - Zentrale AuthenticationOptions Klasse für konsistente Authentifizierungskonfiguration

🏗️ Überarbeitet: - Verbesserte Parameter-Binding in FallanlageController mit expliziten [FromQuery] Attributen - Vollständige Übersetzung aller englischen Abschnitte ins Deutsche - Reduzierung von Anglizismen bei Beschreibungen - Konsistente deutsche Terminologie durchgehend - Verbesserte Strukturierung der Dokumentation - Authentifizierungs-Middleware refactored mit Options Pattern - Vollständige JWT-Token-Validierung mit Signaturprüfung implementiert - Konsolidierung der Authentifizierungslogik (nur Middleware, keine Filter mehr)

🐛 Behoben: - Versionsermittlung für MesoOData.Client im deploy.yml Workflow durch Deaktivierung von GeneratePackageOnBuild - Inkonsistente Konfigurationsabfrage über verschiedene Middleware-Komponenten - Fehlende JWT-Token-Signaturvalidierung in JwtAuthorizationMiddleware - Redundante ApiKeyAuthorizationFilter entfernt

Version 2024.10 (Oktober 2024)

💎 Hinzugefügt: - Automatisierte Bereitstellungs-Workflows (Beta/Release) - Einheitlicher Deployment-Workflow für alle Services - Kubernetes-Bereitstellungsbeispiele

🏗️ Überarbeitet: - Docker Compose Konfigurationen aktualisiert - Umgebungsvariablen-Dokumentation erweitert

Version 2024.09 (September 2024)

💎 Hinzugefügt: - MesoOData.Client NuGet Package - Umfassende API-Testsammlungen - Erweiterte Authentifizierungsoptionen

Version 2024.08 (August 2024)

💎 Hinzugefügt: - MesoWebBrowser Demo-Anwendung - Business API mit benutzerdefinierten Operationen - Health Check Endpunkte

🐛 Behoben: - Verbesserte Fehlerbehandlung - Optimierte Datenbankverbindungen

Powered by CSS EDV Support • Erstellt für WinLine ERP Integration