SaniVisionWebservice - REST Schnittstelle zur Kommunikation mit der SaniVision und Anbindung von Drittanwendungen

SaniVision REST API - Schnittstellenbeschreibung

Diese Beschreibung ist an Entwickler, IT-Experten oder Personen gerichtet, die mit der Integration und Kommunikation der Software SaniVision mit anderen Anwendungen vertraut sind oder daran interessiert sind, diese Funktionalität zu nutzen, um beispielsweise eine Drittanwendung anzubinden.

Funktionsbeschreibung

Die SaniVision REST API ist eine Schnittstelle, die es anderen Anwendungen ermöglicht, regelkonform mit Ihrem ERP-System SaniVision zu kommunizieren. Sie liest Daten aus der SaniVision aus und schreibt sie zurück.
Die REST-API wird über eine Virtuelle Maschine, kurz VM, (Hybrid Cloud) an den Kunden ausgeliefert.

Technische Voraussetzungen

• SaniVision Datenbank ab Version 173/8 incl. der benötigten PowerBuilder Runtime
• Möglichkeit zum Hosten einer virtuellen Maschine (VMware ESXI ab Version 6.7, Proxmox sowie HyperV). Die entsprechende VM wird von uns zur Verfügung gestellt.
• Die VM benötigt ca. 100GB an "Storage" min 4 CPU Cores optimal 8 CPU Cores, min 16GB Ram optimal 32 GB.
• Von dieser Maschine muss eine Verbindung via Port 443/tcp und 1196/udp in Richtung kd.sanivision.de (zur Zeit IP: 213.146.76.50) aufgebaut werden können.
• Zusätzlich Kommuniziert der Rest selbst nur via Port 80 und 443 mit der Außenwelt.
• Zwei feste IPs, eine davon muss der VM zugewiesen werden die zweite wird virtuell von uns zugewiesen.
• Interne Erreichbarkeit via Domainauflösung z.B.: rest.meinedomain.local (Eintrag im Kunden DNS auf die nicht vergebene IP die wir virtuell vergeben).
• Gateway und DNS
• Die Maschine muss den SAP ASE Datenbankserver via Port 5000/TCP erreichen können.
• Bei Verwendung eines eigenen Zertifikates muss dies im Format PEM mit der Dateiendung .crt vorliegen. Ebenso wird der dazugehörige Privatekey mit der Endung .key benötigt.
  Alternativ können der Privatekey und das Zertifikat auch zusammen in einem .cert File vorliegen.

Installation

1. Bei Interesse an der Nutzung der SaniVision REST API reichen Sie bitte ein Ticket bei uns ein und nennen Sie uns Ihr Anliegen zur gewünschten Anbindung bzw. Prozessabbildung.
2. Sie erhalten von uns den Vertrag und die Geheimhaltungsvereinbarung (NDA) zur Unterzeichnung.
3. Ihr Installationsschlüssel für die Ersteinrichtung wird Ihnen via E-Mail zugesandt.
   
   

Umfrage

1. Über diesen Umfrage-Link lassen Sie unserem technischen Support die geforderten Systeminformationen schnell und einfach zukommen, die für eine Installation notwendig sind.
   
   

Erste Schritte

Nachdem Ihre IT die VM in Ihrem VM-Host (Proxmox / VMware / HyperV) eingespielt hat folgen Sie bitte unserer Anleitung für die Ersteinrichtung.

• Anleitung zur Ersteinrichtung

Um mit der REST API arbeiten zu können, müssen Sie nach der Installation einen Admin User und bei Bedarf weitere User anlegen und mit den entsprechenden Rechten und Rollen versehen.
Die Anleitung dazu finden Sie hier:

• Anleitung zum Schnellstart
  
  

Funktionsübersicht des SaniVision REST Webservices

In der nachfolgenden Tabelle stellen wir Ihnen eine Übersicht aller vorhandenen SaniVision REST Services und Funktionen zusammen.

Services und Funktionen

