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: 05.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.

Telefonbuch-Operationen (Kontaktdaten)

Normalisierte Kontaktdaten für Telefonieanwendungen und CTI-Systeme. Siehe Telefonbuch-Integration für ausführliche Dokumentation.

# Kontakte als JSON abrufen
GET /business/api/telefonbuch?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/business/api/telefonbuch?mesocomp=500M"

# Kontakte als CSV-Datei exportieren
GET /business/api/telefonbuch/csv?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/business/api/telefonbuch/csv?mesocomp=500M" \
     --output telefonbuch.csv

Lager-Operationen

Zugriff auf Lagerbestände und Inventardaten. Der BestandSpezialController bietet spezialisierte Endpunkte für verschiedene Suchmethoden.

# Lagerbestand nach Artikelnummer abrufen
GET /api/bestand/nachartikelid/{artikelnummer}?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/api/bestand/nachartikelid/10001?mesocomp=500M"

# Lagerbestand nach EAN-Code abrufen
GET /api/bestand/nach-lager-ean/{ean}?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/api/bestand/nach-lager-ean/4012345678901?mesocomp=500M"

# Lagerbestand nach Lager-Kurzcode abrufen
GET /api/bestand/nach-lager-kurzcode/{kurzcode}?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/api/bestand/nach-lager-kurzcode/HL?mesocomp=500M"

Hinweis: Die Bestand-Endpunkte verwenden die Route /api/bestand (nicht /business/api/Bestand). Die API gibt BestandDto-Objekte zurück mit Informationen zu Lagerort, Menge und Verfügbarkeit.

Archiv-Operationen

Der ArchivController bietet Zugriff auf das WinLine-Archiv für Dokumentenexport und -verwaltung.

# Einzelnen Archiveintrag exportieren
POST /Archiv/ArchiveintragExportieren
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "archivId": 12345,
       "ausgabeVerzeichnis": "C:\\Export\\",
       "vorhandeneDateiUeberschreiben": true,
       "alternativerDateiname": "dokument_export.pdf"
     }' \
     "http://localhost:5502/Archiv/ArchiveintragExportieren"

# Archiveinträge nach Schlagworten exportieren
POST /Archiv/ArchiveintraegeExportieren?ausgabeVerzeichnis=C:\\Export\\
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "schlagwoerter": [
         {
           "schlagwort": "Rechnungsnummer",
           "wert": "RE-2024-001"
         }
       ],
       "archivFormulare": [1, 2],
       "vonDatum": "2024-01-01T00:00:00",
       "bisDatum": "2024-12-31T23:59:59",
       "schlagwortlisteExportieren": true
     }' \
     "http://localhost:5502/Archiv/ArchiveintraegeExportieren?ausgabeVerzeichnis=C:\\\\Export\\\\"

Wichtig: Die Archiv-Operationen benötigen Zugriff auf das WinLine-Dateisystem. Der ausgabeVerzeichnis-Parameter muss ein gültiger Pfad auf dem Server sein.

Fall-Operationen (CRM)

Der FallanlageController bietet umfangreiche Methoden zur Verwaltung von CRM-Fällen in der WinLine. Alle Endpunkte nutzen den WebServiceParameter für Authentifizierung und Mandantenauswahl.

Verfügbare Endpunkte:

1. Fall erstellen (JSON-basiert)

# Fall mit JSON-Struktur erstellen
POST /Fallanlage/ErzeugeFall
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",
       "langbeschreibungIntern": "Interne Notizen hier",
       "projektnummer": "PROJ-2024-001",
       "gesamtbetrag": 1500.00,
       "startDatum": "2024-12-01T09:00:00",
       "eskalationsdatum": "2024-12-15T17:00:00"
     }' \
     "http://localhost:5502/Fallanlage/ErzeugeFall?mandant=500M&benutzernummer=8"

2. Fall mit Anhängen erstellen (Multipart)

NEU in Version 2024.12 - Erstellt Fall und lädt Dateien in einem Request hoch.

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 "langbeschreibungIntern=Interne Notizen" \
     -F "gesamtbetrag=1500.00" \
     -F "anhaenge=@/pfad/zur/rechnung.pdf" \
     -F "anhaenge=@/pfad/zum/bild.jpg" \
     "http://localhost:5502/Fallanlage/ErzeugeFallMitAnhaengen?mandant=500M&benutzernummer=8&archivformular=0"

Parameter: - workflownummer (erforderlich): ID des Workflows - schrittnummer (erforderlich): Workflow-Schritt - kontonummer: Debitor/Kreditor-Nummer - kurzbeschreibung: Kurzer Fallbetreff - langbeschreibungIntern: Interne Beschreibung - langbeschreibungExtern: Externe Beschreibung (für Kunde sichtbar) - projektnummer: Verknüpfung mit Projekt - artikelnummer: Verknüpfung mit Artikel - opNummer: OP-Nummer - gesamtbetrag: Monetärer Wert - startDatum, eskalationsdatum, endDatum: Zeitstempel - anhaenge: Dateiuploads (mehrere möglich) - benutzernummer: WinLine-Benutzernummer (Standard: 8) - archivformular: Archivformular-ID (Standard: 0)

