OBS/Kostenpflichtige Module/RESTServer/Einrichtung: Unterschied zwischen den Versionen

Aus OBS Wiki
Zur Navigation springen Zur Suche springen
Keine Bearbeitungszusammenfassung
Keine Bearbeitungszusammenfassung
Zeile 3: Zeile 3:
=Einrichtung eines REST-Endpunktes=
=Einrichtung eines REST-Endpunktes=


Die folgende Reihenfolge stellt sicher, dass ein lauffaehiger Endpunkt mit moeglichst wenigen Korrektur-Schleifen entsteht.
Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.


==Vorbereitung==
==Vorbereitung==


# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# Pruefen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, ggf. mit Chain), privaten Schluessel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, ggf. mit Chain), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten.


==Schritt 1: Server-Profil anlegen==
==Schritt 1: Server-Profil anlegen==


In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' oeffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:
In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' öffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:


* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
Zeile 19: Zeile 19:
* Auswahl des Modus:
* Auswahl des Modus:
** '''Standard-TLS''' (Default): Zertifikat + Key + Root-Zertifikat hinterlegen.
** '''Standard-TLS''' (Default): Zertifikat + Key + Root-Zertifikat hinterlegen.
** '''mTLS''' aktivieren: zusaetzlich CA-Root-Zertifikat hinterlegen, jeder Client muss ein gueltiges Cert vorlegen.
** '''mTLS''' aktivieren: zusätzlich CA-Root-Zertifikat hinterlegen, jeder Client muss ein gültiges Cert vorlegen.
** '''Kein SSL''' aktivieren: ausschliesslich fuer lokale Tests, der Server akzeptiert dann nur Plain-HTTP.
** '''Kein SSL''' aktivieren: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.


Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server|Server-Profile]].
Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server|Server-Profile]].
Zeile 26: Zeile 26:
==Schritt 2: Bindung anlegen==
==Schritt 2: Bindung anlegen==


Im Server-Profil mit '''F6''' die Bindungs-Liste oeffnen und mit '''Einfg''' eine neue Bindung anlegen:
Im Server-Profil mit '''F6''' die Bindungs-Liste öffnen und mit '''Einfg''' eine neue Bindung anlegen:


* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' fuer alle Adressen, ''127.0.0.1'' fuer lokal).
* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' für alle Adressen, ''127.0.0.1'' für lokal).
* '''Port''' - Port-Nummer (typisch 443 fuer HTTPS, 8099 fuer Debug, ggf. abweichend).
* '''Port''' - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend).
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).


==Schritt 3: REST-Dienst starten / neustarten==
==Schritt 3: REST-Dienst starten / neustarten==


Damit Aenderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.
Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.


==Schritt 4: Zugang anlegen==
==Schritt 4: Zugang anlegen==


Unter '''Zugaenge''' mit '''Einfg''' einen neuen Zugang anlegen:
Unter '''Zugänge''' mit '''Einfg''' einen neuen Zugang anlegen:


* '''Name''' - erscheint im Protokoll und in der Statistik.
* '''Name''' - erscheint im Protokoll und in der Statistik.
* '''API-Key''' - eindeutig, mit dem Schluesselsymbol kann ein zufaelliger Key generiert werden.
* '''API-Key''' - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn moeglich, immer gesetzt werden).
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugaenge]].
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].


==Schritt 5: Endpunkt anlegen==
==Schritt 5: Endpunkt anlegen==
Zeile 52: Zeile 52:
* '''Sub-URL''' - optional, z.B. ''mobile''.
* '''Sub-URL''' - optional, z.B. ''mobile''.
* '''Version''' - z.B. ''v1''.
* '''Version''' - z.B. ''v1''.
* '''Server''' - die Server-Auswahl bestimmt, ueber welches Server-Profil der Endpunkt erreichbar ist.
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.


Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).
Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).