Service Funktionalität ab Version anredenService/getAnreden Anhand der übermittelten Suchparameter werden passende Anreden ermittelt und zurückgegeben. 1.000 ansprechpartnerService/delAnsprechpartner Der übermittelte Ansprechpartner wird gelöscht. 1.005 ansprechpartnerService/getAnsprechpartner Anhand der übermittelten Suchparameter werden Ansprechpartner gesucht und zurück geliefert. 1.000 ansprechpartnerService/insAnsprechpartner Die Funktion legt einen Ansprechpartner anhand der übermittelten Parameter an. 1.000 ansprechpartnerService/updAnsprechpartner Anhand der übermittelten Suchparameter werden passende Anreden ermittelt und zurückgegeben. 1.000 artikelService/getArtikel Liefert eine Liste von Artikeln anhand der übermittelten Suchkriterien. 1.000 artikelService/getArtikelDetails Die Funktion liefert detaillierte Informationen pro übermittelte intArtikelNr zurück. 1.002 artikelService/getLagerbestaende Liefert die Lagerbestände des übermittelten Artikels für die Filiale des angemeldeten Nutzers zurück. 1.001 artikelService/getVertragspreis Ermittelt Vertragspreise zu einem Artikel anhand verschiedener Suchparameter. 1.012 artikelService/setArtikelschluessel Verknüpft einen Artikelschlüssel mit einem Artikel. 1.002 artikelService/updArtikel Ändert den Artikel anhand der übermittelten Informationen. 1.004 auftragService/getAuftraege Die Funktion liefert eine Liste von Auftragsnummern zurück, die anhand der übergebenen Suchparameter gefunden wurden. 1.043 auftragService/getAuftragDetails Die Funktion liefert detaillierte Auftragskopfdaten zur übermittelten Auftrag-Nr. zurück. 1.039 auftragService/getAuftragsstatus Die Funktion liefert die Auftragsstatus zu einem Auftrag. 1.043 auftragService/insAuftrag Die Funktion speichert Aufträge in der Datenbank. 1.000 auftragService/setAuftragsstatus Die Funktion speichert einen neuen Auftragsstatus am Auftrag. 1.002 auftragstatusService/getAuftragsstatus Die Funktion bietet die Möglichkeit, nach Auftragsstatus zu suchen. 1.000 dateienService/getDatei Die Funktion liest Informationen einer Datei anhand der Stammdatendateinummer aus. 1.007 dateienService/getDateien Die Funktion sucht anhand der übermittelten Parameter nach Dateien aus der SaniVision und liefert Informationen zu diesen zurück. 1.007 dateienService/insDatei Die Funktion importiert die übermittelte Datei und legt sie entweder für Windream oder die Stammdatendateien der SaniVision ab. 1.001 diagnosenService/getDiagnosen Die Funktion sucht anhand der übermittelten Parameter Diagnosen aus der Datenbank. 1.000 kostentraegerService/getKostentraeger Die Funktion findet Kostenträger anhand von verschiedenen Suchparametern. 1.000 kostentraegerService/updKostentraeger Anhand der übergebenen Parameter werden die Daten eines Kostenträgers aktualisiert. 1.005 kostenvoranschlagService/getKostenvoranschlaege Die Funktion liefert eine Liste von Kostenvoranschlagsnummern zurück, die anhand der übergebenen Suchparameter gefunden wurden. 1.002 kostenvoranschlagService/getKostenvoranschlagDetails Die Funktion liefert zu einer übermittelten Kostenvoranschlag-Nr. die Details zurück. 1.002 kostenvoranschlagService/insKostenvoranschlag Die Funktion bietet die Möglichkeit, Kostenvoranschläge in der Datenbank anzulegen. 1.001 kundenschluesselService/getKundenschluessel Anhand der übermittelten Suchkriterien wird eine Suche nach Kundenschlüsseln durchgeführt und das Ergebnis als Liste zurückgegeben. 1.000 kundenService/getKunden Die Funktion sucht anhand der übermittelten Parameter Kunden aus der Datenbank. 1.005 kundenService/getKundenschluesselFuerKunden Die Funktion liefert alle Kundenschlüssel zurück, die an dem gesuchten Kunden hinterlegt sind. 1.072 kundenService/getVersorgungen Die Funktion liefert anhand der übermittelten Suchparameter die Versorgungen der Kunden zurück. 1.075 kundenService/getWarenbewegung Die Funktion liefert anhand der übermittelten Parameter gefundene Warenbewegungen aus Bestellung, Wareneingang, Filialorder und internem Warenverkehr für einen bestimmten Artikel eines Kunden innerhalb eines Zeitraums zurück. 1.090 kundenService/insKunde Die Funktion legt einen Kunden anhand der übermittelten Parameter an. 1.006 kundenService/setKundenschluessel Die Funktion fügt übergebene Schlüssel an einen Kunden an, oder entfernt diese. 1.084 kundenService/updKunde Die Funktion ändert die übermittelten Parameter in den Kundenstammdaten. ladenverkaufService/getLadenverkaufAktionen Anhand der Suchparameter werden für einen Ladenverkaufsplatz die Ladenverkäufe in einem bestimmten Zeitraum ermittelt und zurückgeliefert. 1.002 ladenverkaufService/getLadenverkaufDetails Es werden zu einem Ladenverkauf alle relevanten Kopfdaten ermittelt und zurückgeliefert. 1.000 ladenverkaufService/getLadenverkaufPositionen Es werden zu einem Ladenverkauf alle Positionen ermittelt und zurückgeliefert. 1.001 laenderkennzeichenService/getLaenderkennzeichen Die Funktion sucht anhand der übermittelten Parameter Länderkennzeichen aus der Datenbank. 1.000 mitarbeiterService/getMitarbeiter Die Funktion liefert Daten zu Mitarbeitern aus der Datenbank. 1.000 rehamittelService/getRehamittel Sucht alle Rehamittel passend zu den übermittelten Suchkriterien und liefert eine Liste von Rehamittelnummern zurück. 1.003 rehamittelService/getRehamittelDetails Liefert anhand einer RehamittelNr alle Details zu dem entsprechenden Rehamittel zurück. 1.005 rehamittelService/getRehamittelZustandsbericht Liefert den Zustandsbericht zu einem Rehamittel zurück. 1.002 rehamittelService/setRehamittelAnsLager Die Funktion setzt ein Rehamittel nach einer Prüfung ans Lager und ändert entsprechend den Status. 1.005 rehamittelService/setRehamittelRuecknahme Die Funktion setzt ein Rehamittel nach einer Prüfung auf Rücknahme und ändert entsprechend den Status. 1.005 vermittlerschluesselService/getVermittlerschluessel Diese Funktion bietet die Möglichkeit, nach Vermittlerschlüsseln zu suchen. 1.000 vermittlerService/getVermittler Die Funktion liefert alle Vermittler nach übertragenen Suchparametern zurück. 1.000 vermittlerService/setVermittlerschluessel Ordnet einem Vermittler einen Vermittlerschlüssel zu. 1.005 verordnerschluesselService/getVerordnerschluessel Diese Funktion bietet die Möglichkeit, nach Verordnerschlüsseln zu suchen. 1.000 verordnerService/getVerordner Die Funktion sucht anhand der übermittelten Parameter Verordner aus der Datenbank. 1.000 verordnerService/insVerordner Die Funktion erstellt einen neuen Verordner in der Datenbank. 1.004 verordnerService/setVerordnerschluessel Ordnet einem Verordner einen Verordnerschlüssel zu. 1.005 verordnerService/updVerordner Anhand der übergebenen Parameter wird ein existierender Verordner angepasst. 1.005 versorgungsartenService/getVersorgungsarten Die Funktion sucht anhand der übermittelten Parameter Versorgungsarten aus der Datenbank. 1.000 vertriebsaktionenService/setVertriebsaktion Setzen einer Vertriebsaktion zu einem Stammdatensatz. 1.000 vorgangService/getVorgaenge Anhand der übermittelten Suchparameter wird eine Vorgangssuche durchgeführt und eine Liste der gefundenen Vorgänge zurückgegeben. 1.000 vorgangService/insVorgang Erstellt einen neuen Vorgang anhand der übergebenen Parameter. 1.001 vorgangService/updVorgang Anhand der übergebenen Parameter wird ein Vorgang aktualisiert. 1.001 wiedervorlagenService/insWiedervorlage Die Funktion speichert Wiedervorlagen in der Datenbank. 1.000