3. Fall mit Base64-Anhängen erstellen

NEU in Version 2024.12 - Ideal für Web-Anwendungen und API-Integrationen.

POST /Fallanlage/ErzeugeFall
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": "JVBERi0xLjQKJeLjz9MKMy4uLg=="
         },
         {
           "dateiname": "bild.png",
           "base64Inhalt": "data:image/png;base64,iVBORw0KGgoAAAANS..."
         }
       ]
     }' \
     "http://localhost:5502/Fallanlage/ErzeugeFall?mandant=500M&benutzernummer=8"

Hinweis: Unterstützt sowohl reinen Base64-String als auch Data URL Format (data:image/png;base64,...). Das Data URL Format wird automatisch erkannt und verarbeitet.

4. Fall aus JSON-String erstellen

Flexible Variante für dynamische JSON-Strukturen.

POST /Fallanlage/ErzeugeFallVonJson?mandant=500M&vorlagennummer=100&workflownummer=254
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "Workflownummer": 254,
       "Kurzbeschreibung": "Testbetreff",
       "Klassifizierung": "Angebot",
       "Kontonummer": "230A001"
     }' \
     "http://localhost:5502/Fallanlage/ErzeugeFallVonJson?mandant=500M&vorlagennummer=100"

5. Fall aus Feldliste erstellen

POST /Fallanlage/ErzeugeFallAnhandFeldListe?mandant=500M
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "workflownummer": 254,
       "felder": [
         {"feldname": "Kurzbeschreibung", "wert": "Test"},
         {"feldname": "Kontonummer", "wert": "230A001"}
       ]
     }' \
     "http://localhost:5502/Fallanlage/ErzeugeFallAnhandFeldListe?mandant=500M"

6. Anhänge zu bestehendem Fall hinzufügen

POST /Fallanlage/ErzeugeFallUploads?fallId=12345&schrittnummer=1&mandant=500M
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -F "fallUploads=@/pfad/zur/datei1.pdf" \
     -F "fallUploads=@/pfad/zur/datei2.jpg" \
     "http://localhost:5502/Fallanlage/ErzeugeFallUploads?fallId=12345&schrittnummer=1&mandant=500M&benutzernummer=8"

7. Dokument beschlagworten

POST /Fallanlage/BeschlagworteDokument?dokumentenId=67890&fallId=12345&benutzernummer=8
curl -X POST -H "X-MesoAPI-Key: $API_KEY" \
     -H "Content-Type: application/json" \
     -d '[
       {
         "schlagwort": "Rechnungsnummer",
         "wert": "RE-2024-001"
       },
       {
         "schlagwort": "Kunde",
         "wert": "Musterfirma GmbH"
       }
     ]' \
     "http://localhost:5502/Fallanlage/BeschlagworteDokument?dokumentenId=67890&fallId=12345"

Antwortformat: Alle Endpunkte geben ein ErzeugterFall oder ErzeugterFallMitDokumentenResponse-Objekt zurück mit: - ErzeugteFallId: ID des neu erstellten Falls - Fehlermeldung: Fehlerbeschreibung bei Problemen - ErzeugteDokumente: Liste der hochgeladenen Dokumente (falls vorhanden)

Häufige Fehlerquellen: - Ungültige workflownummer oder schrittnummer - Fehlende Berechtigungen für benutzernummer - Ungültige kontonummer (muss im Kontaktestamm existieren) - Bei Base64: Fehlende oder ungültige Codierung

🎯 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

Telefonbuch-Integration (Telefonieanwendungen)

Die Telefonbuch-API bietet normalisierte Kontaktdaten für die einfache Integration in Telefonieanwendungen und CTI-Systeme. Die API liest Daten aus dem WinLine Kontaktestamm und bietet drei verschiedene Zugriffsmöglichkeiten.

Besondere Features: - 📞 Intelligente Telefonnummer-Formatierung: Automatische Normalisierung im E.164-Format (+436641234567) - 🌍 Ländercode-Normalisierung: Unterstützt einstellige Ländercodes (z.B. “D” → “DE”, “A” → “AT”) - 🏢 Automatische Firmenzuordnung: Verknüpfung mit Fibu-Konten über ErmittlePersonenkonto - 🔄 Drei Ausgabeformate: JSON, CSV und OData mit umfangreichen Filtermöglichkeiten - ⚡ Optimierte Performance: Eager Loading verhindert Session-Probleme bei großen Datenmengen

# Alle Kontakte mit normalisierten Telefonnummern abrufen (JSON)
GET /business/api/telefonbuch?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/business/api/telefonbuch?mesocomp=500M"