==Schritt 6: Zugang fuer den Endpunkt freischalten==
==Schritt 6: Zugang für den Endpunkt freischalten==


Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' druecken. Es oeffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugaenge ausgewaehlt und mit '''F2''' uebernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.
Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugänge ausgewählt und mit '''F2''' übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.


==Schritt 7: Funktionspruefung==
==Schritt 7: Funktionsprüfung==


Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):
Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):
Zeile 66: Zeile 66:
  curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Endpunkt]/[Version]
  curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Endpunkt]/[Version]


Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfaelle werden in '''RESTSRV_PROTO''' protokolliert.
Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in '''RESTSRV_PROTO''' protokolliert.


==Schritt 8: Statistik und Protokoll pruefen==
==Schritt 8: Statistik und Protokoll prüfen==


* In der Endpunkt-Liste '''F8''' fuer die Statistik des Endpunkts.
* In der Endpunkt-Liste '''F8''' für die Statistik des Endpunkts.
* In der Zugaenge-Liste '''F8''' fuer die Statistik des Zugangs.
* In der Zugänge-Liste '''F8''' für die Statistik des Zugangs.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse pruefen.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse prüfen.


==Haeufige Stolpersteine==
==Häufige Stolpersteine==


* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* Zugang fuer den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung fuer die Endpunkt-Nutzung''.
* Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung für die Endpunkt-Nutzung''.
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird waehrend des TLS-Handshakes abgebrochen.
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.

Version vom 19. Mai 2026, 07:06 Uhr

Kostenpflichtige Module

Internet-Shop
Der modified ECommerce Shop
Shop-Menü
Automatische Vorgänge
modified eCommerce 2.0
Der Büroring-ShopV4
Einrichtung
Eigene Artikel
brShop24
Einstellungen und Automatiken
Funktionen
Preislisten
Preislistenverwaltung
F10 Weitere Funktionen
Automatiken Kommandos
ZUGFeRD
Factoring
UPS
DHL
IMS Professional
TAPI
SMS
Fleet Management
Mehrlager-Verwaltung
Mehrsprachen Modul
Multilanguage Modul
Einfache Produktionsnachverfolgung
DMS - Dokumenten Management System
DMS Dokumente
Tasten und Schaltflächen
F10 Weit.
E DMS Definitionen
QR Zeiterfassung
EVA Marketing Tool
Technikersteuerung
Termin-Projekte
Edifact-Schnittstelle
Backup Überwachung Email
Anlagenbuchhaltung
OBS Geo Daten
DeliSprint / DPD
Filialen
Auto-Waagen
Cashback
Moebelschnittstelle
Tourenplanung
Tourenplanung
Dokumenten Manager
DocuWare-Schnittstelle
OFML-Kalkulation
Pascom
Versicherungsschaden
Gutschriftsanzeigen
OCPP Ladestationen
Kameraverwaltung
DataInOut
REST-Schnittstelle
Beispiele
Sammelverträge
Craftboxx
OpenMasterData / IDS
Sammelpositionen


Einrichtung eines REST-Endpunktes

Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.

Vorbereitung

  1. OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
  2. Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
  3. Bei TLS-Profilen: TLS-Zertifikat (PEM, ggf. mit Chain), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten.

Schritt 1: Server-Profil anlegen

In Stammdaten -> Z Weitere Stammdaten -> REST-Server den Punkt Server öffnen und mit Einfg ein neues Profil anlegen. Pflichtfelder:

  • Nr - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
  • Name - sprechender Name (z.B. Public-API, Internal-mTLS, Debug-Local).
  • Auswahl des Modus:
    • Standard-TLS (Default): Zertifikat + Key + Root-Zertifikat hinterlegen.
    • mTLS aktivieren: zusätzlich CA-Root-Zertifikat hinterlegen, jeder Client muss ein gültiges Cert vorlegen.
    • Kein SSL aktivieren: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.

Details siehe Server-Profile.

Schritt 2: Bindung anlegen

Im Server-Profil mit F6 die Bindungs-Liste öffnen und mit Einfg eine neue Bindung anlegen:

  • Host - IP-Adresse, auf der gelauscht werden soll (z.B. 0.0.0.0 für alle Adressen, 127.0.0.1 für lokal).
  • Port - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend).
  • Standard setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).

Schritt 3: REST-Dienst starten / neustarten

Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.

Schritt 4: Zugang anlegen

Unter Zugänge mit Einfg einen neuen Zugang anlegen:

  • Name - erscheint im Protokoll und in der Statistik.
  • API-Key - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
  • Host - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
  • Optional: CORS-Origins und JWT-Konfiguration, siehe Zugänge.

Schritt 5: Endpunkt anlegen

Unter Endpunkte mit Einfg einen neuen Endpunkt anlegen:

  • Endpunkt - der Hauptname (z.B. kalender, zeiterfa).
  • Sub-URL - optional, z.B. mobile.
  • Version - z.B. v1.
  • Server - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.

Anschliessend mit F7 das Endpunkt-Skript pflegen (siehe Scripting).

Schritt 6: Zugang für den Endpunkt freischalten

Aus der Endpunkt-Liste den neuen Endpunkt markieren und F6 drücken. Es öffnet sich die Berechtigungs-Liste. Mit Einfg kann ein oder mehrere Zugänge ausgewählt und mit F2 übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.

Schritt 7: Funktionsprüfung

Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in): 

curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Endpunkt]/[Version]

Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in RESTSRV_PROTO protokolliert.

Schritt 8: Statistik und Protokoll prüfen

  • In der Endpunkt-Liste F8 für die Statistik des Endpunkts.
  • In der Zugänge-Liste F8 für die Statistik des Zugangs.
  • In Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll die Ereignisse prüfen.

Häufige Stolpersteine

  • Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
  • Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 Endpunkt nicht vorhanden oder inaktiv.
  • Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 Keine Berechtigung für die Endpunkt-Nutzung.
  • Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
  • mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.
Abgerufen von „http:///index.php?title=OBS/Kostenpflichtige_Module/RESTServer/Einrichtung&oldid=64459“