API Dokumentation

Über die bei Ihnen ausgerollte REST API haben Sie Zugriff auf die zugehörige Swagger-Dokumentation.
Diese ist über den gemeldeten Domainnamen aufrufbar z.B: https://meinrest.kunde.local oder https://rest.kundexy.de

Sofern Sie noch über keine eigene REST API-Installation verfügen, können Sie bei Bedarf auf eine zentrale Swagger Dokumentation zugreifen.
Diese ist ausschließlich für per REST NDA autorisierte Anwender über einen gesonderten Login zugänglich.
Bei Interesse reichen Sie Ihre Anfrage bitte über ein Kundenticket bei uns ein.

Hybrid Cloud / VM

Infrastruktur- und Sicherheitskonzept: REST-API & Service-Umgebung

1. Exklusive Ressourcen-Zuweisung & Isolation

Obwohl unsere Infrastruktur auf einer hochverfügbaren Cluster-Architektur basiert, stellen wir sicher, dass jeder Kunde eine strikt isolierte Umgebung erhält:

• Dedizierte Instanzen: Durch ein intelligentes Zuweisungsverfahren garantieren wir, dass die für Sie reservierten Dienste ausschließlich auf der für Sie bereitgestellten Hardware/VM ausgeführt werden. Ein „Vermischen“ mit Prozessen anderer Kunden ist systemseitig ausgeschlossen.
• Netzwerk-Segmentierung: Ihr Bereich ist durch digitale Barrieren so abgeschirmt, dass kein Datenaustausch mit anderen Kundenumgebungen innerhalb der Infrastruktur möglich ist.