# Kontakte als CSV-Datei exportieren
GET /business/api/telefonbuch/csv?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/business/api/telefonbuch/csv?mesocomp=500M" \
     --output telefonbuch.csv

# OData-Endpunkt mit erweiterten Abfragemöglichkeiten
GET /odata/Telefonbuch?mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/odata/Telefonbuch?mesocomp=500M"

# Nach Nachname filtern
GET /odata/Telefonbuch?$filter=contains(Nachname,'Mueller')&mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/odata/Telefonbuch?\$filter=contains(Nachname,'Mueller')&mesocomp=500M"

# Nur Kontakte mit Mobilnummer
GET /odata/Telefonbuch?$filter=Mobil ne null&mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/odata/Telefonbuch?\$filter=Mobil ne null&mesocomp=500M"

# Bestimmte Felder auswählen
GET /odata/Telefonbuch?$select=Nachname,Vorname,Telefon1,Email&mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/odata/Telefonbuch?\$select=Nachname,Vorname,Telefon1,Email&mesocomp=500M"

# Kontakte sortiert nach Nachname mit Paginierung
GET /odata/Telefonbuch?$orderby=Nachname&$top=50&$skip=0&mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/odata/Telefonbuch?\$orderby=Nachname&\$top=50&\$skip=0&mesocomp=500M"

# Kombination mehrerer Filter
GET /odata/Telefonbuch?$filter=Firmenname ne null and Telefon1 ne null&$orderby=Firmenname&mesocomp=500M
curl -H "X-MesoAPI-Key: $API_KEY" \
     "http://localhost:5502/odata/Telefonbuch?\$filter=Firmenname ne null and Telefon1 ne null&\$orderby=Firmenname&mesocomp=500M"

Hinweis zur Telefonnummer-Formatierung: Die API verwendet die libphonenumber-Bibliothek für die Normalisierung. Telefonnummern werden automatisch im E.164-Format ausgegeben (z.B. +436641234567). Dies ist das internationale Standardformat für Telefonieanwendungen und CTI-Integrationen. Bei fehlenden oder ungültigen Telefonnummern wird null zurückgegeben.

Unterstützte Ländercodes: Die API normalisiert automatisch einstellige Ländercodes zu ISO-Codes: - “A” → “AT” (Österreich), “D” → “DE” (Deutschland), “CH” → “CH” (Schweiz) - “I” → “IT” (Italien), “F” → “FR” (Frankreich), “E” → “ES” (Spanien) - “B” → “BE” (Belgien), “H” → “HU” (Ungarn), “SLO” → “SI” (Slowenien) - Weitere europäische Länder werden unterstützt

Verfügbare Felder: - ID - Eindeutige Kontakt-ID (Key aus KontakteStamm) - Anrede, Titel, Nachname, Vorname - Personendaten - Strasse, PLZ, Ort - Adressdaten (Strasse1 + Strasse2 kombiniert) - Telefon1, Telefon2, Mobil - Normalisierte Telefonnummern im E.164-Format - Email - E-Mail-Adresse - FibuKontonummer, Firmenname - Firmenzuordnung über ErmittlePersonenkonto-Verknüpfung - DatumLetzteAenderung, DatumErstanlage - Zeitstempel

CSV-Format: Die CSV-Datei verwendet Semikolon (;) als Trennzeichen und UTF-8 mit BOM-Encoding für korrekte Darstellung von Umlauten in Excel. Felder mit Sonderzeichen werden automatisch in Anführungszeichen gesetzt.

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: - Telefonbuch-API für normalisierte Kontaktdaten zur Integration in Telefonieanwendungen - Business-Endpunkt /business/api/telefonbuch für JSON-Daten - CSV-Export-Endpunkt /business/api/telefonbuch/csv mit UTF-8 BOM und Semikolon-Trennzeichen - OData-Endpunkt /odata/Telefonbuch mit erweiterten Abfrage- und Filtermöglichkeiten - Automatische Telefonnummer-Formatierung im E.164-Format mit libphonenumber-csharp - Unterstützung für Telefon1, Telefon2 und Mobilnummern mit intelligenter Zusammensetzung - Automatische Firmenname-Zuordnung über ErmittlePersonenkonto-Verknüpfung - TelefonbuchService: Zentraler Service für Mapping und Formatierungslogik - Ländercode-Normalisierung: Unterstützung für einstellige Ländercodes (D→DE, A→AT, etc.) - 14+ europäische Ländercodes werden automatisch normalisiert - 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: - Telefonbuch-API Code-Konsolidierung: Business- und OData-Controller nutzen gemeinsamen TelefonbuchService - 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: - ObjectDisposedException in Telefonbuch-API: Eager Loading der ErmittlePersonenkonto-Property verhindert Zugriff auf disposed Session - Korrekte Verwendung von ErmittlePersonenkonto statt Personenkonto für Firmenzuordnung - Telefonnummer-Formatierung berücksichtigt jetzt einstellige Ländercodes korrekt - 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