2. Datensouveränität & Lokale Datenhoheit (SAP ASE)

Ein Kernaspekt unseres Sicherheitskonzepts ist die strikte Trennung von Anwendungslogik und sensiblen Daten:

• Enterprise-Datenbank: Sämtliche veränderlichen Informationen sowie die komplette Rechteverwaltung werden ausschließlich in Ihrer vorhandenen SAP ASE Datenbank gespeichert.
• Kein Cloud-Abfluss: Es fließen zu keinem Zeitpunkt Kunden- oder Benutzerinformationen in eine externe Cloud. Sie behalten die physische und logische Hoheit über alle datenschutzrelevanten Assets.
• Hybrider Vorteil: Sie nutzen moderne, hochskalierbare Cloud-Technologien als Basis, während die Datenbasis sicher in Ihrer eigenen Infrastruktur verbleibt.

3. Managed Appliance Modell (Wartungsfreiheit)

Die VM wird als geschlossene Managed Appliance ausgeliefert:

• Kein administrativer Eigenaufwand: Um die Integrität und Stabilität des Gesamtsystems zu sichern, ist die Appliance betriebsseitig versiegelt. Es werden kundenseitig keine Betriebssystem-Benutzer oder administrativen Zugänge benötigt.
• Vollumfänglicher Betrieb: Die kontinuierliche Wartung sowie die Bereitstellung von Software-Updates und Patches zur Sicherstellung der Betriebsbereitschaft erfolgen vollständig automatisiert durch uns.

4. Gehärtete Betriebsumgebung & Administrationsschutz

• Plattform-Kompatibilität: Die Auslieferung erfolgt als optimierte Appliance für Hyper-V, VMware oder Proxmox.
• Sicherheits-Betriebssystem: Als Basis dient ein gehärtetes Ubuntu Server Linux (LTS).
• Firewall & Konnektivität: Die integrierte Firewall lässt standardmäßig nur die Ports 80 und 443 zu. Port 80 dient dabei nur der automatischen Weiterleitung auf den verschlüsselten Port 443 (HTTPS).
• Gesicherter Administrationskanal: Für das Monitoring und die Wartung der Instanz wird ein dedizierter, verschlüsselter Tunnel aufgebaut. Dieser Kanal ist strikt für administrative Zwecke konzipiert. Er stellt sicher, dass ein Zugriff von unserer Seite auf Ihre internen Kundendaten technisch ausgeschlossen ist.

5. Sicherheit durch „Stateless Design“ (Unveränderlichkeit)

Unsere Software-Architektur folgt dem Prinzip der Immutability:

• Resilienz gegen Manipulation: Die Funktionalitäten laufen in abgeschlossenen Software-Containern. Da keine persistenten Kundendaten innerhalb dieser Container verbleiben, hat Schadsoftware keine Basis, um sich dauerhaft festzusetzen.
• Individualisierbare Erneuerungszyklen: Auf Wunsch richten wir ein automatisiertes, regelmäßiges Neu-Ausrollen der Dienste ein. Dabei werden die aktiven Software-Komponenten komplett verworfen und durch frische, verifizierte Instanzen ersetzt.
• SMB-Anbindung: Datei-Uploads werden unmittelbar auf Ihren eigenen SMB-Shares abgelegt. Da die Speicherung in Ihrem Haus erfolgt, können Sie Ihre lokalen Sicherheits-Systeme und Virenscanner uneingeschränkt zur Überwachung nutzen.

6. Authentifizierung & Zugriffskontrolle

• Protokolle: Authentifizierung via OAuth 2.0 und OpenID Connect.
• Verschlüsselung: Durchgehender Einsatz von TLS 1.2 oder 1.3.
• Revisionssichere Validierung: Zugriffstokens sind kryptografisch signiert und zeitlich begrenzt gültig. Berechtigungen, die in Ihrer lokalen SAP ASE Datenbank definiert sind, werden bei jeder Anfrage validiert.
• Zentrale Kontrolle: Benutzerkonten können jederzeit gesperrt werden, wodurch der Zugriff unmittelbar unterbunden wird.

Infrastruktur Anforderungen

Unsere Appliance nutzt zur Bereitstellung der Dienste und zur Sicherstellung der Hochverfügbarkeit virtuelle IP-Adressen (Floating IPs / Service IPs). Damit der Netzwerkverkehr aus dem jeweiligen lokalen Netzwerksegment zuverlässig zu den Diensten auf unserer Appliance geroutet werden kann, nutzt unser System standardkonforme Gratuitous ARP-Broadcasts (gARP). Dadurch teilt die Appliance den vorgelagerten Switches und Firewalls dynamisch mit, an welche physische MAC-Adresse der Traffic für die jeweiligen virtuellen IPs gesendet werden muss.

Mögliches Problembild (Verbindungsabbrüche / Port-Sperren):
In stark abgesicherten Enterprise-Netzwerken kann dieses legitime Failover- und Routing-Verhalten von Switch- oder Firewall-Sicherheitsmechanismen fälschlicherweise als Anomalie, zum Beispiel als ARP-Spoofing- oder Man-in-the-Middle-Angriff, eingestuft werden.

Typische Symptome:

• Die Appliance verliert in unregelmäßigen Abständen für exakt 15 bis 30 Sekunden jegliche Netzwerkverbindung.
• Die virtuelle Netzwerkkarte (vNIC) der Appliance auf dem Hypervisor verzeichnet in diesem Zeitraum keinen Link-Verlust und bleibt technisch aktiv.
• Im Switch- oder Firewall-Log häufen sich Warnmeldungen bezüglich der MAC- oder IP-Adresse unserer Appliance.

Erforderliche Konfigurationen auf Kundenseite:
Um einen reibungslosen Betrieb zu gewährleisten und automatische Port-Sperren durch Ihre Netzwerkinfrastruktur zu verhindern, müssen für den Switchport beziehungsweise das Netzwerksegment unserer Appliance die folgenden Ausnahmen berücksichtigt werden.

• Dynamic ARP Inspection (DAI) / ARP-Spoofing-Protection Wenn Ihr Netzwerk die Zuordnung von IP- zu MAC-Adressen strikt überwacht, müssen die von uns zusätzlich genutzten virtuellen IP-Adressen für die MAC-Adresse unserer Appliance autorisiert beziehungsweise freigegeben werden. Andernfalls können unaufgeforderte ARP-Aktualisierungen (Gratuitous ARP) verworfen oder als Sicherheitsereignis behandelt werden.

• MAC-Flapping / Port-Security Da unsere Appliance Traffic für mehrere IP-Adressen über dieselbe physische MAC-Adresse abwickelt, darf der betreffende Switchport nicht zu restriktiv auf eine einzige IP-Adresse oder auf ein unerwartetes Adressverhalten begrenzt sein.

• IPS/IDS und Rate-Limiting Sollte Ihre Firewall oder Ihr Intrusion Prevention System (IPS) ein Rate-Limiting oder Schutzmechanismen für ARP- beziehungsweise Broadcast-Verkehr durchführen, stellen Sie bitte sicher, dass die Appliance bei regelmäßigen ARP-Aktualisierungen nicht aufgrund von vermeintlichem Flooding oder Spoofing temporär blockiert wird.

Zusammenfassung für Ihre Netzwerk-Administration
Bitte stellen Sie sicher, dass im vorgesehenen Netzsegment – zum Beispiel in einem VLAN oder einer DMZ – der Betrieb mit virtuellen IP-Adressen unterstützt wird und die dafür erforderlichen ARP-Aktualisierungen zugelassen sind, ohne dass Sicherheitsmechanismen auf Switches oder Firewalls zu temporären Sperren führen.